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

Annotations already declare the safe read-only/idempotent profile, and the description adds substantially more: routing data provenance (own routing on GB/US roads, open routing service elsewhere), the traffic model choices, automatic in-chat map rendering, what render returns (link, GeoJSON, KML), and the background-job flow with get_job/write_to_sheet.

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?

Dense and front-loaded: the core purpose and the primary example lead, with advanced controls (include_geometry, render) after. The long opening sentence and some run-on clauses cost readability, but nearly every sentence carries information.

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?

Covers a complex, 11-parameter, nested-schema tool well despite having no output schema, including return artifacts and the async job path. Minor gap: it states '200 addresses' while the schema allows 500, and error/failure behavior is not addressed.

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?

With 73% schema coverage the schema already documents much, but the description still adds real meaning: include_geometry yields larger GeoJSON polygons, source accepts a Google Sheets link/Drive file/run_id with header-based column detection, and records ids are used to merge results back. A few params (mode, minutes, origin) are self-evident and left to the schema.

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?

States a specific verb+resource (compute the reachable area from one origin), its scope (5–60 min, up to three bands, drive/walk/cycle, with size), and the secondary record-classification mode. An agent can distinguish it from siblings like plan_routes, find_nearby, get_road_distances and filter_by_location 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.

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

Gives explicit conditions for render ('only when the user wants to keep or share the map'), notes the bands render automatically, and points to update_map for later edits. It does not, however, route the agent away from adjacent siblings such as find_nearby, filter_by_location or get_road_distances, so the when-not-to-use guidance is incomplete.

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