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

Annotations already flag destructive, openWorld, non-idempotent, so the bar is lower, but the description still adds real context: it discloses the external-effect confirmation requirement and the exact two-call pattern (a returned question plus confirmToken to resend after the person agrees). It stops short of saying what a successful undo returns or whether the undo itself is undoable.

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 sentences, front-loaded with the purpose and preconditions before the confirmation mechanics, with no filler. The phrasing around the interactive branch ('where the app can show the question it does') is dense enough to cost a little readability.

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, open-world operation with no output schema, it covers the important unknowns: source of actionId, the precondition for success, and the alternate confirmToken return path. It omits what a successful call returns or how a refusal due to intervening changes surfaces, which is the remaining gap.

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 the baseline is 3, and the description exceeds it by explaining provenance for actionId (the change's own response, readRecentRuns, readStatus) and the safety rule for confirmToken (only from a prior answer, never invented). It does not clarify workspaceId at all, leaving that to the schema.

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 with concrete examples ('Put back what a change replaced (a product listing, a published article)') and adds the precondition that the change kept the prior version. An agent can immediately tell this apart from nearby mutators like updateListing or publishArticle, which change things rather than restore a prior state.

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 clear qualifying conditions — only when the change kept the replaced item and nothing has modified it since — plus the rule that changes affecting the live store or site require human confirmation first. It does not name a sibling alternative for the case where undo is not applicable, which keeps it short of a 5.

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