wp_posts_restore_revision

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

With no annotations, the description must carry the full transparency burden. It discloses exactly which fields are restored (content, title, excerpt) and the important side effect that the parent's current state becomes a new revision automatically, implying reversibility. It doesn't mention permissions, return value, or validation behavior, which prevents a 5.

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 sentences, each earning its place: the first states the purpose, the second explains the mechanism, the third discloses a critical side effect. No vague or redundant language. Front-loaded with the core action.

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 restore tool with no output schema, the description covers the core behavior and its most important consequence (new revision created). It doesn't mention the return value, permissions, or what happens if the revision is invalid, but it is otherwise sufficient for an agent to understand the tool's role.

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?

The schema has no descriptions (0% coverage), so the description must compensate. It clarifies that post_id refers to the parent post and revision_id to the revision being restored, but it doesn't explicitly state that the revision must belong to the post or describe any error conditions. This is adequate but not thorough.

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 'Restore a previous revision of a post' and details the exact mechanism: reads content, title, and excerpt from the revision and writes them back to the parent post. This is specific enough to distinguish it from siblings like wp_posts_get_revision (which only reads) and wp_posts_get_revisions (which lists revisions).

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 use case is clearly implied: use this to roll back a post to a previous revision. However, there is no explicit guidance about when not to use it or comparisons with alternatives (e.g., using wp_posts_get_revision to inspect a revision before restoring). The absence of explicit exclusions or alternative references keeps it slightly below a 4.

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