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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description goes further by disclosing that a key belongs to the TEMPLATE so one change propagates to every page using that layout, and that the change reaches the exported WordPress site, not just the canvas. Those are exactly the mutation side-effects an agent needs; return format is the only omission, which the absence of an output schema makes minor.

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?

Four sentences, all carrying load, with the one-vs-site-wide distinction front-loaded. It is on the dense side but nothing is wasted and the ordering prioritizes the disambiguation first.

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 3-param mutation tool with no output schema, the description covers what it mutates, where the key comes from, what scope the change applies to, and how to revert it. Only projectId's role and the persistence/export timing are left unstated, which are minor gaps.

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 67% and the description compensates: it explains that buttonKey is the button's own text_… or icon_url_… slot key sourced from uichemy_get_page, and clarifies role semantics. projectId is left implicit, but the key-sourcing detail is the piece an agent would otherwise get wrong.

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 (set one button's role) and immediately differentiates from the sibling uichemy_set_button_design, which is the site-wide design. An agent can distinguish the two without opening either 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 says this is the per-button control rather than the site-wide one, tells the agent where to get the key (uichemy_get_page lists label/icon slots) and names reset as the undo path. When-to-use and the alternative are both covered.

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