Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Isochrone Tool

isochrone_tool
Read-onlyIdempotent

Computes reachable areas within a specified travel time from a location and returns them as GeoJSON polygon or line contours for map display, helping compare travel ranges by mode.

Instructions

Computes areas that are reachable within a specified amount of time from a location, and returns the reachable regions as contours of Polygons or LineStrings in GeoJSON format that you can display on a map. Common use cases: - Show a user how far they can travel in X minutes from their current location - Determine whether a destination is within a certain travel time threshold - Compare travel ranges for different modes of transportation'

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>",
      "generalize": "<generalize>"
    },
    "name": "isochrone_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
denoiseNoA floating point value that can be used to remove smaller contours. A value of 1.0 will only return the largest contour for a given value.
excludeNoExclude certain road types and custom locations from routing.
profileNoMode of travel.mapbox/driving-traffic
polygonsNoWhether to return Polygons (true) or LineStrings (false).
depart_atNoAn ISO 8601 date-time string representing the time to depart (format string: YYYY-MM-DDThh:mmss±hh:mm).
generalizeYesPositive number in meters that is used to simplify geometries. - Walking: use 0-500. Prefer 50-200 for short contours (minutes < 10 or meters < 5000), 300-500 as they grow. - Driving: use 1000-5000. Start at 2000, use 3000 if minutes > 10 or meters > 20000. Use 4000-5000 if near 60 minutes or 100000 meters.
coordinatesYesA coordinate object with longitude and latitude properties around which to center the isochrone lines. Longitude: -180 to 180, Latitude: -85.0511 to 85.0511
contours_colorsNoContour colors as hex strings without starting # (for example ff0000 for red. must match contours_minutes or contours_meters length if provided).
contours_metersNoDistances in meters. Distances must be in increasing order. Must be specified either contours_minutes or contours_meters.
contours_minutesNoContour times in minutes. Times must be in increasing order. Must be specified either contours_minutes or contours_meters.

Output Schema

NameRequiredDescriptionDefault
typeYes
featuresYes
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. Changed5 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"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +{}
    • changedOutput schema / properties / features / items / properties / geometry / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "coordinates": {
      -        "items": {
      -          "items": [
      -            {
      -              "type": "number"
      -            },
      -            {
      -              "type": "number"
      -            }
      -          ],
      -          "type": "array"
      -        },
      -        "type": "array"
      -      },
      -      "type": {
      -        "const": "LineString",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "coordinates"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "coordinates": {
      -        "items": {
      -          "items": {
      -            "items": [
      -              {
      -                "type": "number"
      -              },
      -              {
      -                "type": "number"
      -              }
      -            ],
      -            "type": "array"
      -          },
      -          "type": "array"
      -        },
      -        "type": "array"
      -      },
      -      "type": {
      -        "const": "Polygon",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "coordinates"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "coordinates": {
      +        "items": {
      +          "items": false,
      +          "maxItems": 2,
      +          "minItems": 2,
      +          "prefixItems": [
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "number"
      +            }
      +          ],
      +          "type": "array"
      +        },
      +        "type": "array"
      +      },
      +      "type": {
      +        "const": "LineString",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type",
      +      "coordinates"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "coordinates": {
      +        "items": {
      +          "items": {
      +            "items": false,
      +            "maxItems": 2,
      +            "minItems": 2,
      +            "prefixItems": [
      +              {
      +                "type": "number"
      +              },
      +              {
      +                "type": "number"
      +              }
      +            ],
      +            "type": "array"
      +          },
      +          "type": "array"
      +        },
      +        "type": "array"
      +      },
      +      "type": {
      +        "const": "Polygon",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "type",
      +      "coordinates"
      +    ],
      +    "type": "object"
      +  }
      +]
    • 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"
      +}
  2. First observedv0.12.6

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are map-displayable GeoJSON contours, but omits operational constraints an agent would want: the four-contour ceiling, that exactly one of minutes/meters must be supplied, and that depart_at combined with driving-traffic changes results.

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

Conciseness4/5

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

The core definition is a single well-formed sentence with the return format front-loaded, followed by a tight bulleted use-case list. The bullets repeat ideas already implied by the opening sentence (time-based travel), so they add moderate rather than essential value.

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?

With an output schema present and 100% schema coverage, the description need not explain return values or parameters, and it correctly focuses on purpose and scenarios. The remaining gap is the missing mention that contours are mutually exclusive and capped at four, a rule an agent must know to call it successfully even though the schema does encode it.

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% and the parameter docs are unusually thorough (generalize heuristics, denoise semantics, enum values), so the schema carries the parameter burden. The description adds nothing parameter-specific beyond the implied 'time' and 'Polygons' concepts, which is the expected baseline when the schema is this complete.

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?

Names a specific verb and resource ('computes areas that are reachable within a specified amount of time from a location') and states the concrete return shape (Polygons/LineStrings as GeoJSON). The three use cases make it unmistakable against routing siblings like directions_tool or matrix_tool, which return routes or travel times rather than reachable regions.

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

Usage Guidelines4/5

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

The 'Common use cases' block gives clear situational context (travel range display, threshold checks, mode comparison), which is genuine when-to-use guidance. It stops short of naming alternatives or exclusions, and it frames the tool only in terms of time even though the schema also supports distance-based contours (contours_meters).

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