Directions Tool
directions_toolFetches Mapbox routes from coordinates and a routing profile, returning distance, duration, turn-by-turn instructions, and a route ref for map rendering.
Instructions
Fetches directions from Mapbox API based on provided coordinates and direction method. Returns a mapboxRender.ref in structuredContent regardless of the geometries value; if the user wants to see the route on a map, pass it to render_map_tool. Use geometries="none" (default) for compact text/data responses (distance, duration, turn-by-turn instructions, congestion). Use geometries="geojson" when you need the raw route coordinates in the response yourself, e.g. to draw the route in your own app. It defaults to a simplified geometry that keeps the route's shape when zoomed out but cuts corners up close; pass overview="full" for every vertex when your map lets people zoom in on the route. render_map_tool works either way. Only overview="full" on a very long trip can exceed the response size limit; then this tool returns a summary and a mapbox://response/... ref you can read with the MCP resources API.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"coordinates": "<coordinates>"
},
"name": "directions_tool"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exclude | No | Whether to exclude certain road types and custom locations from routing. Multiple values can be specified as a comma-separated list. Available options: - All profiles: ferry, cash_only_tolls - Driving/Driving-traffic profiles only: motorway, toll, unpaved, tunnel, country_border, state_border or point(<lng> <lat>) For custom locations you can use Point exclusions (note lng and lat are space separated and at most 50 points are allowed) Note: country_border excludes all controlled country borders; borders within the Schengen Area are not excluded. | |
| overview | No | Detail level of the geometry named above (has no effect when geometries="none", since no geometry is returned either way). Defaults to "simplified" when geometries="geojson" (a route across an entire country is typically well under 100 coordinate pairs — enough to draw an accurate shape, not enough to bloat the response) and to "full" otherwise. Pass "full" explicitly for the maximum-precision geometry (every road segment vertex) if you need it, e.g. for a map people zoom in on; on a long trip this can be tens of thousands of coordinate pairs, at which point the response no longer fits in this reply and this tool returns a summary and a `mapbox://response/` ref instead (see the tool description). Note: the Directions API cannot return per-segment congestion data (`congestion_information` in the response) together with anything other than "full" — congestion is only included when the effective overview is "full". | |
| arrive_by | No | The desired arrival time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving profile and is not supported by other profiles, not even driving-traffic. The travel time will be calculated based on historical and real-time traffic data. | |
| depart_at | No | The departure time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ, YYYY-MM-DDThh:mmss±hh:mm, or YYYY-MM-DDThh:mm). This parameter is only available for the driving and driving-traffic profiles. The travel time will be calculated based on historical and real-time traffic data. | |
| max_width | No | The max vehicle width, in meters. The Directions API will compute a route that includes only roads with a width limit greater than or equal to the max vehicle width. Must be between 0 and 10 meters. The default value is 1.9 meters. Only available for driving and driving-traffic profiles. | |
| geometries | No | The format of the returned geometry. Options: - none (default): no geometry object is returned in the response. The mapboxRender.ref works with render_map_tool either way; use this whenever you do not need the raw coordinates yourself. - geojson: as a GeoJSON LineString, always returned directly in this response — the coordinate count depends on `overview` (see below), not on trip length, so this works the same way for a 2-mile trip and a 400-mile one. Use this whenever you (the caller) need the coordinates yourself, e.g. to draw the route in your own app; not required for render_map_tool. | none |
| max_height | No | The max vehicle height, in meters. The Directions API will compute a route that includes only roads with a height limit greater than or equal to the max vehicle height. Must be between 0 and 10 meters. The default value is 1.6 meters. Only available for driving and driving-traffic profiles. | |
| max_weight | No | The max vehicle weight, in metric tons (1000 kg). The Directions API will compute a route that includes only roads with a weight limit greater than or equal to the max vehicle weight. Must be between 0 and 100 metric tons. The default value is 2.5 metric tons. Only available for driving and driving-traffic profiles. | |
| coordinates | Yes | Array of coordinate objects with longitude and latitude properties to visit in order. Must include at least 2 coordinate pairs (starting and ending points). Up to 25 coordinates total are supported. | |
| alternatives | No | Whether to try to return alternative routes (true) or not (false, default). Up to two alternatives may be returned. | |
| routing_profile | No | Routing profile for different modes of transport. Options: - mapbox/driving-traffic (default): automotive with current traffic conditions - mapbox/driving: automotive based on typical traffic - mapbox/walking: pedestrian/hiking - mapbox/cycling: bicycle | mapbox/driving-traffic |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | ||
| uuid | No | ||
| routes | No | ||
| waypoints | No | ||
| mapboxRender | No | Map-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry. |