undo_apply

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

Annotations already flag destructive=true and non-idempotent, and the description is consistent with them while adding context the annotations cannot convey: the inverse executes under its own governed tool with its own risk tier and audit row, and a token can only be applied once. The single-use constraint is a critical behavioral detail. It still doesn't describe failure behavior or what the response contains.

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?

Risk tags are front-loaded, the prose paragraph covers behavior, and the Args block covers parameters. There is minor overlap between the dry_run prose sentence and its Args line, but nothing wasteful enough to penalize.

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-idempotent dispatcher with no output schema and zero schema documentation, the description supplies the key facts an agent needs: source of the id, preview path, one-time application, and separate audit trail. What's missing is only failure semantics and the shape of a dry-run preview.

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 description coverage is 0%, so the description must carry the load — and it does, explaining all three parameters: undo_id's origin, dry_run's preview semantics, and target's pass-through behavior ('when it accepts a target'). The remaining ambiguity is inherent to target's tool-dependent nature, not an omission.

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 ('Apply a recorded undo by dispatching its inverse tool') plus the annotated mode '[WRITE][risk=medium]'. It is immediately distinguishable from the sibling undo_list, which supplies the undo_id rather than consuming it.

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?

Tells the agent where the required id comes from ('The undoId from undo_list (or an _undo_id in a write result)') and when to reach for dry_run=True. It lacks an explicit 'do not use this when…' clause, but the guidance is concrete and actionable.

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