Restore a document to a previous snapshot only if the current revision matches the expected revision, preventing accidental overwrites of newer changes.
Guarded snapshot restore with explicit current revision. Inspect current changes first; use document_duplicate to compare without modifying current work.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | Yes | ||
| documentId | Yes | ||
| snapshotId | Yes | ||
| operationId | Yes | ||
| expectedRevision | Yes |
Changes observed during successful MCP inspections.
v0.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds meaningful context: the restore is guarded by an explicit current revision (expectedRevision), implying a conflict check, and advises inspecting changes beforehand to avoid unintended data loss. This goes beyond the raw hint without contradicting it.
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?
Two sentences, both purposeful. The first states the tool's core purpose, the second gives usage guidance and a sibling alternative. No filler, front-loaded, and easily digestible.
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?
Despite the workflow hint, the description omits critical details for a destructive operation with five required parameters: how to obtain expectedRevision, what happens on revision mismatch, whether the restore overwrites all current changes, and the response format. The lack of output schema and parameter explanations leaves the agent under-informed for correct invocation.
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. It only hints at expectedRevision as 'explicit current revision' but does not explain documentId, snapshotId, operationId, or actor. This is insufficient for a tool with five required parameters; the agent cannot deduce the purpose or format of the other fields from the description.
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 action (snapshot restore) and a key characteristic (guarded, requiring explicit current revision). It differentiates from siblings by noting document_duplicate as a non-destructive alternative for comparison. The verb 'restore' plus resource 'snapshot' is specific and unambiguous.
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?
Explicitly instructs to inspect current changes first and names document_duplicate as the tool to use when comparison is needed without modifying work. This provides clear when-to-use and when-not-to-use guidance relative to a sibling, leaving no ambiguity about workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.