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

Goes well beyond the annotations (destructiveHint, non-idempotent) by disclosing token lifecycle behavior: single use and a ten-minute expiry, plus the agent-facing consent requirement. These are operational traits nothing else in the definition conveys, and they matter for calling correctly.

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?

Three short sentences, front-loaded with the action, then the consent gate, then the token constraint. No filler and no repetition of the schema.

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 essential context for a one-parameter destructive tool: what it does, the consent gate, and token validity. It stops short of saying what happens if the token is expired or no preview exists, or whether the change can be undone, but the destructive annotation carries much of that safety signal.

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% and the parameter's own description already says it is the token the prepare tool returned, so the baseline is 3. The description adds real semantics beyond that: the token is single-use and valid for ten minutes, which clarifies what counts as a valid value.

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 ('make a change') and ties it directly to the prepare_* family of tools, so an agent can tell it apart from read_* and prepare_* siblings without opening a schema. The mechanism (executes a previewed change) is unambiguous.

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, checkable precondition: call only after the user explicitly agreed to that preview in this same conversation. That is a when-to-use rule with an implied when-not (no preview, no consent), which is exactly the guidance a destructive tool needs.

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