Skip to main content
Glama

Geocode a place name

geocode
Read-onlyIdempotent

Convert place names or addresses into coordinates (lat, lon) to disambiguate locations or get coordinates for a bounding box. Optionally bias results toward a nearby point.

Instructions

Turn a place name or address into coordinates (lat, lon), best match first. The station and route tools already accept place names, so call this only to pick between ambiguous places or to get coordinates for a bbox. Give lat and lon to prefer results near a point.

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": {
      "query": "<query>"
    },
    "name": "geocode"
  }
}

Input Schema

NameRequiredDescriptionDefault
latNoOptional latitude to prefer nearby results. Give with lon.
lonNoOptional longitude to prefer nearby results. Give with lat.
limitNoHow many matches to return, 1 to 10. Default 5.
queryYesCity, address or point of interest, e.g. "Puerta del Sol, Madrid". At most 200 characters.

Output Schema

NameRequiredDescriptionDefault
queryYes
resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.2.1
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / lat / description
      Previous value: -"Optional latitude for geographic biasing"New value: +"Optional latitude to prefer nearby results. Give with lon."
    • addedInput schema / properties / lat / maximum
      Added value: +90
    • addedInput schema / properties / lat / minimum
      Added value: +-90
    • addedInput schema / properties / limit
      Added value: +{
      +  "default": 5,
      +  "description": "How many matches to return, 1 to 10. Default 5.",
      +  "maximum": 10,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / lon / description
      Previous value: -"Optional longitude for geographic biasing"New value: +"Optional longitude to prefer nearby results. Give with lat."
    • addedInput schema / properties / lon / maximum
      Added value: +180
    • addedInput schema / properties / lon / minimum
      Added value: +-180
    • changedInput schema / properties / query / description
      Previous value: -"Search query (e.g. city name, address, POI)"New value: +"City, address or point of interest, e.g. \"Puerta del Sol, Madrid\". At most 200 characters."
    • addedInput schema / properties / query / maxLength
      Added value: +200
    • addedInput schema / properties / query / minLength
      Added value: +1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "query": {
      +      "type": "string"
      +    },
      +    "results": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "city": {
      +            "type": "string"
      +          },
      +          "country": {
      +            "type": "string"
      +          },
      +          "lat": {
      +            "type": "number"
      +          },
      +          "lon": {
      +            "type": "number"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "state": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "name",
      +          "lat",
      +          "lon"
      +        ],
      +        "type": "object"
      +      },
      +      "type": [
      +        "null",
      +        "array"
      +      ]
      +    }
      +  },
      +  "required": [
      +    "query",
      +    "results"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds valuable behavioral context — results are ranked best-match-first and lat/lon biases ranking toward a point — but says nothing about result limits, error behavior, or no-match outcomes.

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?

Three compact sentences, front-loaded with the core transformation, then the routing guidance, then the optional refinement. Every sentence carries distinct information with no repetition of the schema.

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 a read-only lookup with an output schema, full schema coverage, and rich annotations, the description is complete enough to call correctly: what it returns, how to bias results, and when to prefer siblings are all covered.

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 all four parameters are already documented in the schema, including the lat/lon pairing rule and the 1-10 limit. The description only echoes the proximity behavior, adding no syntax or format detail beyond the schema. 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 (place name/address → coordinates) plus the ordering rule ('best match first'). It also distinguishes itself from the station and route siblings by noting they accept place names directly, so an agent can tell when this tool is not needed.

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?

Explicitly gives both when-not ('the station and route tools already accept place names') and when-to ('pick between ambiguous places or get coordinates for a bbox'). The lat/lon proximity hint adds a second invocation context. 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.