Skip to main content
Glama

route_observations

What a journey PASSES, in sentences ready to be read aloud, each with its position along the route. The named rivers and canals it crosses, the road it runs on and for how far, the settlements it goes through, the protected landscapes it enters and how high the road climbs: the things a passenger who knew the area would say. NONE OF THIS IS IN A ROUTE: a route is a list of movements and a river crossing is not a movement, so do not try to read it out of route's answer. Give geometry_polyline6 straight from the route tool, plus optional units ("miles" default, or "kilometers"), min_gap_m and max_observations. Each observation carries at_m (WHERE it belongs (delivered anywhere else it is trivia, not an observation), a kind, a say sentence to relay verbatim, and a basis naming the map layer and tag the claim rests on. THE SILENCE BUDGET IS THE DESIGN: min_gap_m is a floor, not a target, and when a route yields more than max_observations the gap WIDENS on its own so the survivors stay spread over the whole journey rather than clustering where the map happened to be richest. Inside a window the rarer kind wins. So a short list on a long route is the budget working, not thin data. READ coverage BEFORE REPORTING AN EMPTY LIST: an empty observations with tiles_read of 0 means NO DATA WAS READ, which is not the same claim as quiet countryside, and uncovered_m says how much of the route could not be seen at all. Two things it will never say, deliberately: it never names a hill (a peak two kilometres away behind a ridge is named confidently and seen by nobody), and it never reads a junction number (an observation mistakable for an instruction is not safe to speak beside real guidance). A settlement is a labelled POINT, not a boundary, and offset_m publishes the distance behind the word "through". It is a query and it triggers nothing: no position is held and nothing is pushed. COSTS 10 UNITS a call, flat, whatever is asked for. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose basemap archive and elevation model answer it; a deployment with no archive answers 501 and says so.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
unitsNoUnits for the spoken distances: `miles` (default) or `kilometers`. `kilometres` and `km` are accepted too.
min_gap_mNoLeast distance along the route between two observations, metres (default 2000). A FLOOR, not a target: when the route holds more than `max_observations`, the gap widens past this on its own so the survivors stay spread over the whole journey.
max_observationsNoCeiling on how many observations come back, 1 to 200 (default 40).
geometry_polyline6YesThe route shape, precision-6 encoded: `geometry_polyline6` straight out of the `route` tool's answer. Nothing else is accepted: there is no origin/destination form, because this tool annotates a route somebody already chose rather than computing one.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
caveatYesThe standing limits of the method, for relaying to users.
coverageYesWhat the archive and the elevation model could and could not say: `tiles_read`, `tiles_missing`, `uncovered_m`, and the per-kind censuses. **Read it before reporting an empty list.** `tiles_read` of 0 means nothing was looked at, which is not the same claim as quiet countryside.
attributionYesThe licence notice for this answer. The obligation attaches to the product, not to each spoken sentence, so a visible or linked credit in the app satisfies it.
observationsYesThe observations, in route order, already thinned to the silence budget.
route_length_mYesThe route's own length, metres, as walked.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and is exceptionally transparent. It discloses that the tool is a query and triggers nothing, costs 10 units flat, requires the MapMap gateway, and returns 501 without an archive. It also explains the silence-budget design, coverage semantics, deliberate exclusions like hills and junction numbers, and the meaning of `offset_m`.

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 description is long, but almost every sentence adds operational value, from budget behavior to coverage caveats to error conditions. It is front-loaded with purpose and then structured into distinct behaviors. The rhetorical framing is slightly excessive but not redundant.

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?

The description covers input provenance, output observation fields, the meaning of empty results with `tiles_read` and `uncovered_m`, cost, authentication via gateway environment variables, and error behavior. For a tool with four parameters and no annotations, nothing essential is missing.

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 coverage is 100%, so the baseline is 3. The description repeats the parameter names and emphasizes passing `geometry_polyline6` straight from the route tool, but it does not add meaning beyond what the schema already provides. It therefore meets the baseline but does not exceed 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?

The description states precisely what the tool produces: spoken-style observations of what a journey passes, including rivers, roads, settlements, landscapes, and elevation, each tagged with a position. It also distinguishes itself from `route` by warning that none of this information is present in a route's movement list.

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?

The description gives clear context: this tool annotates an already-chosen route, and `geometry_polyline6` must come directly from the `route` tool. It also gives an explicit when-not by saying 'a route is a list of movements and a river crossing is not a movement, so do not try to read it out of route's answer.' However, it does not explicitly name or compare alternatives such as `search_along_route`.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources