Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Ground Location Tool

ground_location_tool
Read-onlyIdempotent

Find nearby places, neighborhood context, and travel-time reachability for a coordinate; add land, water, elevation, or traffic details as needed.

Instructions

Answer questions about what is near a location, what neighborhood a coordinate is in, or what places are within walking/driving distance. Use this when given coordinates and asked about nearby places, neighborhood context, local discovery, or area summaries. It already includes reverse geocoding, so a separate reverse_geocode_tool call is not needed for the same coordinate. Pass the place category (e.g. "restaurant", "coffee", "park") as the query parameter to get nearby POIs in the same call. Returns place name, nearby POIs matching the query, and travel-time reachability — all sourced from live Mapbox data with citations. Use include for what the spot itself is: land use (is it in a park, a national park, a building?), water (on it, or how near), elevation, and live traffic on the roads around it. So use it for "is this spot in a park?", "is this on the water?" or "how bad is traffic at this address?" too. For elevation along a path or route, use elevation_tool.

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": {
      "longitude": "<longitude>",
      "latitude": "<latitude>"
    },
    "name": "ground_location_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of nearby POIs to return (1-25)
queryNoOptional category or type of places to search for nearby (e.g., "restaurant", "coffee", "park"). If omitted, returns general place context only.
includeNoWhat to report about the spot itself, each one extra request: "land" for land use (park, cemetery, school, residential...), a national park or other protected area, and the building it is in; "water" for whether it is on water and how far the nearest water is; "elevation" for height above sea level; "traffic" for live congestion on the roads around it. Pick what the question needs, e.g. ["traffic"] for "how bad is traffic at this address?". Leave out when the question is only about the area or nearby places.
profileNoTravel profile for isochrone calculation. Use "mapbox/driving-traffic" for traffic-aware driving. Defaults to "mapbox/walking".mapbox/walking
languageNoIETF language tag for the response (e.g., "en", "es", "fr", "de", "ja")
latitudeYesLatitude of the location to ground responses around
longitudeYesLongitude of the location to ground responses around
contours_minutesNoTravel-time thresholds in minutes for the isochrone. Max 4 values, each between 1-60.

Output Schema

NameRequiredDescriptionDefault
landNoWhat the ground is at the point, from Mapbox Streets (include: land)
placeYesHuman-readable place name from reverse geocoding
waterNoOn water, or distance to the nearest water (include: water)
trafficNoLive traffic on nearby roads, from Mapbox Traffic (include: traffic)
latitudeYes
citationsYesMapbox APIs used to produce this grounded response
isochroneNoTravel-time reachability summary
longitudeYes
elevation_mNoGround elevation above sea level, from Mapbox Terrain-DEM (include: elevation)
nearby_poisNoNearby points of interest matching the query
full_addressNoFull address if available
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. Changed11 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"
    • addedInput schema / properties / include
      Added value: +{
      +  "description": "What to report about the spot itself, each one extra request: \"land\" for land use (park, cemetery, school, residential...), a national park or other protected area, and the building it is in; \"water\" for whether it is on water and how far the nearest water is; \"elevation\" for height above sea level; \"traffic\" for live congestion on the roads around it. Pick what the question needs, e.g. [\"traffic\"] for \"how bad is traffic at this address?\". Leave out when the question is only about the area or nearby places.",
      +  "items": {
      +    "enum": [
      +      "land",
      +      "water",
      +      "elevation",
      +      "traffic"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • 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: +{}
    • addedOutput schema / properties / elevation_m
      Added value: +{
      +  "description": "Ground elevation above sea level, from Mapbox Terrain-DEM (include: elevation)",
      +  "type": "number"
      +}
    • addedOutput schema / properties / land
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "What the ground is at the point, from Mapbox Streets (include: land)",
      +  "properties": {
      +    "building": {
      +      "additionalProperties": false,
      +      "description": "The building the point is inside, if any",
      +      "properties": {
      +        "height_m": {
      +          "type": "number"
      +        },
      +        "type": {
      +          "type": "string"
      +        },
      +        "underground": {
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "land_use": {
      +      "description": "Land use polygons the point is inside, e.g. park, cemetery, school, hospital, residential, commercial_area, wood, grass, wetland. Empty when none is mapped there.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "class": {
      +            "type": "string"
      +          },
      +          "type": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "class"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "protected_areas": {
      +      "description": "Protected areas the point is inside, e.g. a national_park",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "class": {
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "class"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "land_use"
      +  ],
      +  "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"
      +}
    • addedOutput schema / properties / nearby_pois / items / properties / external_ids
      Added value: +{
      +  "additionalProperties": {
      +    "type": "string"
      +  },
      +  "description": "Upstream supplier ids for this place, keyed by supplier (e.g. dataplor, tripadvisor). Use to attribute where the record came from.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / nearby_pois / items / properties / mapbox_id
      Added value: +{
      +  "description": "Mapbox id for this place. Pass it to place_details_tool to retrieve ratings, popularity, opening hours, and phone number.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / traffic
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Live traffic on nearby roads, from Mapbox Traffic (include: traffic)",
      +  "properties": {
      +    "radius_m": {
      +      "description": "How far around the point roads were read",
      +      "type": "number"
      +    },
      +    "roads": {
      +      "description": "One entry per road class, at its worst level, nearest first. Empty means no live traffic data nearby (common on quiet streets), not no traffic.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "class": {
      +            "description": "Road class, e.g. motorway, primary, secondary, street",
      +            "type": "string"
      +          },
      +          "congestion": {
      +            "description": "Live congestion: low, moderate, heavy or severe",
      +            "type": "string"
      +          },
      +          "distance_m": {
      +            "description": "Distance to the nearest segment at that level",
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "class",
      +          "congestion",
      +          "distance_m"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "worst": {
      +      "description": "Worst congestion on any of those roads",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "radius_m",
      +    "roads"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / water
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "On water, or distance to the nearest water (include: water)",
      +  "properties": {
      +    "nearest_water_m": {
      +      "description": "Distance to the nearest water within 500 m, when not on water. Absent with on_water false: no water within 500 m.",
      +      "type": "number"
      +    },
      +    "on_water": {
      +      "description": "Whether the point is on a lake, river or sea",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "on_water"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.12.6

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, open-world behavior, and the description adds real context on top: results are sourced from live Mapbox data with citations, reverse geocoding is bundled, and each `include` item is an extra request, which signals cost. It stops short of describing output shape or rate/limit behavior, but with rich annotations and an output schema that is a minor gap.

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?

Front-loaded with the core purpose and alternatives before the `include` detail, and every sentence carries usable routing or parameter information. It is on the long side and circles back to 'so use it for ... too', which is mildly repetitive but not wasteful enough to hurt selection.

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

Completeness5/5

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

For an 8-parameter open-world lookup tool with full schema coverage, rich annotations, and an output schema, the description covers selection, alternatives, query-to-result behavior, and the cost of `include` options. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond it by explaining the interaction between `query` and the returned nearby POIs in the same call, and by framing `include` as question-driven ('pick what the question needs', with a concrete example). `profile` and `contours_minutes` are left to the schema, which already documents them well.

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?

States a specific capability set (nearby POIs, neighborhood context, travel-time reachability, plus optional land/water/elevation/traffic at the point) and names the exact questions it answers. It also explicitly separates itself from reverse_geocode_tool and elevation_tool, so an agent can select it without opening a schema.

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

Usage Guidelines5/5

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

Gives an explicit trigger (given coordinates and asked about nearby places, neighborhood, local discovery, area summaries) and explicit exclusions: no separate reverse_geocode_tool call for the same coordinate, and elevation along a path or route belongs to elevation_tool. It even maps specific phrasings ('is this spot in a park?', 'how bad is traffic at this address?') to the tool.

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