undo

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

No annotations are supplied, so the description carries the full burden and does not meet it. It never states that this mutates image state and history, whether the redo stack is invalidated, or what happens when 'steps' exceeds the available history; the 'Returns: {steps_undone}' line is the one useful hint that fewer steps may be undone than requested.

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?

Short, front-loaded, and structured with a Parameters block and an explicit Returns line. The section labels are slightly ceremonial for only two parameters but no sentence is wasted.

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?

With no annotations and no output schema, the description must be self-sufficient; it covers the parameters and the return shape but omits preconditions, failure behavior on exhausted history, and whether the redo stack survives. Adequate to invoke the tool, incomplete for predicting its side effects.

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 compensate, and it does: both parameters are named with defaults, and 'steps: Number of undo steps' clarifies that the value is a count of undo operations rather than a history index. What 'image_index' indexes into (the list_images ordering) is left implicit, which keeps it from a 5.

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 gives a specific verb and resource ('Undo one or more operations on an image') and implies a scope of multiple steps. It is clearly distinguishable from the sibling 'redo' by name, though the description itself never names redo as the counterpart.

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?

There is no when-to-use guidance, no mention of preconditions (an open/active image, a non-empty history stack), and no routing to the alternative 'redo'. The only implied usage is that the tool applies to a target image via image_index.

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