calculate_route

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond them with real operational detail: an external provider dependency (FOSSGIS/OSRM, overridable via OSRM_API_URL), a hard rate limit of max 1 req/s, and the side effect of drawing the path on the verification map. It stops short of describing failure behavior when a provider is unreachable or a place name fails to resolve.

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

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

Two sentences, front-loaded with the capability and outputs before the provider/rate-limit detail. Dense with little waste, though the trailing parenthetical about OSRM_API_URL and the map-drawing clause are secondary information that could be split or subordinated more cleanly.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on capability, data source, rate limits, and side effects. The main remaining gap for a 4-parameter open-world tool is failure and resolution behavior (what happens when a place name is ambiguous or the routing service errors), which the description leaves silent.

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

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

Schema description coverage is 100%, including per-parameter docs for origin/destination formats, the profile enum, and return_steps, so the schema does the heavy lifting. The description adds only the notion that endpoints can be coordinates or place names and that turn-by-turn output exists, without adding format or edge-case detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource — 'Calculate real-world travel distance, duration, turn-by-turn summary, GeoJSON route geometry, and route bounding box' — and scopes it to 'between two locations or coordinate pairs'. It enumerates the outputs so an agent knows exactly what it gets, and no sibling tool (get_bounds, spatial_calc, search_overpass) covers routing, so the resource is unambiguous.

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

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

Usage is only implied: the phrase 'between two locations or coordinate pairs' hints at routing use cases, and the rate-limit note constrains call frequency, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling (e.g. spatial_calc for straight-line distance, reverse_geocode for resolving place names). An agent must infer the routing niche itself.

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