undo_list

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

Annotations only declare readOnlyHint, yet the description discloses substantial behavior: an extra row is read so 'truncated' is measured rather than inferred, effectVerified=false means the reversed change is probable not confirmed, and it warns against reporting an unverified restore. This is well beyond what the annotation covers.

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?

Front-loaded with purpose, then usage, then a non-obvious implementation note, then args. The paragraph on effectVerified is long but every clause carries decision-relevant information; nothing is filler.

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?

No output schema exists, so the description supplies the return shape itself (original tool, inverse tool, human note, truncated, effectVerified) plus the truncation semantics. Nothing an agent needs to call and interpret this tool is missing.

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 burden — and it does: limit is documented with default 50 and a cap of 500 (the cap is absent from the schema), and target is explicitly marked unused and explained as CLI uniformity.

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 ('List recorded, not-yet-applied undo tokens') with ordering scope ('most recent first') and the [READ] marker. It is immediately distinguishable from its sibling undo_apply, which it names.

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?

Explicitly routes the agent onward ('Use the undoId with undo_apply') and gives a conditional check before applying when effectVerified is false. It doesn't state an explicit when-not-to-use case for undo_list itself, but the workflow context is clear.

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