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

Annotations already carry readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: the output is schematic, not navigable, and it enumerates exactly what it ignores (actual navigation, hazards, traffic separation, drafts, local rules). This is critical misuse-prevention context for a tool whose results could otherwise be mistaken for real navigation guidance.

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 description is front-loaded with action and result, then parameter modes, then the caution, then use cases — a sensible order where the most decision-relevant facts come first. The cautionary section is longer than typical but earns its length because misuse (real-world sailing) carries genuine risk. 'Part of the Maritime Reports add-on' adds minor context without bloating the text.

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 an output schema present, full parameter coverage, and safety-carrying annotations, the description covers the two things an agent most needs: which parameter mode to use per endpoint, and the route's non-navigable nature. The one gap is behavior when called with no parameters at all — with 0 required params, a sentence on the default/error behavior would make it fully complete.

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; the description adds meaning beyond the individual parameter docs by specifying the alternation/grouping semantics: each endpoint (origin/destination) may be supplied as coordinates, a port UUID, or a port UN/LOCODE. This clarifies valid parameter combinations and the mode-per-endpoint decision, which the flat 8-parameter schema alone does not convey.

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 opening sentence names a specific verb ('Calculate') and resource ('schematic sea route between two points'), then pins down the output format (GeoJSON LineString of waypoints) and metrics (kilometres and nautical miles). The 'SCHEMATIC' qualifier and distinct geospatial output clearly distinguish it from siblings in the list (get_weather, find_ports, estimated_vessel_position), so an agent can tell this tool apart without inspecting 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?

The description states explicit intended uses ('estimating distance and travel time, visualizing the approximate path/shape, and similar analysis') and an explicit when-not ('do NOT use it for real-world sailing') with concrete reasons (no hazards, traffic separation, drafts, local rules). It does not name an alternative sibling tool, but none of the listed siblings appears to offer navigable routing, so the exclusion stands on its own.

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