figma_history

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

Annotations carry only openWorldHint=false, so the description bears the burden of behavioral disclosure. It reveals critical behavior: undo's 60-second window, the one-step-per-call consolidation into the file's undo history, and the fallback that a person can Ctrl+Z afterward. It also clarifies snapshot is a restore point, which is meaningful beyond the schema.

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 two action-labeled clauses make the structure scannable and avoid repetition. The undo sentence is long and packs several conditions into a semicolon-connected run-on, but every clause earns its place and the content is dense rather than padded.

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 two-action tool with no output schema, the description covers both operations, their preconditions, the relevant sibling tools, the time window, and the post-window fallback behavior. Nothing essential is missing for an agent to decide when and how to invoke it.

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 67%, and title/description params are already documented as snapshot-specific. The description adds value by defining the action enum semantics in detail — what undo reverts, the timeout, and the scoped mutating tools — which goes beyond the bare 'snapshot'/'undo' enum values.

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 defines two distinct operations: snapshot (save a named version) and undo (revert the last mutating call). Both use specific verb+resource phrasing, and the action labels make the tool's purpose immediately understandable. The title alone is vague, but the description fully resolves that ambiguity.

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 states when to use snapshot ('before risky edits') and exactly what undo applies to (the last mutating call among figma_eval, figma_place_image, or library import) with a 60-second condition. It does not explicitly name exclusions or alternative tools for inspecting history, so it stops short of a full when-not-to-use guideline.

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