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

Goes well beyond the annotations by disclosing the required WordPress capability and, importantly, that the call is queued for human approval through Royally so nothing changes on the site until then — critical context that destructiveHint alone does not convey. It stops short of saying whether a completed deletion is reversible (an mcp_undo_last_operation sibling exists) or whether child items are affected.

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 tight sentences with the destructive action and the approval gate front-loaded; nothing is padded. The inline "(site: demo.royalplugins.com)" duplicates the site_id enum description and is the only redundant element.

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 tool with no output schema this covers the key facts (capability, gate, target site), but leaves open what the agent gets back, what happens on approval failure, and how to discover the menu_item_id. Adequate but with clear gaps for a mutation tool.

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 only 50%: site_id is documented in the schema, but menu_item_id is a bare integer with no explanation in either schema or description. The description does not explain how to obtain a valid menu_item_id or whether the site_id enum is the only permitted value, so it fails to compensate for the coverage 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 ("Delete a menu item"), which is immediately distinguishable from the read/create/update menu-item siblings. It does not explicitly name alternatives such as wp_update_menu_item or wp_reorder_menu_items, but the operation itself is 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?

The description implies the correct context via the edit_theme_options prerequisite and the approval flow, but never says when to delete versus trash/update, nor points to wp_get_menu_items for locating the ID. Usage is inferable rather than guided.

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