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

Although annotations already mark the tool as destructive, the description goes beyond those booleans by specifying what each token type reverses: schedule/confirm_schedule tokens delete booked events and void proposals, while other tokens undo creations, changes, or removals. This gives an agent concrete expectations about side effects and limits.

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 description is dense and informative, with the purpose front-loaded and the token mechanics explained after. The initial synonym string 'revert, roll back, take back, or cancel' is redundant, but the rest of the content is purposeful and earns its place given the breadth of reversible operations.

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, reversible-action tool with no output schema, the description covers the core essentials: what to pass, how long tokens are valid, what different tokens do, what is returned, and the sibling alternative for date-based discard. It does not detail failure behavior for expired or invalid tokens, but the constraints are stated clearly enough for an agent to invoke it correctly.

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?

The schema already documents the tokens parameter at 100% coverage. The description adds valuable context by clarifying that these are the undoToken values returned by prior writes, that they expire after 30 minutes, and that each token type has distinct reversal behavior. This meaningfully supplements the schema rather than merely repeating it.

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?

The description clearly states the tool's purpose: undo a recent reversible operation by passing its undoToken. It explicitly enumerates which sibling operations produce such tokens, which distinguishes it from the other tools in scope. The verb 'undo / revert' is specific and matches the tool name without being a tautology.

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?

The description gives explicit usage conditions: pass tokens containing the undoToken, works only while active before expiresAt (30 minutes), and returns per-token results. It also names the alternative approach for discarding a whole day via review_day with action 'discard', providing clear when-to-use vs when-not-to-use guidance.

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