Skip to content

fix: fewer failed matrix_tool and map_matching_tool calls - #340

Merged
mattpodwysocki merged 2 commits into
mainfrom
fix/matrix-map-matching-errors
Nov 16, 2026
Merged

mattpodwysocki merged 2 commits into
mainfrom
fix/matrix-map-matching-errors

Conversation

@mattpodwysocki

@mattpodwysocki mattpodwysocki commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

The Claude directory shows 6.8% of matrix_tool calls and 15.1% of map_matching_tool calls failing. The hosted server's CloudWatch logs (hosted-mcp-server-production-us-east-1, last 30 days) break it down:

Tool Calls Errors Top causes
matrix_tool 21,716 1,181 (5.4%) 944 single-element 422s, 215 429s, 9 from our "all coordinates used" check
map_matching_tool 320 16 (5.0%) 10 output schema failures (missing geometry), the rest one-offs

I reproduced each cause below against the live APIs.

matrix_tool

  • Single pair (944 errors, 80%). A model asks for one A→B pair (sources=0&destinations=1), which is one matrix element, and the API refuses it: 422: ... only 1 matrix element; minimum number of matrix elements is 2. The tool now requests a 1×2 matrix (destinations=i;j, the source to itself and to the destination), the API's minimum, so it costs the same, and returns only the requested pair. Checked live in both directions.
  • Rate limits (215 errors, 18%). The Matrix API allows 60 requests/min (30 for driving-traffic). The pipeline already retries 429s, but only for a few seconds. The description and the 429 error now tell the model to put all the points in one call (up to 25) instead of one call per pair, which is probably what's tripping the limit.
  • Our own over-strict check (9 errors). With both sources and destinations set, it required every coordinate to be used. The API has no such rule, so that check is gone. A source that is also its only destination is still refused before the call.
  • Unroutable points. When a coordinate can't be snapped to the road network, the API returns 200 with null in sources/destinations. Our schema didn't allow null, and the tool returned the raw response anyway, so SDK v2 threw an output validation error. null waypoints are now allowed, and the result notes which coordinates couldn't be snapped. A response that still fails the schema is now a tool error, as fix: map_matching_tool returns graceful error instead of MCP -32602 on NoMatch #230 did for map matching. This didn't show up in the 30 days of logs, but it's a real failure.

map_matching_tool

  • overview=false (10 of 16 errors). The API leaves out geometry then, and our output schema required it. It's optional now.
  • Used for routing between places. Models call it with a few points far apart: 3 km apart gives NoMatch, 20 km+ gives 422 All coordinates are too far away from each other. The description and both errors now point to directions_tool.
  • Inputs.
    • The radius description said the default is unlimited. It's 5 m.
    • The logs had the API refusing a radius outside 0–50 (must be ... greater than 0 and smaller than 50), so the schema now takes > 0 and ≤ 50.
    • Non-ascending timestamps, which get NoMatch, are rejected.

Not changed

A few input validation errors (coordinates sent as [lng, lat] arrays, an unknown profile) come from the model, not the tool. They're 1–3 each.

Tests

  • Matrix: single pair as 1×2 with the result trimmed, the 429 hint, null waypoints with the note, schema-failing response as an error, asymmetric matrix with unused coordinates, source equal to destination rejected.
  • Map matching: matchings without geometry, non-ascending timestamps, radius 0, "too far away" hint, NoMatch hint.

🤖 Generated with Claude Code

- matrix_tool: allow null waypoints for unroutable coordinates, return a
  tool error instead of schema-violating structuredContent, and replace
  the "all coordinates used" check with the API's two-element minimum.
- map_matching_tool: say it's for dense GPS traces and point to
  directions_tool, fix the radius default in the description, reject a
  radius of 0 and non-ascending timestamps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattpodwysocki
mattpodwysocki requested a review from a team as a code owner November 16, 2026 18:11
@mattpodwysocki mattpodwysocki added bug Something isn't working enhancement New feature or request labels Nov 16, 2026
From the hosted server's logs: most matrix_tool errors were one-element
matrices the API refuses (944 of 1,181), then 429s (215). Map matching's
were matchings without geometry from overview=false (10 of 16).

- matrix_tool: ask for a 1x2 matrix for a single pair and return only
  that pair; explain the rate limit in the description and on a 429.
- map_matching_tool: geometry is optional; radiuses go up to 50, which
  the API enforces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattpodwysocki
mattpodwysocki merged commit 12eb4e2 into main Nov 16, 2026
5 checks passed
@mattpodwysocki
mattpodwysocki deleted the fix/matrix-map-matching-errors branch November 16, 2026 18:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants