fix: directions_tool geojson always returns coordinates, any trip length

[mattpodwysocki]

Summary

Someone trying the MCP server reported that their agent, building an app, couldn't get a drawable route for a long trip (London to a point in Scotland) — it kept burning cycles on a size-based contract split it had no way to anticipate.

Root cause: geometries="geojson" always requested overview=full (maximum-precision geometry) regardless of trip length. For a short trip this fits comfortably in the response; for a long one it can be tens of thousands of coordinate pairs, blowing past the 50KB threshold — at which point the tool silently swapped to a completely different contract: geometry and legs stripped out, replaced by a mapbox://temp/... resource URI. That URI isn't even a fetchable HTTP URL — it only works via the MCP resources API — so an agent trying to embed the route in generated app code had nothing usable.

Fix: new optional overview input ("full" | "simplified"), defaulting to "simplified" whenever geometries="geojson" (and to "full" when geometries="none", unchanged, since no geometry is returned there either way). This mirrors the overview parameter optimization_tool already exposes — and already defaults to "simplified" — which is presumably why that tool never needed this kind of large-response fallback in the first place.

Confirmed live against the real Directions API: a real London→Edinburgh route (~420 miles) drops from 10,057 coordinate pairs / ~700KB (overview=full) to 46 coordinate pairs / ~4.7KB (overview=simplified) — comfortably inside the response limit, and still a fully accurate, drawable line. overview="full" remains available as an explicit, documented opt-in for callers who need maximum precision, accepting the same large-response fallback as before (now a deliberate choice rather than a surprise past a size cliff).

Tradeoff, documented in the schema: the Directions API rejects the congestion annotation unless overview=full (422: Overview option must be full for congestion, confirmed live) — distance/speed annotations have no such restriction and stay accurate at any level. So congestion_information is only present when the effective overview is "full". Along the way, fixed a real pre-existing bug: the code previously reported an all-zero congestion_information breakdown whenever congestion happened to be unavailable, which reads as "confirmed no traffic" rather than "not checked" — it's now correctly omitted instead.

render_map_tool's live map preview is unaffected either way — it already always fetches its own full-detail geometry client-side (mapbox://selffetch/directions...), independent of what directions_tool's own response contains.

Acceptance criteria

• An agent can obtain a drawable route for both a short trip and a long trip (London→Edinburgh tested live) without discovering a second contract — same response shape either way.
• Tool description and geometries/overview schema docs explain how to get coordinates vs. distance/duration/instructions, and what happens (rare, opt-in) when geometry is still large.
• Chat-style use (distance, duration, congestion, render_map_tool preview) still works for both short and long routes.
• Tests cover a compact route and a large-geometry route under the new design.
• CHANGELOG.md records the behavior change under Unreleased.

Test plan

• npx vitest run — all 945 tests pass, including new coverage in buildDirectionsRequestUrl.test.ts, cleanResponseData.test.ts, and DirectionsTool.test.ts (short + long route fixtures, congestion_information omission)
• npm run build succeeds, lint clean
• Live-verified end-to-end against the real Mapbox API and the real built server: long route (geojson, default) → 4.9KB, 46 coordinates, no temp-resource fallback; short route → 2KB, 8 coordinates, same shape; long route with geometries="none" → congestion still present; long route with explicit overview="full" → falls back to the old temp-resource behavior as documented

🤖 Generated with Claude Code