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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds substantive behavior the annotations cannot: the concrete side effects (project creation for plan-generator, per-task moves for schedule-doctor), the 402 project-cap failure, and the all-or-nothing re-check that yields a 409 with nothing written when tasks changed. That is exactly the extra context the annotations leave open.

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 state requirement and permissions come first, side effects second, failure semantics third, and the safety warning last as a capped emphatic sentence. Every clause carries distinct information (per-agent behavior, 402, 409, stale, re-run) with no repetition.

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 destructive, non-read-only mutation with no output schema, the description covers authorization, state precondition, side effects, credit/cap failure, and the stale-conflict outcome, which is everything an agent needs to call it correctly or correctly decline to call it.

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?

There is a single parameter with 100% schema description coverage, so the schema already carries the meaning of 'id'. The description adds only the implicit constraint that the id must reference a run in state 'proposed', not a broader explanation of the parameter or its acceptable values. Baseline 3 applies when the schema does the heavy lifting.

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 ('Apply') and resource ('a run in state "proposed"') and then differentiates behavior by agent type: plan-generator creates the project, schedule-doctor moves every task in the re-plan. That is enough for an agent to tell it apart from sibling run tools such as reject_agent_run, get_agent_run, or run_agent.

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 a clear precondition (the run must be in 'proposed'), an authorization constraint (Administrator/ProjectManager only), an explicit when-not (do not call before the user has seen the proposal and approved), and a recovery route when the run goes stale ('run the agent again'). This is close to a complete decision rule.

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