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

"proposal only: nothing is dispatched until cxt_save_order_plan" explains why readOnlyHint=true despite an optimization operation — context annotations cannot convey. It also discloses the required ITINERARY_PLANNING_ACCESS scope and the backing endpoint. It does not say whether the proposal is returned in the response or persisted server-side.

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?

A single tight sentence with the key constraint (proposal only) front-loaded in the parenthetical. The trailing endpoint is slightly incidental but still useful for tracing. 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?

With 8 parameters, required auth, and no output schema, the description covers permissions and the commit boundary but says nothing about what the call returns (an optimized plan object, an id, a diff). An agent knows how to invoke it safely but not what to expect back.

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 all 8 parameters including both enums are already documented inline, setting the baseline at 3. The description adds no guidance on the non-obvious distinction between plan_order_ids and all_input_order_ids, which is the main semantic risk in the payload.

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?

"Re-optimize a single driver's plan" names a specific verb and scoped resource, and the "single driver" qualifier implicitly separates it from the broader sibling cxt_optimize_route_plan. The sibling is not named explicitly, so the differentiation relies on inference.

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?

"after manual changes" gives a clear trigger condition, and the parenthetical explicitly names cxt_save_order_plan as the follow-up commit step. It stops short of stating when to prefer this over cxt_optimize_route_plan or cxt_plan_orders.

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