WebTwizz

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds the useful 'no build' immediate-write behavior and idempotency warning, but omits return format and whether the addition 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?

Three sentences with no waste; the primary action is front-loaded, followed by the alternative tool and the edge-case warning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers action, alternative routing, and an anti-pattern warning for a mutation tool with an output schema. Missing only permission requirements, but overall adequate.

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 the schema describes the main parameters. The description does not add format detail for site_id, table, or data beyond the sibling hint. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (add a record) and resource (a WebTwizz site's database table), with concrete examples (product, booking). It does not directly name the conflicting sibling by name, but distinguishes from edit-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?

Explicitly names edit-site as the alternative and defines the conditions that select it (new tables/columns, or file-based content). It also warns about a non-obvious duplication behavior.

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 disclose openWorldHint=true (external DNS lookups), destructiveHint=false, and notably readOnlyHint=false. The description adds that it re-checks ('again') and reports missing records, which is useful. It does not explain why a 'check' is marked non-read-only (e.g., it triggers re-verification) nor any rate limits, leaving some tension with the annotation unresolved.

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 behavior following. No filler, though it could be marginally more economical.

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 two-parameter verification tool with an output schema present, the description covers when to use it and what it returns conceptually, so return-format detail is unnecessary. The only real gap is the undocumented site_id and the unaddressed non-read-only annotation.

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%: 'domain' is documented in the schema ('Leave out to check them all') but 'site_id' has no schema description, and the description adds no semantics for either. The phrase 'the site's custom domains' implies site_id scoping but does not compensate for the undocumented parameter. Baseline 3.

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 ('Checks the site's custom domains') and clarifies the return ('each one's status and which records are still missing'). It is distinguishable from connect-domain (setup) and set-site-address, 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?

Gives a concrete trigger: 'when the user has set their DNS records, or asks whether their domain works yet.' That clearly situates it in the domain-verification flow. It stops short of naming the alternative tools an agent might pick instead.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds real context: what approval can trigger (running a command, deleting database data, a Stripe change, publishing) and that declining (approve=false) skips the step while the build continues. It does not address irreversibility, permissions, or what happens if the job is not actually waiting.

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, with the gating condition front-loaded before the parameter effects. The list of example actions is slightly padded but still earns its place by conveying the destructive scope; nothing is redundant with 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?

Since an output schema exists, return values need no explanation, and the description covers trigger, both decision paths, and consequences of each. The only unaddressed case is calling this when no approval is pending (error behavior) and whether the action is retryable.

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; approve is not), and the description compensates by defining both boolean branches of approve and by pointing at the source of job_id (the build card). This is meaningful added meaning beyond the bare boolean type.

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 makes clear this resolves a pending approval gate on a WebTwizz build (the 'needs your OK' card) and states the effect of each decision. It is distinguishable from siblings like stop-build or publish-site, though the core verb+resource ('confirm/deny a pending build action') is embedded in a usage sentence rather than stated front-and-center.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit precondition ('only after the user clearly answers what a WebTwizz build is waiting on') and names the concrete trigger (the card reading 'WebTwizz needs your OK'), which functions as a clear when-to-use and when-not guidance. No sibling tool serves as an alternative here, so the absence of an alternative name is not a 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 declare this is a non-destructive, non-read-only, open-world mutation. The description adds real behavioral value beyond that: it explains that the tool registers the domain and hands back DNS records the user must set at the registrar, plus that verification is a separate step.

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 trigger stated first and the side-effect/follow-up in the second clause. No filler, though the second sentence packs three ideas (add, DNS records, verification) into one dense clause.

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 and the description correctly doesn't re-explain the return payload, though it does hint at it (DNS records). For a low-complexity 2-param mutation it is nearly complete; it omits edge cases like domain-already-connected or invalid domain errors.

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%: domain is documented in the schema, site_id is not. The description reinforces that the domain is user-owned ('a domain they already own') and implies site_id is the target WebTwizz site, but adds no syntax or format detail the schema doesn't already carry.

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 verb (connect), resource (a domain the user already owns), and target (their WebTwizz site), and states the side effect (adds it and returns DNS records). An agent can act on this 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 concrete trigger condition ('when the user asks to connect a domain they already own') and routes to the follow-up sibling check-domain for verification. It stops short of stating when NOT to use it (e.g., versus set-site-address or a domain that isn't yet owned).

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 this is a non-read-only, non-destructive, open-world write, but the description goes well beyond them: it consumes the account's WebTwizz credits (a cost signal), the build starts immediately and is shown live on a card, the result opens in WebTwizz for visual editing, and calling again creates yet another site — an important duplicate-creation warning.

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 invocation condition and efficient across three sentences, but the third sentence bundles several distinct facts (live card, visual editing, credits, repeat creation) that could be tightened slightly.

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 create tool with a full output schema and complete parameter documentation, the description covers what an agent needs: intent trigger, what is created, immediate build behavior, credit cost, and the fact that subsequent calls spawn additional projects. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters, and the baseline is 3. The description only gestures at brief, images and reference_url ('a brief, and optionally the user's pictures or a website to start from') and adds nothing about name, files, template or workspace_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?

States a specific verb and resource: 'Creates a new WebTwizz project from a brief' that 'starts building it right away.' The closing clause 'each call makes another new site' implicitly separates it from duplicate-site and update-site, but no sibling is named explicitly, which is what a 5 would require.

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 given: 'Use this when the user wants an idea or this conversation turned into a real website or web app.' It clarifies the user-intent condition well, but offers no when-not guidance or named alternatives (e.g. editing an existing site with update-site instead).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely new context beyond that: the deletion hits live data immediately with no build/publish step. It does not state whether the operation is reversible or whether confirmation (via the confirm-action sibling) is expected, leaving a modest gap.

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 activation trigger, then the behavioral nuance, then the disambiguation. No filler; the examples ('a booking or an old product') are concrete and earning their 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 values need not be described, and the three required parameters plus the live-vs-build distinction are covered. The only meaningful omission is whether the deletion is permanent/irreversible or requires a confirmation step, which an agent performing a destructive action would want to know.

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%: 'table' and 'row_ids' have descriptions that cross-reference list-site-data and get-site-data, while 'site_id' is undocumented. The description adds no format, count, or constraint detail for any parameter, so it neither compensates for the gap nor helps 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?

Specific verb (delete) plus resource (records/rows in a site's database table) with concrete examples (a booking, an old product). It also differentiates from the sibling edit-site by scope: record deletion vs. table/column removal.

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 delete records...') and states the boundary case with the named alternative ('Use edit-site instead to remove a table or column'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond them: the return is a link, and that link is only valid while the user is signed in to WebTwizz — an expiry/auth constraint the agent could not infer from 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 filler, with the usage trigger front-loaded and the link-validity caveat placed after it. 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?

An output schema exists, so return values need not be explained, and the description nonetheless adds the session-bound link constraint. The remaining shortfall is the undocumented site_id and the absence of any note on what the zip contains or its size limits.

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 site_id parameter, so the schema contributes nothing and the description must compensate. It only indirectly implies the parameter via "their WebTwizz site" and never states what site_id is or where to obtain it, leaving a real 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 (download) and resource (source code of a WebTwizz site as a zip file), which clearly separates it from mutation siblings like publish-site or update-site. It does not explicitly contrast itself with the nearest conceptual sibling, pull-from-github, so it falls 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 wants the source code ... as a zip file" gives an explicit trigger, reinforced by two concrete use cases (host elsewhere, open in an editor). No when-not-to-use or named alternative (e.g. push-to-github for repo sync) is 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?

Adds real behavioral context beyond the annotations: the original site is not modified, the copy is unpublished, and every call produces yet another copy (no idempotency). That last point is exactly the kind of trait annotations cannot express. It omits auth/permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the use case, then the effect, then the repeat-call caveat. The dashboard analogy ('the way Duplicate does on the WebTwizz dashboard') is mildly expendable but the rest 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?

With no annotations about returns and no output schema, the description should say what the agent gets back — critically, the new site's ID needed to publish or edit the copy. It covers what happens to the original but not how to use the result, leaving a real gap for a creation 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 50%: name is documented in the schema (including the '<original name> (Copy)' default), while site_id is undocumented. The description adds no parameter-level detail (e.g., that site_id is the source to copy), so it neither compensates for nor undermines 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 (duplicate/copy) and resource (WebTwizz site), then clarifies the resulting artifact: a new, unpublished project with the same pages, design and content. This distinguishes it from create-site (blank site) and from update-site without needing 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 clear when-to-use contexts: copying to try ideas without touching the original, or starting a similar site. It does not explicitly name an alternative tool (e.g., create-site) or state when-not-to-use, so it stops short of full 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 destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds nothing beyond that: it does not say what is overwritten, whether the change is reversible, how the free-form 'the way they asked' request is interpreted, or that approval may be needed for a destructive edit.

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 and the core purpose is front-loaded, which is good. However, the trailing 'Used by the card' consumes a full sentence while conveying almost nothing actionable, so the brevity reflects under-specification rather than economy.

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 explained. But for a destructive, natural-language-driven mutation with a nested element object and 50% schema coverage, the description omits the behavioral and parameter context an agent needs to invoke it correctly rather than a sibling.

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%: path and request are self-described, but site_id and the nested element object (tag/text/classes) carry no schema descriptions. The description does not compensate, never mentioning site_id, the element structure, or that 'element' identifies the clicked node. With a nested object in the required set, this is a meaningful gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'changes' and the target 'part of a WebTwizz site the user clicked in the card preview' are stated, but the resource is described obliquely rather than named (element HTML/text/classes). Critically, it does not distinguish itself from the sibling edit-text or edit-site, so an agent cannot tell which editor to invoke from the description alone.

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' is a caller note, not usage guidance for an agent. There is no when-to-use vs edit-text/edit-site, no prerequisites, and no exclusions, despite several overlapping edit siblings in the namespace.

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 non-obvious context beyond them: the work is delegated to the site's AI and shown live on the card, it consumes account credits, and 'each call starts another change' (non-idempotent, cumulative). It doesn't cover failure handling or whether confirmation is required for destructive edits.

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, with the usage trigger front-loaded and no filler. The middle sentence is slightly redundant ('Sends the request to the site's WebTwizz AI, which edits the site, and shows the work live on the card') but still earns its place by explaining the async/live behavior.

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 description covers the key operational facts for a destructive, open-world, credit-consuming edit: delegation to site AI, live feedback, per-call credit use. Missing only edge cases like failure behavior or confirmation requirements.

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 schema already documents site_id, request, files, images and reference_url in detail. The description adds 'in the user's words plus any detail from the conversation' for request, which is marginal beyond the schema's own wording. Baseline 3 is appropriate when the schema carries the parameter burden.

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 concrete verb and resource ('change one of their WebTwizz sites') and enumerates the kinds of changes covered (sections, pages, copy, design, features, fixes, question answers). It does not explicitly distinguish itself from close siblings such as update-site, edit-element, or edit-text, but the natural-language AI-request framing is distinctive enough to route an agent.

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 change one of their WebTwizz sites...'), which is clear when-to-use guidance. It does not state when NOT to use it or name the overlapping alternatives (edit-element, edit-text, update-site), so an agent must infer the boundary.

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 known. The description does add real value by disclosing the code-swap-then-fallback mechanism, which is not in the annotations, but it omits reversibility and permission needs.

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 core action, no padding. The trailing 'Used by the card' is low-information but harmless.

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?

No output schema exists, so the description must carry more weight. It explains the core behavior but leaves the return/result, permissions, and the nested element param vague for a destructive mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60%, so the schema documents most params (path, after, before). The description adds no syntax or format detail beyond that, and the nested 'element' object remains unexplained 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?

States a specific verb (saves/swaps text) and resource (text typed by the user in the card preview), so the operation is identifiable. It does not distinguish itself from sibling edit-element, which an agent could easily confuse it with.

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 contextual cue is 'Used by the card', which does not tell an agent when to prefer this over edit-element or edit-site. No when-to-use, prerequisites, or 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 that this is a safe, read-only, closed-world call, so the bar is lower. The description adds genuinely useful behavioral context beyond that: it explains that builds and edits consume credits while data, domain, and preview tools do not, which an agent needs in order to interpret the credit figure it returns.

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 earning their place. The usage triggers come first in a parallel, scannable list, followed by the credit-accounting note that qualifies the returned values.

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 parameterless read tool with an output schema and full annotation coverage, this is complete: it says what triggers the call, what it reports, and how to interpret the credit number. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is empty, so the baseline is 4 and there are no parameter semantics to compensate for. The description correctly avoids inventing arguments.

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 retrieval action and enumerates exactly what it returns: connected account, plan, remaining credits, and workspaces. No sibling tool in the list covers account identity, so an agent can differentiate it without cross-referencing 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?

It gives explicit user-intent triggers ('when the user asks which account is connected, which plan, how many credits, which workspaces'), which is strong when-to-use guidance. It stops short of naming alternatives or conditions where this tool should not be used, so it is not a full 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?

With annotations already indicating readOnlyHint=true, destructiveHint=false, and openWorldHint=false, the safety profile is covered. The description adds valuable behavioral context by mapping connectors to the kinds of data returned, such as visitors/top pages, sales/products, sign-ups/tables, and errors.

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 a single front-loaded sentence that begins with the usage trigger and then supplies examples. The examples earn their place by clarifying connector semantics, though the sentence is long and the enumeration is incomplete.

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?

There is no output schema, and the description provides useful return-content hints and usage context. However, it omits many enum values, does not explain site_id, and does not describe response structure or limitations, leaving gaps for an agent to invoke it optimally.

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 compensate. It meaningfully maps many connector enum values to data domains, but leaves the site_id parameter and numerous enum values undocumented, making the compensation only partial.

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 trigger and implies retrieval of a status/overview for connected services, using examples such as visitors and top pages, sales and products, and errors. It is clear what the tool does, though it does not explicitly name alternatives or siblings for differentiation.

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 usage condition: use when the user asks how something connected to their WebTwizz site is doing. It provides connector-specific examples, but does not state when not to use it or name alternatives such as list-connectors or use-connector.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds conditional behavior not in the annotations: in the unlinked state it returns connection instructions, and once connected it lists the user's repositories. It does not mention that this likely makes remote API calls that can fail or be rate limited.

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 before the enumeration of returned facets. Dense but every clause carries information; only the trailing 'lists their repositories once GitHub is connected' edges toward output restatement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return formatting need not be explained, and the description covers the main facets plus the unlinked edge case. The one gap is the site_id input, which is undocumented in both schema and description, but overall the definition 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?

There is one parameter (site_id) with 0% schema description coverage and no enum. The phrase 'for one of their WebTwizz sites' implies the parameter scopes to a specific site, but no format, ID source, or lookup hint is given. The description adds modest meaning over the bare string type.

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 resource (GitHub integration status for a WebTwizz site) and enumerates exactly what it reports: linkage state, drift between GitHub and the site, last push, recent commits, and open pull requests. This is clearly a read-only status aggregator, which an agent can distinguish from push-to-github and pull-from-github 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?

It gives an explicit trigger condition: 'Use this when the user asks about GitHub for one of their WebTwizz sites.' It further clarifies behavior in two states (nothing linked vs. connected), which tells the agent when the tool is still the right call even before a repo exists. It does not, however, name the push/pull siblings or state when to prefer them.

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 covered. The description adds the useful behavioral fact that the job is in-flight ('live progress'), but says nothing about what happens once the job completes or whether the status is retained after completion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One efficient, front-loaded sentence that leads with the verb and the resource. The trailing phrase 'for its card' is slightly ambiguous filler but costs little.

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 explained. However, for a one-parameter polling tool with zero schema coverage, the description omits the key operational detail of where job_id comes from and how long a job remains queryable, leaving it only minimally 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% and the description never mentions job_id — not its format, nor where the agent obtains it (presumably from the build/edit/publish call that created the job). For a single required parameter with no schema documentation, the description should have compensated and does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb ('Reports') and resource ('live progress of a WebTwizz build, edit or publish'), so the agent knows this is a status-polling tool. It does not differentiate itself from the nearby get-github-status sibling, which an agent could plausibly confuse with this one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use context, no indication that it should be polled after kicking off a build/edit/publish, and no alternatives or conditions for stopping. The word 'live' hints at polling but leaves all guidance 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 the safety profile is covered. The description adds what the response contains, but discloses no additional behavior such as permission requirements, latency, or freshness of the build/chat 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 tight sentences: the usage triggers are front-loaded and the return contents follow. No filler or repetition.

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 compensates by naming what comes back. The remaining gap is the undocumented site_id, which an agent must guess the source of.

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?

There is one parameter (site_id) with 0% schema description coverage, so the schema supplies no meaning at all. The description only implies the id identifies "one of their WebTwizz sites" and never states its format or where the agent should obtain it, leaving the parameter effectively undocumented.

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 clear retrieval purpose and enumerates the returned content (status, latest build or question, recent chat), which lets an agent understand the tool without opening a schema. It does not differentiate against near siblings such as get-site-data, get-job-status, or list-sites, 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 explicit triggering conditions tied to user intent ("how a site is going", "what changed", "whether it is live"), which is strong when-to-use guidance. However, it offers no when-not guidance and never names an alternative tool for adjacent needs like raw site data or build jobs.

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 safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds two useful facts beyond them: results are paginated ('Returns a page of rows') and row_id is the key required by the sibling mutation tools.

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 with zero waste. The trigger condition is front-loaded and the row_id contract is a tight, high-value second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return formatting need not be explained. The description covers the trigger, the shape of results, and the downstream key contract; only the list-site-data relationship and the untaken param descriptions are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60%, so the schema already documents table, search, and page_size. The description mentions pagination but does not clarify 'page' or 'site_id' (undocumented in the schema) or the page_size default of 20, so it does not compensate for 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?

The description names a specific reader action ('see records in one of their WebTwizz site's database tables') and gives concrete examples (bookings, orders, products). It does not, however, distinguish itself from the sibling list-site-data, leaving a real ambiguity about get-vs-list semantics unaddressed.

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 states the trigger condition ('when the user wants to see records') and links forward to update-site-data and delete-site-data as consumers of the returned row_id. No when-not guidance or direct comparison to list-site-data 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them. Beyond the annotations it discloses the return content (connectors, connected accounts, per-site usage, connect link) and the side effect that a connect link opens the given site, which is useful behavioral context.

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 in the first clause and the return shape follows immediately; every sentence earns its place. The 12-item connector enumeration is longer than strictly necessary but is defensible for matching the user's own service vocabulary.

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 carries the return-value burden by describing what each connector entry contains. Safety is covered by annotations and the single param by the schema, leaving no meaningful gap for a read-only list 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 description coverage is 100% and the single optional site_id is fully documented in the schema itself, including its effect on the list and connect links. The description only echoes 'which the site uses' and adds no syntax or defaulting detail beyond the schema, 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 and resource ('Lists each connector') and enumerates the connector set, so the agent knows exactly what is returned. It does not name or differentiate against the overlapping siblings get-connector-overview and use-connector, which is the only thing keeping it from 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?

Gives an explicit when-to-use trigger ('when the user asks which services... is connected to, or wants to add one'), which is unusually actionable. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: only public NEXT_PUBLIC_ values are shown and secret values are never returned, which is critical for an agent deciding whether this tool can answer a question about secrets.

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 return contract and the secret-handling caveat. Every sentence carries information, though the phrasing is slightly conversational rather than maximally tight.

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 list tool with no output schema and a single required parameter, the description covers the trigger, the returned fields, and the security caveat. The only material omission is any guidance on the required site_id argument.

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?

There is one parameter, site_id, and schema description coverage is 0% — the schema documents nothing about it. The description never mentions site_id, its format, or how to obtain it, so it fails to compensate for the coverage gap; the parameter's meaning is only inferable from the tool name and context.

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 (environment variables for a WebTwizz site), and enumerates exactly what is returned: each variable's name, whether it is set, and the managing connector. That detail distinguishes it from the write-side sibling set-env-variable without the agent needing to open 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?

Explicitly names the triggering user intent ("when the user asks which settings or keys their WebTwizz site has, like API keys and environment variables"), which gives clear context. It does not name the alternative tool (set-env-variable) or state any exclusions, so it stops short of a full 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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds the useful scope detail that it lists metadata (tables/columns/row counts, collections) rather than row contents, but discloses no auth needs or limits, and the return format is covered by the output schema.

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, with the usage trigger front-loaded ahead of the behavioral description. Efficient, though the second sentence packs two distinct return elements and could be slightly tighter.

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 moderate-complexity metadata listing tool with full annotation coverage and an output schema, the description adequately covers when to call it and what it enumerates. The only real gap is site_id semantics, which neither schema nor description addresses.

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. The description references "their WebTwizz site" but provides no format, source, or semantics for site_id, so it fails to compensate for the documentation 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 (Lists) and resource (the site's database tables with their columns and row counts, and content collections kept in the site's files). This clearly distinguishes it from the sibling get-site-data, which reads the actual data rather than metadata.

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 what data their WebTwizz site has, or before reading or changing it" gives a clear trigger and a sequencing hint (discovery before get/update/delete). It stops short of naming the alternative siblings explicitly, so it's clear context but not full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one behavioral detail beyond the schema: results are ordered by most recently updated. It does not disclose any result-count cap, pagination behavior, or what happens for an empty account, which are the traits an agent would still want here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the primary trigger is front-loaded ahead of the sibling redirect. Every clause earns its place by either stating scope or routing to an alternative.

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, the single parameter is fully documented in the schema, and annotations cover safety. The description supplies the usage routing that the structured fields cannot. The only gap is not stating how many sites are returned or whether the list is capped, which matters for a 'most recently updated' listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one optional parameter and schema description coverage is 100% ('Only sites in this workspace, from get-account. Leave out for all of them.'), so the schema already carries the full semantics. The description adds nothing about workspace_id, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb and resource ('Lists their most recently updated sites') and adds scope via the 'most recently updated' ordering. It also implicitly distinguishes itself from siblings like get-site and show-preview by framing itself as the multi-site listing for a user. The opening sentence is usage-first rather than purpose-first, which slightly softens the statement of what the tool does, but the intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger ('when the user asks which WebTwizz sites they have, or wants to pick one to work on') and an explicit alternative with its own condition ('when the user names a site they want to see, use show-preview with its name instead'). An agent can route between the two tools without 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 and destructiveHint=false, so the safe-read profile is covered without help from the description. The description does add that results include a picture and a live demo, which is mildly useful return context, but an output schema exists so this is not essential. No permission or rate-limit details, which is fine for a read-only list.

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, then the result shape and the handoff to create-site. No filler or repeated schema content.

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 annotations covering safety, the description only needs to convey when to call it and what to do next, both of which it does. The main omission is any hint about the 'category' filter, a minor gap for an optional 0-required-param 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 description coverage is 50%: the 'search' parameter is documented in the schema while 'category' has only an enum. The description alludes to filtering ("matching templates") but never explains how 'search' or the category values (websites/apps/games) shape the results, so it adds little 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 names the resource (WebTwizz templates) and the outcome (shows matching templates with a picture and a live demo), and contrasts it with the create-site sibling by telling the agent to pass the chosen slug there. The verb is implicit ("shows") rather than a crisp "list", but an agent can still tell this apart from the ~35 other 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 gives an explicit trigger ("when the user wants to start from a ready-made design, or asks what WebTwizz templates there are") and the follow-up action ("pass the chosen slug to create-site as template"). The when-to-use and the workflow handoff are both stated, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the annotations: results are ordered newest first, implying relevance for picking a restore target. It does not describe return format or pagination.

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 is front-loaded ahead of the mechanics. 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 read-only single-parameter list tool with no output schema, the description covers when to use it and what it returns at a high level. It could say more about what a version entry contains (e.g., id/timestamp) to help pick a restore target, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single site_id parameter. The description implies site_id selects which site's versions are listed, which is intuitive, but it adds no format or constraint detail. With one self-explanatory identifier, this is adequate but thin.

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 adds scope detail ('newest first'). An agent can distinguish this from the sibling restore-version 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?

Explicitly names the triggering user intent ('wants to undo changes or go back to an earlier version') and routes the follow-up action to restore-version. The when-to-use condition and the companion tool are both 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 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?

Adds real behavioral context beyond the annotations: each call appends a commit rather than replacing history, and the first invocation requires a repository target. It does not cover auth/permission requirements, though destructiveHint=true and openWorldHint=true already flag the safety and external-impact profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the usage trigger, then behavior, then parameter guidance. No filler or repetition of 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 return values need no explanation. The description covers the trigger, commit semantics, the alternative tool, and the one-time setup path, which is everything an agent needs 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?

At 67% schema coverage the description earns its keep by explaining that repo must come from get-github-status, that create_repo makes a new private repository, and that they are alternatives passed on the first call. The required site_id is left 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: 'Commits and pushes the saved site to its repository'. It clearly distinguishes itself from pull-from-github and get-github-status by naming its direction and by routing other git operations to edit-site.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('when the user wants their WebTwizz site's code on GitHub'), names the alternative for other git work ('undoing a push, goes to edit-site'), and spells out the first-call branch condition for repo vs create_repo.

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=false and destructiveHint=true, so the safety profile is covered. The description adds valuable non-obvious behavior: the current version is preserved in history and remains re-restorable, which directly addresses reversibility despite the destructive hint. It does not mention auth requirements or rate limits, but the reversibility disclosure is the key behavioral context here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first front-loads the trigger condition and precondition, the second delivers the reversibility fact. 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 3-param mutation tool with no output schema, the description covers the workflow position, the key input source, and the reversibility guarantee. It could go slightly further on what a successful restore returns or whether it affects the live site immediately, but the essentials are 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 coverage is 67%, with point_id and only_if_latest documented in the schema. The description reinforces that point_id comes from list-versions ('an earlier version'), adding linkage context, but says nothing about site_id or the only_if_latest flag beyond what the schema states. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

State a specific verb (restore) and resource (version of a WebTwizz site), and it clearly distinguishes itself from sibling list-versions by positioning itself as the follow-up action. However, the phrasing leans on the usage context rather than a crisp standalone definition of what restore does to the 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?

Explicitly states when to use it ('after list-versions when the user picks an earlier version') and names the sibling that produces the point_id. The precondition is unambiguous and actionable.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the capture defaults to the latest draft unless live is set, and it reflects what visitors see. It does not discuss latency or capture limits, but for a read-only tool this is solid.

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 carrying a distinct point (purpose, return value, default behavior), with the primary intent front-loaded. Slightly conversational phrasing but no wasted sentences.

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-format details are unnecessary here. The description covers the tool's scope, the visitor-view semantics, and the draft/live default; nothing an agent needs to invoke it correctly is missing, though alternative-tool routing is left out.

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 80%, so the schema already documents live, path, device and full_page. The description's 'Shows the latest draft unless live is set' largely restates the live parameter's schema description, and 'computer or a phone' echoes the device enum. It adds framing but no new parameter-level detail, 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 ('look at' / capture a screenshot) and resource (one of the user's WebTwizz sites), and frames the outcome ('a picture of a page as visitors see it'). It is distinguishable from siblings like show-preview or get-site, which do not return a rendered visitor-view image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use scenarios: check a change, review the design, compare against the user's request. However, it names no alternative tool or explicit when-not condition, so an agent must still infer when screenshot-site beats 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses what is returned (matching pages, matching lines, links) and that a second call with a page title returns the full page.

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 when-to-use triggers before the mechanics. Every clause carries information and nothing is padded.

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 search with no output schema, the description covers triggers, return content, and the drill-in workflow. Minor omissions (behavior on no matches, result count) are not material to 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 description coverage is 100% and the schema for 'page' already says 'A page title from an earlier help result, to read that page in full' — essentially restating the description's follow-up sentence. The description adds no syntax, format, or constraint detail beyond the schema, 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 gives a specific verb and resource ('Searches the WebTwizz docs') and adds the output shape ('best matching pages with the lines that match and links') plus the read-in-full mode. It is clearly distinct from the site-management siblings, though it never names or contrasts an alternative tool 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 states concrete triggers in user terms: asking how to do something, how a feature works, or about plans and limits. It also explains the two-step search-then-read pattern. No when-not conditions or named alternatives are given, but none are really needed since no sibling covers docs lookup.

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 readOnlyHint=false, but the description adds real behavioral context: public values persist immediately, secrets are never accepted in chat but stored as placeholders, and a paste-link is returned. It does not explain the destructive aspect (e.g. what happens to an existing variable of the same name), which is the one gap the annotation raises.

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-loads the use case, then the public/secret branch, then the redirect to sibling tools. Four tight sentences with no filler, each carrying distinct operational meaning.

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 3-parameter tool with no output schema, the description covers everything needed to invoke it correctly: when to use, the public-vs-secret value decision, and the alternate path for connector-based keys.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% and the description meaningfully reinforces it: 'leave value out' for secrets, value only for public NEXT_PUBLIC_ names, and example-style naming via the schema. It clarifies how the required/optional split drives the secret flow, adding value beyond the raw schema 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 (set) and resource (environment variable) for WebTwizz sites, and explicitly names the sibling tools (list-connectors, use-connector) it is NOT for. An agent can distinguish it from the connector tools 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?

Gives the exact trigger ('when one of the user's WebTwizz sites needs an environment variable') and an explicit when-not with the alternative ('Services WebTwizz connects... get their keys through list-connectors and use-connector instead'). Routing is unambiguous.

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

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

Annotations already carry destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds real behavioral value beyond them: a live site moves to the new address and the old one redirects 'for a while,' which tells the agent the operation is not an instant full cutover. It stops short of stating how long the redirect lasts or whether the new name can collide with an existing one.

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 earning their place, with the usage trigger front-loaded ahead of the behavioral 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description supplies trigger and redirect behavior, leaving only site_id and redirect duration unaddressed for a simple two-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (name documented, site_id not). The description reinforces the name parameter's meaning via 'the name before .webtwizz.app,' matching the schema's own example. It adds nothing for site_id, so it doesn't 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+resource (change the site's free address) and pins down exactly what 'address' means: the name before .webtwizz.app. This scope disambiguates it from the domain-oriented siblings like connect-domain and check-domain without opening their 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?

'Use this when the user wants to change their WebTwizz site's free address' gives a clear triggering condition. The 'free address' qualifier implicitly excludes custom-domain changes handled by connect-domain, but no alternative or exclusion is named explicitly.

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 the call read-only and non-destructive, so safety is covered. The description adds real behavioral context beyond that: the result appears as an interactive card, shows the latest draft by default, and switching live shows the published version – useful framing the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the usage trigger, followed by behavior and parameter hints. Every sentence carries information; it is slightly chatty with the quoted example but not wasteful.

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 explained. For a 3-param read-only tool the description covers purpose, trigger, default behavior, the live override, and the site_id flexibility, leaving little an agent needs to 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 67%; live and path are already documented in the schema. The description compensates by documenting the undocumented site_id, noting it can be the site's name, and reinforces the live/draft distinction. This meaningfully adds to what the schema 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?

States a specific verb and resource: show a preview of one of the user's sites or a page. It further distinguishes itself from a plain fetch by describing the interactive card behavior ("click things to change them"), though it never names siblings like screenshot-site or get-site 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 a clear triggering context ("when the user wants to see or look at one of their WebTwizz sites") plus an example utterance ("show me my bakery site") and the after-a-change scenario. It lacks an explicit when-not or a named alternative, 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 flag this as a non-read-only, destructive operation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: 'Work done so far is kept,' clarifying that stopping does not discard partial progress. It does not cover auth requirements or whether the call is idempotent, keeping it from 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 tight sentences with zero filler, and the usage trigger is front-loaded ahead of the post-condition. Appropriate sizing for a simple one-parameter tool.

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 explained, and annotations cover the safety profile. The description covers when to use it and the key side effect (work retained). The remaining gap is the unexplained site_id, which keeps it from a 5.

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?

There is one required parameter, site_id, at 0% schema description coverage, so the description carries the full burden of explaining it — and it says nothing about which site/build is targeted or what format site_id takes. The only hint is the parameter name itself, which is insufficient compensation.

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 ('stop a WebTwizz build or edit that is running'), so an agent knows exactly what operation this performs. It is clear but does not reference any sibling tool, and there is no other stop-style sibling to be differentiated from, so it lands at a solid 4 rather than 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 an explicit trigger: 'Use this when the user wants to stop a WebTwizz build or edit.' That is clear usage context, but it names no alternatives and gives no exclusions or preconditions (e.g. only when a build is actually in progress).

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 genuinely useful nuance beyond them: the site persists as a draft, is republishable, and custom domains stop pointing at it until then — clarifying that 'destructive' here does not mean data loss. It does not mention auth requirements or whether the domain change is immediate/instant.

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 no filler, and the triggering condition plus the side effects are stated up front. Leading with 'Use this when' rather than the action verb is the only minor structural weakness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the annotations carry the safety profile. The description covers intent and post-conditions well; the only real gap is the undocumented site_id parameter.

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 or how the target site is identified. Although a single site_id is largely self-evident, the parameter is undocumented in both structured fields and prose, so the description does not 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 ('take their published WebTwizz site offline'), which is clearly distinct from siblings like delete-site-data, publish-site, and update-site. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this when the user wants to take their published site offline' gives a clear triggering intent. It stops short of naming the adjacent alternative (e.g., versus delete-site-data or edit-site) or stating exclusions, so it is context without explicit routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is partly covered. The description adds genuinely non-structured behavior: visibility changes only take effect 'the next time the site is published', which is important deferred-effect context an agent cannot get from schema or annotations. It stops short of stating auth/permission requirements or whether a visibility downgrade disrupts an already-live site.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences: the trigger and capabilities first, the publish-timing caveat second, the sibling redirect last. No filler, and the most decision-relevant information (what it does, when it applies) comes before the routing note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description covers both mutations, the enum semantics, and the sibling boundary. Minor gaps remain: it does not say whether renaming affects the published URL/address (a natural confusion with set-site-address) or what permissions the caller needs.

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 lack descriptions), so the description must compensate — and it does by unpacking the three visibility modes and their meaning. The password constraint is echoed from the schema, adding little, and site_id remains unexplained, but the enum semantics are fully carried by the description.

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 two concrete mutations the tool performs: renaming a project and setting published-site visibility (public/password/private). It explicitly distinguishes itself from the sibling edit-site, which handles page titles, descriptions and SEO, so an agent can route correctly 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?

It gives an explicit trigger ('when the user wants to rename... or choose who can see the published site') and an explicit anti-trigger by redirecting SEO edits to edit-site. The password rule ('only send it when the user gives one') further scopes correct invocation.

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, but the description goes beyond them by disclosing that changes hit live data immediately with no build, and that only the columns given are replaced while other values persist. It omits permission/auth requirements and reversibility, so it falls short of 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?

Three short sentences, front-loaded with the triggering condition, then mechanics, then the alternative. Every sentence carries a distinct decision-relevant fact with no padding.

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. The description covers trigger, immediate-write behavior, replacement semantics, and the sibling alternative; only auth/permission expectations and any rollback path are unaddressed for a destructive mutation.

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% (site_id is undocumented) and the description adds little parameter detail beyond 'the columns given' for the data object. The schema documents table and row_id adequately, so the description's marginal contribution is baseline-level.

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 ('change a record in one of their WebTwizz site's database tables') and grounds it with concrete examples (product price, booking time). An agent can distinguish it from add-site-data and edit-site 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?

Gives an explicit when-to-use ('user wants to change a record') plus an explicit alternative and the condition that selects it ('Use edit-site instead for new tables or columns, or for content kept in the site's files'). 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=false and destructiveHint=true, so the agent knows this is a write operation. The description adds genuinely useful behavioral context about the post-call flow ('some connectors need one more choice ... the result says so and links there'), but says nothing about what the call changes, whether an existing connection is replaced, or any auth requirement — notable gaps for a destructive 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 the usage condition, followed by the parameter source and then the post-call behavior. 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?

With no output schema, the description usefully covers what the result can contain and links the follow-up step. Combined with the tool's three required params, the main remaining gap is the absence of any statement about what the call mutates, which matters given destructiveHint=true.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%; connection_id provenance ('From list-connectors') is already in the schema, and connector has its own description. The description adds no meaning for site_id and does not clarify the relationship between connector and connection_id, so it merely matches the schema baseline.

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 ('use this when the user wants one of their WebTwizz sites to use an account they already connected') and names concrete examples (Stripe, Supabase, GitHub). It is clearly distinguishable from list-connectors and get-connector-overview, which it references for the id.

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 triggering condition ('when the user wants ... to use an account they already connected') and routes the agent to list-connectors for the required connection_id. It does not state when-not to use it or explicitly name a competing sibling tool, 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.