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

Goes well beyond the annotations: it discloses the spend cap ('the plan's own price as its cap'), the safety stop points ('stops at reviews and before any step that can't be undone'), and the partial nature of rollback ('undo rolls the plan back as far as it can'). It never contradicts destructiveHint=true. It does not state whether credits are charged on a failed or skipped run, which is the one material cost gap for an operation flagged as destructive and credit-spending.

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 precondition and the credit warning, and nearly every clause carries distinct information. The middle sentence chains four action definitions in a single run-on, which is dense but not padded; nothing here is 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?

Covers the full burden for a destructive, credit-spending mutation with no output schema: precondition, cost cap, stop conditions, per-action recovery paths, and a pointer to get_status for progress. An agent can call it correctly and knows what to do when it halts, which is everything this tool needs.

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 only 40%, so the description must compensate, and it largely does: it explains all five action values, how choices are keyed ('by option id or in the person's own words'), and that alternative takes the id of one of the plan's costed alternatives. project_id and plan_id are left to their names, which are self-evident, so no meaningful ambiguity remains.

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 and resource (run/apply a plan produced by direct) and immediately scopes it with a precondition ('only after the person has heard it and said yes'). The title calls out that it SPENDS CREDITS, and the action verbs (start/continue/retry/skip/undo) make it trivially distinguishable from build_plan, get_plan, and get_status.

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 an explicit when-to-use gate (after the person has heard the plan and said yes) and routes each action: start to run it, continue from a stop, retry a failed step, skip to end, undo to roll back. It also names get_status(plan_id) as the way to poll progress, so the agent knows the alternative to blind re-invocation.

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