Skip to main content
Glama

reverse_geocode

Read-onlyIdempotent

Converts a coordinate pair into the nearest addresses, streets, venues, or administrative places, ordered by proximity. Use when starting from GPS or a map position; for text-to-coordinates use geocode, and for a point's road-network context (name, class, speed limit, legality) use locate instead. Read-only and cached. Near the poles (|lat| >= 85 degrees) the index is too sparse for a real nearest match, so this returns no results rather than a distant wrong guess. Returns up to size candidates (default 5, max 40); layers restricts the type returned (address, street, venue, neighbourhood, locality, county, region, country, postalcode, and more). Each result carries a confidence score, layer, label, and coordinates, same shape as geocode.

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": {
      "lat": "<lat>",
      "lon": "<lon>"
    },
    "name": "reverse_geocode"
  }
}

Input Schema

NameRequiredDescriptionDefault
latYesLatitude
lonYesLongitude
sizeNoNumber of nearby candidates (default 5, max 40)
layersNoRestrict to a comma list of: address, street, venue, neighbourhood, borough, locality, localadmin, county, macrocounty, region, macroregion, dependency, country, continent, postalcode, coarse. Admin layers resolve from the nearest indexed feature's parent hierarchy.

Output Schema

NameRequiredDescriptionDefault
itemsNo
geojsonNo
metricsNo
summaryNoMap of scalar facts the LLM should surface verbatim
precisionNo
display_hintNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed19 schema fields changed
    • changedOutput schema / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / display_hint / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / geojson / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / geojson / properties / features / items / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / geojson / properties / features / items / properties / geometry / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": true,
      -    "properties": {
      -      "coordinates": {},
      -      "geometries": {
      -        "items": {},
      -        "type": "array"
      -      },
      -      "type": {
      -        "anyOf": [
      -          {
      -            "enum": [
      -              "Point",
      -              "LineString",
      -              "Polygon",
      -              "MultiPoint",
      -              "MultiLineString",
      -              "MultiPolygon",
      -              "GeometryCollection"
      -            ],
      -            "type": "string"
      -          },
      -          {
      -            "type": "string"
      -          }
      -        ]
      -      }
      -    },
      -    "required": [
      -      "type"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": {},
      +    "properties": {
      +      "coordinates": {},
      +      "geometries": {
      +        "items": {},
      +        "type": "array"
      +      },
      +      "type": {
      +        "anyOf": [
      +          {
      +            "enum": [
      +              "Point",
      +              "LineString",
      +              "Polygon",
      +              "MultiPoint",
      +              "MultiLineString",
      +              "MultiPolygon",
      +              "GeometryCollection"
      +            ],
      +            "type": "string"
      +          },
      +          {
      +            "type": "string"
      +          }
      +        ]
      +      }
      +    },
      +    "required": [
      +      "type"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / geojson / properties / features / items / properties / properties / propertyNames
      Added value: +{
      +  "type": "string"
      +}
    • changedOutput schema / properties / items / items / additionalProperties
      Previous value: -trueNew value: +{}
    • removedOutput schema / properties / items / items / properties / address_evidence / properties / locality / $ref
      Removed value: -"#/properties/items/items/properties/address_evidence/properties/house_number"
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / locality / enum
      Added value: +[
      +  "matched",
      +  "partial",
      +  "absent"
      +]
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / locality / type
      Added value: +"string"
    • removedOutput schema / properties / items / items / properties / address_evidence / properties / region / $ref
      Removed value: -"#/properties/items/items/properties/address_evidence/properties/house_number"
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / region / enum
      Added value: +[
      +  "matched",
      +  "partial",
      +  "absent"
      +]
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / region / type
      Added value: +"string"
    • removedOutput schema / properties / items / items / properties / address_evidence / properties / street / $ref
      Removed value: -"#/properties/items/items/properties/address_evidence/properties/house_number"
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / street / enum
      Added value: +[
      +  "matched",
      +  "partial",
      +  "absent"
      +]
    • addedOutput schema / properties / items / items / properties / address_evidence / properties / street / type
      Added value: +"string"
    • changedOutput schema / properties / precision / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / precision / properties / learning_overlay / additionalProperties
      Previous value: -trueNew value: +{}
    • addedOutput schema / properties / summary / propertyNames
      Added value: +{
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / size / description
      Previous value: -"Number of nearby candidates (default 3, max 40)"New value: +"Number of nearby candidates (default 5, max 40)"
  3. Changed1 schema field changed
    • changedOutput schema / properties / items / items / properties / postal_code / description
      Previous value: -"An eligible US ZIP5 normalized from the selected native result's available postal-code field; direct address-record origin is not yet guaranteed. Not checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."New value: +"An eligible US ZIP5 read from the selected result's own postal-code field. While origin enforcement is active this field is emitted ONLY when the engine stamped the value as coming from the address record itself (`source_record` provenance); a value inherited from a parent area, or a result cached before that evidence existed, is omitted rather than emitted without provenance — so an absent ZIP under enforcement means \"not proven for this record\", not \"no such ZIP\". Provenance describes only WHERE the value came from. It is not a postal operator check of any kind — no certification, no address-quality rating, and no statement about whether mail would arrive — so a syntactically correct, correctly-sourced value can still be wrong for the address. Also omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."
  4. Changed2 schema fields changed
    • addedOutput schema / properties / items / items / properties / address_components / properties / region_name
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / postal_input_match
      Added value: +{
      +  "description": "STRUCTURED GEOCODING ONLY (`geocode_structured` / `POST /v1/search/structured`); absent from free-text geocoding. Whether the postcode YOU SUBMITTED agrees with this candidate's own postcode — `match` (same five-digit value), `conflict` (they differ), `unavailable` (no comparison was possible). This compares two values already in hand: no lookup, no external reference, and your query text is never parsed to find one. `conflict` does NOT say which side is wrong — your input may name a neighbouring area, the candidate may be a near-miss, or the record's own value may be stale; treat it as a prompt to ask a human, never as a correction to apply automatically. The candidate side counts only when its postcode came from the address record itself; one inherited from a parent area yields `unavailable` rather than a misleading verdict. `unavailable` also covers: nothing submitted, a submitted value not readable as a US five-digit code, and results cached before this field existed.",
      +  "enum": [
      +    "match",
      +    "conflict",
      +    "unavailable"
      +  ],
      +  "type": "string"
      +}
  5. Changed5 schema fields changed
    • addedOutput schema / properties / items / items / properties / address_components
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "The same US components the formatted string is built from. Every field is source-established or absent; nothing is inferred or back-filled.",
      +  "properties": {
      +    "country_code": {
      +      "type": "string"
      +    },
      +    "house_number": {
      +      "type": "string"
      +    },
      +    "locality": {
      +      "type": "string"
      +    },
      +    "postal_code": {
      +      "type": "string"
      +    },
      +    "region_code": {
      +      "type": "string"
      +    },
      +    "street": {
      +      "type": "string"
      +    },
      +    "unit": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / items / items / properties / address_line1
      Added value: +{
      +  "description": "House number and street for an eligible US address result, composed from the result's own components — never parsed from the display label. Absent when the result is not a US street address.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / address_line2
      Added value: +{
      +  "description": "Unit or suite, only when the source record carries one. A unit supplied in your request is never echoed back here.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / formatted_address
      Added value: +{
      +  "description": "Single-line US display form, e.g. `1600 Pennsylvania Avenue NW, Washington, DC 20500, USA`. The postal segment is present only when an eligible ZIP is; its absence never suppresses the street address.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / items / items / properties / postal_code / description
      Previous value: -"Five-digit ZIP taken from the postcode supplied with this address record. It is reported by that record's own data source and has not been checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."New value: +"An eligible US ZIP5 normalized from the selected native result's available postal-code field; direct address-record origin is not yet guaranteed. Not checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied."
  6. Changed1 schema field changed
    • addedOutput schema / properties / items / items / properties / postal_code
      Added value: +{
      +  "description": "Five-digit ZIP taken from the postcode supplied with this address record. It is reported by that record's own data source and has not been checked against any postal operator's records, so a syntactically correct value can still be wrong for the address. Omitted when unavailable or unsuitable for five-digit form. US address results only. Distinct from `address_evidence.postal_code`, which is a presence STATUS rather than a value. On reverse geocoding this describes the RETURNED ADDRESS — it is not a postal assignment to the coordinate you supplied.",
      +  "pattern": "^[0-9]{5}$",
      +  "type": "string"
      +}
  7. Changed2 schema fields changed
    • addedOutput schema / properties / items / items / properties / address_evidence
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "What THIS CANDIDATE carries, component by component — `matched` (a real value is present), `partial` (only a coarser or derived stand-in, e.g. an interpolated house number or a locality falling back to its administrative parent), `absent` (nothing). This describes the result, NOT a comparison against your query: the engine returns no per-component match data, and re-parsing your text here would mean two parsers disagreeing about the same string. Derived from the feature, never from `confidence`.",
      +  "properties": {
      +    "house_number": {
      +      "enum": [
      +        "matched",
      +        "partial",
      +        "absent"
      +      ],
      +      "type": "string"
      +    },
      +    "locality": {
      +      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
      +    },
      +    "postal_code": {
      +      "description": "Whether the candidate carries a postal code. Presence only — this states what the result has, and makes no claim about its correctness.",
      +      "enum": [
      +        "matched",
      +        "partial",
      +        "absent"
      +      ],
      +      "type": "string"
      +    },
      +    "region": {
      +      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
      +    },
      +    "street": {
      +      "$ref": "#/properties/items/items/properties/address_evidence/properties/house_number"
      +    }
      +  },
      +  "required": [
      +    "house_number",
      +    "street",
      +    "locality",
      +    "region",
      +    "postal_code"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / items / items / properties / confidence_scope
      Added value: +{
      +  "const": "query_to_candidate",
      +  "description": "What `confidence` is scoped to. `query_to_candidate` means it scores how well this candidate matches the submitted query — it is NOT a probability that the place is real, that the address is correct, or that mail would arrive. Fixed value today; treat it as a closed set that may gain members.",
      +  "type": "string"
      +}
  8. Changed1 schema field changed
    • changedInput schema / properties / layers / description
      Previous value: -"Restrict to: address, street, venue, locality"New value: +"Restrict to a comma list of: address, street, venue, neighbourhood, borough, locality, localadmin, county, macrocounty, region, macroregion, dependency, country, continent, postalcode, coarse. Admin layers resolve from the nearest indexed feature's parent hierarchy."
  9. Changed18 schema fields changed
    • addedInput schema / properties / lat / maximum
      Added value: +90
    • addedInput schema / properties / lat / minimum
      Added value: +-90
    • addedInput schema / properties / layers / maxLength
      Added value: +200
    • addedInput schema / properties / lon / maximum
      Added value: +180
    • addedInput schema / properties / lon / minimum
      Added value: +-180
    • changedInput schema / properties / size / description
      Previous value: -"Number of nearby candidates (default 3)"New value: +"Number of nearby candidates (default 3, max 40)"
    • addedInput schema / properties / size / maximum
      Added value: +40
    • addedInput schema / properties / size / minimum
      Added value: +1
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
    • addedOutput schema / properties / items / items / properties / cross_street_kind
      Added value: +{
      +  "enum": [
      +    "street",
      +    "route"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / cross_street_route
      Added value: +{
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / intersection_precision
      Added value: +{
      +  "enum": [
      +    "geometric_crossing",
      +    "tangent_intersection",
      +    "centroid_cluster",
      +    "approximate"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / intersection_type
      Added value: +{
      +  "enum": [
      +    "corner",
      +    "interchange"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / street_kind
      Added value: +{
      +  "enum": [
      +    "street",
      +    "route"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / street_route
      Added value: +{
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedOutput schema / properties / metrics
      Added value: +{}
    • addedOutput schema / properties / precision
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "class": {
      +      "type": "string"
      +    },
      +    "learning_overlay": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "actions": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "applied": {
      +          "type": "boolean"
      +        },
      +        "rule_ids": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "applied"
      +      ],
      +      "type": "object"
      +    },
      +    "required_context": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "risk_flags": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "class",
      +    "risk_flags",
      +    "required_context",
      +    "learning_overlay"
      +  ],
      +  "type": "object"
      +}
  10. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "display_hint": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "layout": {
      +          "anyOf": [
      +            {
      +              "enum": [
      +                "summary",
      +                "table",
      +                "summary+table",
      +                "map",
      +                "chart+table"
      +              ],
      +              "type": "string"
      +            },
      +            {
      +              "type": "string"
      +            }
      +          ]
      +        },
      +        "map_layers": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "preferred_charts": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "sections": {
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        }
      +      },
      +      "required": [
      +        "layout"
      +      ],
      +      "type": "object"
      +    },
      +    "geojson": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "features": {
      +          "items": {
      +            "additionalProperties": true,
      +            "properties": {
      +              "geometry": {
      +                "anyOf": [
      +                  {
      +                    "additionalProperties": true,
      +                    "properties": {
      +                      "coordinates": {},
      +                      "geometries": {
      +                        "items": {},
      +                        "type": "array"
      +                      },
      +                      "type": {
      +                        "anyOf": [
      +                          {
      +                            "enum": [
      +                              "Point",
      +                              "LineString",
      +                              "Polygon",
      +                              "MultiPoint",
      +                              "MultiLineString",
      +                              "MultiPolygon",
      +                              "GeometryCollection"
      +                            ],
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "string"
      +                          }
      +                        ]
      +                      }
      +                    },
      +                    "required": [
      +                      "type"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ]
      +              },
      +              "id": {
      +                "type": [
      +                  "string",
      +                  "number"
      +                ]
      +              },
      +              "properties": {
      +                "additionalProperties": {},
      +                "type": "object"
      +              },
      +              "type": {
      +                "const": "Feature",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "type",
      +              "geometry"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "type": {
      +          "const": "FeatureCollection",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "type",
      +        "features"
      +      ],
      +      "type": "object"
      +    },
      +    "items": {
      +      "items": {
      +        "additionalProperties": true,
      +        "properties": {
      +          "confidence": {
      +            "type": "number"
      +          },
      +          "label": {
      +            "type": "string"
      +          },
      +          "lat": {
      +            "type": "number"
      +          },
      +          "layer": {
      +            "type": "string"
      +          },
      +          "lon": {
      +            "type": "number"
      +          },
      +          "method": {
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "place_type": {
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "summary": {
      +      "additionalProperties": {},
      +      "description": "Map of scalar facts the LLM should surface verbatim",
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
  11. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  12. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses that results are cached and, importantly, that near the poles (|lat| >= 85) the index is too sparse and the tool returns no results rather than a distant wrong guess. That is a non-obvious failure mode an agent could not infer from structured fields, and it is exactly the kind of context the description should carry.

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 definition is front-loaded with the core action, then routing guidance, then behavioral caveats, then parameter notes. Every sentence contributes something an agent needs, and nothing is padded or repeated for its own sake.

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?

Although an output schema exists and return values need not be explained, the description still gives a useful shape hint (confidence score, layer, label, coordinates, matching geocode). Combined with the coverage of size, layers, caching, and the polar edge case, an agent has everything needed to call this correctly.

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 coverage is 100%, so both the size bounds (default 5, max 40) and the layers enumeration are already documented in the input schema, and the description largely restates them. It adds only marginal meaning, such as noting that admin layers resolve from the nearest indexed feature's parent hierarchy. Baseline 3 is appropriate when the schema does the heavy lifting.

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 opens with a specific verb and resource: it 'converts a coordinate pair into the nearest addresses, streets, venues, or administrative places, ordered by proximity.' It explicitly distinguishes itself from geocode (text-to-coordinates) and locate (road-network context), so an agent can select it without opening any 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?

It gives an explicit trigger ('Use when starting from GPS or a map position') and names both alternatives with the conditions that select them: geocode for text-to-coordinates and locate for road-network attributes. There is no ambiguity about when this tool is the right choice.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources