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

Annotations only declare mutability, open-world, idempotent, non-destructive; the description adds substantial context beyond them — no credit cost, a two-phase confirm-to-publish protocol, single-use tokens, a no-op path for already-live sites, an indeterminate-outcome path, and the owner-only authorization requirement. Nothing here contradicts the idempotentHint, since re-invocation against a live site is described as a no-op.

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 first sentence front-loads what and where, and the two-phase protocol follows in the order an agent needs it. It runs long and repeats the token mechanics that the schema already sketches, so a sentence could be trimmed, but nearly every clause carries decision-relevant information.

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?

A stateful, multi-call publish flow with authorization and failure paths is fully described, and an output schema exists to cover return values so the description needn't. An agent can execute the whole happy path plus the already-live and unknown-outcome branches from this text alone.

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 100%, so baseline is 3, but the description genuinely adds meaning: subdomain character/length rules, that it applies only on the first call and only when the person chose a name, the fallback to iter0's suggested address, and that the token must be passed back unchanged. The designId's provenance is only in the schema, which keeps this short of a 5.

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 ('Puts a saved site live at its own free address, name.iter0.app') and immediately scopes it away from siblings by describing the publish act itself rather than a push, status check, or unpublish. The address format makes the outcome concrete and distinguishable from iter0_push_site or iter0_check_site.

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?

Gives explicit when-to-call semantics: no token returns address + token, re-call with the token publishes, an already-live up-to-date site needs no token, and an unknown outcome routes to iter0_publish_status by name. It also names the owner-only precondition, which is a genuine eligibility gate rather than a hint.

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