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

Annotations declare destructiveHint=false, and the description earns credit by explaining why: 'Nothing is deleted: a later change branches off', which tells the agent that undo is history-preserving and reversible via restore_revision. It also discloses the conflict-refusal behavior of expect_revision ('nothing moves'), which is real behavioral context beyond the annotation flags. It does not address idempotency (repeated undo keeps stepping back) or what the call returns.

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?

Three short sentences with the core behavior front-loaded and the safety note immediately after. The opening clause is slightly cryptic, and the restore_revision/mutex details, while useful, could be tightened, but there is no 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?

For a two-optional-parameter versioning tool with no output schema, the description covers what undo does, that it is non-destructive, how to go forward again, and how the optimistic-concurrency parameter behaves. What is missing is failure framing (e.g., error if steps exceeds available history) and any hint of what the result reports.

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 coverage is 100%, so both parameters are already documented in the schema, including the expect_revision conflict semantics. The description largely restates that (a write since your read is refused), adding only the emphasis that state does not move on refusal. Baseline 3 is appropriate when the schema does the heavy lifting.

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 conveys a specific operation (moving the model state back by N revisions) and explicitly names the inverse sibling restore_revision, which lets an agent separate the two. However, the phrasing 'Serves the state steps revisions back' is grammatically awkward and takes a moment to parse, which costs a point against a clean verb+resource statement.

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 gives clear context for when to use this tool (retreating revisions) and contrasts with restore_revision, which 'goes forward again'. It also explains the expect_revision use case (refuse a concurrent write rather than take it back). There is no explicit 'do not use when' clause, but the alternative is named with its selecting condition.

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