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

With annotations already declaring destructiveHint=true, the description adds substantial behavioral detail: it deletes created groups, restores prior membership from a pre-write snapshot, and refuses to delete groups currently used by construction stages because deletion strips them from stages. This explains exactly what destruction and restoration occur.

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 four tight sentences, front-loads the core undo behavior, then adds the refusal condition, default resolution, and preview/apply semantics. Every sentence carries useful information.

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 ledger-based undo tool with annotations and a simple schema, the description covers what is undone, what is restored, why the operation may be refused, which run is targeted by default, and how preview mode works. No output schema is present, so no return-value explanation is needed.

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 only 50%, and the apply parameter has no schema description. The description compensates by explaining that apply defaults to false and previews unless apply is true, while also clarifying the runId default as the latest not-yet-undone run.

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 states a specific verb and resource: it reverses an auto_structure_groups run from the ledger. It clearly distinguishes the undo operation from the forward auto_structure_groups tool by naming what gets deleted and restored.

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?

It gives clear usage context: default targets the latest run not yet undone, previews unless apply is true, and refuses while a construction stage uses one of the affected groups. It does not explicitly name alternatives such as auto_structure_groups or stages_undo, so it falls short of the highest bar.

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