Undo and redo

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

The annotation `destructiveHint: true` is already declared, but the description meaningfully adds context: it discloses the partial-failure behavior ('the stack runs out, and an undo that did nothing otherwise looks exactly like one that worked'), clarifies that the server's own writes are pre-wrapped in undo recordings, and warns that the history 'covers the whole session, including the user's own edits.' These are important behavioral traits that annotations alone cannot convey. There is no contradiction between description and 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 moderately long, but every paragraph earns its place — it fronts the core statement of what it does, then explains when to use it, then the critical edge case, and finally the safety warning. Nothing is wasted, and for a destructive tool, the added length is fully justified. It could be tightened slightly, but the density of information is well-matched to the risk profile.

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 tool with no output schema, the description's disclosure that 'It reports how many steps actually applied' is essential return-value context. The description covers the full picture — the mechanics, the failure modes (stack exhaustion), the risks (resetting user work), and the safety guardrail — while the parameters and annotations are all declared. The tool's complexity (3 params, a destructive flag, no nested objects) is thoroughly addressed. There is no meaningful gap an agent would need to resolve before calling this 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?

With 100% schema description coverage, the schema already documents all three parameters completely, so the baseline is 3. The description adds extra value by explaining the edge case relevant to the `steps` parameter — that over-requesting is possible and will silently return fewer steps, and by clarifying how the `action: 'status'` semantics let the caller inspect before mutating. It would have been a 5 with even more explicit per-parameter cross-referencing, but this exceeds the baseline.

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: 'Steps Studio's undo history backwards or forwards' — a specific verb with an explicit resource and scope. It differentiates this from other operations by explaining what it reverses and why ('as cleanly as the user pressing Ctrl+Z — one tool call is one step'). Even though it's named just 'undo', the title 'Undo and redo' plus the description make the full scope clear.

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 provides explicit usage conditions: 'Use it when the user says an edit was wrong, instead of trying to reconstruct the previous state by hand, which is guesswork and usually incomplete.' It also sets clear boundaries with 'Undo only what you just did, and only when asked', and explains the danger case where undoing beyond your own edits will revert the user's work. This is exactly the kind of when-to/not-to guidance that an agent needs.

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