[mattpodwysocki]

Summary

Someone building an app with the MCP server couldn't get a drawable route for a long trip (London to a point in Scotland).

Cause: geometries="geojson" always asked the Directions API for overview=full, every vertex of every road. Fine for a short trip, but a long one is tens of thousands of coordinate pairs, past the tool's 50 KB response limit. Past that limit the tool returns a summary and a ref instead of the geometry, so an agent that asked for coordinates got a different response shape depending on trip length, with no way to know in advance.

Fix: a new optional overview input ("full" or "simplified"):

• Defaults to "simplified" when geometries="geojson". Live, London to Edinburgh (about 420 miles) goes from 10,057 coordinate pairs (about 700 KB) to 46 (about 4.7 KB), and the line still draws accurately.
• Defaults to "full" when geometries="none", as before, since no geometry comes back either way.
• overview="full" stays available as an explicit opt-in. On a long trip it still goes past the limit and returns the summary plus a mapbox://response/ ref (fix: large directions/isochrone responses return a short ref that works on the hosted server #257), now a deliberate choice instead of a surprise.
• Same overview parameter optimization_tool already has, also defaulting to "simplified".

Tradeoff: the Directions API rejects the congestion annotation unless overview=full (422: Overview option must be full for congestion, checked live). So congestion_information only comes back when the effective overview is "full". distance and speed annotations work at any level. Along the way: the tool used to report an all-zero congestion breakdown when congestion wasn't requested, which reads as "no traffic" rather than "not checked". It's now left out instead.

Unaffected: render_map_tool's map fetches its own full-detail route in the browser, whatever directions_tool returned.

Updated after #257, #276 and #296 merged

• The tool description and overview docs now describe the mapbox://response/ ref from fix: large directions/isochrone responses return a short ref that works on the hosted server #257 instead of the old mapbox://temp/ resource, and keep main's render_map_tool wording from the tool-selection work (fix: rewrite tool descriptions flagged by Claude connector directory review #273).
• directionsRequestFromRef (the feat(utils): export directionsRequestFromRef for routes by reference #276 export for apps that draw routes from a ref) now always asks for overview=full. Without that, a ref from a geojson call would have rebuilt the simplified request and apps drawing from it would get a coarser line. That matches the map's own fetch. There's a test and a docs note.
• Tests use the typed helpers from test: fix all test type errors and typecheck tests in CI #298 so they pass the CI typecheck.

Testing

• New tests in buildDirectionsRequestUrl.test.ts, cleanResponseData.test.ts, DirectionsTool.test.ts and directionsRef.test.ts: short and long route fixtures, the overview defaults, congestion only with full overview, and the ref asking for full geometry.
• Typecheck clean, build OK, 97 files / 1092 tests pass, lint 0 errors. CI green.
• Live against the real Directions API and the built server (before the main merge): long route with the geojson default came back at 4.9 KB with 46 coordinates and no fallback; a short route at 2 KB with the same shape; a long route with geometries="none" still had congestion; explicit overview="full" on a long route fell back as documented.

🤖 Generated with Claude Code

[ctufts]

What happens if I don't want to use the render_map_tool and require the full geometry? Maybe I call this tool and render my own map, would this degrade my mapping experience?

[mattpodwysocki]

Good question. The default simplified geometry keeps the route's shape when zoomed out but cuts corners up close, so if you render your own map and let people zoom in on the route, pass overview="full" and you get every vertex. Made that explicit in the tool description and the overview parameter (d384970) so the model knows to ask for it.