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

With destructiveHint=true and idempotentHint=false already in annotations, the description still adds real value: it discloses that changes happen in place, that it takes about a minute (latency expectation), and that there is no undo. It stops short of saying what happens on an ambiguous or failing instruction, or what the returned result contains.

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?

Two sentences, front-loaded with the operation and followed by the operational caveats (in-place, ~1 minute, no undo). Every clause carries information; no boilerplate or repetition 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?

For a three-parameter mutation tool with no output schema, the description covers the essentials an agent needs to call it responsibly: input style, in-place mutation, latency, and irreversibility. Gaps are minor — no guidance on error or ambiguity handling, and no statement of what the call returns beyond the edit happening.

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 for the weakest-documented parameter by clarifying that 'instruction' is free-form natural language in the user's own words, reinforced by three examples that communicate the expected granularity and phrasing. It adds nothing for projectId and only implicitly reinforces design as 'one design' from a set of three.

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?

Specific verb and resource: 'Changes one finished design from a plain instruction', with three concrete example instructions that make the operation unmistakable. This clearly separates it from create_designs (makes new designs) and get_designs/get_design_html (read-only) without needing to name them.

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?

Usage is implied well by the examples ('make the hero darker', 'swap the order...') — an agent understands this is for tweaking an existing design. But it never states when NOT to use it (e.g. creating a new design vs. editing one) or names the sibling alternative, and prerequisites like 'design must already exist and be finished' are only hinted at by the phrase 'one finished design'.

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