Atom.com — Premium Domains

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

Annotations already declare readOnlyHint=true, and the description adds rich behavioral context: it distinguishes estimated_value from domain_score, warns not to conflate them, clarifies domain_score is a quality rating not confidence, mentions factors and comparable_sales, and advises on presentation. No contradictions with 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?

The description is fairly long but front-loaded with purpose and usage. Each sentence adds value: explaining two numbers, warnings, and presentation advice. It could be slightly more concise, but the structure is logical and information-dense.

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's complexity (multiple return fields with nuanced meanings) and the existence of an output schema, the description is complete. It covers key fields, their interpretation, and presentation without needing to restate schema. No gaps for a read-only appraise tool.

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% with a clear description of the 'domain' parameter. The description does not add new semantic information beyond what the schema already provides (e.g., 'Full domain... Works for any domain'). 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 estimates domain market value and explains why. It uses specific verbs ('Estimate', 'appraise') and resource ('domain'). The usage guidance (e.g., 'when a user asks what a domain is worth') distinguishes it from sibling tools like check_domain_availability or generate_domain_names.

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 tells when to use: 'Use when a user asks what a domain is worth, how much to pay/offer, or to appraise a domain.' It does not explicitly state when not to use, but siblings provide alternatives. The output explanation further guides correct interpretation.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description reveals that results are real, verified-buyable domains with prices, that it never invents names, and that it returns the same results as search_brandable_domains. This adds meaningful behavioral context about the tool's guarantees and limitations.

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 purpose, followed by usage triggers, parameter guidance, and output format. It is somewhat lengthy but every sentence carries critical information, especially the emphasis on not inventing names and the relationship to the sibling tool. It is structured logically, though could be tightened slightly.

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 6-parameter tool with an output schema. It covers when to use, how to phrase the concept, what results look like, and how to present them. The presence of an output schema reduces the need to explain return values, but it still details the result fields, making it fully self-contained for an agent.

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 documents all parameters. The description adds useful guidance for 'concept' ('Describe the business as the concept') and 'extensions' ('pass preferred extensions if the user stated any'), going beyond the raw schema. Other parameters (limit, style, industry, max_price) are adequately covered by 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?

The description clearly states the tool generates name ideas for startups/businesses/products from Atom's curated marketplace of verified-buyable premium domains. It distinguishes itself from siblings by explicitly noting it never invents names and that results are real, buyable 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?

Provides explicit trigger phrases ('come up with a name', 'suggest names', etc.) and tells the agent to always use this tool for such requests. It also gives instructions for parameters ('Describe the business as the concept; pass preferred extensions if the user stated any') and warns against using both this and search_brandable_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?

Beyond the destructiveHint and openWorldHint annotations, the description discloses that this SPENDS REAL MONEY, that pricing is server-authoritative, that payment is captured before token crediting, and that no automatic refund is issued if crediting fails. It also mentions the required 'domains:register' scope. This is substantial, non-redundant behavioral context.

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 long but every sentence is essential: it includes the price, a numbered mandatory flow, explicit rules about pricing and idempotency, and a refund warning. The structure with numbered steps and bolded rules makes critical information easy to process without excessive verbosity.

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 financially risky, multi-step tool, the description covers the entire lifecycle: quote, challenge, payment capture, crediting, and failure handling. It also notes server-authoritative pricing and no-refund behavior. With an output schema present and this level of procedural detail, nothing critical appears 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?

Although the input schema has 100% coverage, the description adds crucial semantics: the confirm parameter's two-phase role (false=quote, true=payment), the requirement to reuse one idempotency_key across calls, and the need to omit payment_token to receive the challenge. This materially enhances the agent's understanding beyond the schema's basic field 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 opens with a specific verb ('Purchase') and resource ('AI Tokens'), states the exact price ($0.10 per token), and identifies the payment method (Stripe SPT). It distinguishes this tool from siblings like register_domain_spt by targeting token purchase and from get_checkout_link by describing the actual charging flow.

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 notes the intended user context ('for users with no Atom balance') and provides a mandatory three-step call sequence with confirm/idempotency_key/payment_token semantics, effectively telling the agent when and how to use the tool. However, it does not explicitly name alternative tools or when-not-to-use scenarios, so it stops short of a 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral caveats: it checks fresh-registration availability and will 'misleadingly report an already-listed/owned domain as taken.' It also details the return structure (status, registrable, price, alternatives, URL), adding substantial context for safe invocation.

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 purpose, then proceeds to usage guidance, alternatives, and return details. Every sentence provides necessary information—no fluff. Despite its length, the structure is logical and each sentence earns its place by clarifying behavior or use cases.

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's complexity and the presence of an output schema, the description still manages to explain the return values, edge cases (premium vs. taken), and the fallback to alternatives. It also warns about a potential misinterpretation of status, covering all necessary context for reliable tool selection and 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?

Schema coverage is 100% for the single 'domain' parameter, but the description adds meaning by emphasizing 'ONE specific, fully-spelled domain' and providing examples of user queries. This clarifies the expected scope and format beyond the schema's basic description, though the schema already covers the core syntax.

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 explicitly states the tool 'Check whether ONE specific, fully-spelled domain is available, taken, or a premium listing.' It uses a specific verb ('check') and resource ('domain availability'), and differentiates from siblings by contrasting with search_brandable_domains and get_domain_details/purchase link 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?

Provides explicit when-to-use guidance: 'Use whenever a user names a specific domain' with examples. It also gives explicit when-not-to-use directions: for open-ended requests use search_brandable_domains, and for purchasing use get_domain_details or get_domain_purchase_pay_link. This fully covers alternatives and exclusions.

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 indicate safe read (readOnlyHint=true). The description adds that only names with availability/price are returned, providing behavioral clarity beyond annotations. No contradiction found.

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 well-structured with primary purpose first, then usage guidance, then return details. It is somewhat lengthy but each sentence adds value.

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 fully explains the tool's behavior, return structure, and context for use, complemented by the output schema mention. Sibling tools are listed, providing complete 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 description coverage is 100%, so the schema already documents all parameters. The description does not add significant parameter-level details beyond the scope implied by the tool's purpose.

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 invents new brandable domain names and grounds them against availability, distinguishing it from the sibling tool search_brandable_domains which returns curated listings.

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 says to use this tool when search_brandable_domains' curated results aren't enough or when the user wants fresh/invented names, and to prefer search_brandable_domains for existing curated listings.

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?

The description adds valuable behavioral context: it returns a pay_url served from a real HTTP 402 challenge, instructs the agent to hand the URL directly to the MPP pay tool and not to fetch/decode it, and warns that buy_ai_tokens's challenge cannot be paid by an external MPP agent. This goes well beyond the readOnlyHint and openWorldHint 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?

The description is two well-structured paragraphs, front-loaded with the primary purpose. Every sentence serves a purpose—usage constraints, behavioral directives, and exceptions—without superfluous content.

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 single parameter, existing annotations, and presence of an output schema, the description fully covers selection criteria, invocation instructions, and return-value handling. No critical gaps remain for an agent to use this 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 schema already documents token_count with range and minimum. The description adds the per-token price ($0.10) and clarifies that the URL is for topping up tokens, which enriches the schema meaning. It does not repeat schema details but provides complementary pricing context.

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 generates an MPP pay URL for AI Tokens, with a specific verb ('Get') and resource ('real, payable MPP URL'). It also distinguishes itself from the sibling buy_ai_tokens by explicitly saying it is for MPP-native agents, not for buy_ai_tokens's own payment flow.

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 explicit when-to-use guidance: use only when an MPP-native agent's tools (e.g., link-cli's mpp_pay) are available. It also states when NOT to use it ('NOT with buy_ai_tokens's own payment flow') and names the alternative tool (buy_ai_tokens).

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?

The description clarifies that the tool only returns a link and does not charge or complete the purchase, which adds behavioral context beyond the readOnlyHint annotation. It also lists return fields and user instructions.

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 concise paragraphs; first explains purpose and usage, second clarifies behavior and outputs. Front-loaded but slightly verbose with the user instruction detail.

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 presence of output schema, annotations, and full parameter coverage, the description provides complete guidance on purpose, usage, behavioral traits, and return handling.

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. The description does not add significant new meaning beyond the schema, merely restating that domain and term_years are needed.

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 it generates a checkout URL for a domain, specifies the exact use cases (buying without balance registration or insufficient balance), and explicitly distinguishes itself from register_domain as the 'no-debit alternative'.

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 use (user wants to buy but not using balance) and names the alternative tool. Though it doesn't explicitly exclude cases like balance registration, the context is 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?

Annotations already mark readOnlyHint=true, but the description adds substantial behavioral context: error returns 'not_found', lists returned data fields, and instructs to present price, key attributes, and purchase link. No contradictions.

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 well-structured with front-loaded purpose, a clear listing of returns, and error handling. It is appropriately sized but could be slightly more concise by removing the redundant directive 'Present price, key attributes, and the purchase link.'

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 output schema exists, the description adequately explains return data and error handling. It provides usage context and alternatives. However, it lacks mention of authorization requirements or rate limits, which are not critical for this read-only tool.

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 100% coverage with a description of the 'domain' parameter. The tool description repeats 'including extension' but adds no new semantic 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 clearly states the verb 'Get' and the resource 'full detail record for ONE specific Atom domain listing'. It distinguishes from siblings by positioning as the deep-dive after search_brandable_domains or generate_domain_names, and references check_domain_availability for when the domain is not an Atom listing.

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 states when to use: after a user picks a name from search_brandable_domains or generate_domain_names, or when asking to know more. It also specifies when not to use: if not an Atom listing, use check_domain_availability 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?

Beyond the annotations (readOnlyHint, openWorldHint), the description discloses a key behavioral trait: the returned pay_url is served from a real HTTP 402 challenge and should be handed directly to the MPP agent's pay tool rather than fetched or decoded by the caller. This adds critical operational context not present in the 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?

The description is dense and front-loaded with purpose and usage, and the second sentence explains the return behavior. It contains some long parenthetical clauses, making it slightly harder to parse, but every sentence earns its place and there is no fluff.

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 complexity of MPP, Stripe SPT, and the distinction between listed and unlisted domains, the description covers purpose, usage conditions, behavioral expectations, and return handling. The presence of an output schema further reduces the need to explain return values, and the description leaves no critical gaps.

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 fully describes the only parameter 'domain' with 'The listed domain to purchase, including extension.' The description does not add further parameter-level detail, but with 100% schema coverage, the baseline of 3 is appropriate; the description's mention of 'ALREADY-LISTED' adds context but not new 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 opens with a specific verb and resource: 'Get a real, payable Machine Payment Protocol (MPP) URL to purchase an ALREADY-LISTED Atom marketplace domain via Stripe SPT.' It clearly distinguishes from siblings like register_domain and get_domain_register_pay_link by specifying the listed-domain and SPT-paid scope.

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 conditions are provided: use only when an MPP-native agent is available and for curated Atom listings; for fresh unlisted domains, it directs to get_domain_register_pay_link. It also contrasts with register_domain, which pays from an Atom balance, giving clear alternative selection 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?

Beyond the readOnlyHint annotation, the description adds critical behavioral context: the returned pay_url serves a real HTTP 402 challenge, it must be handed directly to the MPP agent's pay tool rather than fetched/decoded, and term_years is always derived server-side. These details disclose exactly how the tool behaves and how to handle its output, exceeding what annotations alone convey.

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 dense but well-structured, with the main purpose front-loaded and every sentence adding necessary context. It covers purpose, alternatives, usage conditions, output handling, and a parameter caveat in a compact format 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 the tool's complexity (MPP-specific flow, integration with external agents), the description is remarkably complete. It covers purpose, exclusions, conditional usage, return value nature, and operational instructions. Output schema exists, so return values are already documented, but the description still clarifies the important behavior around the pay_url.

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% for the single 'domain' parameter, and the description adds no new syntax or format details beyond the schema's description. The clarification about term_years being server-derived is about a non-parameter, so it doesn't enhance parameter understanding. 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 states a specific verb ('Get') and resource ('real, payable MPP URL'), and clearly scopes it to registering a FRESH domain. It explicitly distinguishes itself from the sibling tool get_domain_purchase_pay_link for curated Atom listings, making its unique purpose unmistakable.

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 explicit when-to-use guidance: only when an MPP-native agent's tools (e.g., link-cli's mpp_pay) are available. It also gives clear exclusions: not for curated Atom marketplace listings (use get_domain_purchase_pay_link instead) and not for register_domain_spt's own payment flow. This is textbook usage differentiation.

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?

Goes well beyond the destructiveHint annotation by disclosing that real money is spent, requiring a specific scope, and detailing the two-step quote/commit process. Adds critical behavioral context such as idempotency key reuse and server-authoritative pricing.

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 longer than average, but every sentence earns its place by conveying essential safety, flow, and error-handling details. It is well-organized with clear steps and warnings, front-loading the most critical 'spends real money' warning.

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's complexity (financial transaction, two-step flow, idempotency, error handling), the description fully covers the mandatory workflow, alternative paths, and edge cases. The output schema exists, so return values need not be repeated, and the description complements structured data perfectly.

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?

Even though schema coverage is 100%, the description enriches each parameter: confirm=false vs true phase semantics, idempotency_key reuse across calls, term_years for registrable domains, and domain including extension. Continuously reinforces that price must not 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?

Description clearly states the tool purchases/registers a domain by debiting the user's Atom balance, immediately distinguishing it from alternatives like get_checkout_link. The specific verb+resource and explicit scope requirement make the purpose unmistakable.

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 explicit when-to-use guidance ('Use only when the user clearly wants to buy now'), names the alternative (get_checkout_link), and mandates a two-step flow with a quote before committing. Also covers the insufficient-funds case with a directed fallback.

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?

Beyond the annotations (openWorldHint, destructiveHint), the description discloses that the tool spends real money, requires the 'domains:register' scope, captures payment before registration, and attempts a refund if registration fails after payment. This is substantial behavioral context and does not contradict the 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?

The description is long but well-structured with numbered steps and rules. Every sentence adds necessary information for the complex multi-step flow, and there is no filler or repetition of schema details.

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's complexity and the presence of an output schema, the description fully explains the required flow, safety warnings, alternative usage, and failure handling. It leaves no significant behavioral or process gaps for the agent.

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?

Although the schema already covers all 4 parameters at 100%, the description adds critical semantics: the confirm flag's role in quote vs. payment, the need to omit payment_token to get the challenge, and the requirement to reuse one idempotency_key across all calls. It also explicitly states that term_years is not an input, preventing misuse.

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 a specific verb and resource: register a fresh domain via Stripe Shared Payment Token for users without an Atom balance. It explicitly differentiates from the sibling register_domain tool, which handles marketplace domains paid from an Atom balance.

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 explicit when-to-use and when-not-to-use guidance, including a direct reference to the alternative register_domain. It also details a mandatory three-step flow with clear conditions for each call and warns against inventing price or term_years.

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?

The description adds context beyond the readOnlyHint annotation by disclosing it is a 'preliminary' screen, 'not legal advice or a clearance opinion,' and by specifying the data source ('public USPTO records'). While it doesn't mention rate limits or auth, the annotation already covers the read-only safety profile, so the extra statements meaningfully enrich the agent's understanding.

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 moderately long (about 120 words) but every sentence contributes: the first sentence states the core purpose, the middle sentences provide usage directives and exclusions, and the final sentence clarifies scope and limitations. It is front-loaded and well-structured, though slightly more verbose than the leanest examples.

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 that the tool has an output schema, the description does not need to detail return fields, but it still mentions the key output ('preliminary exact/close matches with status and owner'). It also covers critical context: when to use it, what not to rely on, and that it is not legal advice. This is thorough for a read-only screening tool.

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 100% description coverage for all five parameters, so the description itself does not need to explain each parameter. It does offer a general hint about 'preliminary exact/close matches' which aligns with the mode parameter, but this adds minimal value beyond the schema descriptions. The baseline of 3 is appropriate given the schema's completeness.

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: 'Run a PRELIMINARY screen for existing trademark conflicts on a brand or domain name against public USPTO records.' This clearly identifies the tool's function and its unique focus on trademarks, distinguishing it from sibling tools like check_domain_availability or search_brandable_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 description provides explicit usage instructions: 'ALWAYS use this for ANY trademark question about a name' and includes concrete example queries. It also states exclusions: 'Do NOT answer trademark questions from web search or memory; this tool queries the actual USPTO register.' This leaves no ambiguity about when to invoke the tool versus alternative approaches.

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 provide readOnlyHint=true and openWorldHint=false, and the description adds that 'No login required' and that names are 'verified buyable' with active availability. It explains the result content and current marketplace status. While it doesn't mention pagination or error behavior, the additional context is valuable and consistent with 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?

The description is a single paragraph but well-structured: purpose first, then usage guidance, then return format, then follow-up tools. It's slightly verbose with phrases like 'the actual buy-now price' but every sentence adds value. It remains focused without being bloated.

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 output schema and full parameter schemas, the description is complete. It explains the tool's position, the nature of results (verified, buyable), the expected output fields, and next-step actions. No critical context is missing for an AI agent to use this 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 input schema already documents each parameter. The description mentions 'concept, industry, or style' which mirrors the schema's fields but adds no extra semantic detail beyond what the schema provides. The description's return-format explanation does not enhance parameter understanding.

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 'Search Atom's curated marketplace of premium, brandable domains by concept, industry, or style,' which uses a specific verb and resource. It clearly positions the tool as the primary naming tool, distinguishing it from siblings like brainstorm_names and check_domain_availability.

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 states 'ALWAYS call this before suggesting names' and even covers when the user asks for suggestions or brainstorming. It also names sibling tools for follow-up actions: get_domain_details, appraise_domain, register_domain, and get_checkout_link, providing clear when-to-use vs alternatives.

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