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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds what they cannot: results are a ranked shortlist carrying surface, ascent, course shape and national park fields, plus canonical Skamper URLs. It does not discuss result-set size behaviour or what happens when no route matches, which is the remaining gap for a recommendation engine.

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?

Three sentences, each doing distinct work: purpose, usage trigger with example, return shape and disambiguation. The purpose and the routing decision are front-loaded, and there is no restatement of the title or filler wording.

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?

For a 10-parameter, zero-required recommendation tool with no output schema, the description covers purpose, invocation style, return fields and sibling routing, which is close to sufficient. The minor hole is that it never states all parameters are optional or what the defaults produce, leaving the agent to infer behaviour when the user gives minimal context.

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 80%, so baseline is 3; the description earns a bump because the example sentence demonstrates how free-text runner intent maps onto specific fields (trail_runner, ~15k, avoid roads, scenic, low technicality). It still adds nothing for limit, distance_tolerance_km or the near_lat/near_lng pair, which remain schema-only.

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 and resource ("Recommend a UK running route") plus the scope qualifier "that fits the runner", which distinguishes it from filter-based listing tools. The final sentence names the sibling it is not (search_routes), so an agent can separate the two without opening either 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 an explicit when-to-use trigger ("when a user describes who they are and what they want") with a concrete worked example, and states the selection rule against the alternative: preference-based requests go here, exact numeric filters go to search_routes. Both the use case and the exclusion are spelled out.

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