Restore a page to an earlier version

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

With no annotations, the description fully carries the transparency burden. It explicitly discloses the non-destructive behavior: 'appends a new version to the page’s history rather than erasing anything,' that intermediate edits remain, and that a mistaken restore can itself be restored. These are behavioral traits not derivable from the tool name or 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 description is three sentences, each earning its place: purpose, behavioral clarification, and usage workflow. It is front-loaded with the core function and remains concise without fluff.

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 simple two-parameter tool with no output schema, the description covers the essential context: what it does, the nature of the operation, and how to obtain the required inputs. It could mention the return format or permissions, but these are not critical for a basic restore operation. The non-destructive nuance is well explained.

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 the baseline is 3. The description adds minimal parameter insight beyond the schema: it reiterates that versionId comes from wiki_page_history, which the schema already states. No additional semantic detail is provided for pageId or versionId.

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 opens with a specific verb+resource: 'Roll a page back to an earlier version from its history.' It also distinguishes the tool from siblings by calling it 'the undo for everything else this connector can do,' making its role unique among the listed tools.

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 gives clear usage context: retrieve the versionId from wiki_page_history and preview with wiki_get_page_version before restoring. It implies the appropriate workflow and positions the tool as a general undo mechanism, though it doesn't explicitly state when not to use it or name alternatives beyond the preview/history tools.

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