Skip to main content
Glama

MapMap

by ai.mapmap
OverviewDiscussionsAdmin

reverse_geocode

Turn coordinates into the nearest places: addresses, POIs and localities with distance in metres. The inverse of geocode. Provide lat and lon; returns up to limit (default 5, max 10) results, nearest first, each with name, one-line label, lat/lon, type, address parts and distance_m, plus categories and a details object of display tags (opening_hours, website, phone, wikipedia, ...) on POI hits when the index carries them. Every result also carries bearing_deg and a spoken direction. Pass heading_deg (degrees clockwise from true north, 0 = north, 90 = east) and results are described from where the user stands, "ahead and slightly to your right, about 80 metres", with a signed relative_bearing_deg (negative left, positive right); without a heading the phrasing falls back to cardinals ("north-east of you"), so this works with or without a compass. Add fov_deg to keep only what lies within that cone of the heading, it is the FULL width, so 90 keeps what lies within 45 degrees either side of dead ahead; anything dropped is counted in out_of_view. Prefer reading direction aloud over coordinates.

Input Schema

NameRequiredDescriptionDefault
latYesLatitude in decimal degrees (−90 to 90).
lonYesLongitude in decimal degrees (−180 to 180).
limitNoMaximum number of results (1–10, default 5). The hosted first-party index answers at most 5 nearest hits per lookup.
fov_degNoField of view: the full width in degrees of a cone centred on `heading_deg`, outside which results are dropped, it is the FULL width, so 90 keeps only what lies within 45 degrees either side of dead ahead. Needs `heading_deg`, a cone has to point somewhere. The count of results removed is reported as `out_of_view`.
heading_degNoWhich way the user is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Supply it and every result is also described from the user's point of view ("just ahead on your right"); omit it and results fall back to cardinal directions ("to the north-east"), so the tool works with or without a compass.

Output Schema

NameRequiredDescriptionDefault
resultsYesNearby places, nearest first.
out_of_viewNoHow many otherwise-matching places were dropped for falling outside `fov_deg`. Non-zero means there are places near the user that are simply not in front of them, say so rather than reporting nothing nearby. Always 0 when no field of view was set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / fov_deg / description
      Previous value: -"Field of view: the full width in degrees of a cone centred on\n`heading_deg`, outside which results are dropped — it is the\nFULL width, so 90 keeps only what lies within 45 degrees either\nside of dead ahead. Needs\n`heading_deg` — a cone has to point somewhere. The count of\nresults removed is reported as `out_of_view`."New value: +"Field of view: the full width in degrees of a cone centred on\n`heading_deg`, outside which results are dropped, it is the\nFULL width, so 90 keeps only what lies within 45 degrees either\nside of dead ahead. Needs\n`heading_deg`, a cone has to point somewhere. The count of\nresults removed is reported as `out_of_view`."
    • changedOutput schema / $defs / ReverseGeocodeHit / properties / direction / description
      Previous value: -"The direction phrased for speech — \"ahead and slightly to your\nright, about 80 metres\" with a heading, \"to the north-east, about\n80 metres\" without one. Deliver this verbatim rather than reading\nout coordinates."New value: +"The direction phrased for speech, \"ahead and slightly to your\nright, about 80 metres\" with a heading, \"to the north-east, about\n80 metres\" without one. Deliver this verbatim rather than reading\nout coordinates."
    • changedOutput schema / properties / out_of_view / description
      Previous value: -"How many otherwise-matching places were dropped for falling\noutside `fov_deg`. Non-zero means there are places near the user\nthat are simply not in front of them — say so rather than\nreporting nothing nearby. Always 0 when no field of view was set."New value: +"How many otherwise-matching places were dropped for falling\noutside `fov_deg`. Non-zero means there are places near the user\nthat are simply not in front of them, say so rather than\nreporting nothing nearby. Always 0 when no field of view was set."
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses ordering (nearest first), default/max limits, that fov filtering silently drops results counted in 'out_of_view', and the fallback from heading-relative to cardinal phrasing. It does not mention auth, quota or error behavior, but this is a read-only lookup with no side effects implied.

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?

Purpose is front-loaded and the rest is information-dense rather than padded, but the long multi-clause sentences with nested parentheticals are heavy going, and the heading/fov mechanics are repeated verbatim in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be spelled out, yet the description enumerates the payload (name, label, type, address parts, distance_m, bearing_deg, direction, details tags). Combined with the filtering and fallback rules, an agent has everything needed to call it correctly; only cross-tool routing is thin.

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 the baseline is 3. The description's heading_deg and fov_deg explanations largely restate the schema text; the only added value is the presentation hint to read 'direction' aloud instead of coordinates, which does not change invocation.

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 ('turn coordinates into the nearest places: addresses, POIs and localities with distance in metres') and immediately positions it against the sibling geocode ('The inverse of geocode'). An agent can distinguish it from nearby_places, geo_nearest_point_on_line and other point-query tools without opening a schema.

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

Usage Guidelines4/5

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

Gives clear operating context: supply lat/lon, results come nearest-first, and the heading/fov knobs are optional so 'this works with or without a compass'. It does not, however, say when to prefer this over alternatives such as nearby_places or geocode, so there are no explicit exclusions.

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

All MapMap toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources