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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it discloses that each result carries a drawn map and a per-route link to external material (3D fly-through, elevation profile, GPX, reviews), and it explicitly instructs the agent to report returned numbers rather than pre-call estimates. It does not state result limits or behavior when no trails are found.

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?

The tool's core behavior is front-loaded in the first clause, and the input instruction and reporting rule follow compactly. The long parenthetical inventory of output fields is dense but earns its place by substituting for the missing output schema.

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 five params, 20% schema coverage and no output schema, the description does the heavy lifting on return values, which is the biggest gap filled. It remains incomplete on input-side details an agent needs: default radius, what 'kind' omits (both?), and whether place or coordinates wins when both are given.

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 coverage is only 20% (only radius_km is documented), so the description must compensate and partly does: it clarifies that place and lat/lng are alternative locators and that place accepts any granularity ('any town, valley, park'). It says nothing about the 'kind' enum's effect, the radius default of 12 km, or precedence when both place and coordinates are supplied.

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 uses a specific verb and resource ('Marked hiking or cycling routes near a place from Wai Trails') and enumerates the returned fields, so the agent knows exactly what it gets. It never names the obvious sibling wai_trail_detail, so differentiation is left to inference rather than stated.

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?

It gives partial input guidance ('Give place ... or lat / lng') and one behavioral rule ('Answer with the returned numbers, not an estimate made before the call'), which is a useful anti-hallucination instruction. However, it never says when to prefer this list tool over wai_trail_detail, nor what to do when a place name is ambiguous or yields nothing.

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