Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Optimize Multi-Stop Route

optimization_tool
Read-onlyIdempotent

Finds an optimal travel-time route through 2–12 coordinates by solving the Traveling Salesman Problem, with start, end, and roundtrip options.

Instructions

Find the optimal (shortest by travel time) route through a set of 2-12 coordinates. Solves the Traveling Salesman Problem to determine the best visiting order. Supports options for starting point, ending point, and whether to return to start.

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": "optimization_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
stepsNoWhether to include turn-by-turn instructions
sourceNoLocation to start the trip. IMPORTANT: If you set roundtrip=false you MUST set source="first" (and destination="last"). The Mapbox V1 API rejects roundtrip=false with source="any". "any" allows the optimizer to pick any coordinate as the start (only valid when roundtrip=true).any
profileNoRouting profile to use for optimizationmapbox/driving
languageNoLanguage for instructions (if steps=true). ISO 639-1 code (e.g., "en", "es").
overviewNoDetail level of route geometrysimplified
roundtripNoWhether to return to the starting point. Default true returns a closed loop through the coordinates. Set false for one-way trips — REQUIRES source="first" AND destination="last" together. Passing roundtrip=false without both endpoint constraints will fail.
geometriesNoFormat for route geometrygeojson
annotationsNoAdditional metadata to include for each route segment
coordinatesYesArray of {longitude, latitude} coordinate pairs to optimize a route through. The V1 API supports 2-12 coordinates and returns the optimal visiting order.
destinationNoLocation to end the trip. IMPORTANT: If you set roundtrip=false you MUST set destination="last" (and source="first"). The Mapbox V1 API rejects roundtrip=false with destination="any". "any" allows the optimizer to pick any coordinate as the end (only valid when roundtrip=true).any

Output Schema

NameRequiredDescriptionDefault
codeYesStatus code (e.g., "Ok" for success, error code otherwise)
tripsYesArray containing the optimized trip (typically 1 trip for all waypoints)
messageNoError message if code is not "Ok"
waypointsYesInput coordinates snapped to the road network in optimized order
mapboxRenderNoMap-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.18.1
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedInput schema / properties / destination / description
      Previous value: -"Location to end the trip. \"any\" allows any coordinate, \"last\" forces the last coordinate as end."New value: +"Location to end the trip. IMPORTANT: If you set roundtrip=false you MUST set destination=\"last\" (and source=\"first\"). The Mapbox V1 API rejects roundtrip=false with destination=\"any\". \"any\" allows the optimizer to pick any coordinate as the end (only valid when roundtrip=true)."
    • changedInput schema / properties / roundtrip / description
      Previous value: -"Whether to return to the starting point. Set to false for one-way trips."New value: +"Whether to return to the starting point. Default true returns a closed loop through the coordinates. Set false for one-way trips — REQUIRES source=\"first\" AND destination=\"last\" together. Passing roundtrip=false without both endpoint constraints will fail."
    • changedInput schema / properties / source / description
      Previous value: -"Location to start the trip. \"any\" allows any coordinate, \"first\" forces the first coordinate as start."New value: +"Location to start the trip. IMPORTANT: If you set roundtrip=false you MUST set source=\"first\" (and destination=\"last\"). The Mapbox V1 API rejects roundtrip=false with source=\"any\". \"any\" allows the optimizer to pick any coordinate as the start (only valid when roundtrip=true)."
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / properties / mapboxRender
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Map-payload reference for `render_map_tool`. Surfaced so the LLM can chain the next call without re-emitting geometry.",
      +  "properties": {
      +    "ref": {
      +      "description": "Server-side payload reference. Pass to `render_map_tool` via `payload_refs: [\"<this ref>\"]` to display the data on a live Mapbox GL JS map, or, in ChatGPT Desktop, to the `redraw_map` tool of the open Mapbox map.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "ref"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / waypoints / items / properties / location / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / waypoints / items / properties / location / maxItems
      Added value: +2
    • addedOutput schema / properties / waypoints / items / properties / location / minItems
      Added value: +2
    • addedOutput schema / properties / waypoints / items / properties / location / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
  2. First observedv0.12.6

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context by stating the optimization objective and coordinate range, but it does not mention response behavior, performance limits, or failure modes beyond what the schema already documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three focused sentences with the core purpose front-loaded. Each sentence adds relevant context: the optimization objective, the TSP framing, and the supported trip-shape options.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 10-parameter optimization tool, the description is reasonably complete because the rich input schema and output schema carry the detailed contract. It could be stronger if it briefly highlighted the one-way trip constraint or when to choose this over other routing tools, but no critical invocation information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter semantics are already well covered by the input schema, including the important roundtrip/source/destination constraints. The description only broadly mentions start, end, and return options and adds no parameter detail beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: finding the optimal route through 2-12 coordinates, explicitly framed as a Traveling Salesman Problem optimization. This distinguishes it from a plain directions or routing tool by emphasizing optimized visiting order rather than just path retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies the use case clearly enough: optimizing a multi-stop route over a small coordinate set. However, it does not explicitly say when to prefer this over siblings such as directions_tool or matrix_tool, nor does it state exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.