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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is partly covered. The description adds real behavior beyond that: the confirm gate makes the call a no-op without it, and the omission rule clarifies that leaving a list out is non-destructive for side items, which directly softens the destructive hint. It stops short of saying what happens to top-menu entries or existing items that are not restated.

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 core rules are front-loaded and useful, but roughly half the text is a bulleted-out icon name list that repeats structured enum data and is truncated relative to the schema. That duplication is what makes the description long, not the information an agent actually needs, so it does not earn 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 destructive, idempotent, three-array mutation tool with no output schema, the description covers the confirm gate and side-item omission semantics. It does not address the most consequential unknown, whether setting navigation replaces or merges with existing top-menu items, and it does not distinguish the tool from crm_set_menu or upsert_menu, so it is incomplete for a destructive write.

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%, so the schema already documents confirm, top, side, target, model, and view. The description adds some meaning the schema lacks, notably that a top item names a list and that side target must be dashboard, model, or view. However, the long icon enumeration duplicates the schema's enum and is actually an incomplete subset, since the schema also allows flashOutline, hardwareChipOutline, receiptOutline, and many short aliases, so it adds less value than its length suggests.

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 gives a specific verb and resource: it sets both the side menu and the top menu, and the rest of the description explains what a menu item is. However, it never distinguishes itself from the close siblings crm_set_menu and upsert_menu, which also appear to write menu data, so an agent cannot tell from this text which one to pick.

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 gives one imperative usage rule, 'Does not save unless confirm is true', which usefully implies a preview-then-commit workflow. It also gives one omission rule, 'A list you leave out stays on the side menu'. But there is no guidance on when to choose this tool over crm_set_menu, upsert_menu, or crm_get_menu, which are the most likely alternatives.

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