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

With no annotations, the description carries full burden and does an excellent job: it discloses the return value (CNAME target + DNS instructions), the status flow (`dns_pending` until propagation), cost (5 credits), and ongoing billing implications (Active Sites $10/site/month). This goes well beyond a minimal description.

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

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

The description is four sentences and covers action, return value, status, usage guidance, and cost. Each sentence adds value, though it is slightly verbose with the Active Sites detail. Structurally front-loaded with the main action, then supporting details.

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

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

The description fully covers the tool's purpose, return value, status behavior, cost, and alternative. It is complete enough for an agent to select and invoke the tool correctly, especially given the detailed schema and no output schema (return value is described).

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 both parameters are documented in the schema. The description adds no extra parameter-level detail beyond the schema, which is acceptable per the baseline, but it does not enhance understanding 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 clearly states the action ('Attach a domain the customer already registered elsewhere') and the resource ('to a deployed Warpweb site'). It explicitly contrasts with `register_domain`, distinguishing from a sibling tool.

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

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

Provides explicit when-to-use guidance: 'Use this when the customer says I already own the domain' and an explicit alternative: 'versus `register_domain` for new purchases through Cloudflare Registrar.' This is clear 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It explicitly states the tool has no side effects, is free, and that the price must match later or registration will fail. It could mention edge cases like invalid domains or response error patterns, but the key behavioral traits are clearly disclosed.

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

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

The description is two sentences long, front-loads the core purpose, and every sentence earns its place. It packs the essential usage flow, cost behavior, and side-effect information without redundancy or fluff.

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?

Despite lacking an output schema, the description explains what is returned (availability, price_cents, suggestions) and how it fits into the broader registration flow. Combined with the schema's 100% parameter coverage, the tool is fully contextualized for an agent 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?

Schema description coverage is 100%, so the baseline is 3. The description adds context about how the domain should include a TLD and that city/industry bias suggestions, but it does not significantly extend beyond the schema. The key price_cents detail is an output, not a parameter, so it does not elevate parameter semantics further.

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

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

The description clearly states the tool checks domain availability and price through Warpweb, and it distinguishes itself from register_domain by explicitly positioning this as step 1 of a two-call flow. It names the specific output (availability + price_cents) and related suggestions, making the purpose unmistakable.

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 provides explicit when-to-use guidance: it is step 1 of a two-call flow, and the returned price_cents must be passed exactly to register_domain. It also clarifies that it is free, consumes no credits, and has no side effects, helping the agent decide when to invoke this tool versus 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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses HMAC-SHA256 signing, secret issuance only on first config or rotate, idempotency, and the email fallback. Also states the tool is free, covering cost behavior.

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

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

The description is well-structured, starting with the core purpose, then layering critical caveats in order of importance. Every sentence contributes new information, and the IMPORTANT callout highlights the most critical action for the user.

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

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

Despite lacking an output schema and annotations, the description is remarkably complete. It covers the tool's purpose, usage context, security signing, secret lifecycle, idempotency, fallback behavior, and cost. The key response field (secret_issued) is explicitly mentioned, which is essential for correct usage.

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 already covers all three parameters (100% coverage), so baseline is 3. The description adds significant value by explaining the secret_issued response behavior tied to rotate_secret and idempotency with the same URL, going beyond the schema's basic parameter descriptions.

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

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

The description clearly states the tool configures the URL to which Warpweb sends POSTs when a form is submitted. It distinguishes itself from sibling tools focused on site creation, refresh, and domain management.

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?

Explains that unconfigured sites fall back to email, and that most API customers want the webhook for structured JSON plus verification. This gives clear context on when to use the tool, though it doesn't name an explicit alternative tool beyond the email fallback.

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 no annotations provided, the description proactively discloses async behavior (immediate revisionId/queue_position), 30s–4min timing, serial queue with depth cap, clarification flow, webhook/polling options, and cost. This goes far beyond basic operation, giving the agent full expectations for how the tool behaves.

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

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

The description is long but well-structured: it opens with the core purpose, then walks through async behavior, queue, and cost in a logical sequence. Every sentence adds unique operational information, so the length is justified.

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

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

Given the tool's async nature, no output schema, and no annotations, the description fully covers the workflow: immediate response, how to track progress (polling/webhooks), how to handle clarification, queue limits, and cost. This is complete for an agent to use it effectively.

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

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

The schema already provides 100% coverage for both parameters (siteId and prompt) with meaningful descriptions. The tool description adds context about using the prompt to include clarification answers, but otherwise doesn't enhance parameter semantics 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 clearly states the tool's function: 'Conversational edit of a deployed site' with natural-language prompts, and provides specific examples of surgical and structural edits. This distinguishes it from siblings like refresh_site or get_site by focusing on editing via prompt rather than direct actions.

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 implicitly conveys when to use it (whenever a user wants to change a deployed site with plain-English instructions), but doesn't explicitly name alternative tools or state exclusions. The 'right size of edit is chosen automatically' suggests it's the go-to for edits, but no alternatives are referenced.

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 no annotations provided, the description carries the full transparency burden. It thoroughly discloses critical behavior: immediate async return of siteId/status, 3–8 minute build time, polling/webhook options, credit cost, failed-builds-are-free policy, and the risk of building for the wrong business if searching fails. This is far beyond minimal disclosure.

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

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

The description is dense but every sentence earns its place. It opens with a high-level action, then structured details, bolded requirements, warnings, and a cost/async addendum. It is long because the tool is complex, yet it avoids fluff and prioritizes mission-critical information. The formatting (bold, paragraph breaks) makes it easy to scan.

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

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

Given the absence of an output schema and the high complexity (9 params, async behavior, fallback risk), the description is remarkably complete. It explains the return value shape (siteId, status), next steps (poll or subscribe), cost, failure policy, and ideal business fit. No significant informational gap remains for an agent to use the tool effectively.

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?

Although the schema already documents all 9 parameters (100% coverage), the description adds critical operational semantics: contactEmail is the only user-required input, placeId must come from a prior search_businesses call, ownerPrompt should only be captured if voluntarily offered, and businessLocation is strongly recommended for local SEO. This guidance goes well beyond the schema and is essential for correct invocation.

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

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

The description clearly states the tool's purpose: 'Kick off an end-to-end website build for a real business' and enumerates exactly what the build includes (research, copy, design, multi-page site, SEO, deployment). It naturally distinguishes itself from sibling tools like get_site (which retrieves status) and search_businesses (which supplies the required placeId).

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 provides explicit usage guidance: it names the ideal use case ('Best for service-based local businesses'), instructs when to use search_businesses first, warns against asking the user for content inputs, and explains the async flow with polling alternatives. It also specifies when falling back without a placeId is acceptable, giving clear when-to/not-to-use context.

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 no annotations provided, the description fully carries behavioral disclosure. It details the return fields (status, generation_phase, generation_message, deployment_url), enumerates possible status values, explains the polling stop conditions, and documents the 404 behavior for missing or unowned sites. This is rich, honest context beyond mere 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?

The description is front-loaded with the core purpose, then flows logically into usage, return fields, polling pattern, status values, and error behavior. Every sentence adds necessary information; nothing is filler or repetitive. It is appropriately sized for the tool's complexity.

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?

Despite having no output schema, the description adequately explains what the tool returns and under what conditions. It accounts for the single parameter, lists all relevant statuses, provides a practical polling algorithm, and covers the not-found case. It is complete for a simple site lookup/polling 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?

The schema already provides a clear description for siteId ('Site UUID returned by create_site'), giving a baseline of 3. The tool description adds value by explaining that the id refers to a site record, implying the 'by id' lookup, and clarifying that a 404 occurs if the id is not owned by the account. This enriches parameter meaning without redundancy.

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

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

The description clearly states the tool fetches the current record for one site by id, using the specific verb 'Fetch' and resource 'site record'. It distinguishes itself from sibling tools like list_sites (which lists multiple) and create_site (which creates), by focusing on a single site lookup with a clear scope.

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 instructs when to use: to poll build status after create_site or create_revision. It provides a concrete polling pattern with intervals and stopping criteria, and mentions the 404 case for non-existent/unowned sites, offering clear context for usage.

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?

No annotations provided, so description must carry behavioral context. It discloses that the operation is a read-only enumeration, returns an array of site rows with key fields, and is free/unmetered. It does not cover authentication or pagination, but for a simple, parameterless list this is reasonable.

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: one states the action and ownership scope, the other gives return format and cost. 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?

No output schema exists, so description compensates by listing return fields. With zero parameters and simple semantics, it fully covers usage. Alternative tools are not referenced, but the description is sufficient for 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?

Tool accepts zero parameters; schema coverage is 100% by default. Description has no parameters to explain, so baseline 4 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?

Description starts with 'List every site owned by the calling account' – a specific verb and resource scope, and 'array of site rows' clarifies output. This clearly distinguishes it from singular get_site, search_businesses, and create_site siblings.

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

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

No mention of when to use versus siblings like get_site or search_businesses; it only states what it does and that it's free/not metered. The 'every site' phrasing implies broad enumeration, but there are no explicit exclusionary guidelines.

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 no annotations provided, the description carries the full burden and discloses idempotency ('safe to retry'), cost ('free'), and the precise effect (bumps timestamp and restores if paused). It also notes the behavioral difference for custom-domain sites, adding valuable context beyond the 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?

Three sentences cover the auto-pause context, the action taken, and the custom-domain exception without unnecessary fluff. Every sentence earns its place and the purpose is front-loaded.

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

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

For a one-parameter tool with no output schema, the description is comprehensive: it explains the underlying problem, the action, idempotency, cost, and when it is not needed. This gives an agent all the context required to decide whether to invoke the 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?

The schema has 100% description coverage for the sole parameter `siteId` ('Site UUID to refresh'). The tool description adds no further parameter details, but none are needed given the schema's clarity, 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 clearly states the tool refreshes a free-subdomain Warpweb site, specifically bumping `last_refreshed_at = now()` and restoring the live bundle if paused. It distinguishes itself from siblings by focusing on the refresh action rather than creation, listing, or domain operations.

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 explains when to use: for free `*.warpweb.app` subdomain sites that auto-pause after 7 days of inactivity. It also states a clear exclusion: custom-domain sites stay live and do not need this call, with a note about their paid hosting.

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 no annotations, the description carries the full burden. It discloses pricing (at-cost, 50 credits + pass-through), automatic DNS and Pages wiring, the strict price-match guard, a $50 cap, and the Active Site cost implication. It omits failure scenarios but is otherwise highly transparent.

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

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

The description is moderately long but organized with clear sections (precondition, cost, implications). Every sentence adds relevant information and nothing is wasted, though it 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?

Despite no output schema and no annotations, the description thoroughly covers purpose, preconditions, costs, and side effects. It does not describe the return value, which is a minor gap, but the tool context is well understood.

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

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

Schema coverage is 100% for all four parameters, so the baseline is 3. The description reiterates the price-match requirement and slug source, adding minimal new semantics beyond what the schema already documents.

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

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

The description states a specific action: 'Purchase a domain via Cloudflare Registrar at-cost and attach it to a deployed Warpweb site in one shot.' It clearly identifies the resource (domain and site) and distinguishes from sibling attach_domain by emphasizing the combined purchase+attach flow with automatic DNS wiring.

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 an explicit precondition: call check_domain first and pass an exact matching price. It also references create_site for the pagesProjectName. However, it does not explicitly name alternatives like attach_domain for already-owned domains, leaving that 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is free, has no side effects, returns up to 5 candidates, and can silently resolve to the wrong business if skipped. It also details retry behavior, auto-pick rules, and exact fields returned—highly transparent about behavior and edge cases.

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

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

The description is longer than average, but every sentence earns its place: it covers the canonical flow, risks, failure handling, and result fields. It is well-structured with clear sections (purpose, requirement, flow, failure). Slightly verbose but not wasteful for a tool that gates a critical workflow.

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?

Despite having no output schema, the description lists the exact fields returned (placeId, name, address, phone, rating, userRatingCount, businessType), explains how to present results to the user, and covers fallback behavior if the tool fails. Given the tool's complexity and central role in disambiguation, the description fully equips an agent to use 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining that 'query' is free-form business text and by strongly recommending 'location' for common names to avoid globally popular wrong matches. It also contextualizes how the parameters interact with the disambiguation purpose, which goes beyond the schema's simple field descriptions.

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 ('Search Google Places for a business by name') and resource ('Google Places'), and clearly distinguishes it from sibling tools like create_site and list_sites by framing it as a lookup/disambiguation step. It also specifies the return candidate count, which concretely defines its function.

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 explicitly declares when to use this tool ('REQUIRED before create_site whenever you have only a business name'), provides a canonical flow, and gives alternative handling for failures (retry once, then ask the user about proceeding without a placeId). It also warns against skipping search even when confident, which is strong usage guidance beyond basics.

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