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

Annotations only flag readOnlyHint=false and idempotentHint=true; the description goes well beyond them by disclosing that the domain is reserved rather than delivered, that the provider releases it over following days, that post-charge failures auto-refund with refunded:true, and how to observe completion (poll list_domains or the domain.registered webhook). It never contradicts the annotations.

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

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

Front-loads the money-spending consequence, then layers workflow, delivery caveat, refund behavior, and error routing as distinct short blocks. Every sentence carries operational information; nothing is 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?

For a non-idempotent-feeling purchase with four parameters, no output schema, and real financial consequences, the description covers charging semantics, quoting, delivery timing, verification path, failure/refund handling, and error-code triage. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real value by explaining the enforcement rule ('cost_cents must equal totalPrice from get_closeout exactly — any other value is refused') and the dry_run/cost-0 pairing. It adds little on the deprecated `cost` alias or the `domain` parameter, which the schema already covers.

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?

Opens with a specific verb and resource plus the exact effect: 'Spends account credit. Buys a closeout at its current price and claims the name.' This clearly separates it from get_closeout and search_closeouts, which read rather than purchase.

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

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

Gives explicit preconditions (confirm total with the user, use dry_run with cost 0 to quote) and explicit do-not-retry rules keyed to error codes (CLOSEOUT_UNAVAILABLE, CLOSEOUT_NOT_ELIGIBLE). It also states the eligibility requirements, so the agent knows when this call is valid at all.

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

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

Goes well beyond the destructive/openWorld annotations by disclosing the internal sequence (mark cancelled locally, withdraw at registry, verify, refund), the restore-on-failure semantics, the TRANSFER_STATE_UNCONFIRMED outcome, and escalation policy. This is exactly the kind of behavior an agent cannot infer from annotations.

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

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

Front-loads the what and the confirm-first rule in bold, then walks through the ordering and failure path. Mostly every sentence earns its place, though 'The order is deliberate' is slightly chatty filler around otherwise load-bearing detail.

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

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

For a destructive, non-idempotent mutation with no output schema, it supplies the safety preface, the failure/rollback behavior, the error code to expect, and the response fields (withdrawnAtRegistry, registryResultCode, refunded, refundAmount). An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and both parameters are self-documented, so the baseline is 3. The description never mentions 'domain' or 'dry_run' and adds no syntax or selection meaning beyond the schema.

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

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

States a specific verb (cancels) plus a precise resource and effect (paid inbound transfer, refunds the order). An agent can distinguish this from list_transfers, get_transfer_status, and start_transfer 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 clear operative context: 'Confirm with the user first' and, on the unconfirmed path, 'escalate to support rather than retrying.' It does not name alternative siblings such as get_transfer_status for inspection, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety bar is low, yet the description adds real behavioral context beyond them: concrete rate limits (10 checks/10s here vs 200/min on check_domains), the rationale (Porkbun chunks per registry, batching is cheaper), currency (USD), and a hard downstream constraint that register_domain rejects a mismatched `cost_cents`. None of that is derivable from the structured fields.

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

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

Front-loaded with the purpose and return values, then the cost-match warning, then the sibling routing. Every sentence carries actionable weight — the return-field list, the USD note, the register_domain constraint, and the budget rationale each earn 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?

No output schema exists, and the description compensates by enumerating the return fields (availability, registration/renewal/transfer price, premium pricing details) and currency. For a single-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

With one parameter at 100% schema coverage, the schema already documents the FQDN format and example, so the baseline is 3. The description reinforces the single-domain scope ('a single domain', 'Checking more than one name?'), which is useful but does not add syntax or format detail beyond the schema.

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

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

States a specific verb (check availability) plus resource (a single domain) and even names the sibling it must not be confused with: 'Checking more than one name? Use `check_domains` instead'. The agent can distinguish check_domain from check_domains, get_pricing, and preflight_domain 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 prerequisite ('Use this BEFORE register_domain to confirm cost'), an explicit exclusion, and an explicit alternative with the condition that selects it (batch of up to 25 names → check_domains). Nothing about when-to-use or when-not-to-use 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 only cover the safety profile (readOnly/idempotent/openWorld). The description adds the budget model (200 domains/60s counted per domain vs the single check's 10/10s), failure modes (BULK_CHECK_TOO_MANY, BULK_CHECK_TOO_SLOW, RATE_LIMIT_EXCEEDED with reason SUSTAINED_BULK_CHECKING), timing (~3s, no polling), and the critical semantic that `unresolved` is neither available nor taken.

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

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

Front-loaded with the core action, then bolded sections for result lists, limits, and error handling. Despite its length, every paragraph carries distinct operational information (budgets, error codes, TLD handling) with no filler.

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

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

There is no output schema, and the description compensates fully by enumerating the three result lists and their distinct meanings, including the subtle 'unresolved is neither available nor taken, retry those' trap. Nothing needed for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so 3 is the baseline; the description goes beyond by explaining the consequence of exceeding maxItems (error, checks nothing, no silent truncation) and that duplicates are stripped before the budget is charged. That adds meaning over the schema's terse 'Max 25; duplicates are ignored.'

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, and scope: 'Check up to 25 domains for availability and price in ONE call.' It explicitly distinguishes itself from the sibling `check_domain` and frames the batch-vs-single tradeoff, so an agent can route 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?

Gives explicit when-to-use ('more than one name'), when-not ('not in a loop' for sustained scanning volume), and prerequisite grouping rules (isolate .de names, split lists over 25). The registry-chunking rationale makes the guidance actionable rather than arbitrary.

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 mark this destructive/non-read-only/idempotent, and the description adds context the annotations cannot: it authorises real card charges, requires user confirmation, neither adds nor changes cards (nor can a card be added over the API), and that disabling keeps the amount on file. This is exactly the behavioral detail that goes beyond structured hints.

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

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

Front-loaded with the core action, then structured into per-parameter paragraphs using backticked names. It is on the long side and repeats some cent-unit examples that also appear in the schema, but each paragraph carries usable information rather than filler.

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

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

With no output schema, the description still discloses the dry_run return (`wouldSucceed`) and what changes vs. persists for each flag combination, covering the interaction model an agent needs for a 6-parameter opt-in/opt-out 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 100%, so the baseline is 3, but the description genuinely adds meaning beyond it: `amount_cents` stands on its own and can be set without enabling, the $500 cap/$5 floor behave differently via API vs. account settings, and `enabled: false` preserves the stored amount — none of which the schema states.

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

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

The first sentence states a precise verb+resource: setting the top-up amount and/or toggling auto top-up. The body further distinguishes this from `top_up_account_credit` (on-demand charge of the same figure) and from reading state via `get_auto_topup`, so an agent can place it among its siblings without opening a schema.

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

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

It explicitly covers the when-to-use conditions: setting `amount_cents` alone is normal, `enabled: true` with a threshold makes it fire, `enabled: false` stops firing but keeps the amount, and dry_run validates. It also names the alternative tool (`top_up_account_credit`) and gives an instruction to confirm with the user before calling.

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 cover safety hints (readOnly=false, idempotent=true, openWorld=true), but the description goes well beyond them by disclosing post-success behavior (retry VERIFICATION_REQUIRED failures), the meaning of emailVerified: false, and the PHONE_CODE_INVALID failure semantics. This is exactly the contextual layer structured fields cannot carry.

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 purpose and prerequisite are front-loaded in the first clause, followed by success and error handling. It is a dense multi-clause paragraph but each clause carries actionable information; only slight tightening would help.

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 supplies the missing return semantics (emailVerified flag, PHONE_CODE_INVALID error) and the follow-up workflow. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% with a single parameter whose format constraints (4-12 chars, case-insensitive) are fully documented in the schema. The description only restates that the code comes from the sibling tool, adding no syntax or format 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 (verify) and resource (the account's phone number) plus the required input (the code), and explicitly ties the code's origin to the sibling tool send_phone_verification_code. An agent can distinguish it from send_phone_verification_code 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?

Clearly states when to use it (after the user receives a code from send_phone_verification_code), what to do on success (retry the VERIFICATION_REQUIRED failure), and how to recover from failure (check code with user or send a new one). Both the success path and the error path route the agent to the correct next action.

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 destructive=true and idempotent=true, but the description adds far more: it is ASYNCHRONOUS and a success means QUEUED not connected, results are per-domain with individual reasons, a non-empty `skipped` is normal rather than an error, and eligibility is re-checked before each domain acts. These are exactly the behavioral traits annotations cannot express.

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?

Dense but front-loaded: the async/queued caveat and the poll-it-next instruction come early where they matter most, and each subsequent sentence adds a distinct fact (per-domain results, skipped-is-normal, eligibility re-check, dry_run, domain cap). 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?

There is no output schema, yet the description tells the agent the exact result shape (`queued`, `skipped`, `alreadyQueued`) and how to interpret it, plus the async handoff to get_cloudflare_queue. Nothing an agent needs to invoke and correctly interpret this tool 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 both parameters are already documented in the schema. The description's dry_run guidance and 500-domain limit largely restate the schema's description and maxItems constraint rather than adding new semantics, 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 action (queue domains to move into the customer's own Cloudflare account) and then spells out the mechanics: Porkbun creates the zone, copies DNS records, repoints registry nameservers. This is clearly distinguishable from siblings like preview_cloudflare_move or retry_cloudflare_domain.

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 prerequisite (Cloudflare account must be connected first, see get_cloudflare_connection), the follow-up action (poll get_cloudflare_queue), the preview path (use dry_run), and the boundary (max 500 domains per call). When-to-use and what-comes-next are both 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 declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety baseline is covered. The description adds useful behavior the annotations cannot: dry_run support and the per-type constraints (MX needs priority, proxied only for A/AAAA/CNAME, structured types need data). It does not discuss auth requirements or duplicate-record 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 critical migration caveat is front-loaded as IMPORTANT before the per-parameter rules, which is the right ordering. Density is high and appropriate for 10 parameters, though the back-to-back constraint clauses read as a run-on list rather than cleanly grouped guidance.

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

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

For a 10-parameter mutation with a nested data object and no output schema, the description covers type-conditional rules, defaults, and dry_run well. It omits any statement about what the call returns or how to verify the record landed, which is the remaining gap.

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

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

Schema coverage is high (90%), so the baseline is 3, but the description meaningfully supplements it: "@" for apex, ttl 1 = automatic, priority required for MX only, proxied applicability, and the content-vs-data split for structured record types. This is more than restating 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 ("Create a DNS record in a domain's Cloudflare zone") and explicitly distinguishes itself from the sibling create_dns_record by naming which zone actually resolves. An agent can select between the two without opening either schema.

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

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

Gives a clear when-to-use rule against the closest alternative ("for a domain that has been moved to Cloudflare this is the tool that changes what actually resolves"), including the consequence of picking the wrong one. It stops short of naming when-not to use it (e.g. for existing records where edit/delete apply), so it is clear context rather than full 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?

Goes well past the annotations, which only declare non-readOnly, non-destructive, idempotent, closed-world. The description discloses cost ('free, doesn't spend account credit'), the two error codes and their payload fields, the dry_run validation path, and the important quirk that a write can return SUCCESS with a warnings string when the zone is not actually authoritative. Minor ding: it never reconciles the duplicate-fails behavior with the idempotentHint=true annotation, leaving a small ambiguity about repeat-call semantics.

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 purpose and return value before drilling into edge cases, and every paragraph addresses a real failure mode. It is still fairly long with heavy bolding and a mid-paragraph meta-instruction ('Check warnings in the response and pass it on'), which is slightly awkward 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?

There is no output schema, so the description must carry return semantics — and it does: id for downstream update/delete, existingId on DUPLICATE_RECORD, conflictingRecords on RECORD_CONFLICT, warnings on non-authoritative zones, and wouldSucceed under dry_run. Combined with full schema coverage, an agent has everything needed to invoke and interpret the call.

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 ttl, name, prio, domain and content are already documented in the schema; per the rubric that sets a baseline of 3. The description restates the apex/prefix rule for `name` and the MX/SRV requirement for `prio`, which corroborates but adds no syntax or format detail beyond what the schema already carries.

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 ('Create a DNS record on a domain') and immediately disambiguates from siblings by naming update_dns_record and delete_dns_record as consumers of the returned id. An agent can distinguish this from create_cloudflare_record or import_dns_records 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 concrete routing conditions: duplicate content → reuse existingId instead of retrying or creating a variant; CNAME name clash → delete conflictingRecords or pick another name; non-Porkbun nameservers → make the change at the other provider or call update_nameservers. It states both when to use and when not to, plus named alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but the description goes well beyond them: registry-specific (not global) validation, the DNSSEC_ALGORITHM_DEPRECATED refusal and that retrying identical values won't help, and that a SUCCESS response may include a warnings array even though the record WAS created.

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 purpose and usage, then escalation-relevant operational detail; every sentence carries information (error code, safe defaults, sibling scope). It is dense and slightly long, but there is no filler or repetition of the schema field list.

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 10-parameter mutation with no output schema, the description supplies the missing behavioral layer: failure semantics (named error code, non-retryable), partial-success semantics (warnings array on SUCCESS), and a universal safe default. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it separates the five required DS fields from the rare optional key-data fields, and recommends safe values (alg 8 or 13 with digestType 2) that are accepted everywhere. It does not cover fields like maxSigLife or keyDataFlags, which the schema handles alone.

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?

Starts with a specific verb+resource: 'Submit a DNSSEC DS record to the registry for a domain.' It is clearly distinguishable from siblings like create_dns_record (zone records), list_dnssec_records, and delete_dnssec_record, and it even scopes the difference by naming the latter two.

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: 'Use when you sign DNS yourself (custom nameservers running BIND/Knot/PowerDNS/etc.) and need to publish the chain-of-trust at the parent zone.' It also tells the agent where the tool does NOT apply by noting deprecation never affects list_dnssec_records or delete_dnssec_record.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description's only behavioral note, 'Idempotent', merely repeats the annotation and adds no new information such as auth requirements, error behavior, or conflict handling. With annotations covering the safety profile, a 3 is appropriate as the minimum viable, though the description adds little beyond them.

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 purpose and use case, and the four sentences are generally tight. The final sentence 'Idempotent.' is redundant because the annotation already declares idempotency, and the IPs sentence repeats the schema. Still, it is appropriately sized and 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?

For a create operation with full schema coverage and annotations covering safety and idempotency, the description supplies the essential purpose and usage context. It does not explain return values or error behavior, and there is no output schema to compensate. However, the combination of description, schema, and annotations is sufficient for an agent to call the tool correctly, making it nearly 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 100%, so the schema already documents all three parameters. The description's notes that 'subdomain is just the host part' and 'Provide IPs as an array of IPv4 and/or IPv6 addresses' mirror the schema descriptions exactly, adding no new syntax or format constraints. The 'domain' parameter is not mentioned at all in the description. Baseline 3 is correct when the schema does the heavy lifting.

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 (Create) and resource (glue record for a host on a domain), and the term 'glue record' distinguishes it from the sibling create_dns_record. The example clarifies the exact scenario, allowing an agent to differentiate it from update_glue_record and delete_glue_record.

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 use case: 'Used when running your own nameservers on the same domain they serve (e.g. ns1.example.com serving example.com).' This tells the agent when to choose this over a regular DNS record. However, it does not explicitly name an alternative tool or state when not to use it, 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 declare a destructive, non-readonly mutation, and the description adds substantial context beyond them: the 15-day free trial with auto-renew, re-provision charging, one-trial-per-domain limit, mandatory nameserver switch, the cost-acknowledgment gate, and async PENDING status. This is a genuinely informative behavioral 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?

Front-loaded with the core action, then sequenced into trial/billing, nameserver, cost-ack, dry-run, async, and WordPress caveats. Dense but nearly every clause carries operational weight; slightly long for a single tool description.

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, the description covers the async lifecycle, the polling target, the SKU-dependent tooling difference, and the billing implications. An agent has everything needed to call this correctly and handle the response.

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

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

Schema coverage is 100%, so the schema already documents sku, domain, dry_run, agree_to_terms, acknowledged_cost_cents, and agree_to_nameserver_change in detail. The description reinforces the cost-echo requirement and nameserver consent but adds little syntax or format detail beyond 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 (provision hosting for a domain) and explicitly scopes the two plan families (Secure Static Hosting vs Cloud for WordPress) selected by `sku`. It cleanly distinguishes itself from siblings like list_hosting_plans, get_hosting, and deploy_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 routes the agent: use `dry_run` to preview, poll get_hosting until ACTIVE before deploying, and for WordPress plans use create_wp_credentials instead of the file tools. 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 declare a non-read-only, non-destructive creation, but the description adds rich context beyond them: no credentials or approval needed, returns a pk1_sb_ / sk1_sb_ pair, seeds $1000 fake credit, and runs against an isolated sandbox with no real registry actions or charges.

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

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

Front-loaded with the core action and key benefit, then details follow logically. Slightly dense but every sentence earns its place with no 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?

No output schema exists, but the description fully explains the return values (pk1_sb_ / sk1_sb_ pair) and how to use them via PORKBUN_API_KEY / PORKBUN_SECRET_API_KEY. It covers all an agent needs to call and apply the tool correctly.

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

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

Only one optional parameter (`name`) with 100% schema description coverage. The description merely restates that it labels the key, adding no syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb (create) and resource (sandbox API key), and distinguishes it from siblings by emphasizing it is the bootstrap step that works before any keys exist. An agent can immediately tell it apart from tools like sandbox_reset or sandbox_topup.

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 clear context: use it for rehearsing register → DNS → renew end-to-end before using a live key, and notes no credentials are needed. No explicit when-not or direct alternative is named, but the sandbox-only scope is implied.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and repeat-safety profile is covered. The description adds a useful cost signal ('Free') and the apex default, but says nothing about required permissions, whether an existing forward on the same domain is overwritten, or rate limits. With annotations doing most of the work, this is adequate but not rich.

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

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

Three short sentences with zero waste: the action, the apex-vs-subdomain scope, the rationale, and the cost note. The key behavior is front-loaded and nothing is repeated from 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?

For a 7-parameter mutation tool with no output schema, the description covers purpose, scope, and cost, and the annotations carry the safety profile. The schema fully documents the parameters, so omission of redirect_type precedence in prose is not a real gap; only the overwrite/existing-rule behavior is left 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 100%, so every parameter including type, wildcard, includePath, and redirect_type is already documented in the schema with enums and precedence rules. The description only echoes the subdomain/apex default, adding no syntax or format detail beyond the schema. 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?

States a specific verb and resource ('Add a URL forwarding rule for a domain') and clarifies the apex-vs-subdomain behavior up front. It cleanly separates itself from the hosting tools by noting it avoids running a web server, but it does not explicitly differentiate from create_dns_record, which an agent might also consider for redirects.

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

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

The description gives a use case ('redirects without setting up a web server') and a cost note, which implies when to reach for it. However, it names no alternatives and states no conditions under which another tool (e.g. create_dns_record) should be preferred, leaving the routing decision partly 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses the returned secret, the HMAC-SHA256 signature scheme over {timestamp}.{rawBody}, the exact validation rules, the INVALID_WEBHOOK_URL failure mode, and that rules are re-checked before every delivery. This is unusually rich operational 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?

Front-loaded with the core action and the secret-handling warning, and each sentence carries real information. It is dense and somewhat long, but nearly every clause earns its place; only minor tightening is possible.

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 compensates by explaining what is returned (the endpoint including its secret). Combined with the URL constraints and event subscription rules, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds rules the schema omits: no credentials embedded in the URL, port 443 only, and the note that an unresolved hostname is accepted at registration. It also restates the events wildcard semantics already in the schema.

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

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

States a specific verb and resource ('Register a webhook endpoint') and immediately scopes the behavior (Porkbun POSTs signed JSON on subscribed events). It is clearly distinguishable from siblings like update_webhook, delete_webhook, and list_webhooks.

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

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

Gives explicit when-to-use guidance and named alternatives: use a public HTTPS tunnel (ngrok, Cloudflare Tunnel) or sandbox_trigger_webhook for local development, and it warns against pointing at localhost/internal hosts. Exclusions are concrete rather than implied.

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

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

Annotations only cover the generic safety profile; the description adds the operationally critical facts: the password is returned once and must be saved, the default is a least-privilege porkbun-agent/editor user, administrator implies arbitrary code execution and requires acknowledge_full_access, and there is a 20-per-hour rate limit.

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 CLOUD FOR WORDPRESS ONLY scope and the core action, then the caveats. Dense but every sentence carries a distinct constraint; only the restated 'save it immediately' warning is mildly redundant with the one-time-return statement.

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, and the description covers what matters about the return value (one-time password, save immediately) plus the credential semantics. For a 5-param mutation with full schema coverage and annotations, 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 coverage is 100%, so the baseline would be 3, but the description reinforces the role/acknowledge_full_access coupling with consequences the schema cannot encode (full site control, code execution). It adds risk semantics beyond the enum labels rather than merely restating them.

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 (mint), resource (WordPress Application Password for a domain's managed WP site), and the downstream purpose (drive it over the WP REST API with Basic auth). An agent can distinguish this instantly from list_wp_credentials, delete_wp_credentials, and deploy_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?

Explicit prerequisites (site provisioned and ACTIVE, poll get_hosting), explicit exclusion (free $0 preview sites), explicit routing to a sibling for cleanup (delete_wp_credentials), and an escalation condition for the administrator role. 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 flag destructive and non-readOnly, but the description adds real context beyond them: live DNS impact, the risk of taking a site or its mail offline, the confirmation requirement, the read-before-delete behavior that makes the response authoritative, and dry_run support.

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

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

Four tight sentences with the destructive warning front-loaded and no wasted clauses; every sentence carries operational 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?

No output schema exists, and the description compensates by explaining that the response reports exactly what was removed, plus confirmation and dry_run behavior — everything needed to call this destructive tool safely.

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 dry_run has no schema description, so the description's 'Supports dry_run' supplies the missing meaning. The record_id provenance is echoed from the schema but reinforced with the sibling tool name.

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 ('Delete a DNS record from a domain's Cloudflare zone') and scopes it to Cloudflare-authoritative zones, which distinguishes it from the sibling delete_dns_record.

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 preconditions ('confirm with the user first') and routes the agent to get_cloudflare_records for the record_id. It does not, however, state when to prefer this over the sibling delete_dns_record, so the alternative selection is left implicit.

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

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

Goes well beyond the annotations: it explains that Porkbun hosts a zone for every domain regardless of delegation, that the write succeeds either way, that success may still carry a `warnings` string, and that the agent must not report plain success in that case. It adds cost ('Free') and the exact idempotency semantics (already-deleted returns success), which contextualizes the idempotentHint annotation rather than contradicting it.

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 core action in the first sentence, then layers idempotency, cost, and the warnings caveat. The warnings paragraph is long but every sentence carries actionable information (what a SUCCESS+warnings means and what to do), so little is waste.

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

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

With no output schema, the description compensates by explaining the response's `warnings` field and its implications, plus the dry_run preflight. For a destructive, idempotent mutation with annotations covering safety, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so `domain`, `record_id`, and `dry_run` are already fully documented. The description reinforces record_id's provenance (from list_dns_records) but adds no syntax or format detail beyond the schema; 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?

States a specific verb ('Delete') and resource ('a single DNS record') and identifies the required key 'record_id' plus where to obtain it (`list_dns_records`). An agent can distinguish it from create_dns_record/update_dns_record and from the DNSSEC/Cloudflare/glue delete siblings 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 clear operational guidance: delete by record_id from list_dns_records, expect idempotent success, and when the response carries `warnings`, either change the record at the answering provider or offer `update_nameservers`. It routes decisively to a sibling, though it does not explicitly say when NOT to use this tool (e.g., versus delete_cloudflare_record).

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 idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by spelling out what idempotency means concretely ('deleting a non-existent key tag returns success') and by scoping the effect to the registry. It stops short of noting downstream consequences such as the domain losing DNSSEC validation.

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 action and scope, then the use condition, then the idempotency guarantee. Every sentence carries distinct information with no filler.

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

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

For a two-parameter mutation with no output schema, the description covers scope, use case, and idempotency behavior, which is sufficient to call it correctly. It omits any note on required permissions or the fact that removing a DS record disables DNSSEC for the domain, a relevant consequence for a destructive registry operation.

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

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

Schema description coverage is 100% for both parameters, so the schema carries the burden. The description adds no syntax or format detail beyond noting the record is 'identified by key tag', which merely restates the schema. 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 precise verb and resource ('Remove a DNSSEC DS record from the registry for a domain') that unambiguously separates it from sibling deletions like delete_dns_record, delete_glue_record, and delete_cloudflare_record. It does not explicitly name a sibling or contrast scope, so it falls short of the top tier.

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 when retiring a key' gives an explicit condition for invocation, which is more than implied usage. It does not name alternatives or state when NOT to use it (e.g., when the key is still active), so 4 rather than 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description usefully spells out what idempotency concretely means ('deleting a non-existent glue record returns success'), but it restates what the annotation hints at and omits the operational consequence of removing a glue record (e.g., nameserver resolution breaking).

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, zero filler, with the action and identifier front-loaded and the idempotency caveat immediately after. Nothing is wasted.

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

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

For a two-parameter delete with no output schema and annotations covering destructiveness and idempotency, the description supplies what an agent needs to call it correctly. The only gap is the real-world impact of deleting a glue record, which is a minor omission.

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%, with both domain and subdomain fully documented including examples, so the schema carries the burden. The phrase 'by host on a domain' loosely maps to the two params but adds no format or constraint detail beyond the schema.

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

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

States a specific verb (Delete) and resource (glue record), plus the identifying key (by host on a domain). This clearly distinguishes it from sibling tools like create_glue_record, update_glue_record, and list_glue_records.

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 says what the tool does but gives no guidance on when to choose it over alternatives or what prerequisites exist (e.g., that the glue record must currently exist, or implications for the domain's nameservers). No when/when-not 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, consistent with 'deprovision'. The description adds genuinely new behavioral context beyond them: teardown is asynchronous ('scheduled by Porkbun') and irreversible in cost terms (re-provisioning is charged, no second free trial).

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

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

Front-loaded with the action and resource, then a short parenthetical and one 'Note:' clause. Every clause carries information, though the sentence is slightly dense and could be split for clarity.

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

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

For a single-param destructive mutation with no output schema, the description covers the safety-relevant facts an agent needs: what is destroyed, that teardown is deferred, and that re-provisioning incurs cost. It lacks only explicit when-to-use/alternative routing.

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

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

Only one parameter, and schema coverage is 100%, so the schema fully documents 'domain' (minLength 3, target of deprovisioning). The description adds no format, constraint, or meaning beyond what the schema already provides, so 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?

States a specific verb plus resource ('Deprovision (cancel) Secure Static Hosting') and scopes it to a domain, which distinguishes it from siblings like delete_hosting_file or create_hosting. 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?

The description implies usage (cancelling hosting) but never states when to use this versus alternatives such as delete_hosting_file or create_hosting, nor prerequisites like ownership of the domain. The free-trial note gives consequence context but not selection 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?

Goes well beyond the annotations (destructive/idempotent hints) by disclosing concrete semantics: already-absent paths return alreadyAbsent: true, non-empty directories fail with HOSTING_DIR_NOT_EMPTY and list contents, recursive caps at 2,000 items, and the site root is undeletable. This is exactly the failure/limit context an agent 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?

Front-loads the core action, then each subsequent sentence carries distinct load: idempotency, error behavior, recursive semantics, and the recommended bulk strategy. No filler or restatement of the name.

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

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

With no output schema, the description still communicates what the call returns on the interesting cases (alreadyAbsent flag, error code plus contents list) and the practical limits. 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?

Schema description coverage is 100% (baseline 3), and the description adds real meaning on top: it explains what recursive actually does (delete a directory with everything inside, up to 2,000 items) and constrains path (root cannot be deleted). It adds little on domain, hence not a 5.

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

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

States a specific verb (delete) and resource (file or directory) and scopes it precisely to 'a domain's Secure Static Hosting space', which separates it from service-level tools like delete_hosting and from make_hosting_dir/list_hosting_files. An agent can select it 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 clear operational guidance: no need to pre-check because of idempotency, use recursive instead of file-by-file to clear a site, and recursive handles directories with contents. It does not explicitly name sibling tools (e.g., delete_hosting vs. this) or state prerequisites such as domain ownership, so it stops just short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description restating 'Idempotent' is redundant with the annotation but does not contradict it, and it adds no new behavioral context such as irreversibility of the domain or rate limits.

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?

Single tight sentence, front-loaded with the verb and resource, one clause for the id source and one word for idempotency. No waste.

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

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

For a destructive, no-output schema delete tool, the definition is adequate but thin: it omits whether deletion has side effects, what the response confirms, or error behavior when the id is stale. Annotations carry the safety bits, leaving the agent to infer the rest.

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 both domain and record_id are already documented, including the note that record_id comes from list_url_forwards. The description repeats the id sourcing but adds no syntax or format 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' on specific resource 'URL forwarding rule', with the identifier named. Distinguishes from siblings like delete_webhook, delete_dns_record, delete_glue_record by naming the exact resource.

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?

Points to list_url_forwards as the source of the id, which implies you must list first, but gives no explicit when-to-use vs alternatives or preconditions (e.g., that the rule must exist, or what happens to the domain if it's the only rule).

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

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

Annotations already mark destructiveHint=true and idempotentHint=true, but the description adds that deliveries stop immediately and clarifies idempotent behavior—a non-existent id returns an error that is safe to ignore. These are useful nuances beyond the annotations, though auth requirements and permanence details remain unstated.

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 action and followed by impact and idempotency clarification. No redundant or filler text.

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

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

For a simple one-parameter delete with rich annotations and no output schema, the description covers the essential effects. However, it lacks details about whether deletion is reversible or what happens to webhook secrets/events, leaving minor gaps for a destructive operation.

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

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

Schema coverage is 100%, and the single parameter is fully documented in the schema. The description only restates 'by id' without adding format, range, or source-of-id guidance, 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 ('Delete') and resource ('webhook endpoint') and identifies the key parameter ('by id'). The action is unmistakably distinct from sibling reads (get_webhook, list_webhooks) and other mutations (update_webhook, create_webhook).

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 when-to-use guidance or alternatives are given. The description does not say when deletion is preferable to disabling via update_webhook, nor does it mention prerequisites such as ownership or authentication.

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 idempotentHint=true, but the description adds a consequence that structured fields cannot express: 'Anything using that credential stops authenticating immediately.' That instant-effect disclosure is exactly the kind of behavioral context an agent needs before choosing to revoke.

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 hard constraint (Cloud for WordPress only) and the instant-effect warning. Every clause carries information; nothing is 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?

For a destructive, single-domain revocation tool with no output schema, the definition covers the applicable context, both revocation modes, the uuid source, and the operational consequence. Minor gaps remain around wp_user defaults and the dry_run validation path, though the schema covers those fields.

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 already 100%, so the schema documents each parameter. The description still adds value by linking uuid to its origin (list_wp_credentials) and clarifying that all: true revokes every credential for the user, which is more meaningful than the bare schema text. It says nothing about domain, wp_user, or dry_run, so it is not fully additive.

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 (revoke), a specific resource (WordPress application password), and a scope qualifier (CLOUD FOR WORDPRESS ONLY). It also distinguishes the two revocation modes (single uuid vs all: true), so an agent can tell exactly what this does versus siblings like list_wp_credentials.

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 bounds the applicable context with 'CLOUD FOR WORDPRESS ONLY' and points at list_wp_credentials as the source of the uuid, which tells the agent when this tool applies. It does not name an explicit alternative for the non-revocation case or mention prerequisites/permissions, so it falls just short of full 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 / idempotentHint=false, and the description adds the concrete consequence: files at the same path are replaced, so prior content is lost. It also discloses size limits (≤10MB per call), accepted file types, rejection of server-executable types, and automatic parent-directory creation.

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 core action and constraint data, then the routing/consent guidance. Every sentence carries information, though the final sentence is long and could be split for readability. 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?

Covers operation, encoding, path semantics, size limit, file-type restrictions, host-state prerequisite, destructive overwrite behavior, and agent routing/consent behavior. With no output schema needed for an upload tool, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: base64 encoding of content is restated helpfully, path values may include directories, and missing parents are auto-created. The ≤10MB total constraint on files is also a semantic constraint the schema lacks.

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 (upload) and resource (static files to a domain's Secure Static Hosting), and is clearly distinguishable from siblings like delete_hosting_file, make_hosting_dir, and create_hosting. 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?

Explicitly states the prerequisite (hosting must be ACTIVE; check get_hosting first), the alternative to avoid (giving dashboard upload steps), the trigger context (building/editing a site for a Porkbun domain), and the consent requirement (get their OK first). This is about as complete as usage guidance gets.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: the meaning of missing/extra/inSync, that `extra` records survive a restore unless prune is passed, matching on name/type/content/priority rather than id, SOA/NS exclusion, and masked-record value semantics. This is rich context well 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?

Front-loads the core action and the imperative ordering before expanding into result semantics. Dense but every sentence carries distinct, useful information with no filler.

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

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

No output schema exists, yet the description fully explains the return shape (missing/extra/inSync) and matching rules, which is exactly what the agent needs to interpret results. Nothing material is missing for a read-only diff tool.

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

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

With 100% schema coverage and only 2 required params, the schema already documents domain and snapshot_id (including the list_dns_restore_points reference). The description adds interpretive semantics (matching rules) but no parameter syntax or format detail, so 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?

States a specific verb (compare) and resource (DNS restore point vs live zone), and explicitly distinguishes itself from restore_dns_zone as the safe pre-flight step. An agent can tell exactly what this does and why it differs from its nearest sibling.

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

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

Explicitly instructs 'Always do this before restore_dns_zone', naming the alternative and the ordering condition. It also notes it is free, giving the agent a clear when-to-use signal with no inference required.

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, idempotentHint=true, and readOnlyHint=false. The description adds valuable context beyond annotations: that domains already moved remain resolving on Cloudflare, and reconnecting requires browser authorization again — information not derivable from annotations alone.

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

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

Three tightly written sentences front-load the core action, follow with important consequences, and end with a practical caution. Every sentence 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 single-parameter, no-output-schema tool with rich annotations, the description covers the key behavioral nuances: what persists, what stops, and what reconnection entails. Minor gap: does not clarify whether the dry_run parameter triggers any actual state changes.

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

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

Schema coverage is 100%, and the single dry_run parameter is already described in the schema. The description adds no syntax or format details for the parameter, so baseline 3 applies.

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

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

States a specific verb (Remove) and resource (this account's stored Cloudflare connection), clearly distinguishing it from sibling connection-management tools like get_cloudflare_connection and connect_domains_to_cloudflare.

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 clear context on consequences (domains stay on Cloudflare, no further changes made on customer's behalf) and a caution to confirm before calling. No explicit when-not-to-use or naming of alternative tools, but the context is sufficient.

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 idempotentHint=true; the description adds genuinely useful behavior beyond them: partial-update semantics, that the response returns both the new and previous record, and that dry_run is supported. It does not explain what dry_run actually does or what authorization is required, keeping it below a 5.

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

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

Four short sentences, front-loaded with the core action, then prerequisites, return behavior, and dry_run. No filler; each sentence carries information. Slightly terse on dry_run rather than verbose.

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 and 11 parameters including a nested object param, the description does cover return shape ('new record and the previous one'), which is valuable. However it omits what dry_run does, the meaning of the free-form `data` object, and validation constraints, leaving real gaps for a tool of this complexity.

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 45% across 11 params, so the description must compensate. It clarifies partial-update behavior and where record_id comes from, but leaves several parameters (data, comment, content, type, priority) unelaborated in the description while the schema also omits descriptions for them. Baseline 3 for partial 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?

Specific verb+resource: 'Update a DNS record in a domain's Cloudflare zone.' An agent can distinguish this from create_cloudflare_record and delete_cloudflare_record by name and verb. It does not explicitly differentiate from the non-Cloudflare sibling update_dns_record, but the scope wording ('Cloudflare zone') largely covers that.

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 prerequisite/context: 'Get `record_id` from get_cloudflare_records.' It states the partial-update contract (omitted fields keep current value), which tells the agent how to invoke it. It lacks any explicit when-not or alternative-tool routing, so it stops short of a 5.

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

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

Annotations already cover read-only/idempotent/non-destructive safety, yet the description adds real behavioral context: the semantics of `source` (account/default/none with the $100 fallback), the exact error code a purchase over the cap raises, and the authorization constraint that only the account holder can raise the limit. This is value well beyond the structured fields.

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

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

Front-loaded with the core purpose and dense with useful specifics, but the field enumeration is long and slightly list-like. Nearly every clause earns its place, so it stays efficient despite the length.

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 and no parameters, the description must carry the full burden of explaining what comes back and how to act on it, and it does so thoroughly — field meanings, fallback defaults, error code, and remediation path are all 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?

The tool takes zero parameters, so the baseline is 4. The description instead documents the response field semantics in detail (limit/source/spent/remaining, added), which is extra helpful given there is no output schema, though it is not strictly parameter semantics.

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

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

States a precise verb+resource: retrieving the account's API spend controls and the limits actually enforced. It enumerates the three top-level result groups (spendLimit, topupLimit, settings) so the agent knows exactly what the tool surfaces, distinguishing it from balance/pricing 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?

Explicitly says to check `remaining` before an expensive operation and describes the resulting failure mode (MONTHLY_SPEND_LIMIT_EXCEEDED) plus the escalation path (only the account holder can raise it, on the website). It lacks an explicit pointer to sibling tools (e.g. get_balance) for related needs, keeping it short of a 5.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuinely useful context beyond them: the inert-when-no-payment-method behavior and the constraint that a card can only be saved on porkbun.com, never through the API. It could go further on how effectiveAmount is computed, but this is solid added value.

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

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

Two sentences, front-loaded with what the tool reads before the caveats. Every clause carries information, though the second sentence stacks two distinct warnings and is a little dense.

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 must explain return values, and it does so by naming the key fields and the meaning of effectiveAmount. Combined with annotations covering the safety profile, an agent has enough to call and interpret it, though it does not describe the concrete type/format of the numeric fields.

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

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

Zero parameters, so the baseline is 4. Though there is nothing to disambiguate on input, the description explains the semantics of the returned fields (notably `effectiveAmount` and `paymentMethodOnFile`), which compensates for the absence of any other field documentation.

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

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

States a specific verb ('Read') and resource ('auto top-up configuration') and enumerates exactly what is returned: on/off state, threshold, amount, payment-method-on-file, and effectiveAmount. This cleanly distinguishes it from siblings like configure_auto_topup and top_up_account_credit.

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

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

Usage is implied rather than stated: it clarifies that effectiveAmount is what top_up_account_credit would charge, which hints at the read-before-write relationship, and warns that settings are inert without a payment method. But it never explicitly says when to call this versus configure_auto_topup or the other top-up siblings, nor any preconditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description is not required to establish safety. It does add genuinely non-schema behavior: the balance is denominated in cents as an integer with a parallel display string, and it explains the side-effect-free but decision-critical role of the value in the purchase flow. It stops short of stating auth prerequisites or refresh/staleness behavior, so it is strong but not exhaustive.

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

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

Front-loaded with the purpose and return format in the first two sentences, with the routing guidance after. The final sentence about the card-less fallback and the top-up branch is dense and slightly run-on, but each clause corresponds to a real decision the agent must make, so nothing is decorative 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?

For a zero-parameter read with no output schema, the description covers everything an agent needs: what is returned and in what unit, when to call it, and where to route the user when the balance is insufficient. No return-value gap is left open because the description itself supplies the response shape.

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

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

The tool takes zero parameters, so the baseline is 4. The description usefully compensates for the absent output schema by describing the returned fields (integer cents and a human-readable string such as `$12.34`), which is more than the empty input schema conveys.

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 and resource ('Get the available account credit balance for the authenticated Porkbun account') and immediately distinguishes it from related sibling operations by scoping it to prepaid credit rather than card charges. The return shape (integer cents plus display string) is stated up front, so an agent knows exactly what this tool produces versus get_auto_topup or get_pricing.

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 ('Call it before offering to buy anything'), the reason (purchases are paid from prepaid balance, so this decides whether a registration/renewal/transfer goes through), and named alternatives with conditions: top_up_account_credit when the account has a saved card, get_auto_topup to check whether a card is on file. It even covers the negative case (no card, or agent does not charge cards on the user's behalf) with a concrete fallback URL.

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 cover the read-only/idempotent/safe profile, and the description adds substantial context beyond them: the renew-vs-transfer pricing rationale, the `available: false` sentinel meaning, and the warning not to quote the search `price`. This is exactly the non-obvious behavior an agent cannot infer from structured fields.

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

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

Front-loads the core purpose in the first clause, then layers contract, rationale, and sentinel meaning. Dense and mostly waste-free, though the pricing explanation sentence is long and slightly hard to parse in one reading.

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

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

With no output schema, the description correctly takes on return-value explanation: it defines `totalPrice` and `available`, and warns that `totalPrice` (not the search `price`) is user-facing. Nothing needed to call and use the result correctly is missing.

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

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

Schema coverage is 100% with a single documented `domain` parameter, so the schema carries the load. The description references `cost_cents` (a parameter of the sibling `buy_closeout`, not this tool) and adds no syntax or format detail for `domain`; 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?

States a specific verb (get) and resource (one closeout), and immediately qualifies it with the derived `totalPrice` field that makes the tool distinct. An agent can distinguish it from `search_closeouts` and `buy_closeout` without opening any schema.

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

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

Explicit sequencing rule: 'Always call this before buy_closeout' plus the exact contract (pass totalPrice as `cost_cents`). It also explains why search results are insufficient, and gives an exclusion condition (`available: false` means already claimed).

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 it as a safe, idempotent, read-only, non-open-world call, and the description adds the crucial non-obvious behavior: authorization is bound to the web session and cannot go over the API, plus the polling contract and the connectUrl fallback. This is well beyond what the annotations 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-loads the core purpose and the poll-target role, then adds the human-action caveat and the loop. Slightly dense but every sentence carries operational weight; 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, yet the description explains the key return values and the state machine (connected false → connectUrl → poll). For a zero-parameter read tool this covers everything an agent needs to call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes further by describing response fields (connected, connectUrl) and the conditional when connectUrl is present, which is useful though not strictly a parameter concern.

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

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

States a specific verb and resource ('Check whether this Porkbun account is connected to a Cloudflare account, and which one') and immediately identifies its role in the larger connect flow. It is clearly distinguishable from siblings like disconnect_cloudflare and connect_domains_to_cloudflare.

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 frames itself as 'THIS IS THE POLL TARGET for the connect flow', states when connecting is not API-drivable (human browser consent), and prescribes the exact loop: show connectUrl, ask user to authorize, re-call every few seconds until connected is true. Also notes everything else is automatable downstream.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the return payload (zone id, replaced nameservers kept for undo) and the NOT_QUEUED sentinel for unqueued domains.

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

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

Two sentences, no waste, with the scope constraint and purpose front-loaded before the return-value detail. 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?

With no output schema, the description must carry return-value meaning, and it does name the key fields plus the NOT_QUEUED case. It stops short of describing the full status enumeration or the error/missing-domain behavior, leaving a small gap.

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

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

Schema description coverage is 100% for the single 'domain' parameter, so the schema already documents it. The description adds no format, casing, or validation detail beyond what the schema supplies, matching the baseline for a fully covered 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 (get), resource (Cloudflare move status) and narrows scope to ONE domain, which cleanly separates it from batch siblings like get_cloudflare_queue and get_cloudflare_zone. The two key payload fields are named, so an agent knows what it retrieves.

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 NOT_QUEUED sentence implies when the tool is meaningful (a domain that has been queued for a Cloudflare move), but there is no explicit guidance on when to use this versus get_cloudflare_queue, get_cloudflare_zone, or preview_cloudflare_move. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds real behavioral context beyond that: rows are never deleted, making this the audit trail, and each row carries per-domain status plus a message.

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

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

Three tight sentences, all front-loaded: what it returns, when to call it, and a durability/audit property. No filler, and each sentence adds a distinct piece of information.

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

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

With no output schema, the description usefully signals the return shape ('per-domain status and message'), and annotations cover the safety profile. It stops short of describing ordering, grouping, or volume of rows, but for a zero-parameter read tool this is close to 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?

The tool takes zero parameters, so the schema carries no parameter semantics to document and the baseline is 4. Nothing is missing on this dimension.

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 ('List'), resource ('every Cloudflare move this account has requested'), and output content ('per-domain status and message'). The account-wide scope cleanly separates it from per-domain siblings like get_cloudflare_domain_status and get_cloudflare_connection.

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 workflow: 'Use this to poll progress after connect_domains_to_cloudflare.' That is clear when-to-use guidance, but it offers no when-not-to-use or explicit alternative (e.g., when to prefer get_cloudflare_domain_status for a single domain).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: the returned fields (proxied state, proxiable flag) and a specific error condition (ZONE_NOT_READY when the zone does not exist). Not fully exhaustive, but meaningfully additive.

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

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

Three tight sentences, front-loaded with the core action and result shape, with the sibling-disambiguation and error case following. No wasted text.

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

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

No output schema exists, but the description compensates by naming the key returned attributes (proxied, proxiable) and the failure mode. Adequate for a single-param read tool, though return-shape detail is only partial.

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

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

Schema coverage is 100% with a single well-described 'domain' parameter, so the schema does the heavy lifting. The description adds nothing about the parameter's format or constraints, so baseline 3 applies.

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

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

States a specific verb+resource (list a domain's LIVE DNS records) with scope qualifiers, and explicitly distinguishes itself from the sibling list_dns_records by naming which zone each reads. An agent can select 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?

Gives explicit when-to-use ('Once a domain has moved to Cloudflare THIS is the authoritative record set') and names the alternative (list_dns_records reads the Porkbun zone, no longer answering queries). The selection condition 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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it explains why live data can disagree with the stored row and discloses the nameserversDrifted boolean, though it says nothing about auth, rate limits, or freshness guarantees.

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

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

Purpose is front-loaded in the first clause and each sentence contributes (what it returns, why drift matters, what the response adds). The drift example is slightly long-winded, but nothing is pure filler.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does so by listing status, paused, nameservers, activation date, and the nameserversDrifted flag. Combined with annotations covering safety, an agent has everything needed to call this single-parameter read 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% for the single 'domain' parameter, so the baseline is 3. The description only paraphrases the parameter ('a domain's zone') and adds no format or constraint detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Get what CLOUDFLARE ... says about a domain's zone') and enumerates what it returns (status, paused, nameservers, activation date). It also distinguishes the source of truth from the Porkbun queue row, so an agent can tell it apart from get_cloudflare_queue and get_cloudflare_domain_status.

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

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

Explains the drift scenario that motivates using this over the remembered queue row, which is clear contextual guidance. It stops short of naming the alternative tool or an explicit when-not-to-use condition, leaving that inference to the agent.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds genuinely new behavior: it warns when SSL mode is `off` or `flexible` (origin fetched over plain HTTP) and documents the CLOUDFLARE_REAUTHORIZE_REQUIRED error with a concrete one-click reconnect remedy.

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 resource and the settings list, then the warning and the error remediation. Dense but every sentence carries distinct information; minor length from the enumerated settings list.

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 carries the return-value burden and does so by naming the settings returned, the warning condition, and the error code with recovery steps. An agent has what it needs to call and interpret the result.

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

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

Only one parameter (domain) with 100% schema description coverage, so the schema already fully documents it. The description adds no format or syntax detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (read) and resource (Cloudflare zone settings) and enumerates the exact settings returned (ssl mode, always_use_https, min_tls_version, etc.), which distinguishes it from siblings like get_cloudflare_zone and set_cloudflare_zone_settings.

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?

Anchors usage to a clear context ('settings that matter after a move') and gives explicit remediation for the CLOUDFLARE_REAUTHORIZE_REQUIRED case. It does not, however, contrast this with get_cloudflare_zone or get_cloudflare_connection, so the alternative-selection guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that the contacts are for an authenticated account and lists the returned field values, but it repeats 'Read-only' from the annotations and does not disclose error behavior or handling for domains not in the account.

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 and compact, using one main sentence plus a short 'Read-only' note. The final note is somewhat redundant with the annotations, slightly reducing the score from a perfect 5.

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 single-parameter read tool with rich safety annotations, the description provides enough context about what is retrieved and what fields are returned. It could mention not-found or permission behavior, but no output schema exists and the essential retrieval semantics are covered.

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

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

Schema description coverage is 100% for the single domain parameter, which already documents the expected fully qualified domain name format. The description adds the context that the domain belongs to the authenticated account, but it does not provide additional syntax or parameter-level 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 states a specific verb and resource: 'Get the four contacts ... for a domain in the authenticated account.' It further enumerates the exact contact types and field values returned, making the tool clearly distinguishable from siblings such as update_contacts or get_domain.

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 clearly implies a read-only lookup for an authenticated domain, but it does not explicitly say when to use this tool versus alternatives like update_contacts, get_domain, or list_domains. The usage context is adequate but not directive.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that by naming the DOMAIN_NOT_FOUND error code and the exact fields returned, giving the agent behavioral detail the annotations do not carry.

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

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

Front-loaded with the core verb and resource, followed by a compact field list and a second sentence on the error case. Every clause carries information, though the long enumeration in the first sentence is slightly dense.

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 sensibly enumerates the returned fields and documents the not-found error, which is exactly what an agent needs to interpret results. Nothing material is missing for a two-parameter read tool.

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

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

Schema coverage is 100%, so both parameters (domain, include_labels) are already documented in the schema. The description only lightly reinforces include_labels ('optionally labels') without adding 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?

States a specific verb and resource (get a single domain's metadata) and enumerates exactly what is returned: status, TLD, dates, lock, privacy, auto-renew, API opt-in, labels. The word 'single' cleanly distinguishes it from the sibling list_domains.

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

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

Signals the scope ('a single domain in the authenticated account') and gives the failure condition (DOMAIN_NOT_FOUND when the domain isn't in the account), which tells the agent when the call is appropriate. It stops short of explicitly routing to list_domains for bulk needs, so it is clear context without named alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The description adds genuinely new behavior: it returns null when the domain has no hosting and it enumerates the field set returned when hosting exists—useful given no 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 dense sentences with zero filler, front-loading the resource and scope before the null case and the deploy_site relationship. 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 one-param, read-only lookup with no output schema, the description supplies the return-field list and the null case, which is what an agent needs to interpret results. It lacks only explicit guidance on alternative status-check tools.

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

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

There is a single parameter with 100% schema coverage, so the baseline is 3. The description only restates 'for a domain' and adds no format, validation, or lookup nuance beyond the schema.

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

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

States a specific verb (Get) and resource (Secure Static Hosting status) scoped to a domain, and enumerates the returned fields (plan, server, trial, expiry, auto-renew). It even distinguishes itself from deploy_site by naming the deployment relationship, so an agent can place it among the many sibling 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?

The clause 'When ACTIVE, deploy_site publishes site files to it' implies the workflow (check status before deploying) but never states when to call this versus alternatives like get_domain or list_hosting_plans. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaningful behavior beyond them: url and pdfUrl require a signed-in user while downloadUrl works unauthenticated for only 15 minutes, amounts are normalized to cents, and an ID from another account yields INVOICE_NOT_FOUND. These are operational details an agent cannot derive from the schema or 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?

Three sentences, front-loaded with what the call returns, then the differing URL behaviors, then the ID source and error case. Dense but no filler; the field enumeration is long yet each item is load-bearing for understanding the payload.

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 must carry the return contract — and it does, naming the principal response fields, their units, and link lifetimes, plus auth requirements and the failure mode. The only material omission is differentiation from the get_invoice_pdf 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?

There is a single parameter with 100% schema description coverage, so the schema already carries its meaning; the description's cross-reference that IDs come from list_invoices reinforces the schema text rather than adding new semantics. Baseline for a fully documented small parameter set.

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+resource ('Get one invoice as data') followed by an enumeration of exactly what comes back: bill-to, payment method with card brand/last four, line items with term and resulting domain expiry, and gross/refunded/net totals in cents. It also states the source of valid IDs ('Invoice IDs come from list_invoices'), which separates it from the list sibling.

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

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

It gives the prerequisite for obtaining an invoice_id (list_invoices) and the error behavior for a foreign ID, plus practical guidance on which URL to hand a user. However, it never addresses the obvious alternative sibling get_invoice_pdf — an agent choosing between retrieving invoice data and fetching the PDF gets no explicit when-to-use/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material context beyond them: the PDF arrives as an embedded resource, the accompanying fields (filename, sizeBytes, downloadUrl), and crucially that downloadUrl is unauthenticated and expires in 15 minutes. The warning against re-emitting bytes is a genuine behavioral 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?

Front-loaded with the core purpose, then layered with return-shape and expiry facts – all of which earn their place for a tool whose output has no schema. It runs slightly long with three dense clauses in one sentence, but nothing is filler.

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

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

With no output schema, the description carries the full burden of the return contract and does so: embedded resource, field names, unauthenticated 15-minute link, and expiry field. An agent has everything needed to retrieve and hand off the file correctly.

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

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

The single parameter has 100% schema description coverage, and the schema already states it is an 'Invoice (order) ID from `list_invoices`.' The description adds no parameter-level syntax or format 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+resource (get an invoice PDF) and anchors it to a concrete user-facing equivalent ('the same document as Download PDF on porkbun.com'), which removes ambiguity about what artifact is produced. It also differentiates from the sibling get_invoice by noting that tool only returns a link.

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 routes the agent: use this when you need the file, hand the user `downloadUrl`, and use `get_invoice` 'if you only need the link.' It also gives a direct instruction on what NOT to do (do not reproduce the file's bytes yourself), which is exactly the kind of when/when-not guidance that helps selection and 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?

Goes well beyond the readOnly/idempotent annotations by disclosing that data is read live from the registry and that ordering is non-deterministic and semantically meaningless. The warning never to report a reordering as a change is exactly the kind of operational context annotations cannot convey.

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

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

Purpose is front-loaded, followed by return shape and then the ordering caveat; every sentence earns its place. The heavy bold emphasis is slightly noisy 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?

Even without an output schema, the description states the return shape (array of nameserver hostnames), its source (registry), and the key interpretation rule. Nothing an agent needs to call and correctly use this tool 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?

There is a single parameter with 100% schema description coverage (fully qualified domain name with an example), so the schema already carries the semantics. The description adds nothing about the domain argument itself, which is the expected 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 ('Get the current nameservers configured for a domain') and explicitly frames itself as the 'read-only complement to update_nameservers', so an agent can separate it from the sibling write tool 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?

Clear that this is the read side of the nameserver pair versus update_nameservers, and it gives a concrete handling instruction (treat as unordered set). It doesn't spell out a general when-to-use/when-not-to-use rule beyond that pairing, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on genuinely non-derivable behavior: no authentication required, unsupported TLDs returned in an `unsupported` field rather than priced, and a hard INVALID_TLD failure when no requested TLD is sold. It also discloses that input normalization (case, leading dot, IDN) is handled server-side.

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?

Roughly four sentences, front-loaded with the purpose and version-free output shape, then the parameter advice, then edge-case handling. No filler; each sentence carries either routing, parameter, or error information.

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

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

With no output schema, the description takes on return-shape disclosure and does it: pricing categories, currency, the `unsupported` list, and the INVALID_TLD error. Combined with annotation-covered safety and a fully documented single parameter, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: acceptance of mixed case, leading dots, and IDN forms, plus why the parameter matters (response size). It does not mention the schema's 200-item cap, which is the only 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?

Opens with a specific verb+resource (get Porkbun pricing) and enumerates exactly which prices are returned: registration, renewal, transfer, per TLD, in USD. It further separates itself from the closest sibling by noting premium name pricing lives in check_domain, 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?

Gives explicit when-to-use guidance ('Pass `tlds` whenever you know which TLDs matter') plus the consequence of omitting it (a ~900-entry response). It also names the alternative tool and the condition that selects it: premium names go to check_domain. Both the when and the alternative are spelled out.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing what is returned (registerability flag, request-body schema, registry eligibility fields) — significant given there is no output schema. It stops short of error/auth behavior, so not 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?

Front-loaded with the core action, then the return shape, then the usage directive. It is a dense single paragraph but each clause carries distinct information; only the long parenthetical about .us/.ca could be trimmed.

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 must explain what comes back, and it does so thoroughly — including the two-schema structure and the registry-requirements edge case. An agent has everything needed to call it correctly before register_domain.

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 `tld` parameter is fully documented in the schema (including the no-leading-dot format), so the baseline of 3 applies. The description only refers to 'a TLD' generically and adds no syntax beyond the schema.

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

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

States a specific verb (get) and resource (TLD registration requirements) and enumerates the concrete payload contents (apiRegisterable, register_domain body schema, privacy/address/registrant flags, registryRequirements). This clearly separates it from siblings like check_domain, preflight_domain, and register_domain.

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 'Call this BEFORE register_domain to confirm a TLD can be registered and to build a valid payload, instead of discovering requirements from a failed registration.' That is a named alternative plus the condition and the anti-pattern to avoid — no inference required.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: that the response includes a private key, that it is PEM-encoded, and that certificates are auto-provisioned only for domains on Porkbun nameservers — a precondition the annotations say nothing about.

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 what is returned, then the provisioning condition, then the use case. Every sentence earns its place with no filler.

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

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

No output schema exists, and the description compensates by describing the return payload (certificate chain, private key, public key, PEM-encoded). Combined with 100% parameter coverage and full annotations, an agent has everything needed to call and consume the result 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% for the single 'domain' parameter, so the schema already carries the semantics. The description adds only the implicit constraint that the domain must be Porkbun-registered; baseline 3 applies when the schema does the heavy lifting.

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 ('Retrieve the free Porkbun-issued SSL certificate bundle for a domain') and enumerates what the bundle contains. No sibling tool touches SSL certificates, so it is trivially distinguishable from the rest of the family.

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 to install TLS on a server you control' gives a clear use context, and the note about Porkbun nameservers implies a prerequisite. It does not name an alternative or an explicit when-not-to-use, but with no competing sibling that is a minor 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is handled. The description adds genuine behavioral value by disclosing the specific states it inspects (PENDINGDNS hold, DNS zone existence, record count, current delegation, next step), which is beyond what the annotations provide. It stops short of explaining timing or any failure modes.

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 purpose before the enumerated state list and the usage note. The colon-separated inventory is dense but each clause is informative; slightly long, though nothing is redundant.

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

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

There is no output schema, so the description must describe what comes back — and it does, enumerating the transfer state, DNS zone existence, record count, delegation target, and the recommended next step. For a single-parameter read tool with annotations carrying the safety profile, an agent has everything needed to call it.

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

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

Schema coverage is 100% and the single parameter carries its own description including an example value, so the schema fully documents the input. The description adds no syntax or constraint detail beyond that, making the baseline 3 correct.

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 (report) and a precisely scoped resource (where a held inbound transfer is and what it's waiting on), then enumerates the exact state dimensions inspected. An agent can distinguish this from get_transfer_status, list_transfers, and prepare_transfer 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?

Explicitly frames the use case: 'Use this to resume a no-downtime transfer instead of tracking that state yourself.' That gives clear context for when to reach for it, but it never names the alternative tools (e.g. get_transfer_status) or a when-not condition, so routing is inferred rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful context beyond that: the polling pattern, the multi-day completion window, and that status values match list_transfers plus a human-readable description. It doesn't cover error/edge behavior (e.g. unknown domain) but is solid for a read tool.

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