Skip to main content
Glama
atlasfetch-dev

atlasfetch-mcp

Official
by atlasfetch-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Look up the boundaries containing a coordinate

lookup_location
Read-only

Reverse geocode a latitude/longitude to country, region, municipality, ISO 3166 codes, optional nearest street, and account boundary sets for geofence checks.

Instructions

Reverse geocode a coordinate to the administrative areas that contain it — country, region (state or province) and municipality — as names plus ISO 3166 codes, optionally the nearest street, and matches from boundary sets the account has uploaded: all in one call.

Use for: which country, region or municipality a point is in; which street a point is on (add "street" to base); geofence checks against your own polygons; tagging data with region codes. For the other direction, an address to a coordinate, use geocode_address. For a route, a travel distance or a travel time, use get_route — 10 lookups on the standard plans to this one’s 1. Do NOT use for place search by name or for fetching boundary geometry.

Caveats worth repeating to the user: municipal is the finest unit AVAILABLE, not a consistent kind of thing — Los Angeles returns a city, rural Kansas returns a county, so do not assume it names a city. A layer that matched nothing comes back null. The errors array is always present: a boundary set that is unavailable or not granted to this key is skipped and reported there, while the call itself still succeeds.

STREETS (opt-in via base, worldwide). base.street is ALWAYS three answers, for 5 m, 20 m and unlimited in that order, each with radiusMeters, streetNumber, streetName, postcode and distanceMeters. A numbered address within the radius wins over a nearer street (for the unlimited entry the address must still be within 20 m); otherwise the nearest named street; unnamed roads never answer. Two different nulls: base.street === null means there is no street data for the point’s country, while an entry whose fields are null means nothing was within that radius — never report them the same way. streetNumber and postcode are STRINGS (44A, 12-14, 0181), house numbers are rare outside well-mapped areas. Street geometry comes back only when streetGeometry is set — leave it off unless something will draw the line.

One call is one billed lookup however many layers, sets or grid codes it touches, and a call that matches nothing still bills.

Input Schema

NameRequiredDescriptionDefault
latYesLatitude, -90 to 90.
lngYesLongitude, -180 to 180.
baseNoWhich reference layers to resolve. Defaults to country, region and municipal. "street" is opt-in: add it explicitly to get the nearest street.
setsNoNames of the boundary sets on this account to match against. Defaults to none.
h3resNoH3 resolution 0-15. 9 is about 400 m across.
encodeNoAlso return the point as an H3 cell index and/or Google Plus Code. Output only — neither can be used AS a location, because both name areas rather than points.
pluslenNoPlus Code length. 9 is not a valid length. 10 is about 14 m.
streetGeometryNoGive each street answer the line of the street it names, trimmed to about 250 m either side of the point. Implies the street layer. Off by default, and leave it off unless something will draw it: a line is hundreds of characters nobody reads.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.1
    • addedInput schema / properties / streetGeometry
      Added value: +{
+  "description": "Give each street answer the line of the street it names, trimmed to about 250 m either side of the point. Implies the street layer. Off by default, and leave it off unless something will draw it: a line is hundreds of characters nobody reads.",
+  "enum": [
+    "polyline6",
+    "geojson"
+  ],
+  "type": "string"
+}
  2. Changed2 schema fields changedv0.1.6
    • changedInput schema / properties / base / description
      Previous value: -"Which reference layers to resolve. Defaults to all three."New value: +"Which reference layers to resolve. Defaults to country, region and municipal. \"street\" is opt-in: add it explicitly to get the nearest street."
    • changedInput schema / properties / base / items / enum
      Previous value: -[
-  "country",
-  "region",
-  "municipal"
-]New value: +[
+  "country",
+  "region",
+  "municipal",
+  "street"
+]
  3. First observedv0.1.2

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, so the description carries the behavioral burden and does so richly: it discloses billing semantics (one call = one billed lookup regardless of layers, and a no-match call still bills), that the errors array is always present and reports skipped/ungranted boundary sets while the call still succeeds, and the distinction between the two kinds of null for streets. This is 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?

The definition is front-loaded (purpose, then Use for / alternatives, then caveats, then a dedicated STREETS section) and nearly every sentence carries information that changes agent behavior. It is dense and long, and lines like 'caveats worth repeating to the user' are slightly meta/marketing-toned, but no section is genuinely filler.

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?

With eight parameters, no output schema, and only two required params, the description compensates thoroughly: it explains the shape of street answers, the always-present errors array, the meaning of each null variant, unit and code formats, and the billing model. An agent has everything needed to call it correctly and interpret the response without a schema.

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?

Although schema coverage is 100%, the description adds meaning the schema does not: base.street always returns exactly three answers (5 m, 20 m, unlimited) with named fields, streetNumber and postcode are STRINGS with examples, streetGeometry is trimmed to ~250 m and implies the street layer, and 'add street to base' is the opt-in mechanic. Null-vs-null-field semantics for street results are spelled out, which the schema cannot express.

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 first sentence states a specific verb (reverse geocode) plus the exact resource (administrative areas containing the coordinate) and enumerates the outputs: country, region, municipality with ISO 3166 codes, optional street, plus uploaded boundary-set matches. It also explicitly names the sibling it is not (geocode_address for the opposite direction, get_route for routes), so an agent can disambiguate 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?

A dedicated 'Use for:' block lists the concrete tasks (country/region/municipality lookup, street identification, geofence checks against own polygons, tagging with region codes) and names the alternatives with their conditions. It adds explicit exclusions: 'Do NOT use for place search by name or for fetching boundary geometry,' and cites a cost differential versus get_route. 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.

Deploy Server

Other Tools