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

Annotations already establish that this is read-only, idempotent, and non-destructive, but the description adds meaningful behavior: it checks chart depths, tides, bridges, clearance, weather samples, and can take 110 seconds with cold charts. It also discloses that saved vessel settings are not inferred and that corridor=icw is a hard constraint, which is valuable operational context.

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 core route-planning information is front-loaded, but the description becomes heavily bloated with unrelated interpretation rules about lightning, kitesurfing, activity keys, surf, paddleboarding, and other non-route topics. Much of this does not help an agent invoke plan_route and dilutes the relevant guidance.

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 complex route-planning tool with no output schema, it describes the main processing behavior, constraints, limitations, latency, and source/freshness metadata adequately. The major gap is the large amount of unrelated content, but the route-specific essentials are mostly present.

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 schema coverage at 0%, the description compensates by naming most key inputs: from/to, boat or draft, beam, airDraft, ukc, bridgeMargin, speed, via stops, and corridor. It also provides units in feet/knots, though it does not explain the time parameter or fully define each acronym's semantic role.

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: chart-aware water routing between from/to spot IDs or coordinates. It clearly states the route-planning purpose, but it does not explicitly distinguish itself from the similar sibling plan_my_route or check_route_conditions.

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 some usage context, such as supplying a confirmed boat or measured draft and omitting boat unless confirmed, plus support for via stops and corridor=icw. However, it never says when to use this tool instead of plan_my_route or check_route_conditions, and the kitesurfing guidance is unrelated to selecting this route tool.

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