shopify_delete_menu

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

Despite annotations already carrying destructiveHint=true, readOnlyHint=false, and idempotentHint=true, the description adds substantial beyond-annotation behavior: the collateral damage ("any theme section bound to the menu handle loses its links"), the retention of a sanitized recovery snapshot with independent provider-side absence verification, and the specific auth error and remediation path. This is exactly the kind of contextual disclosure an agent needs before invoking a destructive operation.

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?

The description is front-loaded: the destructive core, precondition, safety net, and collateral damage all appear in the first paragraph before the Args block. The parameter list is cleanly structured. It is verbose and dense with governance jargon ("governed semantic preimage", "semantic-tree digest"), which is necessary for this domain but slightly heavier than an ideal minimal definition.

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 complex destructive tool with 8 parameters and no schema-level descriptions, the definition is nearly complete: it covers preconditions, failure modes, auth requirements, idempotency, and every parameter. The one gap is that the workflow for obtaining expected_preimage_sha256 is only referenced via "governed get_menu semantic-tree digest" rather than spelled out as a sequence, and the role of approval_ref in the write-resumption flow is hinted at but not fully sequenced.

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 0%, placing the full burden on the description, and it fully compensates. All 8 parameters receive meaningful explanations in the Args block: menu_id is typed as "numeric or GID", expected_preimage_sha256 is tied back to the governed get_menu digest, effect is described as claimed and verified by Spring, and approval_ref is contextualized as "when resuming a write". No parameter is left unexplained.

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 opening clause "Permanently delete a storefront navigation menu" states a specific verb, resource, and permanence qualifier. The additional precondition ("only while its exact governed semantic preimage still matches") sharpens the scope, and the destructive consequence distinguishes it clearly from sibling tools like shopify_get_menu, shopify_create_menu, and shopify_update_menu.

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 strong when-to-use context: the preimage-matching precondition must hold, and it warns that a connection lacking online-store-navigation scopes will fail with SHOPIFY_NAVIGATION_SCOPE_REQUIRED, including the recovery action (offer a Shopify reconnect). However, it never explicitly names alternatives or says when NOT to use this tool versus shopify_get_menu or shopify_update_menu, so the exclusion guidance is left implicit.

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