Skip to main content
Glama
atlasfetch-mcp

atlasfetch-mcp

Official

Geocode an address to a coordinate (South Africa)

geocode_address
Read-only

Convert a single delivery address into a point with its precision level, so you can tell whether to dispatch, ask for a landmark, or confirm with the customer.

Instructions

Turn ONE address into a point, with an honest account of how much of it was found. Built for deliveries. South Africa today; more countries as their data loads. 1 lookup per address, found or not.

Send either q (one line) or address (housenumber, street, suburb, city, postcode, unit) — never both. If the address is already split, send it split: it matches better.

READ precision BEFORE using the point. "address" means the house was found; "interpolated" means it was estimated between the numbers either side; "intersection" means a street corner ("Cnr Main Rd and Belmont Rd", "Bree & Strand Streets"), at the point where the two meet, with the second street in matched.crossStreet; "site" means a named site — a shopping centre, office park, complex or estate, hospital, school, airport or hotel — at a point inside it, named in matched.site; "street" means the right street but NOT the house; "locality" means only the suburb or town. NEVER present a street- or locality-level point as a door: a driver sent there will be at the wrong house. In South Africa most answers are street-level, because OpenStreetMap has house numbers on about 13% of street names — that is the data being honest, not a failure.

What to do with an answer — the result line says which applies:

  • address, interpolated, intersection or site, not ambiguous, confidence 0.5 or more: dispatch. For a site, pass on the unit or shop number from the original address ("Shop 12") — the answer does not include it, and the driver needs it.

  • street: ask the recipient for a pin or a landmark.

  • ambiguous, or locality: ask the customer before dispatching. When the advice is to ask the customer, ASK — do not pick one. result.alternatives holds up to 4 other candidates the answer was chosen from, and the result line lists them with the suburb each lies in and its distance and direction from the first, because they often share a street name AND a town (five "Long Street, Cape Town"s: City Centre, Observatory, Maitland…). Put the first answer and those to the user, by suburb. Free: still one lookup. matched.locality is the place the caller wrote; matched.suburb is the suburb the point actually lies in, absent at locality precision and where no suburb is near. confidence ranks answers; it is NOT a probability. ambiguous means a same-named street elsewhere scored about as well, or the street was a near-miss spelling with no house number to confirm it. result null means nothing trustworthy was found, and that still costs the lookup.

Some addresses name something that cannot be placed: an erf, stand, plot or farm portion (land parcels — there is no cadastre), a township stand, a PO box or private bag. Those parts come back in unmatched and the answer is the place named, at locality: ask the customer for a street address.

country is a hard filter; region (ZA-WC, or "Western Cape") only ranks streets inside it first, so a wrong province does not lose the address. An uncovered country is refused, unbilled, with the list of covered countries in the message — that message is the live coverage list; there is no other. sets and base answer "which delivery zone is it in" in the same call, at no extra cost.

One address per call, deliberately. For a delivery list, call this once per row so the user sees what is being spent; programs with thousands of rows should use the API’s POST /geocode/batch directly. Not for: searching for a business or landmark by name, or a coordinate to an address (that is lookup_location with the street layer).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "geocode_address"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoThe whole address on one line, e.g. "25 Adderley Street, Cape Town".
baseNoAdministrative layers to resolve at the found point.
setsNoBoundary sets on this account to match at the found point, e.g. delivery zones.
regionNoISO 3166-2 ("ZA-WC") or a name ("Western Cape"). A preference, not a filter.
addressNoThe address already split into parts. Needs at least a street. Use instead of q.
countryNoISO 3166-1 alpha-2, e.g. "ZA". A hard filter: only that country is searched.
streetGeometryNoThe matched street’s line, trimmed to about 250 m. Only if something will draw it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.1

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description carries the real behavioral load: billing (one lookup per address, found or not, null still billed), unbilled refusal for uncovered countries, country as a hard filter vs region as a preference, what confidence and ambiguous actually mean, and that sets/base are free in the same call. Far beyond what the annotations supply.

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 correctly with the one-address-per-call constraint and the precision warning, and nearly every paragraph carries operational information. It is nevertheless very long and repeats itself slightly ("1 lookup per address" vs "One address per call, deliberately", plus the multi-paragraph "Long Street, Cape Town" illustration), which costs it the top mark.

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?

No output schema exists, so the description must describe returns — and it does: precision values, matched.crossStreet, matched.site, matched.locality vs matched.suburb, result.alternatives with suburb/distance/direction, and result null. Combined with the precision-to-action mapping, an agent has everything needed to call this and interpret the response.

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

Parameters5/5

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

Schema coverage is already 100%, yet the description still adds non-obvious semantics: q vs address are mutually exclusive and pre-split input "matches better", country is a hard filter, region "only ranks streets inside it", and sets/base answer zone questions at no extra cost. It also explains that streetGeometry is trimmed and only worth requesting if something will draw it.

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?

Opens with a specific verb+resource+scope: "Turn ONE address into a point, with an honest account of how much of it was found. Built for deliveries. South Africa today." It also distinguishes itself from the reverse-geocoding sibling at the end ("a coordinate to an address — that is lookup_location"). An agent can tell what this does and what it does not without opening the 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 routing per precision level (dispatch / ask for a pin / ask the customer), explicit when-not (business or landmark name search, reverse geocoding, bulk rows which should use the API's batch endpoint), and explicit exclusivity between q and address. This is about as complete a routing guide as a tool description gets.

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