Domain Operator Kit

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the 'owned' scope and the fact that a revision is returned, but says nothing about rate limits, permissions beyond ownership, or result shape beyond the revision hint.

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

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

A single front-loaded sentence with no filler. Every clause (read, owned, records, revision, before update) carries meaning.

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

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

For a one-parameter read tool with annotations covering the safety profile and no output schema, the description supplies the key context: what is read, whose records, and that a revision is returned. The only gap is the total absence of parameter documentation.

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

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

Schema description coverage is 0% and the single 'domain' parameter is never mentioned in the description. The name is fairly self-explanatory, but the description adds no format, ownership, or scoping detail to compensate for the undocumented 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?

Names a specific verb+resource ('Read owned DNS records') plus an additional artifact ('their revision'), which scopes the operation clearly. It does not name the sibling dnsSet explicitly, so differentiation from the write counterpart is implied rather than stated.

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

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

'before an update' implies this is a prerequisite read preceding dnsSet, giving implicit usage context. However, it never names the alternative tool or states when a read is not needed, so the routing guidance is inferred 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 destructiveHint=true and readOnlyHint=false, so the description's job is to add beyond that — and it does: it scopes the destruction to named record sets while preserving others, and discloses the optimistic-concurrency precondition ('requires the current DNS revision'). It does not say what happens on a stale revision or whether changes are recoverable.

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

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

Two sentences, no filler, with the preservation guarantee and the revision precondition front-loaded where an agent will see them before invoking.

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, open-world mutation with no output schema and fully undocumented parameters, the description covers the key precondition but omits failure behavior on a stale revision, return shape, and record-level constraints. Adequate but with clear gaps against the tool's 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 description coverage is 0% with 3 required parameters, so the description must compensate. It clarifies the meaning of 'revision' (the current DNS revision, a concurrency token) and implies 'records' are named record sets, but says nothing about 'domain' or the record object's required fields, TTL bounds, or the 50-item cap.

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 (replace/set) and resource (DNS record sets) plus the exact scope: 'only named DNS record sets, preserving other names and types.' This distinguishes it from the read-oriented dnsGet sibling by action, though it never names the sibling explicitly.

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

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

The 'only named ... preserving other' phrasing implies when the tool is appropriate (partial updates versus a full zone replacement), but it gives no explicit when-to-use/when-not guidance or names an alternative in the sibling list. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful context by implying an ownership prerequisite ("owned domain") and listing the data read, but it does not cover error behavior, permissions details, 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?

A single, front-loaded sentence with no filler. It is appropriately sized for a simple read operation, though slightly terse and fragment-like.

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

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

For a simple read tool with annotations and no output schema, the description adequately indicates the returned fields. However, it remains vague on what "verification requirements" includes and does not explain output structure or ownership-check failure modes.

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

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

Schema description coverage is 0% and the single "domain" parameter has only a type and no format. The description implies the parameter is a domain name but adds no syntax, example, or format guidance, so it does not compensate for the schema gap.

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

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

States a specific verb ("Read") and resource ("owned domain") with the fields retrieved (expiry, nameservers, verification requirements). It does not differentiate from siblings like status or dnsGet, so it falls short of a 5.

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

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

Provides no when-to-use guidance, no exclusions, and no alternatives. The sibling tools status and dnsGet likely overlap, but the description never mentions them or the conditions that select this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing an auth requirement (owner signature for renewals) and a side-effect caveat (availability is not a reservation), which is exactly the kind of extra context still useful under 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 short, front-loaded sentences with no filler; the core action, the renewal caveat, and the non-reservation warning 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?

With no output schema, the description carries the burden of explaining what a quote returns, and it is silent on price/currency, quote validity or expiry, and whether the quote can later be executed. It covers prerequisites well but leaves the return semantics an agent needs to act on the quote undefined.

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 only 33% (only 'domain' is documented). The description compensates by explaining the fixed one-year period (the period_years const) and by framing the 'register' vs 'renew' operation enum and its signature requirement, adding meaning the schema does not carry.

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

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

States a specific verb (Quote) plus the exact resource and scope (one-year domain registration or renewal), and the line 'Availability is not a reservation' makes clear it is a non-mutating price query rather than an action, distinguishing it from the sibling register/renew tools. An agent can route to 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?

Adds the prerequisite that renewal requires the owner signature and that a quote does not reserve the domain, which implies you must follow with register to secure it. However, it never explicitly says when to call quote versus register/renew, or that it should be used before those tools, leaving the routing 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/open-world, and the description meaningfully adds beyond them: the operation is irreversible once registered, and a separate x402 payment step is required. It doesn't cover what happens on partial failure or how the registrant data is validated, but the risk profile is clearly communicated.

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 filler, front-loading what is bought before the irreversible and payment warnings. Every clause carries operational weight.

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

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

No output schema exists, so the description could say more about what a successful registration returns (order id, status). For a 5-param irreversible mutation with a nested registrant object and a terms-acceptance contract, the description covers the essentials but leaves key parameters and the post-call state underspecified.

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

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

Schema description coverage is 0% across 5 required params including a 13-field nested registrant object. The description only gestures at the registrant and implies quote_id; accept_terms, terms_version, and client_order_id (which has a 16-80 char constraint suggesting idempotency) are entirely unexplained.

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 – buying/registering the exact domain from an existing quote – tied to the supplied registrant. It reads clearly as the purchase step, distinguishable from the sibling `quote` (pricing) and `renew` (extension), though it never names those siblings explicitly.

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

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

Usage context is implied rather than stated: the tool requires an 'unexpired quote' and mentions a separate x402 payment, which tells the agent roughly when this applies. There is no explicit when-not guidance or routing to `quote`/`renew` as alternatives, leaving the precondition chain to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful non-annotated behavior: the renewal term is one year, payment is handled separately, and automatic registrar renewal is disabled. It does not cover failure modes or permission requirements, but it meaningfully extends the annotation-based 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?

Two sentences, front-loaded with the core action and zero boilerplate. Every clause carries information, though the second sentence is slightly terse and could integrate parameter flow more usefully.

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, open-world mutation with four required parameters all lacking schema descriptions and no output schema, the description is too thin. It omits what accept_terms/terms_version mean, whether client_order_id provides idempotency, and what happens on failure or partial payment, leaving important agent-relevant details unaddressed.

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

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

Schema description coverage is 0% and all four parameters are required, so the description must compensate. It only hints at 'quote_id' via 'using a renewal quote' and says nothing about accept_terms, terms_version, or client_order_id. This leaves most parameter meaning undocumented.

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

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

States a specific verb and resource: 'Renew an owned domain for one year using a renewal quote.' This clearly separates it from the sibling 'register' (new domain) and implies dependence on 'quote'. However, it does not explicitly name an alternative tool or clarify scope against all siblings, so it falls just short of a 5.

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

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

The phrase 'using a renewal quote' implies the prerequisite flow of obtaining a quote first, and 'Separate payment; automatic registrar renewal is disabled' adds operational context. There are no explicit when-to-use vs when-not-to-use statements or named alternatives, so usage guidance is implied 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely useful behavior context by warning that a 'pending' state is normal and must not be treated as failure or trigger a re-purchase. It still doesn't describe what statuses can be returned or how long pending may persist.

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 recovery scenario and the timeout warning front-loaded in that order. 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-parameter read tool with no output schema, the description handles usage well but leaves the returned status values and their meaning largely unexplained — it names only 'pending'. Enough to invoke safely, not enough to fully 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 description coverage is 0% for the single required order_id parameter, and the description never says what identifies an order or its format. The phrase 'private order' hints at the resource but adds no meaning beyond the schema's parameter 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?

The description states a specific action — recovering the state of a private order after a lost response — which lets the agent distinguish this status/retrieval call from purchase-oriented siblings like register, renew, and quote. It is clear enough to act on, though the resource is described indirectly through the scenario rather than as an explicit 'get order status' statement.

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 triggering condition (a lost/timeout response) and an explicit anti-pattern ('never buy again to resolve a timeout'), which is strong when-to-use guidance. It does not name a sibling alternative to use instead, so it stops short of full routing guidance.

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