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

Annotations already cover readOnly/idempotent/non-destructive, yet the description still adds real value: PREMIUM license gating, the 200-stop ceiling, the never-raises-protocol-error contract with the {"error": ...} payload shape, and explicit retry safety after correcting input. It also discloses solver outcomes (FEASIBLE, unserved list) and the time_matrix fallback rule.

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?

Front-loaded with the one-line capability statement, followed by a worked example and then behavioral caveats — logically ordered with no filler sentences. The inline JSON example is long but carries real signal about the nested stop/vehicle shape, so the length is largely earned.

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 7-parameter solver tool, the definition covers modeling semantics, a worked input/output sample, error behavior, and runtime budget. An output schema exists so return values need not be explained, and the brief return sketch is harmless redundancy rather than a gap.

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 already 100%, so baseline is 3, but the description adds meaning the schema lacks: windows and service_min are minutes from the start of the day, and if time_matrix is absent the distance matrix is read as minutes. drop_penalty's INFEASIBLE tradeoff is also explained beyond the schema's one-liner.

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+resource with scope: 'Capacitated, time-windowed routing for a fleet over up to 200 stops.' That concretely distinguishes it from route_plan (single-vehicle) by the word 'fleet' and the stop cap, though it never names the sibling explicitly.

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?

'Use for daily dispatch' gives the intended context, and 'Set drop_penalty to allow stops to be left unserved at that cost instead of returning INFEASIBLE' tells the agent how to handle a key modeling decision. 'Not a map service; bring your own matrices' steers callers toward the matrix sibling without naming it, so the routing-vs-matrix split is implied rather than spelled out.

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