tld.expert

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the data sources checked (live DNS, registry RDAP/WHOIS, a registrar), the confirmation guarantee before claiming availability, and the shape of the response including buy links and a citation URL.

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

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

Three tightly packed sentences, front-loaded with the usage trigger, then input modes, then sources and return contents. No filler; every clause carries information an agent needs.

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

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

With no output schema, the description carries the return-value burden and does so explicitly (verdict per domain, buy links, tld.expert URL). Sources, TLD coverage and confirmation behavior are all specified, leaving nothing an agent must guess 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 coverage is 100% so baseline is 3, but the description adds genuine semantics: a full domain yields one verdict while a bare name fans out across popular or custom TLDs, which explains the otherwise non-obvious purpose of the two modes. It stops short of documenting the tlds list format, which the schema covers.

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

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

States a specific verb and resource (check availability of a domain name) and immediately names the sibling concern it does not cover: it returns availability verdicts, not explanations or prices. An agent can distinguish it from explain_tld, get_tld_prices and suggest_tld_alternatives without reading further.

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 triggering conditions, including a literal user phrasing ("can I get <name>") and the two input modes. It does not explicitly route to or exclude sibling tools like suggest_tld_alternatives, so the guidance is clear but not fully disambiguated.

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

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

Annotations already establish read-only, idempotent, closed-world safety, so the description's job is additive. It does that by disclosing a non-obvious behavior: it still answers for well-known non-existent TLDs like .eth or .web rather than erroring, and it reveals the content is an editorial/subjective verdict from tld.expert.

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, with the triggering user intents front-loaded before the return-value inventory. The parenthetical examples and the return list are dense but each earns its place by clarifying scope.

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

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

No output schema exists, so the description must carry the return-value burden, and it does: verdict, pros/cons, registry, restrictions, use cases, typical price. The remaining gap is that editorial-verdict semantics (subjectivity, freshness) are only lightly implied.

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?

One parameter with 100% schema description coverage; the schema already documents that the TLD may be given with or without a leading dot. The description adds nothing further about the argument format, so baseline 3 is appropriate.

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

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

Specific verb (explain) plus resource (TLD), and the description enumerates exactly what questions it answers: meaning, operator, registration eligibility, project fit. It is clearly distinguishable from siblings get_tld_prices, check_domain_availability, and suggest_tld_alternatives.

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

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

Gives a concrete trigger condition and three example user utterances, which is strong 'when to use' guidance. It stops short of naming alternatives for overlapping questions (e.g., price lookup routes to get_tld_prices) since it advertises a typical price in its own output.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds substantial value beyond them: enumerates returned fields, lists tracked registrars, and flags the important scoping caveat that prices are TLD standard, not premium names. That caveat prevents a common misinterpretation an agent could not infer from annotations.

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

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

Three sentences, zero filler, and the usage trigger is front-loaded before the return-value detail. The final caveat sentence is short and 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?

There is no output schema, so the description must describe return values — and it does so thoroughly (per-registrar pricing, cheapest buy, wholesale floor, renewal-trap flag, date-stamped). An agent has everything needed to call it and interpret results.

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 `tlds` parameter is fully documented in-schema (with dot or without, max 20). The description adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource (get TLD prices) and enumerates the exact data returned: first-year, renewal and transfer prices per registrar, cheapest buy, wholesale floor, renewal-trap flag. It is implicitly distinguishable from siblings (check_domain_availability, explain_tld) by its pricing focus, but never names an alternative explicitly.

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

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

The opening sentence gives concrete trigger conditions: 'when the user asks what a domain extension costs, where it is cheapest, or what it renews at.' That is a clear use context, though no when-not-to-use case or explicit sibling pointer is provided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds real operational context: it performs up to ~30 live lookups, is slower than a single check, and filters the response down to only available candidates. That latency and filtering disclosure is valuable beyond the annotations, though it doesn't mention rate limits or failure behavior for individual lookups.

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 trigger condition is front-loaded in the first clause, followed by the mechanics and the performance caveat. It is a single dense paragraph with little waste, though the enumeration of candidate-generation strategies is slightly verbose for a one-parameter 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?

There is no output schema, and the description compensates by stating exactly what comes back ('returns only the ones that are not taken'), plus the input shape and the cost profile. An agent has everything it needs to decide whether to call this and what to expect.

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

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

Only one parameter exists and schema coverage is 100%, so the schema already fully documents 'domain' including length bounds and format. The description restates the expected input with an example ('acme.com'), which is consistent but adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (proposes alternative domain endings/words for a taken domain) and enumerates the concrete strategies: TLD swaps, added words, domain hacks, related words. It is clearly distinguished from the sibling check_domain_availability by describing a multi-candidate generative workflow rather than a single lookup.

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

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

Gives an explicit trigger condition: use it when the desired domain is taken or the user asks for other options for a name. It also implicitly contrasts with a single check ('Slower than a single check'), but it never names the sibling tool check_domain_availability, so routing still requires a small inference.

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