WebTwizz

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

Annotations already establish a non-read-only, non-destructive, closed-world write. The description adds important behavior beyond that: the write goes live immediately without a build, and repeated calls create duplicate records (non-idempotent). It does not discuss permissions or rollback, but the key operational traits are disclosed.

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 tightly written sentences, front-loaded with the use case, followed by the alternative and the idempotency warning. Every sentence carries useful routing or behavioral 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?

Given the output schema and annotations, the description covers the important operational facts: where the record goes, that it is live immediately, and that duplicates are not prevented. The only minor gap is the unexplained site_id parameter, which is left to the 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 67%, with data and table documented in the schema and site_id undocumented. The description adds some context by tying the tool to database tables and giving example records, but it does not explain the site_id parameter or add syntax guidance beyond 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?

The description states a specific verb and resource: add a record to a WebTwizz site's database table, with concrete examples (product, booking). It clearly separates this from edit-site and implicitly from update-site-data by emphasizing 'add' rather than modify.

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 explicitly says when to use this tool and names the alternative (edit-site) for new tables, new columns, or file-based content. The exclusions are concrete, so an agent can route correctly without opening other schemas.

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 the safety profile (destructiveHint=false, openWorldHint=true, readOnlyHint=false), so the description mainly needs to explain the quirks. It adds that the check is re-run ('again'), which hints at a live DNS lookup, but it does not explain why this is not read-only, whether results are cached, or how propagation timing affects results. The description of returned fields (status, missing records) largely restates what the output schema already provides.

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 usage trigger and followed by the behavior. No filler; only mild redundancy in restating the return fields that the output schema already encodes.

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 tool needn't spell out return structure, and annotations cover safety. Remaining gaps are the undocumented site_id and the absence of any note on DNS propagation delays, which is the main source of misuse for a re-check 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 only 50%: 'domain' is documented in the schema ('leave out to check them all'), but 'site_id' has no schema description and is never mentioned in the description. The phrase 'the site's custom domains' implies site scoping but doesn't define what site_id is or where the agent gets it.

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?

Names a specific action and resource: re-checking a site's custom domains and returning each one's status plus the records still missing. The trigger phrase ('user has set their DNS records') also separates it in practice from connect-domain, but the description never names that sibling, so the differentiation is inferred rather than stated.

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 when-to-use condition: after the user sets DNS records, or when they ask whether the domain works yet. It stops short of when-not-to-use guidance (e.g. don't re-check repeatedly while propagation is pending) and does not name alternative tools.

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 destructiveHint=true and openWorldHint=true; the description adds real value beyond them by enumerating what the gated step may be (run a command, delete database data, Stripe change, publish) and stating that approve=false skips the step while the build continues. It does not cover error states (e.g., job not actually waiting) or whether the decision is reversible.

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 gating precondition is front-loaded in the first clause, followed by the two-branch outcome. It is dense but every clause carries meaning; minor cost is that it reads as one long sentence rather than cleanly separated guidance.

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 no explanation, and the two-parameter surface is essentially covered. The remaining gap is failure/edge behavior — what happens if the job is not actually awaiting confirmation — but the core decision semantics are complete.

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 50%: job_id is documented in the schema, but the approve boolean has no description there. The description fills exactly that gap by explaining approve true = proceed and false = skip the step and continue the build, which is the semantics an agent most needs.

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 action (answer a pending WebTwizz build gate with approve true/false) and anchors it to the UI signal 'WebTwizz needs your OK'. It is clearly distinguishable from read-only siblings like get-job-status, though it never names those siblings explicitly.

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?

Strong precondition: 'Use this only after the user clearly answers what a WebTwizz build is waiting on' tells the agent both when to call and when not to (i.e., do not call preemptively). It lacks explicit routing to alternatives such as get-job-status or stop-build, 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?

Annotations declare it is not read-only, not destructive, and open-world. The description adds meaningful behavioral detail beyond that: it returns DNS records to set at the registrar and that check-domain confirms it. That workflow context is genuinely useful and not in 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?

Two sentences, zero waste, trigger and outcome front-loaded. Efficient 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?

Output schema covers return values and annotations cover safety, so the description doesn't need to. However, the undocumented site_id parameter leaves a real gap for a required input the agent must supply.

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 50% with only 'domain' described; 'site_id' is undocumented in both schema and description. The description repeats the domain example but adds no meaning for site_id, 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?

States a specific verb and resource ('connect a domain ... to their WebTwizz site') and explicitly distinguishes from the sibling check-domain ('check-domain then confirms it'). An agent can tell this apart and understand what it produces 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 a clear trigger ('when the user asks to connect a domain they already own') and names check-domain as the confirming follow-up. It does not state exclusions or prerequisites, but the usage context is explicit.

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?

Adds meaningful behavioral context beyond the annotations: it builds immediately, the card shows a live build, the site opens in WebTwizz for visual editing, it consumes account credits, and each call creates another new site (warning about unintended duplication). It does not cover authentication or rate limits, but the disclosed behavior is substantial for a creation 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?

Four sentences, front-loaded with the usage trigger, then creation behavior, live build process, and cost/idempotency warning. Each sentence contributes useful information without redundancy.

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 and rich annotations, the description covers when to use the tool, what it does, its live build behavior, credit consumption, and non-idempotency. It leaves out explicit sibling alternatives and edge cases like build failure, but is otherwise complete for calling the tool 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 description coverage is 100%, so parameter meanings are already fully documented in the schema. The description only summarizes optional inputs ('pictures or a website to start from') without adding syntax or constraints beyond what the schema provides, making the baseline of 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: 'Creates a new WebTwizz project from a brief' and 'starts building it right away.' The purpose is immediately clear, though it does not explicitly name a sibling alternative to distinguish it from, for example, duplicate-site or update-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?

Provides a clear usage trigger: 'Use this when the user wants an idea or this conversation turned into a real website or web app with WebTwizz.' It does not explicitly state when not to use it or name alternative tools, but the context is sufficiently clear for an agent to select 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?

The annotations already mark this as destructive and not read-only, and the description adds useful operational context: deletion happens on live data immediately and without a build. It does not explicitly say the action is irreversible or whether confirmation is required, but the key behavioral trait beyond annotations is disclosed.

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 short sentences, front-loaded with the use case, followed by the immediate live-deletion behavior and the relevant alternative. There is no redundant or low-value 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?

Given the annotations, output schema, and sibling tools, the description provides enough context for an agent to select and invoke the tool correctly. It could be slightly more complete by mentioning irreversibility or confirmation expectations, but the essential routing and behavior are covered.

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%, with table and row_ids described in the schema, while site_id has no description. The description does not add parameter-level detail beyond schema, though its mention of database tables and records loosely supports the table/row_ids meaning. This is adequate but not compensating for the undocumented site_id.

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 and resource: deleting records from a WebTwizz site's database tables. It gives concrete examples (removing a booking or old product) and explicitly distinguishes the tool from edit-site, which handles table/column removal rather than row deletion.

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 states exactly when to use the tool: when the user wants to delete records from a site database table. It also names the alternative for a related but different operation, saying to use edit-site instead to remove a table or column, which gives the agent a clear routing rule.

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 and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior beyond that: the result is a download link rather than the archive itself, and the link expires after 30 minutes — an operational constraint an agent cannot infer from structured fields.

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, zero waste, and the triggering condition is front-loaded before the return-value detail. Nothing is repeated from annotations or the 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 the description need not detail the response shape, yet it still flags the link and its lifetime. The only shortfall is the missing identification of site_id, which is the single input an agent must supply.

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% and the description never mentions site_id, what form it takes, or how to obtain it (presumably from list-sites/get-site). With only one required parameter this is a modest gap, but the description does nothing to compensate for the undocumented 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: delivering the source code of the user's WebTwizz site as a zip file. That is concrete enough to separate it from siblings like get-site, show-preview, or publish-site, though it never names those siblings explicitly.

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?

"Use this when the user wants the source code... for example to host it elsewhere or open it in an editor" gives a clear triggering condition with two concrete example intents. It stops short of exclusions (e.g., use get-site for metadata, use list-versions for rolling back), so it is not a full when/when-not rubric.

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 (readOnlyHint=false, destructiveHint=false), the description adds that the original is never modified, the copy starts unpublished, and — critically — "Each call makes another copy," warning that repeated invocations are not idempotent and will spawn duplicates. That is real behavioral value an agent cannot get from the structured fields.

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, front-loaded with the usage trigger, then outcome, then the repeat-call caveat. The dashboard analogy ("the way Duplicate does on the WebTwizz dashboard") is slightly decorative but cheap and orients the user.

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 no output schema, the description never says what comes back — presumably the new site's id, which the agent would need for follow-up calls like edit-site or publish-site. It also doesn't say where the copy appears (drafts list?). The mutation and non-idempotency are covered, but the return-value gap is real.

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 50%: site_id has no description anywhere, and the description never states that it identifies the source site or what happens on an invalid id. The optional name parameter and its "<original name> (Copy)" default are documented only in the schema, so the description adds nothing on parameters.

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 names a specific verb and resource ("a copy of one of their WebTwizz sites") and spells out the outcome: a new, unpublished project with the same pages, design and content. That copy semantics implicitly separates it from create-site, though no sibling is named explicitly.

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?

"Use this when the user wants a copy of one of their WebTwizz sites, to try ideas without touching the original or to start a similar site" gives clear trigger conditions with intent. It stops short of an explicit when-not or a named alternative such as create-site for building from scratch.

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=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds nothing: it does not say the edit mutates the live site, whether it is reversible, whether it requires a version/publish step, or what happens to sibling elements matched by the same selector.

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 action front-loaded and no padding. The trailing 'Used by the card' is a bit cryptic and arguably costs more in ambiguity than it earns.

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 not be covered, but this is a destructive mutation with a nested selector object and an undocumented site_id. An agent still lacks enough to construct the element locator confidently or understand the consequences of the write.

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 50%: path and request are documented, but site_id and the nested element object's tag/text/classes fields have no descriptions, and the description does not explain how those three fields act as a locator. 'The way they asked' does signal that request is freeform user language, which is a small genuine addition.

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: changing the part of a WebTwizz site the user clicked, driven by the user's natural-language request. The action is clear, but it gives no differentiation from near-neighbours such as edit-text, edit-site, or update-site, leaving the agent to guess which editing tool applies.

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 card' plus 'the part... the user clicked in the card preview' implies the triggering situation: a preview-driven, element-targeted edit. However, there are no exclusions and no named alternative, so the boundary with edit-text (also text/element editing) is left entirely 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 flag destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavioral context: it consumes the account's WebTwizz credits, each call starts a distinct new change, and the work is shown live on the card. It stops short of saying whether changes are reversible or what happens on failure, and does not mention restore-version as a recovery path.

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, front-loaded with the trigger condition, and the credit/one-change-per-call facts come before the mechanism description. Minor redundancy between 'which edits the site' and the change examples, but nothing is wasted.

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 no explanation, and the annotations plus description together cover safety, cost, and live-progress behavior. The main remaining gap is failure/reversibility guidance for what is a destructive, credit-consuming operation.

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 five parameters (files, images, request, site_id, reference_url) are already documented with meaningful prose. The description adds no parameter-level detail such as when to prefer files over images or how reference_url interacts with request, so the 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?

The description uses a clear verb-plus-resource framing ('change one of their WebTwizz sites') and enumerates concrete change types (sections, pages, copy, design, features, fixes, answering a pending question). It explains the mechanism (request routed to the site's WebTwizz AI), which distinguishes it from low-level siblings like edit-element/edit-text. It does not, however, explicitly name those siblings or update-site/update-site-data as alternatives.

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?

'Use this when the user wants to change...' gives an explicit trigger condition, and the inclusion of 'an answer to a question WebTwizz asked' widens the context usefully. There are no stated exclusions or named alternatives (edit-element, edit-text, update-site), so the agent must infer routing when a change is element-level.

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=true and readOnlyHint=false, so the safety profile is partly covered. The description adds useful conditional behavior—swapping text into code when safe, otherwise WebTwizz makes the change—but does not explain what may be destroyed or what permissions are required.

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 brief and front-loaded, with the core action stated first. The final sentence 'Used by the card' is vague but not sufficiently wasteful to undermine the overall concision.

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 mutation tool with five parameters, a nested object, and no output schema, the description is too thin. It does not cover side effects, safety conditions, return behavior, or the meaning of site_id and element, leaving important gaps for correct invocation.

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 moderate at 60%, with descriptions for path, after, and before but not for site_id or the nested element object. The tool description provides no additional parameter guidance, leaving required parameters like site_id and element undocumented beyond their names.

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: saving text typed by the user in the WebTwizz card preview. It is reasonably clear what the tool does, though it does not explicitly distinguish itself from the sibling edit-element 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 only usage context is 'Used by the card,' which does not explain when an agent should call this tool instead of alternatives like edit-element. No exclusions or prerequisites are provided.

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?

The read-only, non-destructive annotations already establish the safety profile, and the description adds useful context about credit consumption rules—builds and edits consume credits while data, domain, and preview tools do not. This is valuable behavioral guidance beyond the structured annotations, though it does not discuss permissions or freshness of account data.

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, both front-loaded and purposeful. The first sentence lists the exact user intents, and the second adds a useful credit-consumption distinction without wasting space.

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 description need not explain return values. For a parameterless, read-only lookup, the description is complete enough: it states what the tool retrieves and when to use it, and the annotations cover 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 the baseline is 4. The description appropriately does not invent parameter details, and the empty input schema is fully consistent with a parameterless account lookup.

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 names the exact resource—the connected WebTwizz account—and enumerates the specific pieces of information it returns: account identity, plan, remaining credits, and workspaces. This is a concrete verb-plus-resource statement that an agent can match directly to user questions about account status.

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 clear triggering conditions: use when the user asks which account is connected, which plan it is on, how many credits remain, or which workspaces exist. It also distinguishes credit-consuming build/edit operations from non-credit data, domain, and preview tools, though it does not explicitly name sibling tools as alternatives.

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, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds a behavioral nuance — that AI connectors report 'whether an AI key works' — but says nothing about what happens when a connector is not yet connected, whether credentials are required, or what the overview payload 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?

It is front-loaded with the usage trigger, which is the right lead, and every clause carries intent-to-connector information rather than filler. The single sentence grows long and enumerative, and some of the mapping work is redundant with the enum, but nothing is wasted.

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 no output schema, two required params, and an enum that covers 47 connectors while the prose covers roughly a dozen, the description is not fully sufficient — an agent still cannot tell what an 'overview' response looks like or how to handle a connector with no stored credentials. The intent routing it does provide is solid, so it is adequate rather than complete.

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 must carry the parameter burden, and it only partly does: it implies what values the 'connector' enum maps to (google-analytics → visitors/top pages, stripe → sales/products), which real guidance. But site_id is never mentioned, the mapping omits many enum members (calcom, twilio, whatsapp, razorpay, paypal, hubspot, mcp-*), and neither parameter's format is explained.

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 the resource and intent clearly: it reports how a service connected to a WebTwizz site 'is doing,' and enumerates the concrete signals per connector (visitors, sales, errors, commits). It is weaker on the verb/scope edge — it never says it returns a single consolidated overview rather than raw records — and does not differentiate from the sibling list-connectors or use-connector.

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 opens with an explicit trigger: 'Use this when the user asks how something connected ... is doing,' and maps user intent (visitors, sales, errors, key validity) to the right connector, which is genuinely useful routing guidance. It stops short of exclusions or naming alternatives — e.g. it never says to use list-connectors to discover available connectors or use-connector to invoke one.

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?

While annotations cover safety (readOnlyHint: true), the description provides rich behavioral context by detailing the specific data points it monitors. It explains the tool's functional behavior across different states—unlinked vs. linked—which goes far beyond the scope of a simple safety hint.

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 highly efficient, providing a wealth of technical information in a focused, single paragraph. Every sentence directly contributes to defining the tool's scope and expected behavior without any redundant language.

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 complexity of status reporting (requiring knowledge of PRs, commits, and link status), the description is exceptionally complete. It manages to describe the operational logic and the two major states (connected/unconnected) of the tool without needing an 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?

Since schema coverage is 0%, the description must define the parameter's context. It clarifies that the 'site_id' must correspond to 'one of their WebTwizz sites,' providing essential semantic context. It scores a 4 instead of 5 because it doesn't describe the format or constraints of the ID itself, only its domain.

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 purpose is perfectly clear: to retrieve comprehensive status information regarding a GitHub integration for a specific WebTwizz site. It specifically enumerates the data retrieved (link status, changes, last push, commits, and PRs), distinguishing it from action-oriented siblings like push-to-github or pull-from-github.

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 guidelines are explicit, stating the exact scenario for usage ('when the user asks about GitHub for one of their WebTwizz sites'). Furthermore, it covers the necessary behavioral guidance for the tool's states, addressing what happens when nothing is linked yet versus when it is connected.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that the progress is 'live', implying fresh status rather than a cached snapshot, but says nothing about what statuses are returned, whether job_ids expire, or how unknown ids behave.

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 front-loaded sentence with the verb and resource up front and no filler. It is efficient, though the trailing 'for its card' phrase adds ambiguity rather than 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?

An output schema exists, so return values need no explanation, but the description still omits essential context for a one-param status-polling tool: the origin of job_id and the polling lifecycle. An agent would not know how to obtain the id without inspecting other tools.

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 required job_id, and the description never mentions it — not where it comes from (the initiating build/edit/publish call), its format, or what happens if it is stale. The description fails to compensate for the 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?

States a specific verb and resource: reports live progress of a build, edit or publish job. The scope ('for its card') is vague but the core action is clear enough to distinguish it from siblings like stop-build or get-github-status.

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?

No guidance on when to call it versus alternatives, no mention that it is a polling tool invoked after starting a build/edit/publish, and no indication of when to stop polling. The agent must infer the entire workflow from the name alone.

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, destructiveHint=false and openWorldHint=false, and the description adds real value on top by disclosing the return payload shape: status, latest build or question, and recent chat activity. It stops short of covering error behavior or whether chat history is truncated, which keeps it off a 5.

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, no waste, with the usage trigger front-loaded ahead of the return-value summary. Every clause earns its place.

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 simple one-parameter read with no output schema, the description does the heavy lifting by describing what comes back, so an agent can decide and act. The remaining gap is procedural — how to obtain a valid site_id — which matters given the crowded sibling set including list-sites.

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 required site_id parameter, so the description must compensate and it does not — it never says what form the id takes or that it can be obtained from list-sites. The phrase 'one of their WebTwizz sites' only implies that an identifier is required, which is already visible in the schema's required list.

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 combination ('get-site' → returns the site's status, latest build or question, and recent chat) and enumerates exactly what 'current state' means. It does not name a sibling such as list-sites or edit-site, so differentiation relies on the agent's own comparison of the tool list.

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, concrete trigger conditions: 'when the user asks how one of their WebTwizz sites is going, what changed, whether it is live, or anything else about its current state.' That covers the main entry scenarios well, but there are no exclusions and no pointer to alternatives (e.g. use list-sites to find the id, or update-site to change something).

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, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses pagination behavior ('Returns a page of rows') and the row_id contract that links this read to the mutation tools. It does not mention page-size limits or total counts, but the schema carries the default.

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, zero waste, with the trigger condition front-loaded and the downstream row_id contract second. Every clause earns its place.

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-value explanation is not required, and annotations cover safety. For a 5-parameter read tool with two undocumented params (page, site_id), the description is nearly complete, with only paging semantics for the bare page/site_id params left unaddressed.

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%: table, search, and page_size are documented in the schema, while page and site_id are not described anywhere. The description reinforces the table parameter's provenance via the row_id/update-site-data note but adds no syntax or constraint detail beyond 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 ('see records in one of their WebTwizz site's database tables') with concrete examples (bookings, orders, sign-ups, products). It distinguishes itself from the mutation siblings by noting row_id is what update-site-data and delete-site-data consume, though the contrast with list-site-data 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?

Opens with an explicit trigger condition ('Use this when the user wants to see records...'), and the row_id note routes the agent forward to the update/delete tools. No explicit when-not-to-use or exclusion against list-site-data, so it falls 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is settled structurally. The description adds real value beyond that by describing the returned payload: per-connector accounts, which the site uses, and a connect link. It does not state auth/permission requirements or whether connect links expire, which keeps it off a 5.

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 usage trigger is front-loaded and the return-value sentence follows logically. The twelve-provider enumeration is the one expendable element, though it does help an agent confirm relevance to a named service.

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 single optional parameter, read-only annotations, and no output schema — the description covers both when to call it and what comes back, which is most of what an agent needs. The missing piece is routing versus use-connector, since 'wants to add one' could tempt an agent to call this instead of the actual connect 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% and the site_id description already explains the scoping effect and connect-link behavior. The tool description only alludes to this with 'which the site uses' and 'connect links open that site,' adding little beyond the schema. Baseline 3 applies when the schema carries the 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?

States a specific verb (lists) and resource (connectors) and enumerates the twelve supported providers, plus what each entry contains: accounts, site usage, and a connect link. It never names the closely related siblings use-connector or get-connector-overview, so an agent must infer the boundary itself.

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?

Opens with an explicit trigger condition: 'Use this when the user asks which services their WebTwizz account or site is connected to.' It also covers the adjacent intent 'or wants to add one.' No exclusions or alternative-tool routing are given, which is the remaining gap.

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 the safety profile (readOnly, non-destructive, closed-world), but the description adds genuinely new behavior: per-variable output shape (name, set state, managing connector) and a redaction rule that public NEXT_PUBLIC_ values are shown while secrets never are. Permission requirements or pagination behavior are not mentioned.

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 tight sentences: trigger first, return shape second, value-visibility caveat last. Nothing is redundant and the most decision-relevant information is front-loaded.

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 no output schema, the description correctly compensates by describing returned fields and the secret-redaction rule. It leaves open whether variables unset on the site are included and whether the user needs any permission, but an agent has enough to invoke it 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?

The single required parameter site_id is undocumented in both the schema (0% coverage) and the description; 'their WebTwizz site' only weakly implies that site_id selects the scope. With one parameter and no schema text, a modest gap remains but is not severe.

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 (lists environment variables/settings keys for a site) and even enumerates the returned fields, so an agent can tell it apart from data-oriented siblings like list-site-data and get-site. It doesn't explicitly name a sibling, so it stops short of the top mark.

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?

"Use this when the user asks which settings or keys their WebTwizz site has" gives a clear triggering condition that maps directly onto a user intent. No when-not guidance or named alternative (e.g. vs get-site or list-connectors) is offered.

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/not-destructive/closed-world, so the safety profile is covered; the description adds valuable disclosure of the return contents (tables, columns, row counts, content collections) and its role as a prerequisite before read/change operations. It does not mention cost, pagination, or size limits for large sites.

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 tight sentences with the usage trigger front-loaded and the return contents immediately after; no filler or restatement 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?

Output schema exists, so return values need not be spelled out, and annotations cover safety; the description is nearly complete for a simple read tool. The one gap is the unexplained required site_id, which an agent must infer.

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% for the single site_id parameter, so the description would need to compensate but says nothing about it — not where to obtain a site_id (e.g., from list-sites) nor its format. Only the parameter's self-evident name carries any meaning.

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 (lists) and precisely what is returned: database tables with columns and row counts, plus file-based content collections. This implicitly separates it from get-site-data and the add/update/delete-site-data siblings, but no sibling is named explicitly.

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 trigger: 'when the user asks what data their WebTwizz site has, or before reading or changing it', which usefully frames it as a discovery step ahead of the data CRUD tools. No when-not conditions or named alternatives are given.

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, non-destructive, closed-world behavior, and the description adds useful behavioral detail beyond them: results are most recently updated, include a picture, sorted newest first, returned a page at a time, and searchable by site name. That is substantial transparency for a list 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?

Three sentences, front-loaded with usage and followed by return behavior and the sibling alternative. There is no noticeable filler, and each sentence contributes useful 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?

Annotations cover the safety profile, the schema fully documents parameters, and an output schema exists, so the description does not need to explain return values in depth. It still adds enough context about ordering, pagination, and filtering to call the tool 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 description coverage is 100%, so the baseline is 3. The description adds some meaning for pagination and search (“a page at a time”; “search narrows them by name”), but it does not mention workspace_id, leaving that parameter 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 (“list-sites” for the user’s WebTwizz sites) and clearly distinguishes it from the sibling show-preview when the user names a specific site. An agent can identify the tool’s role 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 explicit when-to-use guidance (“when the user asks which WebTwizz sites they have, or wants to pick one to work on”) and an explicit alternative (“use show-preview with its name instead”) for a named site. This is strong routing 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 and destructiveHint=false, so safety is covered; the description adds genuinely new context with 'Works before the user signs in' (no auth prerequisite) and 'a page at a time' (pagination behavior). Return format is left to the output schema, which exists.

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 tight sentences, front-loaded with the usage trigger, then the alternatives and the auth caveat. 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?

For a read-only paginated list with an output schema, an agent has everything it needs to invoke correctly, including the pre-sign-in caveat. The one gap is what the category values mean, which is minor given the enum is self-descriptive.

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 page/search are already documented; the description only reinforces pagination with 'a page at a time'. The category enum (websites/apps/games) is left unexplained in both schema and description, so no value is added beyond structured fields.

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 (shows matching templates) and resource, plus what the caller receives (picture and live demo, paginated). It explicitly distinguishes itself from show-template and create-site, so an agent can route between the 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 an explicit trigger ('when the user wants to start from a ready-made design, or asks what WebTwizz templates there are') and names the follow-on alternatives: show-template to open one, its slug to create-site. Nothing is left 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the ordering guarantee (newest first), which is genuinely useful for picking a restore point, but says nothing about pagination, result limits, or what a version entry contains — and there is no output schema to fall back on.

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 trigger condition and followed by the downstream step. No filler or restatement of the name.

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 simple read-only single-parameter lister whose safety profile is carried by annotations, the description covers the essential workflow. The main gap is the absence of any return-shape or pagination hint and the unannotated site_id.

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% and the description never explains site_id — not its format, nor that it comes from list-sites. The phrase 'the site's saved versions' only implies that site_id selects the site, which is weaker than what an agent needs for a single undocumented required parameter.

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 ('Lists the site's saved versions') and gives the ordering ('newest first'). It is not fully distinguished from siblings in the text itself, but naming restore-version as the consumer makes the split between listing and restoring clear.

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?

Explicit trigger condition ('when the user wants to undo changes or go back to an earlier version') plus an explicit follow-up ('to pick one for restore-version'). It lacks a when-not clause, but the workflow routing is clear.

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 declare destructiveHint=true and openWorldHint=true, and the description adds valuable behavioral context: a user confirmation step occurs first, the latest saved version is published, and progress is shown. It doesn't explain what makes this destructive or whether re-publishing overwrites, but adds real process detail beyond 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?

Two sentences, front-loaded with the trigger condition, no wasted words. The sequencing (confirm, then publish, then progress) is clearly ordered.

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 values needn't be explained. Description covers trigger, confirmation flow, and what gets published, which is sufficient for a state-changing tool with destructive/openWorld annotations. Minor gap: no mention of failure modes or prerequisites like domain setup.

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 50%. The confirm parameter is well documented in the schema (card-only, agent should leave it out), and the description implies the confirmation flow. But site_id has no description in schema or description. Baseline 3 given the schema covers the tricky parameter.

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 (publish the user's site live) and distinguishes itself clearly from siblings like unpublish-site and show-preview. An agent immediately knows this makes a site publicly live.

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?

Clear trigger context: 'when the user wants their WebTwizz site live on the web.' It doesn't explicitly name unpublish-site as the inverse or discuss preview vs publish, but the usage condition is well 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 destructiveHint=true and readOnlyHint=false, so the write/overwrite nature is covered structurally. The description adds real context by saying the AI pulls the changes in and verifies the site still runs, but it omits that existing WebTwizz edits may be overwritten and that a GitHub connection is required. It does not contradict 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?

Two sentences, front-loaded with the usage trigger, and nothing redundant. The trailing phrase 'the card follows it like an edit' is product jargon that costs a little clarity without adding instruction.

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 not be described, and there is only one parameter. For a GitHub-sync tool the description covers the trigger and the core behavior (pull plus build check) adequately, leaving only permission/prerequisite details unstated.

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% and the description never mentions site_id, its format, or which site it targets. With a single obligatory parameter the omission is partly forgiven by the self-explanatory name, but the description does not compensate for the coverage gap as low-coverage schemas require.

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+resource+direction: pulling the user's GitHub code changes into WebTwizz. The direction (GitHub -> WebTwizz) implicitly separates it from the sibling push-to-github, though it never names that sibling explicitly.

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 a clear trigger condition: 'Use this when the user changed their WebTwizz site's code on GitHub and wants those changes in WebTwizz.' That is a well-specified when-to-use, but it offers no when-not guidance and does not point to push-to-github or download-code as alternatives.

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 non-read-only, destructive and open-world; the description adds real value on top by disclosing that each call appends another commit (cumulative history, not a reset) and that repo must come from get-github-status. It does not explain what makes the operation 'destructive' or what happens on conflict/failure, leaving a small gap against the annotation bar.

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 tight sentences, front-loaded with the trigger, then the behavior, then the exclusion, then the parameter setup. Every sentence carries distinct information with no restatement of the name or 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?

With an output schema present the description needn't explain return values, and annotations cover the safety profile; the description supplies the commit-accumulation and first-run setup context an agent actually needs. It is nearly complete, missing only failure/conflict behavior and what site_id selects.

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%, so repo and create_repo are already documented; the description adds the crucial framing that they are alternatives used on the first push and that repo originates from get-github-status. site_id is left unexplained in both schema and description, which is the remaining 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?

States a specific verb and resource — 'Commits and pushes the saved site to its repository' — and immediately distinguishes itself from sibling git work routed to edit-site. An agent can tell exactly what this does versus pull-from-github or get-github-status 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?

Explicit trigger ('Use this when the user wants their WebTwizz site's code on GitHub'), explicit exclusion ('Other git work, like undoing a push, goes to edit-site'), and first-time setup guidance ('pass repo ... or create_repo'). Both the when and the when-not are named.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds useful reversibility context by saying the current version stays in history and can be restored later, but it does not address permissions or other side effects.

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 usage trigger, and no filler. Every sentence carries information about when to use the tool or what it preserves.

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 restore tool with annotations and no output schema, the description covers the key action, dependency on list-versions, and reversibility. It could say more about site state or permissions, but the core decision information is present.

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 67%: point_id and only_if_latest are documented in the schema, while site_id is not. The description repeats that point_id comes from list-versions but adds no parameter-level meaning beyond what the schema already provides.

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 action: restoring an earlier version of a WebTwizz site. It clearly distinguishes the tool from list-versions, which supplies the version to restore, so an agent can tell what it does 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?

It explicitly says to use this after list-versions when the user selects an earlier version, giving a clear trigger and dependency. It does not state when not to use it or name a competing restore path, so it falls 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 establish that this is a read-only, non-destructive, closed-world operation. The description adds real context beyond them: the default target is the latest draft unless 'live' is set, and the capture reflects what visitors see rather than an editor view. It says nothing about latency, build state, or failure modes for unpublished sites.

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 short sentences, front-loaded with the primary use case and followed by the return value and default behavior. No filler, though the reflexive 'yourself' is slightly awkward phrasing.

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 and 80% parameter coverage, the description does not need to explain return shape; it still usefully states that a picture is returned. What is missing is minor — whether unpublished drafts always resolve, or whether it works on sites outside the user's account.

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 80%, so the schema already explains site_id, path, device, full_page and live. The description's draft-vs-live and desktop/phone framing largely restates the schema and covers no additional parameter nuance, so the 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?

The description uses a concrete verb ('look at', i.e. capture a picture) on a specific resource (one of the user's WebTwizz sites) and states what comes back ('a picture of a page as visitors see it'). It does not distinguish itself from the sibling show-preview, so it falls short of a 5.

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 clear use cases — checking a change, reviewing the design, comparing against what the user asked for — which tell an agent when this tool is the right choice. There are no explicit exclusions or pointers to alternatives such as show-preview.

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/openWorld=false safety, so the bar is lower; the description still adds value by disclosing the two-phase search-then-read flow and the shape of results (matching pages, matched lines, links). It stops short of describing ranking, result limits, or what an empty/no-match response looks like.

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, zero waste, and the use-case trigger is front-loaded ahead of the mechanics. Each clause earns its place.

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 two-param read-only retrieval tool with no output schema, it supplies the trigger conditions, the return content, and the follow-up pattern. An agent has everything needed to decide when to call it and how to continue from the result.

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 both parameters are already documented. The description adds the workflow relationship between them — `page` is used on a second call to read in full, `question` is for the initial search — which clarifies sequencing beyond the standalone field text.

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 ('Searches the WebTwizz docs') plus the return content ('best matching pages with the lines that match and links'). This is clearly distinct from the site-management siblings, which cannot be confused with a docs lookup.

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?

Opens with an explicit trigger set: 'when the user asks how to do something in WebTwizz, how a feature works, or about plans and limits.' It also names the follow-up pattern ('call it again with a page title to read one in full'), so both invocation modes are routed.

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?

Strong disclosure beyond the annotations: public values persist immediately, secrets are never accepted in chat and instead create a placeholder plus a paste link. That is exactly the kind of auth/side-effect context annotations can't convey. The one gap is that destructiveHint=true is never explained — nothing says whether setting an existing variable name overwrites or errors, which matters for a mutation 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?

Four sentences, each carrying distinct information, with the primary trigger front-loaded and the secret-handling rule following immediately. No restatement of the name or title, 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?

Complete for a 3-param mutation with no output schema: it covers the trigger, the secret flow, the return value (the paste link), and the sibling alternative. The only omission is overwrite behavior for an existing variable name, which is a meaningful unknown 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 67%, with name and value documented but site_id bare. The description compensates by supplying the conditional rule the schema can't express ('leave value out' for secrets, only populate it for NEXT_PUBLIC_ variables), which is the critical decision point for this tool. It does not explain site_id, leaving that param unqualified in both places.

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 first sentence names the specific verb+resource ('set an environment variable on one of the user's WebTwizz sites') and immediately distinguishes the three value paths: public, secret, and connector-managed. An agent can tell this apart from list-connectors/use-connector without opening any 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?

Explicit when-to-use ('when one of the user's sites needs an environment variable') and explicit when-not-to-use with the named alternative ('services WebTwizz connects, like Stripe, Supabase or Resend, get their keys through list-connectors and use-connector instead'). It also states the prerequisite behavior for secrets (leave value out).

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?

The description adds real behavior beyond the destructiveHint annotation: a live site moves to the new address and the old one keeps redirecting 'for a while'. It does not say what happens after the redirect window, whether existing links break permanently, or what permissions are required, which is notable for a destructive operation.

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 usage trigger followed by the key behavioral consequence. Every sentence earns its place with 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?

With annotations covering safety and an output schema present, the description supplies the essential behavioral outcome (address move plus temporary redirect). It stops short of the full lifecycle of the old address or any rollback information, which a destructive tool should ideally state.

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 description clarifies what 'name' means (the subdomain label) and the schema reinforces that, but 'site_id' is undocumented in both places at 50% coverage. Value added over the schema is marginal rather than compensating for the 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?

States the specific action (change the site's free address) and disambiguates the resource by explaining it is 'the name before .webtwizz.app', which separates it from connect-domain and update-site. An agent can identify the right tool 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?

Opens with an explicit trigger: 'Use this when the user wants to change their WebTwizz site's free address'. It does not contrast with alternatives such as update-site or connect-domain for custom domains, so a when-not clause is missing.

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/non-destructive, so the description's job is to add beyond that — and it does: the result is a rendered card, it shows the latest draft by default, and it is interactive. Note that 'click things to change them' describes user-driven UI editing rather than tool side effects, which is worth flagging but does not contradict the read-only hint for this call itself.

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 usage trigger, then behavior, then the live override — a sensible order with fairly tight phrasing. It is somewhat conversational and runs long in a single paragraph, but no sentence is pure 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?

An output schema exists, so return values need not be described; combined with annotations and the 67% schema coverage, the description supplies the remaining pieces an agent needs: when to call it, draft-vs-live default, and the flexible site_id form.

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 site_id has no schema description at all, so the description earns credit for documenting that 'site_id can be the site's name.' It also reinforces live (published site) and implies path targeting, though it does not illustrate the path format the way the schema does.

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 ('shows the latest draft' of a WebTwizz site/page) and adds a distinguishing trait versus screenshot-site: it renders in an interactive card where elements can be clicked and edited. It never names screenshot-site, so the differentiation is implicit rather than explicit.

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?

'Use this when the user wants to see or look at one of their sites... for example after a change' gives a concrete trigger context. It also specifies the live-vs-draft selection rule, but offers no exclusion guidance against sibling tools like screenshot-site or get-site.

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 the read-only/non-destructive/closed-world profile, and the description adds real context beyond them: the tool works before the user signs in (an auth constraint agents would otherwise have to discover) and it describes the shape of the returned detail. It stops short of noting size or rate limits, so it earns a 4 rather than 5.

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, each doing distinct work: trigger, return contents, and prerequisites/next step. The scoping and auth facts are front-loaded and 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?

An output schema exists so return-value documentation is unnecessary, and the remaining agent questions — when to call it, where the slug comes from, whether login is required, and what to do next — are all answered.

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% and the single parameter is documented as "A template slug from list-templates"; the description repeats the same provenance without adding format or validation detail. Baseline 3 is correct when the schema already carries the 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?

States a specific resource (one WebTwizz template) and enumerates exactly what a caller gets: purpose, pages, large picture, and a live demo link. It also implicitly contrasts with list-templates by taking its output as input, so the agent can separate 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?

"Use this when the user wants a closer look at one template" gives a concrete trigger, "Takes a slug from list-templates" gives the prerequisite, and "create-site with the slug as template starts a site from it" names the alternative path. When-to-use, input source, and next step are all explicit.

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?

While the annotations provide the critical `destructiveHint: true`, the description adds valuable behavioral context by stating that 'Work done so far is kept.' This is a crucial piece of information that mitigates the agent's fear of data loss.

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 definition is extremely concise, using only two sentences. Every phrase is dedicated to describing the tool's function, context, or behavior without unnecessary 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?

Given the low schema coverage, the description provides all necessary operational context. It informs the agent of the action, the state of the target, and the outcome of the action before invocation.

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 schema coverage is 0%, meaning the description carries the full weight. Although it doesn't explicitly define `site_id` semantically, as the single required parameter, the context implies it must be the identifier of the build/edit being targeted.

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 clearly defines the action ('stop a WebTwizz build or edit') and the context in which it should be used (when something is running). It clearly distinguishes this destructive action from site management tools.

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 provides a clear condition for usage: 'when the user wants to stop a WebTwizz build or edit that is running.' This effectively guides the agent on the correct operational state for invoking the tool.

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=true and openWorldHint=true, so the safety profile is known. The description adds essential context beyond annotations: the site remains in WebTwizz as a draft, can be republished later, and custom domains stop pointing at it until then.

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 tight sentences with the usage trigger front-loaded and the second sentence explaining consequences. There is no repetition or 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?

For a simple one-parameter mutation with annotations and an output schema, the description covers when to use it and the important side effects. The main remaining gap is the unexplained site_id parameter, but otherwise it is complete enough to invoke 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?

The single required parameter, site_id, has 0% schema description coverage. The description never explains what identifier is expected, its format, or how to obtain it, so it does not compensate for the missing schema documentation.

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 action (take a published WebTwizz site offline) and resource (site), and distinguishes the operation from deletion by explaining the site remains a draft and can be republished. An agent can identify the tool 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 a clear trigger: use when the user wants their published site offline. It also clarifies the outcome and custom-domain effect, but does not explicitly name alternatives such as publish-site or delete-site, nor does it state 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 declare destructiveHint=true, readOnlyHint=false, but the description never explains what is destructive or irreversible about the change. It does add one genuinely useful behavioral fact not in the annotations: visibility only takes effect on the next publish. That partial disclosure earns more than the minimum but leaves the risk profile unexplained.

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 trigger condition is front-loaded and each of the three sentences carries distinct information: capability, deferred-effect caveat, and sibling routing. Slightly dense in one paragraph, but nothing is 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?

An output schema exists so return values need no explanation, and annotations cover the safety flags. For a 4-parameter mutation tool the description is nearly complete, though it could say whether renaming affects the published URL or whether a password is required when switching to password visibility.

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 50% (site_id and visibility have no schema descriptions), but the description compensates by explaining the three visibility values semantically — public, password-protected, and workspace-private — which is more than the bare enum conveys. The password and name params are already documented in the schema, and site_id is self-evident as the target.

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?

Names the specific resource (a WebTwizz project/site) and the two concrete mutations it performs: renaming and setting visibility. It also explicitly routes SEO/page-content changes to the sibling edit-site, so an agent can distinguish the two 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?

Opens with an explicit trigger ('Use this when the user wants to rename... or choose who can see...') and names the alternative tool (edit-site) plus the condition that selects it (page titles, descriptions, SEO). Both when-to-use and when-not-to-use are 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 destructiveHint=true and readOnlyHint=false, and the description reinforces this with the key behavioral facts an agent needs: changes apply 'right away, without a build' and 'replace the old values of the columns given.' It is silent on permissions or failure modes (e.g., unknown column names), which keeps it below a 5.

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, no filler: the trigger comes first, the behavioral consequence second, and the sibling hand-off last. Every clause carries 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?

With an output schema, annotations, and 75% parameter coverage, the description supplies what structured fields cannot: immediacy and replace semantics. Slightly incomplete on permissions and how unlisted columns behave, but adequate for correct invocation.

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 75% and the schema itself documents the meaningful parameters, including provenance hints ('A table name from list-site-data', 'The row_id from get-site-data'). The description adds only the partial-update nuance ('columns given'), which is a slight value-add, so the 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 ('change') applied to a concrete resource ('a record in one of their WebTwizz site's database tables') and gives examples ('a product's price or a booking's time'). This distinguishes it clearly from sibling tools like add-site-data and delete-site-data.

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?

Opens with an explicit trigger ('Use this when the user wants to change a record...') and names the excluded case with its own alternative: 'Use edit-site instead for new tables or columns, or for content kept in the site's files.' The routing decision is fully specified.

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=true and readOnlyHint=false, so the safety profile is partly covered. The description adds real value about the post-call flow: some connectors require a follow-up choice and the result links there. However, it never explains what is destructive — e.g. whether attaching a connection replaces or invalidates an existing site connection — which is the most important behavioral fact for an agent to 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?

Three short sentences, with the trigger condition front-loaded before the parameter sourcing and the follow-up caveat. No filler, though the last sentence could be tightened.

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 no output schema, the description usefully sketches the return case ('the result says so and links there') and covers the multi-step flow most agents would miss. The main gap is the absence of any warning about the destructive effect implied by the annotations.

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%; connector and connection_id are documented in the schema (with a slug example), but site_id is undescribed. The description reinforces that connection_id comes from list-connectors but adds no new semantics and says nothing about which site is affected or how site_id pairs with connector.

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: making a WebTwizz site use an already-connected account, with concrete examples (Stripe, Supabase, GitHub). It is clearly distinguishable from the sibling list-connectors, which only enumerates connections, and from connect-domain, which is about 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 an explicit trigger ('when the user wants one of their sites to use an account they already connected') and names the prerequisite source tool list-connectors. It lacks an explicit when-not or an alternative for the case where the user has not connected the account yet (presumably list-connectors/connector overview), so it falls 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.