Skip to main content
Glama

Geocode a place name

geocode
Read-onlyIdempotent

Free-text place name -> ranked candidate locations, from Overture divisions and places.

Instructions

Free-text place name -> ranked candidate locations, from Overture divisions and places.

No Nominatim, no third-party geocoding API. Matches localities,
neighborhoods, regions, and countries by name (exact > prefix >
substring), falling back to named places if that doesn't fill `limit`.
Returns {"results": [{name, type, lat, lon, id (GERS), admin_context,
rank_score}, ...]}, budgeted like every other tool. Returns a structured
{"error": ...} instead of raising if the remote scan fails.

A trailing "City, ST"/"City, Region" suffix has resolved against a US
state or another region since #46; a trailing "City, Country" suffix
resolves the same way (#457) — "Cambridge, UK", "Cambridge, GB",
"Cambridge, GBR" and "Cambridge, United Kingdom" all constrain the
search to the UK's Cambridge, excluding any same-named division
elsewhere. `country` (ISO 3166-1 alpha-2, also accepting alpha-3 and
aliases like "UK"/"USA", case-insensitive) is the explicit form of the
same constraint, for a caller that already knows the country instead
of writing it into `query`. An unrecognized `country`, or one that
disagrees with a country/region suffix parsed off `query` itself,
returns {"error": "bad_request", ...} naming both. A comma-suffix that
names neither a region nor a country still searches the name half
alone rather than returning nothing, with a "note" naming the
unrecognized qualifier; a recognized country/region that matches
nothing degrades the same way, with a "note".

A query with no location context in it at all (a bare place name that
matches no division, e.g. "Blue Bottle Roastery") can't be bounded to a
region, so the places half of the search is skipped rather than
scanning the global places dataset — minutes, not seconds (#105). That
case comes back empty with a "note" saying so and what to do instead.

A misspelled name that matches no division literally ("Berekley", or
"Berekley, CA" — the region suffix is set aside first) gets one
close-spelling retry over the local divisions table (#215); those
results rank below any literal match, carry "matched_by": "fuzzy", and
come with a "note" naming the spelling they were corrected to.

A query that is entirely a postcode ("94110", "1011AB") is answered as
one (#223): one result per country whose address points carry that code,
with "type": "postcode", "country", "address_count" and a null "id" (a
postcode is not a GERS entity). Codes are shared across countries far
more often than not, so the alternates below the top row are real
ambiguity. The accompanying "note" carries the granularity caveat (a
Dutch code is a street block, a US ZIP a district) and the coverage
limits -- including the countries the addresses theme covers but that
carry no postcode values at all, which is why a valid postcode can still
come back empty.

Exonyms work too (#214): names are matched against Overture's ~100
localized alternates as well as its canonical one, so "Munich" answers
München and "Tokyo" answers 東京都. `name` is always the canonical
spelling; such rows carry an extra "matched_name" naming the alternate
that matched.

lang (#410) requests Overture's language-tagged name variant instead
of a division row's primary name, when the data has one for that row
and language: `name` becomes the variant and `name_primary` is added
only when it differs. Default: the stored `preferences()` lang, else
the primary name unchanged. Never invented or transliterated — only a
variant actually present in Overture's data is ever returned.
`PLACEROOT_HOME=<city/area>` (#406) sets a home region once at startup;
a bounded score bonus then nudges same-tier ambiguous namesakes (the
"which Springfield" case) toward it — a bias, never a filter, so a
distant result stays in the answer, just not first. Only when the bias
actually changed the top result does a "note" say so, e.g. "ranked
toward your configured home region (Seattle); pass a city/near hint to
override". No home configured -> no bias, no note, behavior unchanged.

Input Schema

NameRequiredDescriptionDefault
langNoResult-language code (2-3 lowercase letters, e.g. "de"). Overture-tagged name variants only — never transliterated or invented. Default: stored preference, else the primary name.
limitNo
queryYes
countryNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.11.0
    • addedInput schema / properties / country
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Country"
      +}
  2. First observedv0.10.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds extensive behavioral detail: return shape, error handling, fallback logic, note semantics, postcode handling, exonym matching, language variants, and home-region bias. This goes far beyond what the annotations convey.

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

Conciseness3/5

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

The description is very long and includes several parenthetical issue references (e.g., #46, #457) that are noise for an AI agent. While front-loaded with core purpose and return format, the extensive edge-case detail could be trimmed without losing essential invocation guidance.

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?

Given the tool's complexity and the presence of an output schema, the description is thorough: it covers ranking, fallbacks, errors, suffixes, postcodes, exonyms, lang, and home bias. An agent has enough to invoke it correctly across a wide range of inputs.

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 description coverage is only 25% (only lang is described), but the description amply compensates by explaining country (ISO 3166-1 alpha-2/3, aliases, case-insensitivity, error behavior) and query (suffix parsing, fallback behavior) in detail. The limit parameter is only mentioned in passing, leaving a minor gap.

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 states a specific verb and resource ('geocode' a 'free-text place name') and clearly scopes it to 'ranked candidate locations, from Overture divisions and places.' It distinguishes itself from address geocoding by focusing on localities, neighborhoods, regions, and countries.

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

Usage Guidelines3/5

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

The description provides rich context about query formats and edge cases, but it never explicitly states when to choose this tool over siblings like geocode_address or geocode_batch. Usage is implied through the detailed behavior rather than through direct guidance or exclusions.

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