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

Annotations only mark it as destructive/non-idempotent; the description goes far beyond by explaining partial-update preservation, refusal of destructive empty values, the full refusal code list (insufficient_caps, menu_item_not_found, url_dropped, expected_mismatch, field_dropped), the required edit_theme_options capability, and the fact that nothing changes until a human approves it in Royally. That last point is critical and not derivable from annotations.

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-loaded with the core update semantics and the destructive-clearing caveat before the preview and refusal-code detail. It is dense — the refusal-code run-on sentence and the em-dash clauses are heavy — but nearly every clause carries actionable information.

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 mutation tool with no output schema, nine parameters, and 33% schema coverage, this covers capability requirements, dry-run behavior, concurrency guard, failure modes, and the approval gate. The remaining gap is the undocumented ordering/nesting parameters (position, parent_id) and target, which an agent must infer.

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 33%, so the description has to compensate: it gives real semantics for `title`/`url` (empty values refused, post_type/taxonomy items keep their own link), for `dry_run` (returns current vs proposed, changes nothing), and for `expected` (stale-read guard). It leaves `position`, `parent_id`, and `target` entirely unexplained, which is a genuine gap for a 9-parameter tool.

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 first sentence names a specific verb and resource ('Update an existing menu item') and the description immediately distinguishes the operation from wp_delete_menu_item/wp_create_menu_item by naming those siblings as the route for clearing values. An agent can tell what this tool is and is not without opening the schema.

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?

It states when to use this tool (partial updates that preserve unspecified fields), when to use an alternative (explicitly clearing title/url requires delete + create), and how to preview safely (dry_run true). The conditional guard pattern with `expected` is also documented with its trigger condition ('when the item changed since it was read').

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