AgentDomains

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

No annotations are provided, so the description carries the behavioral burden. It explicitly discloses the DNS mutation, the exact record name, that propagation is fast, and that the ACME client should continue afterward. It does not mention cleanup of the challenge record or behavior when a TXT record already exists, which is a modest gap for a mutating DNS operation.

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

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

The description is four sentences, front-loaded with the core operation and target, followed by use cases, propagation timing, and a useful guardrail. Every sentence earns its place and 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?

For a DNS mutation tool without annotations or an output schema, the description covers why, when, what happens, and what to do next. The main omission is what to do with the challenge record after validation, and there is no mention of what the tool returns or whether it can overwrite an existing record.

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 parameters. The description adds useful meaning by linking label, domain, and value to the generated _acme-challenge hostname and says the value must be published verbatim, but it does not need to compensate for missing schema entries.

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: it creates a Let's Encrypt DNS-01 TXT record at _acme-challenge.<label>.<domain>. It clearly distinguishes this from generic DNS record operations and from HTTP-01 validation.

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

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

It gives explicit when-to-use guidance: get a certificate without exposing port 80, such as a wildcard cert or a NAT-hosted domain. It also gives a when-not-to-use signal: normal public web servers should use HTTP-01 validation and need no DNS record 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?

No annotations exist, so the description carries the full behavioral burden and does so well: non-destructive add semantics, the exact 409 conflict condition, and the escape hatch via a sub-label. It stops short of mentioning auth/permission requirements, propagation timing, or the response payload, 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?

Three dense sentences, each front-loading the actionable constraint: what to add, which type for which content, and the conflict behavior with fix. No filler and nothing 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?

With no annotations and no output schema, the description closes the important gaps: mutation scope, unique-conflict error semantics, and alternatives. An agent can call this correctly and handle the main failure mode without further context.

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 all five parameters — baseline 3. The description adds genuine meaning by mapping type values to expected content (A/AAAA→IP, CNAME→hostname, TXT→verification string) and clarifying the 'host' sub-label hostname distinction, which goes beyond the schema text.

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

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

States a specific verb+resource ('Add a DNS record to a subdomain you already own') with enough scope detail to separate it from delete_record, remove_forward, and remove_proxy. The record-type enumeration (A/AAAA/CNAME/TXT) further pins the tool's identity.

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 tells the agent when each record type applies, that adding does not replace existing records, when the call is refused (409 while the label carries a forward or proxy), and the two remediation paths (remove_forward/remove_proxy first, or use 'host' for a different hostname). This is textbook routing guidance.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure, and it delivers. It reveals that the account is provisional, that a human must click the verification link, that the deadline is 30 days, and that the account and its domains will be deleted if verification doesn't happen. This is exactly the kind of side effect an agent needs to know before calling a mutation tool.

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

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

The description is only two sentences long, yet it packs the core action, the required human action, the deadline, the deletion consequence, and the usage timing. Every sentence earns its place, and the most important directive is front-loaded.

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

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

For a single-parameter tool with no output schema and no annotations, this description gives an agent enough to decide when to call it, what input to provide, and what significant behavioral risks exist. The only minor gap is that success/error response behavior is not described, but that is not essential for invoking such a 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?

The input schema already provides complete coverage of the only parameter, including its type and intended meaning. The description adds essentially no semantic information beyond what the schema states, so the baseline 3 applies.

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

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

The description states a specific action ('attach an email address'), the resource ('the account'), and a concrete follow-up behavior (sending a verification link). It also ties the tool to the signup flow, making its purpose easy to distinguish from domain-related siblings like claim_domain or set_forward.

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

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

The description explicitly says 'Use this right after signup,' giving the agent a clear temporal instruction for when to invoke this tool. It does not explicitly name alternatives or exclusions, but the placement in the signup flow makes the intended context 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?

With no annotations, the description carries the full burden. It discloses that no API key is required, defines the full return shape, enumerates the possible reason values, and clarifies the detail field. It doesn't mention rate limits or edge cases, but for a simple check this is solid coverage.

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

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

Two tight sentences: the first states the action and timing, the second covers auth and the exact return contract. No filler, no repetition of schema. The key scoping context ('before claiming it') is front-loaded.

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

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

There is no output schema or annotations, so the description must directly compensate. It provides the complete return structure, explains every reason value, and includes domaine-related fields. For an agent that needs to decide, call, and parse the result, this is sufficient.

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?

Input schema already covers both parameters with 100% description coverage, so a baseline score of 3 is appropriate. The description adds no input-specific semantics beyond the return shape mentioning 'domain' and 'fqdn'; it doesn't elaborate on label constraints or domain nuance that the schema already handles.

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

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

Description uses a specific verb ('check') and resource ('subdomain label'), and states the precise predicate (whether free) while explicitly tying to claim action. It clearly reads as a pre-check for claim_domain and is not confusable with listing, creating, or deleting 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?

The phrase 'before claiming it' gives a clear usage context relative to claim_domain, but it does not explicitly name alternatives or state when not to use the tool. This is contextual but relies on the agent to infer the connection to claim_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?

With no annotations, the description carries the full burden and does so: it discloses the email-confirmation prerequisite, the 30-day reaping consequence, the atomic claim+record coupling, and the meaning of 400/503/409 responses. This is exactly the mutating-operation context an agent needs before writing.

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?

Five sentences, each carrying distinct load: what it does, the email prerequisite, the return shape, the atomic failure mode, and the 409 semantics. Nothing is redundant and the scope statement is front-loaded.

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

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

There is no output schema, so the description supplies the return contract ('returns the fqdn and, when a record was requested, the created record') plus error-mode behavior. For a 6-parameter mutating tool with no annotations, it covers everything needed to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'email' is conditionally required on first registration, 'domain' selects which suffix the label lives under, and 'host'/'type'/'content' are bound together as one optional first record. The coupling of these parameters is not obvious from the schema 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?

States a specific verb and resource ('register a subdomain on this account') and immediately scopes it with concrete examples of the naming space (label.makes.fyi / label.agentdomains.co). It is clearly distinct from siblings like add_dns_record (record-only) and check_availability (read-only).

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 between claim_domain and attach_email ('pass email here or call attach_email first'), and gives a decision rule for the 409 case ('carry on using it, not pick another label'). It also states the retry condition for malformed/refused records.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does well: it warns that existing AgentDomains records, forwards, and proxies will no longer apply once delegation is active. It also states the requirement of at least two nameservers, which adds operational expectations beyond a simple tool name.

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 efficient, front-loaded with the core action, and uses every sentence to convey material information: control shift, behavior change, and input requirement. No repetition or filler.

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

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

For a destructive-ish but reversible action, the description explains the concrete consequences and the minimum input, and the schema covers all parameter details. It does not state whether delegation can be undone, but given the strength of the other context, this is a relatively minor 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%, so all three parameters are already documented meaningfully in the schema. The description does little to add semantic value beyond reinforcing the 'at least two nameservers' rule, which was already present 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?

The description names a specific verb and resource ('Delegate the subdomain to your own nameservers') and clearly distinguishes itself from sibling tools by stating AgentDomains stops answering and existing records/forwards/proxies no longer apply. This makes the tool's unique role obvious without needing to inspect other schemas.

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

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

The description gives clear context for when this tool is appropriate: when you want full control via your own nameservers rather than using AgentDomains' built-in DNS, forwards, or proxies. It does not explicitly name alternative tools as recommendations, but the behavior contrast with those futures is enough to infer the choice.

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

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

With no annotations, the description carries the full burden and delivers: it marks the action as destructive/irreversible, explains API key invalidation and subsequent 401 failures, describes the 409 refusal behavior and name list, and details the force=true consequences including name release. This is exceptionally thorough 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?

The most critical facts are front-loaded ('DESTRUCTIVE AND IRREVERSIBLE'), followed by precise behavioral and safety details. Despite its length, every sentence earns its place for a destructive account-level operation.

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

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

Given no annotations, no output schema, and a single optional parameter, the description is complete for an agent to call this correctly and safely. It covers the destructive nature, refusal conditions, force behavior, and the required user-consent workflow.

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 input schema already documents the single force parameter with 100% coverage, so baseline is 3. The description adds meaningful operational context beyond the schema — the 409 response with name list, the need to show it to the user, and the fact that names stop resolving and become claimable — clearly aiding correct invocation.

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

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

The description states a specific verb and resource — deleting the whole AgentDomains account and invalidating its API key — and immediately distinguishes this from sibling tools like delete_domain or delete_record by scoping it to the entire account. An agent can tell this is not a cleanup tool without opening any schema.

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

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

It explicitly states when to call this ('only when the user has asked to close the account itself') and when not to call it ('never as cleanup after a task, and never to start fresh on your own initiative'). It also gives a concrete precondition: without force, the call refuses with a 409 and requires explicit user confirmation before retrying.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers permanence, irreversibility, cascading deletion of attached resources, immediate resolution loss, and the label being released. This is comprehensive for the context, and there is no contradiction with annotations because annotations do not exist.

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 compact, front-loaded with the most important warning—'DESTRUCTIVE AND IRREVERSIBLE'—and every sentence contributes to user intent, consequences, or invocation conditions. There is no filler.

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

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

For a destructive delete operation with no output schema and no annotations, the description covers the material facts an agent needs: what gets deleted, immediate resolution impact, irreversibility, and when it is appropriate to call. It is sufficient on its own.

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 input schema already describes both parameters fully—label format is documented with an example and domain has its values and default explained. Since schema coverage is 100%, the description's high-level language about deleting a subdomain is sufficient; it does not need to add parameter-level detail.

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 is explicit and specific: 'permanently delete a subdomain and every DNS record, forward, and proxy attached to it.' It names the exact resource and the full scope of deletion, which cleanly distinguishes this from sibling tools like remove_forward or remove_proxy.

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

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

It provides a strong decision rule: 'Only call this when the user has explicitly asked for this specific name to be deleted.' It also explains why caution is needed—destruction is permanent and affects DNS, forwarding, proxying, and label availability. This is the kind of when/when-not guidance an agent needs for a destructive operation.

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

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

With no annotations, the description carries the full burden and does so: it flags destruction upfront, states the change is immediate ('stops resolving through that record immediately'), declares irreversibility ('there is no undo'), and specifies what is preserved (the name and every other record). Only auth/permission requirements are absent, which is a minor omission for an unannotated mutation tool.

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

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

Four sentences, zero filler, and the destructive warning plus scope are front-loaded before the parameter clarification and the irreversibility note. Every sentence carries distinct 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?

For an unannotated mutation tool with no output schema, the description supplies the safety profile (destructive, immediate, irreversible), the routing decision against delete_domain, and the id-vs-name disambiguation. Nothing essential for a correct call 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 all three parameters are already documented in the schema, including the identical 'id not name/type/content' warning for record_id. The description's only genuine addition is provenance — that the id comes from get_domain and is returned by claim_domain and add_dns_record — which is marginal, 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 and resource ('permanently remove ONE DNS record from a subdomain'), quantifies scope (one record, not the whole name), and explicitly names the sibling it is not (delete_domain). An agent can distinguish it from every other sibling 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?

Gives concrete when-to-use triggers ('undo a single record — a wrong IP, a spent ACME challenge') and an explicit exclusion with the alternative to prefer instead ('instead of delete_domain, which takes the whole name'). Routing is unambiguous.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates that this is a read-oriented inspection tool and enumerates the specific data elements returned. It does not discuss error behavior, auth requirements, or side effects, but the 'Show' verb makes the non-mutating nature clear.

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

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

One compact sentence that front-loads the core action ('Show one subdomain in full') and then lists the relevant content areas. No filler, repetition, or schema restating.

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 low-complexity read tool with two simple parameters, the description adequately describes the operation and return content. The lack of an output schema is mitigated by the explicit list of fields returned, though error behavior for nonexistent labels is not mentioned.

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 input schema already covers both parameters thoroughly, including the default for domain and the distinction between makes.fyi and agentdomains.co. The description adds no additional parameter-level meaning, so the baseline score 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?

The description uses a specific verb ('Show') and identifies the exact resource ('one subdomain in full') along with the details returned (fqdn, DNS records, forward/proxy configuration, delegation state). This clearly distinguishes it from sibling tools like list_domains, which show multiple subdomains at a higher level.

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 context is clear: use this when you need complete detail for a single subdomain. It does not explicitly name alternatives or state when not to use them, but the contrast with list_domains is strongly implied by 'one subdomain in full'.

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

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

With no annotations, the description carries the burden of explaining behavior, and it does: it is a read-only listing operation that returns specific details per subdomain. It does not mention pagination, rate limits, or authorization, but the lack of parameters and clear return scope make it a transparent description.

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

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

The entire description is a single, information-dense sentence with no filler. It front-loads the main action and then lists the exact attributes returned for each subdomain, making it easy for an agent to quickly parse and use.

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

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

Given zero parameters, no output schema, and no annotations, the description provides enough information to successfully invoke the tool and interpret the response. There is no hidden behavior or missing prerequisite that would prevent an agent from using this tool effectively.

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

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

The input schema has zero parameters, so there are no parameter semantics to clarify. The description also tells the agent what the output contains, which is the only meaningful semantic information. A score of 4 is appropriate for a zero-parameter tool.

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 starts with the action 'List every subdomain on this account' and precisely specifies the scope: account-wide. It also states exactly what is included per domain: DNS records, and status flags for forwarding, proxying, or delegated nameservers. This makes it easy to distinguish from the sibling domain-specific 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 account-wide scope and 'list every subdomain' language makes it clear that this is the enumeration tool for a domain overview, rather than a single-domain lookup or mutation tool. It does not explicitly name alternative tools or when-not-to-use conditions, but for a zero-parameter listing operation, the context is sufficiently clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that a human must open the link (not an API-callable action), that cancellation preserves Pro through the paid period, that names are never deleted, and the 409 failure mode. It stops short of stating auth scopes or link expiry, but the behavioral surface is unusually well covered.

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, front-loaded with what the tool returns and what it is for, then the constraints and error path. Every clause carries information; 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 zero-parameter, no-output-schema tool, the description covers the return value (portal link), the human-in-the-loop requirement, side-effect semantics of cancellation, and the error route to the sibling tool. Nothing an agent needs to select or 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?

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly does not invent parameter guidance.

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 (Stripe billing-portal link) and enumerates exactly what the portal enables: update card, view invoices, switch billing cadence, cancel. It also distinguishes itself from the sibling upgrade_to_pro by naming the 409 case that routes there.

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

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

Explicit when-to-use (pro account billing self-service), an explicit constraint ('a human must open it'), and an explicit alternative for the edge case: 409 if the account has never subscribed, use upgrade_to_pro. 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?

No annotations exist, so the description carries the full transparency burden. It discloses the key non-obvious behavior: the registration is retained and only the redirect is removed, preventing a common misconception. It does not mention idempotency or failure modes, which are minor for such a simple mutation.

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 entire description is two sentences, with the action and scope front-loaded. Every sentence earns its place: the first states the operation, the second clarifies how it differs from deletion.

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

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

Given a simple two-parameter tool with fully covered schema, the description should clarify result and side effects. It did: it confirms the redirect is removed but registration remains. It would be slightly stronger if it noted the expected success response, but it is not necessary for correct invocation.

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

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

Input schema description coverage is 100%, and the parameter descriptions already explain 'label' with an example and 'domain' with defaults/enumerations. The tool description itself adds no parameter-specific semantics, so a baseline score 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?

The description opens with a specific verb and resource: 'Stop forwarding a subdomain.' It further clarifies scope by stating the domain name remains registered, which differentiates it from deletion tools like delete_domain or remove_proxy.

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 makes the intended use case clear if you need to stop forwarding, and 'only the redirect is removed' implies you should not choose this if you want to remove the subdomain registration itself. However, it does not explicitly name alternatives or say when not to use it relative to remove_proxy or delete_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?

There are no annotations, so the description carries the full burden of disclosing behavior. It clearly states what the operation does, that it removes TLS termination and backend serving at the edge, and that the subdomain remains registered on the account. It does not discuss prerequisites or idempotence, but the core behavior is transparent.

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

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

The description is two sentences with no wasted words. The main action is front-loaded, and the second sentence adds a meaningful boundary condition about the registration remaining intact.

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

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

For a simple two-parameter operation with no output schema, the description provides the action, the post-condition of the edge behavior, and the persistence of the domain name. Together with the fully documented input schema, an agent has enough to select and correct the tool correctly.

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

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

Schema description coverage is 100%, so the parameters label and domain are already fully documented. The description adds no parameter-specific detail, but none is needed because the schema already explains formats, defaults, and when domain should be passed.

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

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

The description names a specific action (stop reverse-proxying), the resource (a subdomain), and concrete consequences (no longer serves the backend or terminates TLS). It also explicitly notes that the name stays registered, which distinguishes it from deletion-focused tools like delete_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?

The phrase 'Stop reverse-proxying a subdomain' gives a clear use case, and 'the name stays registered' hints that this is not the tool for deleting the domain itself. It does not explicitly compare against set_proxy or remove_forward, but the proxy-specific wording makes the intended scope clear enough.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: takeover semantics, deleted A/AAAA/CNAME records, returned replaced_records, untouched sub-label/TXT records, failure restoration with new ids, and default 302 behavior. These details are exactly what an agent needs to safely invoke a mutating call.

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

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

The description is front-loaded with the core action, then layers necessary caveats and failure behavior without wasted prose. Every sentence contributes operational detail for a complex mutation.

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

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

Given no annotations, no output schema, and seven parameters, the description is complete enough to call the tool correctly. It covers prerequisites, defaults, destructive side effects, recovery behavior, and the important detail to report replaced records to the user.

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 meaning beyond the schema by tying email to the claim flow and stating the default redirect type and path/query preservation. The added value is real though not exhaustive across every parameter.

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

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

States a specific verb and resource: HTTP-redirect a subdomain to another URL. It clearly differentiates from sibling tools by describing the takeover of DNS records and the relationship to claim_domain, so 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?

Provides strong context for when the tool applies, including that it claims the label if not owned and may require email like claim_domain. It also explains defaults and edge behavior. It does not explicitly name alternatives such as set_proxy or add_dns_record for non-forwarding use cases, so it falls short of a full when/when-not rubric.

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

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

With no annotations, the description carries the full burden and discloses critical side effects: claiming the label, deleting A/AAAA/CNAME records on the label while leaving sub-label and TXT records untouched, returning deleted records in 'replaced_records', and being mutually exclusive with a forward. It also warns about apps that hardcode hostnames (e.g. OAuth callbacks).

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

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

The description is front-loaded with the core purpose, then contrasts with a forward, then details side effects and a caveat. Every sentence conveys useful information without redundancy, and the length is justified for a mutation tool with no annotations.

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

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

Given no annotations and no output schema, the description still covers what the tool does, when to use it, what it destroys, what it returns ('replaced_records'), and important caveats. It is complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds little parameter-specific meaning beyond what the schema provides—it does not clarify the domain parameter or email semantics beyond existing schema descriptions.

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

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

The description states a specific action: serve a backend at a subdomain via the AgentDomains edge with TLS termination, and explicitly contrasts it with a forward (proxied vs redirected). It clearly distinguishes the tool from its sibling set_forward.

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 explains when to use this tool (getting working HTTPS for an origin lacking its own certificate) and when not to use it (mutually exclusive with a forward on the same label). It names the alternative forward and the key behavioral difference that should drive selection.

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

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

With no annotations present, the description carries the full burden and does so excellently. It discloses the one-time visibility of the API key, the need to store it immediately, the 30-day provisional account policy, deletion consequences, and per-IP rate limiting—all behaviors an agent must know to avoid losing 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?

Every sentence carries essential, non-redundant information: creation action, credential requirement, security-critical key-retrieval warning, provisional-account deletion policy, and rate limiting. The key warning is front-loaded, and there is no filler or repetition.

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

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

Given the tool has no parameters, no annotations, and no output schema, the description compensates fully. It tells the agent what will happen, what to do with the result, how long the account lasts, and what follow-up action is needed. Nothing critical is missing for successful invocation.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific meaning, but this is not a gap because there are no parameters to document. The API key return behavior is described, which is relevant but not 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?

The description clearly states the action ('Create a new AgentDomains account') and the result ('get an API key'), distinguishing it from siblings by being the only account-creation tool. It also clarifies that no existing key is required, which separates it from all other tools.

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

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

The description gives clear context for when to use this tool: when creating an account and obtaining an API key, and explicitly notes 'Requires no existing key.' It references attach_email as a follow-up step, but it does not explicitly describe scenarios where another tool should be chosen instead.

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

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

With no annotations provided, the description carries the full burden and does so: it is read-only in effect (only returns a link, never charges), requires human action to complete payment, changes answer shape (kind:'portal') for existing Pro accounts, and specifies the 404 'billing is not enabled' failure mode. This is unusually rich 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 deliverable and price, followed by usage condition and the no-charge/no-open rule. Dense but each sentence earns its place; only the redundant restatement of interval pricing is mildly 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?

For a one-parameter tool with no output schema, the description covers trigger, return shape (link vs portal), the human-in-the-loop requirement, and the error case — everything an agent needs to call and interpret it correctly.

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

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

Schema description coverage is 100% and the single interval parameter's enum and pricing are already documented in the schema. The description restates the 'year' option at $48, adding marginal value beyond the structured field, 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 (get a Stripe checkout link), the resource/product (AgentDomains Pro), and the concrete deliverables (100 names, unreachable names retained, priority email support) with pricing. An agent can distinguish this from manage_billing and claim_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?

Explicitly names the trigger condition ('when a claim is refused because the account is at its name limit and the user wants more') and the already-Pro branch that routes to a portal-style answer. It also states the agent-facing rule: show the URL and price, do not open or pay.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful conditional behavior — quota omitted and unlimited:true when quotas are disabled, max_subdomains semantics with plan-specific caps, plan enum values, and the upgrade hint. It does not state read-only nature or auth requirements, leaving a modest gap.

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

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

Front-loaded with the core action, then elaborated in a single dense paragraph. Given there is no output schema, the field-level detail is largely justified, though the plan/quota trivia is borderline verbose for a read tool.

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

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

With no output schema, the description must describe the return shape, and it does so thoroughly, including conditional fields and enum values. Missing only minor operational detail such as auth requirements, which is low-stakes for an account-introspection 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?

The tool takes zero parameters, so there is nothing beyond the schema to document. Baseline 4 applies; the description appropriately spends its detail on return values instead of non-existent parameters.

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

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

States a specific verb and resource ('Show the current account') and enumerates the exact fields returned (id, state, email + verified flag, domains, claimable domains). This is clearly distinguishable from siblings like list_domains or get_domain, which operate on domains rather than the account.

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 explicit 'use when / don't use when' guidance, though the tool's self-inspection nature is implied by the name and description. The only routing signal is the passing reference to upgrade_to_pro, which is a side note rather than guidance for choosing this tool.

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