Sitey — free subdomains

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

With no annotations, the description carries the burden of explaining behavior. 'Check' and 'returns true if free to claim' convey read-only, boolean semantics, but the description does not explicitly state false/error behavior, whether the check reserves the name, or that availability may change before a later create call. 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?

The description is a single, front-loaded sentence with no filler. It states the operation, the resource, the context, and the return condition in an efficient way.

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 check tool with no output schema, the description provides the key return condition and clarifies the relationship between subdomain and domain. It falls just short of a 5 because it does not explicitly define the false/error return value or warn that availability is not a reservation.

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 with descriptions and examples, so schema description coverage is 100%. The tool description adds little beyond confirming that the subdomain is checked 'under a given domain,' 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 ('Check if') and identifies the exact resource ('subdomain name ... available for registration under a given domain'). It also states the return value, making it clearly distinct from sibling tools like create_subdomain, delete_subdomain, or list_subdomains.

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 'available for registration' implies this is a pre-flight check before create_subdomain, and the tool is clearly the only one of the siblings that checks availability. However, it never explicitly says 'use before create_subdomain' or mentions when not to use it, leaving the agent to infer the intended workflow.

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 richly: it discloses the 301 semantics of REDIRECT, that the record is created even when the target does not answer (reachable:false), that owner_token is minted and shown only once, and the ACCOUNT_REQUIRED refusal conditions. This is well beyond what structured fields provide.

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?

Long but front-loaded and dense — the core purpose and example come first, followed by constraints. Every sentence adds operative information (token handling, error codes, reachable flag), though it is on the verbose side.

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 returns, and it does (reachable, owner_token), along with the error condition ACCOUNT_REQUIRED. For a 5-parameter creation tool with no annotations, nothing essential for correct invocation 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: the owner_token lifecycle ('save it, shown once, only way to change or delete'), the https-only constraint for REDIRECT, and the no-API-key restrictions on CNAME/REDIRECT targets.

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 (DNS record for a subdomain), then enumerates the exact record types supported (A, CNAME, REDIRECT) with a concrete example. An agent can distinguish this from create_txt_record and update_subdomain immediately.

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 conditions: no account/API key needed, and 'claim the name first, deploy second' ordering advice. It also rules out TXT ('not available'), implicitly routing to create_txt_record. It stops short of explicitly naming the sibling alternative to use instead, 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?

No annotations are provided, so the description carries the full burden, and it does well: it discloses the auth requirement (Authorization: Bearer styo_…), the exact failure response (ACCOUNT_REQUIRED), and that the value is merged alongside other owners' values at the root rather than replacing them. Gaps remain around create-vs-update semantics (what happens if the record already exists) and any rate limiting.

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 and scope are front-loaded in the first two sentences, and the auth constraint is stated before the failure code. The middle sentence is dense and slightly circuitous about how the hostname is formed, but no sentence 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?

For a 6-param, no-annotation, no-output-schema tool, the description covers purpose, auth, error behavior, and placement semantics. It omits what the call returns (the minted owner_token is only mentioned in the schema) and how an update interacts with an existing record, which an agent would want before calling.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it shows the composed record name (_vercel.sitey.my) that host_prefix produces and confirms TXT records are always written at the root domain. That composition insight is not derivable from the individual schema descriptions 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+resource ('Create or update a TXT record') and a concrete purpose (domain verification), which separates it from the delete_txt_record and listing siblings. The Vercel/Netlify example grounds the purpose in a real scenario.

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 tells the agent when this applies (DNS-based ownership proof for services like Vercel/Netlify) and states the account prerequisite plus the ACCOUNT_REQUIRED failure mode. It does not, however, explicitly name the alternative tool for removal or the case when a record already exists, leaving that to inference.

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

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

With no annotations provided, the description carries the full behavioral burden. It clearly discloses the destructive nature ('permanently delete'), the immediate consequence ('will stop resolving immediately'), and implicitly warns about irreversibility. It does not mention authorization or side effects on related records, but the core hidden behavior is 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 short sentences with no wasted words. The key facts—permanence and immediate resolution impact—are front-loaded, and every phrase 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 simple destructive tool with no output schema, the description gives the essential outcome and permanence. It does not explain return behavior, but the required parameters are already fully documented in the schema, so the agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional parameter-level meaning, which is acceptable but not above the 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?

The description states a specific verb ('delete') and a specific resource ('subdomain DNS record'), and clarifies ownership. It is clearly distinguishable from the sibling delete_txt_record, which targets a different record type.

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?

There is no guidance about when to use this tool versus alternatives such as delete_txt_record, or when deletion might be inappropriate. The phrase 'you own' implies a prerequisite but does not explicitly tell the agent how to choose 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the action (delete) and ownership requirement, but does not mention that the action is permanent/irreversible, any permission requirements, or side effects on the subdomain itself. For a destructive operation, this is insufficient transparency.

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 a single sentence with no filler. It front-loads the action and resource, then adds the scope condition. Every word earns its place, making it highly concise and well-structured.

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 delete operation with no annotations and no output schema, the description is minimal. It omits irreversible side effects, what happens on success (e.g., confirmation or errors), and any guidance on when to use this tool versus delete_subdomain. Given the tool's complexity (4 params, destructive nature), the description leaves critical context missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description adds the ownership condition ('subdomain you own'), which relates to domain ownership but not to specific parameters. It does not add new meaning beyond the schema, so a 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?

The description uses a specific verb (Delete) and resource (TXT verification record) with a clear scope ('from a subdomain you own'). It clearly distinguishes from delete_subdomain, which would delete the subdomain itself, and from create_txt_record. This is not a tautology; it tells the agent exactly what action is performed on what object.

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 the tool is used when you need to remove a TXT record from a subdomain you control, but it does not explicitly contrast with sibling tools like delete_subdomain or provide conditions for when not to use it. It gives clear context (ownership requirement) but no explicit alternatives or exclusions, which is a moderate 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?

With no annotations, the description carries the full burden and discharges it: it discloses the deterministic outcome (always returns PAYMENT_DISABLED) rather than the general behavior an agent would infer from the name. It also explains why the alternative is preferable (free, one month added), which is exactly the behavioral context needed to avoid a wasted 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?

Two sentences, no waste, and the blocking constraint (payment disabled) is front-loaded ahead of the redirect to renew_subdomain.

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 tool whose only meaningful behavior is a guaranteed failure, the description is complete: it tells the agent what happens, why, and what to call instead. With full schema coverage and no output schema, nothing an agent needs to call or avoid calling 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%, including detailed notes on payment and owner_token, so the schema already does the heavy lifting. The description adds no parameter-level meaning beyond alluding to payment being disabled, which warrants the baseline 3.

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

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

The description conveys that this tool extends a subdomain by paying for a year ('Paying for a year is switched off'), and explicitly distinguishes itself from the sibling renew_subdomain. It never states the purpose in a clean verb+resource sentence, but the implication is unambiguous and routing to the alternative is explicit.

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

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

It states the exact condition under which this tool would be used (paying for a year), declares that this server disables it, and names the alternative (renew_subdomain) with the reason to prefer it ('free and adds a month'). 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?

With no annotations provided, the description carries the full burden of disclosure. It states the tool lists available root domains, which is a read-only operation with no implied side effects. While it doesn't explicitly say 'read-only' or mention any limitations (e.g., pagination), the simplicity of the action makes the behavior transparent enough.

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 a single, information-dense sentence that front-loads the purpose, provides examples, and gives a usage directive. There is no redundant wording or filler; 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 simple, parameter-less list tool with no output schema, the description covers everything an agent needs: what is listed, what it's for, and when to call it. The examples clarify the domain format. No additional behavioral or return details are 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?

The tool has zero parameters, so schema coverage is trivially 100%. The description adds no parameter-specific information because none exist. Per calibration, the baseline for 0 parameters is 4, but the description doesn't add any meaningful parameter semantics beyond what's implied; it simply describes the list operation. I'll keep baseline 3 since there is nothing to compensate for.

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 ('List') and the resource ('available root domains'), provides concrete examples ('sitey.my, sitey.one'), and distinguishes itself from sibling 'list_subdomains' by specifying root domains. The purpose is unambiguous.

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

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

The description explicitly instructs 'Call this first to know which domains are available,' which implies it should precede subdomain creation. It does not explicitly mention when not to use it or name alternatives, but the context with siblings like 'list_subdomains' and 'create_subdomain' makes the intended usage 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 behavioral burden. It clearly signals a read-only listing operation, enumerates the returned fields, describes the extra REDIRECT hit data, and documents the three filtering modes. It does not mention pagination or empty results, but nothing about its behavior is hidden or misleading.

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 compact sentences, with the core purpose front-loaded and every sentence earning its place. It efficiently packs return fields, the REDIRECT-specific detail, and authentication modes without redundancy.

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 there is no output schema, the description does well to enumerate the returned fields and the special REDIRECT counter data. It also clarifies the only non-obvious parameter use. It lacks an explicit statement about response shape or empty-result behavior, but nothing essential is missing for a simple list 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%, so the baseline is 3. The description's mention of owner_token filtering mostly restates what the schema already says; it adds only the contextual note about pre-token records and IP-based filtering. No significant meaning is added 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?

Begins with a specific verb and resource: 'List all subdomains you own.' It immediately distinguishes from the sibling list_domains by naming the exact record type, and adds the useful scope qualifier 'you own' plus the key return fields.

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 clearly explains the filtering context: by API key, by optional owner_token, or by IP for pre-token records. This tells an agent when passing the owner_token is appropriate, though it does not explicitly contrast with sibling tools like check_availability or list_domains.

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 so thoroughly. It explains that subdomains are lent, not given, with different durations for agent-created vs user records. It discloses that one call resets the clock from today, and that renewal opens only in the last two weeks. It also notes that no emails are sent, so the agent must read expires_at. This fully informs the agent of operational behavior.

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

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

The description is compact and front-loaded with the core purpose. Each sentence adds essential context: the lending concept, the renewal window, and the token requirement. There is no redundancy; every sentence earns its place. It's appropriately sized for the complexity.

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

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

The description is complete for a renewal tool. It covers when to use, how to use (read expires_at from list_subdomains), constraints (last two weeks), and side effects (resets clock). There is no output schema, but the description could mention the response (e.g., new expires_at) to be fully complete, but given the context signals (no output schema) and the richness of the description, this gap is minor. Overall, an agent has everything needed 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?

Schema description coverage is 100%, so the schema already documents all three parameters with examples. The description adds context about the owner_token's role ('The owner token you were given when you created the record') and when it can be omitted, which is beyond the schema. However, it doesn't explain the domain and subdomain parameters beyond what the schema provides. Since coverage is high, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to extend a subdomain before it expires, with a specific verb (renew) and resource (subdomain). It differentiates from siblings like create_subdomain and list_subdomains by focusing on renewal semantics. The phrase 'Extend a subdomain you own before it expires' is precise and actionable.

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 explicit when-to-use guidance: check expires_at from list_subdomains and call before that date. It also clarifies when not to use: 'Renewal only opens in the last two weeks before expires_at — an earlier call is refused.' It references the sibling list_subdomains, providing clear context for 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, the description carries the behavioral disclosure burden and does so well: it reveals that the target need not be live, that reachable:false appears in the result, and that the record is updated regardless. This goes beyond what the schema conveys.

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, all earning their place: the first states the action, the second gives a concrete example, and the third discloses non-obvious behavior. The main point is front-loaded with no wasted words.

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 there is no output schema and no annotations, the description covers the key side effect and result signal (reachable:false). The owner-token nuance is fully handled by the schema, so nothing critical is missing for a correct 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 the baseline is 3. The description adds a concrete example (IP address for value, demo.sitey.my for subdomain/domain) but does not materially expand parameter 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?

The description states a specific verb and resource ('Update the DNS record value of a subdomain you own') and includes a concrete example that makes the operation unmistakable. This clearly differentiates the tool from create/delete/list 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?

The description provides clear context for when to use the tool: updating an existing, owned subdomain's DNS target. It does not explicitly name alternatives or exclusions, but the operation is unambiguous enough that an agent can select it correctly.

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