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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses the undo envelope with a 7-day token consumable by mcp_undo_last_operation, partial-failure behavior via the 'skipped' array, and the human-approval pause where nothing changes on the site until approved. These are exactly the mutation-side traits an agent needs before calling.

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?

Front-loads the action and orders the rest by importance (preservation, undo, partial failure, permission, approval). Slightly overloaded — the inline '(site: demo.royalplugins.com)' duplicates the site_id enum and the approval clause is tacked onto the end.

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, non-idempotent mutation with no output schema, the description covers safety, rollback, partial failure and permissions — nearly everything needed. Minor omission: how reordering interacts with nested parent hierarchies, and what the response body looks like outside the undo/skipped envelopes.

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?

Adds real meaning beyond the 67%-covered schema: the array determines final positions, and the 'skipped' discussion implies partial orders are tolerated rather than requiring every item. It never clarifies whether menu_id must be an existing menu or whether item_order must be exhaustive, which is the remaining gap.

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 ('Reorder menu items') plus the exact mechanism (an array of menu_item_ids in desired order). It is clearly distinguished from siblings like wp_update_menu_item by noting that titles, URLs, parents and other fields are preserved, so only ordering changes.

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 the precondition ('Requires edit_theme_options capability') and the operational context (approval gate via Royally), which tells the agent when the call is valid. It stops short of naming alternatives — e.g. that changing a title or parent is wp_update_menu_item's job — leaving that inference to the agent.

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