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

Adds materially beyond the annotations: it discloses that the operation is gated on human approval in Royally and that 'nothing on the site changes until then', which qualifies the destructiveHint=true and non-idempotent hints rather than repeating them. It also surfaces the refusal/retry semantics tied to edited_since_write via the token staying valid. It does not say how long a token remains valid or whether it is single-use.

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 core behavior is front-loaded in one good sentence, but it is followed by an exhaustive 30-plus tool enumeration that dominates the length and reads like reference documentation. The final 'Through Royally' sentence also appears clipped mid-thought, hurting structural clarity.

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 destructive, approval-gated mutation with no output schema, the description covers the token source, scope of supported operations, and the human-approval gate that determines whether anything happens. Gaps remain around token expiry, reuse, and result reporting, but the agent has enough to call it correctly.

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 token, force, and site_id are already fully documented in the schema, including the force/escalation semantics. The description only restates the token origin, adding no syntax or format detail beyond the schema; baseline 3 applies.

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?

States a specific verb and resource ('Reverses a prior tool operation') and pins down the exact input identity ('the undo token emitted in that tool's response envelope, surfaced as structuredContent.undo_token'). The supported-tool list further distinguishes it from siblings like fleet__undo or wp_restore_revision.

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?

Gives a clear trigger condition (you have an undo token from a prior tool response) and enumerates which tools emit usable tokens, which effectively bounds when the tool applies. It does not explicitly contrast with alternatives such as wp_restore_revision or fleet__undo, so it stops short of full when-not guidance.

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