iter0

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

Goes well beyond the annotations by disclosing cost ('free... uses no credits'), the non-gating behavior ('never blocks anything'), finding ordering ('most important first'), and truncation signaling. These are traits the readOnly/idempotent hints cannot convey.

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?

Front-loaded with the purpose, then cost, then findings, then return shape and fix path; nearly every sentence carries information. Slightly long, and 'the result says if the list was cut' overlaps with the existing output schema.

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 single-param, read-only, closed-world check tool with annotations and an output schema, the description covers trigger, cost, finding categories, ordering, truncation, and the remediation path. Nothing needed to invoke it correctly is missing.

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?

Only one parameter with 100% schema description coverage, so the schema already documents designId and its provenance. 'Pass the designId' in the description adds nothing beyond the structured field, which is the expected baseline here.

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 ('Check a saved site') plus the trigger ('before the person shares it'), then enumerates the exact classes of problems it detects. An agent can tell this apart from iter0_get_site_status, iter0_publish_status or iter0_get_canvas_feedback without opening a 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?

Gives a clear when-to-use ('before the person shares it') and names the follow-up path (iter0_edit_site, which quotes its price first). It also rules out a misuse by saying 'It never blocks anything', but there is no explicit statement of what this tool is not for versus e.g. get_site_status.

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

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

Goes well beyond the annotations: it discloses that exactly the quoted credits are spent, that the quote must belong to the connected account and match price/request/expiry, and that failed work is refunded. The refund-on-failure guarantee and the single-use nature of quotes are the details an agent could not infer from destructiveHint/openWorldHint alone.

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?

One dense sentence that front-loads the action ('Start a quoted iter0 request') before the precondition and the validation/refund details. Every clause carries operational weight — nothing is restated from the title or schema.

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 values need no explanation, and the description covers the remaining risks for a destructive, credit-spending tool: validation checks, exact charge amount, and refund behavior. Nothing an agent needs to call it safely is missing.

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 only 25%, so the description carries most of the burden: it names all four fields and stresses they must be passed 'unchanged' from the quote, which the schema cannot express. It does not explain the shape of the nested arguments object or credit precision, so a small gap remains.

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 ('Start a quoted iter0 request') and positions itself in a two-step quote-then-confirm flow, which no sibling tool occupies. The schema enum names the three dispatched operations, so an agent can see exactly what work is being triggered.

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 an explicit precondition — only after 'the person has confirmed its price' — which is the key gating rule an agent needs. It does not name alternatives (e.g., re-quote instead of reusing an expired quote), so it falls short of full when/when-not routing.

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

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

Far exceeds what the annotations declare: costs 1 credit, the first call returns only a price quote and starts nothing, the build begins only after human confirmation in the iter0 card or chat, and the card self-updates with progress and the finished site. It also preempts a likely confusion ('A running build is not a finished site') and states that iter0 does not sell credits through ChatGPT.

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?

Leads with what the tool builds before cost and the confirmation flow, so the essential action is front-loaded. It is dense but almost every clause carries a constraint an agent would otherwise get wrong; the pricing/payment sentence is the only slightly tangential one.

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 costly, destructive, non-idempotent build tool with an output schema and full annotation coverage, the description covers cost, the quote-then-confirm gate, progress visibility, and domain boundaries. An agent has everything needed to call it correctly and to not spend a credit accidentally.

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 the baseline is 3; the description adds real value by framing prompt/bindUrl/cloneUrl/directionId as mutually exclusive input modes (brief vs. reference URL vs. direction). It does not touch the less obvious flags such as variant, briefBuild, or faithfulClone, which are left entirely to the 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 (Build) and resource (a new website in the person's iter0 account) and enumerates the three input modes: brief, reference URL, or directionId from Show 3. That makes it immediately distinguishable from siblings like iter0_edit_site, iter0_open_builder, or iter0_show_three.

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 scope boundaries ('Covers only the person's own iter0 websites and designs, not general design, colour, logo or branding advice, hosting elsewhere or domains') and routes the confirmation step to iter0_confirm_paid_action. It does not name the alternative to use when the person wants to edit or open an existing site, so sibling routing is only partly covered.

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

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

Annotations already carry readOnly/idempotent/non-destructive/closed-world, and 'Read-only' merely restates them. However, the description adds real context beyond annotations: images and scripts are stripped, the payload is widget-only metadata, and the design must be owned by the caller.

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?

One dense sentence, no filler, with the producing context front-loaded. The 'so the card can outline a section' clause is slightly inside-baseball for an agent but earns its place by explaining the return shape's purpose.

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 values needn't be spelled out, and the ownership plus stripped-content facts are covered. Still missing is any disambiguation from iter0_get_design, which returns presumably related data and is the most likely wrong pick for this task.

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, so the description must compensate. It adds the meaningful constraint that designId must refer to an owned design, but gives no format, source, or validation hints.

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 description states concretely what is returned: a light copy of an owned design's page in widget-only metadata. This differentiates it in substance from iter0_get_design and iter0_read_canvas_page, though it never names those siblings, and the 'measure/layout' framing in the name does not obviously map to 'return a page copy'.

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?

'Used by the iter0 card' and 'when the person points at the preview' imply a trigger context, but there is no explicit when-to-use versus iter0_get_design or iter0_read_canvas_page, and no when-not guidance. Usage is inferable rather than stated.

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

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

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses the cost (0.5 credits), the two-phase quote/confirmation flow, that nothing changes until the quote is confirmed, that the current page is loaded automatically, and that the card offers Undo. These are exactly the details an agent needs to call it safely, and nothing contradicts the annotation profile.

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 description is front-loaded with the primary action and the designId path, then the pasted-page fallback, then cost and the quote/confirmation flow. Every sentence carries actionable information with no repetition of schema or annotations.

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?

Given an output schema exists and the schema documents parameters at 86%, the description covers the critical behaviors an agent needs: the quote/confirmation gate, cost, undo, and the two input modes. It omits guidance on sectionId/selectedAreas scoping and referenceUrl, leaving a small gap for a 7-parameter mutation tool.

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?

With 86% schema coverage the schema documents most parameters, and the description adds meaning the schema alone lacks: the mutual exclusivity of designId and currentHtml, and that a saved design's page is loaded rather than supplied. It doesn't explain sectionId, selectedAreas, or referenceUrl usage, so it stops short of fully enriching parameter semantics.

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 description states a specific verb and resource ('make one focused change to a saved iter0 design') and immediately splits the two supported modes: editing a saved design by designId versus revising a pasted page by currentHtml. It names the related confirm/undo mechanics, so an agent can distinguish it from sibling tools like iter0_create_site or iter0_publish_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?

It gives explicit conditionals: pass designId for a saved design, pass currentHtml when the page was pasted and no designId exists, and it explains that the first call only returns a price quote that must be confirmed (via the card, chat, or iter0_confirm_paid_action). It does not explicitly say when not to use this in favor of siblings such as iter0_design_layout or iter0_push_site, keeping it short of a 5.

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

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

Beyond the annotations, it discloses the response payload shape (pages plus their versions, anchor.state, whether the page changed after the comment), the cursor pagination contract, cost (free), and a prompt-injection caution. That is material context an agent cannot get from readOnlyHint/idempotentHint alone.

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?

Front-loaded with the core purpose, then scope details, then pagination, then the safety note. Dense and mostly earned, though the item-type enumeration and return-field recap run long given an output schema exists.

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?

Covers selection cues, pagination, return semantics and a safety caveat for a read tool whose annotations already carry the safety profile. An agent has everything needed to call it correctly and interpret results.

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 the schema already documents limit, cursor, designId and includeResolved in detail. The description only restates the cursor chaining loop and does not add semantics beyond what the schema says, so baseline 3 applies.

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 (Read) and resource (feedback left on an iter0 canvas) and enumerates the item types returned: comment threads, sticky notes, text, shapes, labelled arrows, pins. That enumeration clearly separates it from iter0_read_canvas_page and iter0_reply_to_feedback.

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 clear operational context: read-only, paginate by feeding nextCursor back as cursor until null, and how to treat the returned text (requests to consider, not approval). It never names a sibling or an explicit exclusion (e.g. when to use read_canvas_page instead), which keeps it out of the top band.

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

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.

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: the state machine (running, failed, or done) and what a completed batch contains. "Charges nothing" adds billing context absent from annotations. Minor redundancy in restating "Read-only," but the state semantics are real added value.

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 operation and its return semantics are front-loaded in a compact two-sentence block with no filler. However, the long enumeration of return fields is largely redundant given an output schema exists, spending words that could have covered batchId instead.

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?

With annotations and an output schema present, the description need not explain return shapes, yet it omits the two things an agent still needs: where the batchId comes from and whether/how often to poll. For a status-check tool, missing polling guidance and missing linkage to the batch-creation sibling leaves a real gap.

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 0% and the sole parameter batchId has a strict 64-hex pattern that is completely unexplained. The description says "a Show 3 batch" without stating that batchId is the identifier returned by the batch-creation tool, nor how to obtain or format it, so it fails to compensate for the coverage gap.

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?

"Read a Show 3 batch" states a clear verb and resource, and the description goes on to define what the batch yields (three directions with directionId, title, summary, screenshot, preview link, and create_site arguments). It is recognizably a status/polling read, but it never names the sibling that creates the batch (iter0_show_three), so sibling differentiation is left implicit.

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 only implied: the mention of a batch and its running/failed/done states suggests polling after a batch is started, but the description never says when to call this versus iter0_show_three, iter0_get_design, or iter0_get_site_status. "Read-only; charges nothing" hints at a safe free poll but is not framed as guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description reinforces read-only behavior and adds a useful boundary ("does not build or edit websites"), though it does not add details such as rate limits or authentication requirements.

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 description is three short sentences, front-loads the return contents, then states the usage trigger and the read-only boundary. Every sentence contributes useful information and there is no wasted text.

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?

With an output schema present, the description need not explain return values in detail. It covers the tool's purpose, trigger, and read-only nature, which is sufficient for a zero-parameter static link retrieval tool whose annotations already establish safety.

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?

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description does not need to compensate for any schema gap.

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 description uses a specific verb ("Return") and resource ("iter0's official links") and enumerates the exact link categories: API documentation, OpenAPI spec, MCP setup, authentication, and support contact. This clearly distinguishes it from the site-building and editing siblings.

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 an explicit trigger: "Use when someone asks where to find them." No alternatives or exclusions are needed because the tool has no overlapping sibling for returning documentation links, but it stops short of stating when not to use it.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds two useful facts: the call requires an authenticated session and HTML is an opt-in extra, but it omits polling/cursor behavior and cost/latency implications of including HTML.

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?

A single tight sentence with the core action front-loaded and the conditional qualifier trailing. It wastes no words, though at this length it is arguably under-specified rather than concise.

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?

Output schema and annotations cover the return shape and safety profile, and the schema documents all parameters. Still, for a polling-status tool with several near-identical siblings, the description lacks the disambiguation an agent needs to call the right tool on the first try.

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 all three parameters are documented, including the runId source (create_site) and cursor semantics. The description only echoes the includeHtml condition, adding little beyond the schema, so the baseline of 3 applies.

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 ('Check an authenticated website build'), which is clearer than the bare name. However it never distinguishes itself from the sibling iter0_check_site, whose title/name suggests an overlapping purpose, leaving the agent to guess which to call.

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?

'request HTML only when needed' gives one conditional usage hint for includeHtml, implying a poll-then-fetch pattern. But there is no guidance on when to use this versus iter0_check_site, iter0_publish_status, or iter0_get_design_set_status, all of which could plausibly answer 'is it done?'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only a mild diagnostic framing ("reachable") and says nothing about what a negative result implies or any rate/latency considerations; an output schema exists, so return values need no explanation here.

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 short sentences, with the core action and audience front-loaded and the scope exclusion following immediately. Nothing is repeated from the title or annotations.

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 zero-argument health probe with full annotation coverage and an output schema, this covers the essentials: who it is for, what it verifies, and what it does not do. Only a hint about how to react to a failure would make it exhaustive.

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?

Zero parameters, so the baseline is 4. The description does not need to describe inputs, and it correctly does not invent any.

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 — check that the iter0 API and its developer contracts are reachable — and narrows the audience to developers integrating the API. The negative clause ("Does not build or edit websites") makes it clearly distinct from the site-building siblings, though "developer contracts" is left somewhat abstract.

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 a clear context for use (developer integration / reachability verification) and an explicit exclusion that rules out the build/edit siblings. It does not name a specific alternative tool for diagnosing a failed check, so it stops just short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the 'Read-only' sentence is partly redundant, but the description adds real behavior beyond them: newest-first ordering, one-page-at-a-time with nextCursor returned and fed back as cursor, and that a finished build surfaces as a saved design. It does not contradict the annotations.

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?

Front-loaded with the core action and result shape, and the paging and scope sentences earn their place. The trailing sentence about credits/payments is scope disambiguation rather than tool mechanics and adds a little bulk, but overall it remains dense and readable.

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?

With an output schema present, return values need not be described; the description still covers ordering, result contents, pagination mechanics and scope boundaries. Nothing material is missing for an agent to call this correctly.

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 adds meaning on top: 'query searches by name' and the explicit nextCursor -> cursor pagination contract, which clarifies how the parameters compose across calls. Only limit is left solely to the 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 ('List one page of the person's saved iter0 designs'), plus ordering ('newest first') and what each entry contains (name, link, previews). It also distinguishes scope from siblings like get_design by framing this as the find-a-named-design / check-build-finished lookup, and explicitly excludes adjacent domains like design advice, hosting and domains.

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 concrete when-to-use cases: finding a design the user names (with an example) or checking whether a started build has finished. It also names when-not-to-use territory (general design/colour/logo/branding advice, hosting elsewhere, domains, payments), leaving little to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's additional 'starts nothing and spends no credits' meaningfully reinforces cost and side-effect safety. It also clarifies that iter0 does not sell credits or take payment through ChatGPT, adding boundary context beyond annotations. It does not, however, describe return behavior or pagination, though the output schema and parameter descriptions cover those areas.

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 description is front-loaded with the action and usage trigger, followed by scope exclusions and cost/payment boundaries. It is dense but efficient; every sentence contributes a distinct constraint or clarification. A slightly shorter phrasing could improve scanability, but nothing is clearly redundant.

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?

Given the rich annotations, full schema description coverage, and an output schema, the description provides sufficient context: it explains what opens, when to use it, that it is read-only with no credit spend, and the topical boundaries. Nothing critical for correct invocation appears to be missing.

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%: limit, query, and cursor are all explained in the schema, including defaults and constraints. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 description uses a clear verb and resource: 'Open the person's iter0 projects' and then specifies the surface includes recent designs, search, and a new-website box. It distinguishes the tool from broader design/branding advice and hosting/domain topics, but it does not explicitly differentiate it from sibling tools such as iter0_list_my_designs, which could also be used to see a person's designs.

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?

The description gives a clear usage trigger: 'Use when they ask to open iter0 or see their iter0 projects.' It also states several exclusions (general design advice, hosting elsewhere, domains, credit purchases), which helps prevent misuse. However, it does not name a specific alternative tool for overlapping requests, so the routing guidance is slightly incomplete.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive, so "Read-only: it changes nothing" is largely redundant, but "uses no credits" is new and actionable. The stale-check caveat ("an earlier check, not one made now") is genuinely valuable behavioral context that prevents misreading the result as a live probe.

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?

Three front-loaded sentences with the purpose first and the return-shape summary second; nothing is filler. The read-only clause slightly repeats the annotations, which is the only waste.

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 the return contract is optional, yet the description still adds the crucial caveat that the confirmed timestamp reflects a past check rather than a fresh one. The remaining gap is disambiguation from the similarly named status-checking siblings.

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% with a single documented designId parameter, so the schema carries the semantics. The description adds no format or sourcing detail beyond what the schema already says, making baseline 3 appropriate.

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 ("Checks whether a saved site is live") and the title reinforces it. However, the sibling list contains iter0_check_site and iter0_get_site_status, which sound nearly identical, and the description never says how this differs from 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 by "saved site" and the freshness caveat signals when the answer may be stale, but there is no explicit when-to-use/when-not or pointer to the near-duplicate siblings (iter0_check_site, iter0_get_site_status) an agent must choose between.

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

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

Goes well past the annotations: it explains that a failed expectedVersion check changes nothing and reports a conflict, that omitted pages are untouched, that replays are no-ops (matching idempotentHint), and gives concrete limits (20 pages per canvas/call, byte caps). What it doesn't say is what a partial-failure mid-batch leaves behind, which matters for a destructiveHint=true tool.

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?

Purpose and the free/non-publishing framing are front-loaded, and every clause carries information an agent needs (versioning, conflict handling, limits). It is a dense single block though — the byte limits and the HTML self-containment rule would read better split out, and '1,800,000 bytes' vs the schema's maxLength in characters is a mildly confusing restatement.

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 multi-mode upsert tool with an output schema present, the description covers everything an agent must decide before calling: identity model, create-vs-update branch, conflict protocol, batch-size guidance, and asset constraints. Return payload detail is correctly delegated to the output schema.

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?

With 80% schema coverage the baseline is a 3, but the description adds real semantics: sourceId is a stable identity reused across pushes, pageKey defaults to the route without its leading slash, expectedVersion must come from a prior push or the feedback/read tools, and designId acts as a no-op check. It also constrains html to one self-contained document with inline assets or absolute https URLs, which the schema alone does not.

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?

First sentence names a specific verb and resource: putting finished HTML pages on the person's iter0 canvas for comments and notes. It immediately distinguishes itself from iter0_publish_site ('publishes nothing') and from iter0_edit_site by framing the input as whole HTML documents.

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 contrasts with publishing ('free, no credits, publishes nothing') and spells out the exact conditions for each mode: first push with a sourceId vs later pushes, when to pass expectedVersion, and how to split a large site across calls with the same sourceId. Retry behavior is also explicitly stated.

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

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

Annotations already declare readOnlyHint/idempotentHint, so 'Free and read-only' is partly redundant, but the description adds genuinely new behavior: large pages are returned in parts, the offset/nextOffset loop, and the requirement to verify version is identical across parts. Nothing contradicts the annotations.

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?

Front-loaded with the purpose in the first clause, then pagination mechanics in a short second half — every sentence is doing work. Minor waste in restating 'Free and read-only,' which the annotations already declare.

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?

Output schema exists, so return-value documentation is unnecessary; the description nevertheless covers the multi-part read strategy, cursor handling and version-consistency check, which are the only things an agent could get wrong here. Nothing material is missing for a read-only, 3-parameter tool.

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 the baseline is 3; the description goes further by explaining offset as the pagination cursor that completes the read loop ('call again with it as offset and append'). It says nothing about designId/pageKey semantics, but the schema covers those fully.

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 + scope: 'Read the current HTML of one page on an iter0 canvas, with its version.' That single page/raw-HTML scope distinguishes it from broader siblings like iter0_get_design or iter0_get_canvas_feedback 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?

Gives a clear motivating context ('so you can merge the person's own edits before pushing a revision') that tells the agent when this tool belongs in a workflow. It does not name an alternative or an exclusion, so it stops short of a 5.

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

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

Goes well beyond the annotations: it discloses that the reply is appended and marked as an agent's, enumerates exactly what it will not do (resolve/reopen/delete/approve), explains retry safety via operationId, and describes optimistic concurrency refusal via expectedVersion. That is the mutation, side-effect and failure profile an agent needs before calling.

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?

Purpose is front-loaded in the first sentence, followed by the safety profile, idempotency and concurrency note. Four dense sentences with little waste, though the final sentence packs three ideas and is a touch heavier than needed.

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?

With an output schema present, return values need not be explained; the description instead covers the mutation footprint, agent attribution, idempotency and the concurrency guard. Nothing an agent needs to invoke this correctly is missing.

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 60% and the description fills the main gap: expectedVersion has no schema description at all, yet the description explains it must be the version from iter0_get_canvas_feedback and that it refuses the reply if the thread changed. It also restates operationId idempotency semantics; the remaining 'text' constraints are left to the schema, which is acceptable.

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 ('Add a reply to one comment thread or pin') plus the scope ('on the person's iter0 canvas'), and illustrates intent with 'answer their question or say what you changed'. No sibling tool appends replies, so the boundary is unambiguous.

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 clear context for when to reach for it and routes the agent to iter0_get_canvas_feedback to obtain the thread version for expectedVersion. It also implicitly rules out moderation actions by saying it never resolves, reopens, deletes or approves, though it doesn't name an explicit alternative for those cases.

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

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

Annotations already flag the operation as destructive, idempotent, and non-readonly. The description adds valuable context beyond that: the operation is free, the first call changes nothing and reveals which version replaces which, and a confirmation token gates the actual restore. It stops short of explicitly stating that the current site version will be overwritten, but the preview semantics convey the replacement.

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?

Three sentences, zero waste, with the cost and the two-step contract front-loaded before the mechanics. Every clause carries information the agent needs to call the tool correctly.

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 three-parameter mutation with annotations and an output schema, the description supplies the critical missing pieces: the source of versionId, the confirmation-token flow, the no-op preview behavior, and the cost. Return-value details are appropriately delegated to the output schema.

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%, so the description carries the burden. It clarifies that versionId comes from iter0_get_design, that designId and versionId must be repeated identically across both calls, and that confirmationToken is only passed on the second call. designId itself is only implicitly defined, keeping this just below 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 ('Restore an earlier saved version of the person's site') and names the sibling tool that produces the versionId. An agent can distinguish it from edit, undo, or publish siblings without opening schemas.

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 explains the intended use case and the two-step confirmation workflow, including that the first call is a no-op preview. It does not name explicit alternatives (e.g., iter0_undo_edit) or when not to use restore, but the context is unambiguous.

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

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

Goes well beyond the annotations: it discloses the 1-credit cost, the free-allowance case, the quote-first/two-step paid flow, that nothing starts before confirmation, which sibling redeems the quote, what the iter0 card displays and that it self-updates, and how the results are subsequently built. These are exactly the consequential behaviors an agent cannot infer from readOnlyHint/destructiveHint/idempotentHint.

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?

Front-loaded with the action, then cost, then the confirmation flow, then what the card shows and what comes next. It is dense but nearly every clause carries actionable information; the one soft spot is that the card-display sentence is longer than it needs to be.

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 values need no explanation, and the description covers cost, confirmation flow and downstream wiring for a tool with nested objects and 5 parameters. What is missing is any statement about the businessContext object and about what a failed or refunded batch leaves behind, which matters given destructiveHint=true.

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 60%, so the schema documents prompt, variant and approvalId, while directions and businessContext items are undocumented there. The description helps by saying to pass 'the brief and a name and short summary for each direction', which maps onto prompt and directions.title/direction, but businessContext (kind, businessKind, offering) is never explained and the retry/quote semantics of variant and approvalId are left entirely to the 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: 'Prepare three rough draft website design directions for the person's business from approved design references', plus what must be passed in. It names downstream siblings (iter0_confirm_paid_action, iter0_create_site) so the agent can see where this sits in the flow, but it never contrasts the tool with iter0_design_layout, the closest-sounding sibling.

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 real procedural context: this is the batch-of-three draft step, a paid request first returns a quote and starts nothing, and work begins only when the person confirms in the card or in chat. That is clear when-to-use guidance, but there is no explicit exclusion such as when to pick iter0_design_layout or iter0_get_design_set_status instead.

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

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

With annotations already declaring destructive, non-read-only, and idempotent behavior, the description adds useful context: the action is free, iter0 keeps an exact copy of the prior page, and there are current-page and expiration preconditions. It does not explain token acquisition or error behavior, but it meaningfully adds to the annotation profile.

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 description is short, front-loads the core action, and every clause adds relevant information: verb, cost, restoration semantics, and preconditions. There is no filler.

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?

The description covers the core behavior and preconditions, and an output schema exists so return values need not be explained. However, for a mutation tool with two undocumented required parameters, the missing explanation of undoToken provenance and designId semantics leaves a meaningful gap.

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 only 33%; the html parameter is documented in the schema as ignored, but designId and undoToken have no schema descriptions. The tool description implies a design context and an undo token but does not explain where undoToken comes from or what designId must identify, so it does not compensate for the low schema coverage.

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 description gives a specific verb and resource: 'Undo the last saved edit from the iter0 card,' and clarifies that it restores the exact prior page. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling restore_version tool.

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?

The description implies when the tool is valid by saying it works only while the edit is the design's current page and the undo has not expired. However, it gives no explicit guidance on when to use this instead of restore_version or other edit-related siblings.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds substantial context: the design and address are preserved and republishing is possible, the confirmation-token handshake guards the destructive step, and unknown outcomes must be reconciled via iter0_publish_status. It also discloses the owner-only authorization requirement, which annotations do not cover.

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?

Front-loaded with the effect of the call, then the safety protocol, then the recovery path. Dense and mostly waste-free, though the short fragment "Free." and minor repetition of the token flow keep it just short of ideal.

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 described, yet the description still flags the two things that matter operationally: a confirmationToken may come back, and an unknown-outcome result requires a follow-up check. Nothing needed to call it correctly is missing.

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 adds protocol-level meaning: the same designId must be reused on the second call and the token must be passed unchanged. That reinforces the two-phase contract beyond the field-level text in the 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 ("Takes a live site offline") plus the concrete consequence ("its address stops working"), which clearly separates it from iter0_publish_site and iter0_edit_site. An agent can identify the operation without opening the 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?

Gives an explicit two-step protocol: first call with only designId, second call with the returned confirmationToken. It also names the fallback path (iter0_publish_status) when the outcome is unknown and says the token is reusable, so the agent knows exactly when and how to invoke.

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