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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real context: no code is returned, the card renders the design, and edits made via iter0_edit_site become the design's current page with Undo offered. Useful behavioral detail beyond the safety hints, though it doesn't mention error behavior for a stale or foreign designId.

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 return content is front-loaded, which is good, but the description is a long semicolon-chained run that mixes return fields, edit semantics, scope exclusions, and a payment disclaimer. The out-of-scope tail (credits, payment, domains) is boilerplate that dilutes the core sentence.

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?

An output schema exists, so return shapes need not be spelled out, and the description still names the key fields plus the edit/undo relationship. Only the designId acquisition path is missing, which is the one thing an agent needs to actually call it.

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% for the single designId parameter, and the description only alludes to it indirectly ('iter0_edit_site takes this designId'). It doesn't say how the ID is obtained or what it identifies beyond a design, so it only partly compensates for the empty schema.

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 and resource ('Read one of the person's iter0 designs') and enumerates what comes back: name, link, section IDs and labels, headline, short summary as text. It also explicitly says the page's code is not returned, which sharply bounds the tool against page-reading siblings like iter0_read_canvas_page.

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?

Clearly positions the tool in a workflow: iter0_edit_site consumes this designId, so read first then edit. It also enumerates out-of-scope requests (general design/branding advice, hosting elsewhere, domains, payments). The notable gap is that it never names iter0_list_my_designs as the way to obtain a designId, so discovery is left implicit.

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