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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds the crucial specifics annotations cannot: it rewrites existing routes if previously optimized (what gets destroyed), it consumes a rate-limited quota (30/min, 100/10min), and it does NOT notify drivers. This is exactly the behavioral context needed for a destructive, non-idempotent write.

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 'WRITE:' marker, then a dense sequence of scope, side effects, quota, non-effects, return handling, and prerequisites. Every clause earns its place with no filler.

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?

There is no output schema, and the description fills that gap by explaining the return (an operation handle) and the polling follow-up. Combined with prerequisites, rate limits, and destruction semantics, an agent has everything needed to invoke and sequence this tool.

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 one parameter at 0% schema description coverage, the description must compensate. It only implicitly reveals the parameter through the endpoint 'POST /plans/{planId}:optimize', mapping plan_id to planId, but adds no format, source, or constraint detail beyond that.

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 states a specific verb and resource — 'start the route optimization of a plan' — and clarifies the effect with the parenthetical 'orders and assigns its stops to its drivers'. It is unambiguous about what the tool does, but it never names or contrasts a sibling such as spoke_distribute_plan, so the 5-level sibling differentiation is absent.

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 a concrete precondition ('needs at least one driver and one stop') and an explicit follow-up workflow ('Returns an operation: poll spoke_get_operation until done'), which is strong context for invocation. It stops short of stating when NOT to use it or which sibling to prefer for adjacent tasks (e.g. distribute_plan), so no explicit alternatives.

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