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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds real behavioral value on top: the get-or-create fallback ('returns the existing one if the name is taken') and the operational prerequisite that the tool is writes-gated and needs Xyle Connector v0.6.0+. There is a mild tension between the get-or-create behaviour and idempotentHint=false, but it is a hint-level nuance rather than a direct contradiction of a stated effect.

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?

Three short clauses, zero padding: the create semantics and collision behaviour are front-loaded, the workflow pointers follow, and the version/gating note is last. Every sentence earns its place.

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 two-parameter, no-output-schema tool this covers the creation semantics, collision behaviour, follow-on workflow, and access gating. The one gap is that it does not say the response yields the menu identity needed to call wp_set_menu_items next; with no output schema, that handoff detail is left implicit.

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 description coverage is 100%: both 'name' and 'site_id' are already documented in the schema with an example value. The description adds nothing beyond that for either parameter, so the baseline of 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 + resource ('Create a WordPress nav menu by name') and immediately bounds the case where the object already exists. It also names the follow-on tools (wp_set_menu_items, wp_assign_menu_location), which distinguishes it from the other wp_* menu siblings an agent sees in the list.

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 gives forward workflow context — create the menu here, then populate it with wp_set_menu_items and attach it with wp_assign_menu_location — which is exactly the sequencing an agent needs. It stops short of an explicit 'do not use this to add items or assign locations' exclusion, so it is clear context rather than a full when/when-not pair.

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