Skip to main content
Glama
Mapbox MCP Server

Mapbox MCP Server

Official
by mapbox

Reverse Geocode Tool

reverse_geocode_tool
Read-onlyIdempotent

Convert longitude and latitude coordinates into a human-readable address or place name for location display and labeling. Use it when you need only an address or place name from a point.

Instructions

Convert geographic coordinates (longitude, latitude) into a human-readable address or place name. Use only when you need an address/place name alone. If you also need nearby places, neighborhood context, or travel-time reachability, use ground_location_tool instead — it already includes reverse geocoding plus POI search and isochrone in one call. This tool cannot reverse geocode businesses, landmarks, or POIs. Supports JSON and text output formats.

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

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of results (1-5). Use 1 for best results. If you need more than 1 result, you must specify exactly one type in the types parameter.
typesNoArray of feature types to filter results
formatNoOutput format: "json_string" returns raw GeoJSON data as a JSON string that can be parsed; "formatted_text" returns human-readable text with place names, addresses, and coordinates. Both return as text content but json_string contains parseable JSON data while formatted_text is for display.formatted_text
countryNoArray of ISO 3166 alpha 2 country codes to limit results
languageNoIETF language tag for the response (e.g., "en", "es", "fr", "de", "ja")
latitudeYesLatitude coordinate to reverse geocode
longitudeYesLongitude coordinate to reverse geocode
permanentNoWhether results can be stored permanently
worldviewNoReturns features from a specific regional perspectiveus

Output Schema

NameRequiredDescriptionDefault
typeYes
featuresYes
attributionYes

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"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / properties / features / items / properties / geometry / properties / coordinates / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / maxItems
      Added value: +2
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / minItems
      Added value: +2
    • addedOutput schema / properties / features / items / properties / geometry / properties / coordinates / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedOutput schema / properties / features / items / properties / properties / properties / bbox / items
      Previous value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "number"
      -  }
      -]New value: +false
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / maxItems
      Added value: +4
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / minItems
      Added value: +4
    • addedOutput schema / properties / features / items / properties / properties / properties / bbox / prefixItems
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
  2. First observedv0.12.6

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description only needs to add operational context. It does so by declaring the POI/landmark exclusion and the two output formats, which tells the agent what results will and will not contain. It stops short of noting rate limits, result accuracy, or how ambiguities at borders are resolved.

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?

Four short sentences, front-loaded with the core action, then the exclusion, then the sibling alternative, then the format note. Every sentence carries routing or scope information; nothing is filler.

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 9 parameters, a 100%-covered schema, an output schema, and rich annotations, the description covers the decisions an agent must make (when to use, when to defer, what it cannot return). It does not explain result cardinality or behavior when limit>1 with multiple types, though the schema handles that constraint itself.

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%, with the schema itself documenting limit's coupling to types, the format enum semantics, country codes, language, and worldview. The description only restates "Supports JSON and text output formats", adding no meaning beyond the format parameter's own description, so the baseline 3 applies.

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 verb and resource (convert coordinates into an address or place name) and immediately bounds scope: it cannot reverse geocode businesses, landmarks, or POIs. That negative scope is what lets an agent distinguish it from ground_location_tool without opening either 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?

Explicit when-to-use ("Use only when you need an address/place name alone") and an explicit alternative with the condition that selects it (nearby places, neighborhood context, or travel-time reachability → ground_location_tool, which bundles geocoding plus POI search and isochrone). Nothing is left to inference.

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