Add a menu item

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

Goes well past the annotations: append-at-end positioning, non-deduplication on repeated calls, rejection of javascript:/data: schemes, required capabilities (edit_theme_options plus assign_term, which a site can withhold per menu), and the absence of an undo point. The duplicate-add and no-undo disclosures corroborate idempotentHint=false and destructiveHint=true rather than contradicting them.

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?

Five compact sentences, front-loaded with verb, resource, and placement, then behavior, then constraints, then permissions and recovery. No filler and no restatement of the title.

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?

With 6 params and no output schema, the description covers the return shape ("Returns added and item_id"), the failure mode for bad URLs, capability requirements, and the recovery tool. Nothing an agent needs to call this mutation correctly is missing.

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 the baseline is 3; the description earns above that by framing the object_id-vs-url precedence as a mode choice rather than a per-field note, which is the main semantic decision when calling this tool. It does not add syntax or format detail (e.g. parent/item_id lookup) beyond the schema.

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 ("Add a published item to a navigation menu") plus position ("at the end"), then immediately disambiguates the two operating modes: content link via object_id vs custom link via url. An agent can tell this apart from wp_create_menu and wp_delete_menu_item without opening any 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?

Explicitly gives the selection rule between the object_id and url paths, warns that duplicate targets still create new items, and names wp_delete_menu_item as the removal path. It does not state the prerequisite that the menu must already exist (wp_create_menu / wp_list_menus is only implied by the menu param description), so it stops short of full when/when-not coverage.

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