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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds non-obvious behavior: it never raises a protocol error, returns a structured {"error": ...} object on bad input, and is therefore always safe to retry after correction. It also discloses the 12-stop ceiling and that costs can be in arbitrary units. Minor deduction because the full input/output example overlaps with what the existing output schema already provides.

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 most decision-relevant facts (what it does, cost, stop cap) are front-loaded before the example. The single dense paragraph carrying example JSON, matrix rules, exclusions, and error semantics is efficient but harder to scan; a light break would improve it.

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?

Covers everything needed to invoke correctly: required inputs, matrix shape and depot convention, the 12-stop limit, capacity extension, sibling routing, and error/retry semantics. With an output schema present, the description is not obligated to explain return values further, and it still sketches them.

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 baseline is 3; the description earns more by explaining that the matrix is in the caller's own units (km, minutes, cost), must be square, and that pairing optional per-stop demand with vehicle_capacity upgrades the call into a capacity check — a relationship the schema fields state only in isolation.

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?

Opening sentence states a precise verb and resource — 'Order up to 12 stops into the shortest single-vehicle route on your distance matrix' — including the scale cap and the required input type. It is immediately distinguishable from route_plan_fleet, which it names explicitly for the multi-vehicle case.

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 both positive scope ('one driver's day or a courier's loop') and explicit exclusions ('Not for several vehicles or time windows: use route_plan_fleet'), plus a dependency alternative ('call distance_matrix_haversine for straight-line values'). An agent can route itself without inspecting any sibling schema.

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