Pop Undo Stack

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

With no annotations provided, the description carries full responsibility. It clearly states the behavior: it pops up to `steps` entries, stops early on empty stack, and returns `steps_performed`. This gives the agent a good understanding of the tool's behavior without contradicting any annotations.

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 extremely concise: two sentences that cover the core operation, default behavior, edge case, and return value. Every sentence adds value with no waste.

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 simple tool with one parameter and no output schema, the description covers the parameter semantics, default, edge case (empty stack), and return value. It is fully self-contained and sufficient for an agent to use 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 provides 100% parameter coverage with a description and default value. The description adds context by explaining the 'pop up to' behavior and early stop, which goes beyond the schema's basic definition. This is valuable for correct invocation.

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 it pops undo entries from the active document's undo stack. The verb 'pop' accurately describes the action, and the resource 'undo stack' is unambiguous. There are no sibling tools with similar functionality, so it is well-distinguished.

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 explains that the tool stops early if the stack empties and returns the number of steps performed, which helps the agent know how many steps were actually undone. While it doesn't explicitly mention when to use vs. alternatives, the lack of an alternative undo tool makes this less critical.

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