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

Annotations only declare readOnly/openWorld/destructive hints; the description goes well beyond them by disclosing the conversation-side effect (every call renders a card), the once-per-answer budget, and the downstream instruction not to restate ferry times. It also explains the side effect of targetKm (response describes the custom walk, permalink opens it in the planner). These are exactly the operational traits annotations cannot convey.

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 purpose and the return payload are front-loaded, then usage rules, then the card protocol — a sensible order with no filler sentences. It is on the long side and the 'ALWAYS'/'in the planner'/'the map is the main deliverable, not optional' phrasing is slightly repetitive emphasis, but each block carries distinct 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?

For a tool with an output schema and annotations, the description still covers the non-obvious parts: identifier formats, custom-distance behavior, required follow-up map call, and the card-rendering constraint. Nothing an agent needs to invoke it correctly or handle the result appears to be missing.

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 100%, so the baseline is 3, and the description still adds meaning: 'section' accepts the same identifiers as fetch (sat:section:…, slug, uid), 'hub' ties to values returned by check_day_trip/day_trip, and 'targetKm' is explained in terms of response behavior and the planner permalink rather than just a range. No meaning is added for 'towards' or 'direction' beyond the schema, keeping it just short of 5.

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 first sentence gives a specific verb and resource ('Plan a ready round-trip day trip to one trail section (island)') plus the exact scope of a single island. It then enumerates what comes back (hub, outbound/return ferry times, walking time, ferry count), so the agent knows precisely what it gets. Sibling tools are named explicitly, so confusion with plan_route or check_day_trip is ruled out.

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?

Explicit when-to-use ('user wants a day-trip suggestion to a single island'), explicit when-not-to-use with named alternatives for one-way trips (plan_route), probing (check_day_trip) and multi-day trips (multi_day). It also prescribes sequencing (always follow with show_section_map using the same section, date and targetKm) and a frequency rule (at most once per answer, never to compare).

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