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?

With no annotations, the description carries the full burden and discloses important behavior: the record is created even if the target doesn't answer (reachable:false), and a newly minted owner_token is shown once and is the only way to later modify/delete. It also states no auth is required, which is useful non-obvious 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?

At roughly four sentences, every clause earns its place: purpose, example, auth requirements, and edge-case behavior. It is front-loaded and scannable.

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 with no annotations and no output schema, the description covers the essential call-time facts: supported record types, example, auth, pre-deployment usage, and result semantics (reachable, owner_token). It could mention conflict behavior, but it is sufficiently complete 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 coverage is 100%, so each parameter already has descriptions. The description adds value with a concrete example ('demo.sitey.my pointing to 1.2.3.4') and clarifies the semantics of owner_token, including when to omit it. This is a modest but genuine addition 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?

Description opens with a specific verb+resource: 'Create a new DNS record for a subdomain' and enumerates supported record types (A, CNAME). This clearly distinguishes it from siblings like create_txt_record (TXT records) and delete_subdomain.

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 clear context: no account/API key needed, and the target need not be serving yet, so the tool can be used to claim a name before deployment. It does not explicitly name alternatives like check_availability or create_txt_record, so it lacks explicit when-not guidance.

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

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

With no annotations, the description carries the behavioral burden and it does disclose important placement behavior: records live at the root domain under the given prefix alongside other owners' values. However, it omits idempotency/reversibility, authentication requirements, and what the response contains, so there is a meaningful gap for 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 three focused sentences: it states the action, gives the use case, and clarifies placement. Every sentence adds value and the most important information 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?

The parameter schema already documents all six parameters in detail, so the description only needs to supply selection and behavioral context. It does that well with purpose, use case, and the unexpected root-domain placement. It could add response/error behavior, but this is not a major gap given the schema richness.

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 clarifying example of how host_prefix and domain combine into the record name, which helps, but it does not substantially explain parameters beyond what the schema already provides.

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

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

The description states a specific action ('Create or update a TXT record') on a specific resource and clearly ties it to a purpose (domain verification for Vercel/Netlify). This distinguishes it from sibling tools like delete_txt_record and create_subdomain.

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 concrete usage context by naming Vercel and Netlify DNS ownership proof, which helps an agent recognize when this tool applies. It does not explicitly state when not to use it or name an alternative, but the context is clear enough 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 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 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 provided, the description carries the full burden of behavioral disclosure. It explains what is returned, the ownership filtering modes, and the legacy token behavior. It doesn't cover edge cases like pagination or error behavior, but for a simple list tool the provided behavior is well disclosed.

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

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

Two sentences, both purposeful and front-loaded. The first states the core action and scope; the second covers return fields and filtering logic. No filler or redundant wording.

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 list tool with one optional parameter and no output schema, the description is complete: it names the output fields, explains ownership scoping, and covers the legacy token case. An agent has enough information 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?

The schema covers the only parameter, owner_token, with detailed guidance on omission conditions. The description adds context about filtering by API key and IP, but largely restates what the schema already communicates, so it doesn't meaningfully increase understanding beyond 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 uses a specific verb and resource: 'List all subdomains you own.' It clearly differentiates from sibling list_domains by focusing on subdomains, and from create/delete/update tools by being a read/list operation. The scope 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 provides clear context for when to use the tool: when you want to list subdomains you own, filtered by API key, owner token, or legacy IP ownership. It doesn't explicitly mention alternatives or when not to use it, but the context is strong enough that an agent can select it appropriately among the siblings.

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.