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 critical behavioral traits: 'SPENDS REAL MONEY', requires the 'domains:register' scope, payment is captured before crediting, and if crediting fails after payment, no automatic refund is issued. This adds significant context and no contradiction 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 long but every sentence earns its place, given the complex payment flow. It is well-structured with numbered steps and clear rules, front-loading the purpose and the most critical warning about real money. No fluff or redundant 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?

The tool has a complex multi-step payment process, and the description covers all essential aspects: the three-step flow, fallback options, no-refund policy, and the exact behavior of payment capture. The output schema exists but the description still clarifies what to expect at each step, making it complete for an agent to use confidently.

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 schema coverage is 100%, the description adds crucial meaning: pricing is server-authoritative and must not be assumed or passed, the same idempotency_key must be reused across all calls, and payment_token is omitted to receive a challenge. These details go far beyond the bare parameter descriptions and are essential for correct invocation.

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

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

The description opens with a specific verb and resource: 'Purchase AI Tokens ($0.10 per token) by charging a Stripe Shared Payment Token (SPT)' and clearly scopes it to 'users with no Atom balance'. It distinguishes itself from sibling tools by explicitly setting priority over get_ai_tokens_pay_link. The purpose is unambiguous and not a mere restatement of the name.

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 extensive when-to-use guidance: it says to try this tool first (priority 1) and specifies exactly when to fall back to get_ai_tokens_pay_link. It also gives a mandatory three-step flow with confirmation flags and idempotency key reuse, leaving no ambiguity about the correct procedure versus alternatives.

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 signal readOnlyHint=true, and the description adds useful behavioral context: it checks fresh-registration availability, may misleadingly report already-listed/owned domains as taken, and explains status semantics and follow-up tools. However, this contradicts the stated 'premium' status definition ('for sale on Atom'), creating genuine confusion about whether an Atom marketplace listing returns 'premium' or 'taken'.

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

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

The description is front-loaded with the core purpose, then organized into clear usage, returns, and IMPORTANT follow-up sections. It is longer than strictly necessary, and the contradictory 'taken' sentence should be corrected, but each section carries meaningful operational information for an agent.

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 covers when to use the tool, what status values mean, the alternatives array, which sibling to call next based on status, URL interpretations, and how to recover from the registrant_contact_required error. The only material gap is the unresolved 'taken' vs 'premium' inconsistency, which prevents full contextual completeness.

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. The description adds value by emphasizing that the domain must be ONE specific, fully-spelled domain and by giving natural-language examples like 'is acme.com available?', which clarify the expected input beyond the schema's brief description.

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 opening sentence states the exact verb and resource: checking one specific, fully-spelled domain for whether it is available, taken, or premium. It further differentiates from search_brandable_domains and get_domain_details with concrete examples, so an agent can immediately identify this tool's distinctive role.

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 ('whenever a user names a specific domain') and names alternatives for other cases, such as search_brandable_domains for open-ended requests and get_domain_details for known Atom purchases. It also provides downstream routing rules, including explicit warnings against calling register_domain for premium/taken domains or purchase_domain for available ones.

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 fully discloses the tool's side effects: it creates or updates a contact, does not charge, and requires a full set of fields. It even clarifies the default email behavior. However, the annotation readOnlyHint: true contradicts the described mutation, but the description itself is transparent.

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

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

The description is well-structured and front-loaded with the core purpose. However, it repeats the upsert behavior in the middle and end ('Create or update' and later 'If a contact already exists, this UPDATES it...'), making it slightly redundant. Still, it remains concise and easy to parse.

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 covers the trigger condition, the exact behavior, required fields, and even the charge note. It provides all necessary context for an agent to decide and execute correctly, especially given the provided output schema. No critical information 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?

The description adds meaningful context beyond the schema: it explains which fields are required vs optional, that state is only where applicable, and that email defaults to the Atom account email. This clarifies the purpose of each parameter and fills gaps left by the schema descriptions.

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

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

The description clearly states the tool's purpose: to create or update the authenticated user's registrant contact. It specifies the resource (registrant contact) and the action (create/update), making it unambiguous. It also distinguishes it from sibling tools by referencing the specific error that triggers its use.

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: 'Call this when a tool reports error 'registrant_contact_required''. This provides a concrete trigger condition. It also explains the upsert behavior, clarifying that it updates if a contact exists and that no charge is incurred, which helps the agent decide when to invoke it.

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?

Annotations include readOnlyHint=true, which is consistent with the description's emphasis on not fetching or decoding the URL yourself. The description adds behavioral context: the URL is served from a real HTTP 402 challenge, and it must be handed directly to the MPP agent's pay tool. It also clarifies that the tool's own payment flow cannot be paid by an external MPP agent, which is important behavioral disclosure beyond 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 well-structured with clear sections: purpose, usage priority, and return behavior. It is concise but packed with essential information, using bold for key terms and bullet-like structure. Every sentence adds value, and it is front-loaded with the core purpose.

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 (interaction with external MPP agents, priority ordering, and no fallback), the description is complete. It covers when to use, how to use, what to expect, and what not to do. The output schema exists, so return values are not needed in the description. The description fully compensates for the lack of annotations beyond readOnlyHint.

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 provides 100% coverage for the single parameter token_count, including a description with range and minimum. The description adds context about the price ($0.10/token) and the minimum purchase, which reinforces the parameter's meaning. Since schema coverage is high, the baseline is 3, and the description adds a bit more value, so a 4 is justified.

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 get a real, payable MPP URL for topping up AI Tokens. It specifies the resource (AI Tokens), the action (get a pay link), and distinguishes it from the sibling tool buy_ai_tokens by noting it is for use with an MPP-native payment agent, not buy_ai_tokens's own 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, and only after buy_ai_tokens's in-band payment flow isn't viable. It also states there is no checkout-link fallback, and instructs to hand over the exact server-computed pay_url/price, never estimate. This is exemplary usage 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?

The description discloses critical behavior beyond the readOnlyHint annotation: the tool only returns a link, does not charge or complete the purchase, and the link is not pre-authenticated. It also explains error behavior for sold or make-offer/price-on-request domains. This materially helps the agent set user expectations and handle failures. The description is 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 long but every section earns its place: primary purpose, usage priority, non-debit behavior, authentication caveat, error cases, and return values. The information is front-loaded and organized with clear signposts like PAYMENT PRIORITY and IMPORTANT. The length is justified by the tool's complexity and the large sibling set.

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 role as a last-resort payment fallback with many sibling tools, the description is complete. It covers when to use it, what it returns, what it does not do, the login requirement, and likely errors. An agent has enough context to invoke this tool correctly and communicate the result to the user.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add much parameter-specific meaning beyond what the schema provides for domain and term_years. It reinforces the overall purchase context but does not deepen understanding of the individual parameters.

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

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

The description specifies a clear verb and resource: generate a pre-filled Atom checkout URL for a chosen domain. It explicitly differentiates itself from register_domain as the no-debit alternative and clarifies its scope to premium/marketplace purchases. This makes it easy for an agent to distinguish from the many sibling tools.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it is priority 3, last resort, only after register_domain and get_domain_purchase_pay_link + link-cli are unavailable. It also states there is no equivalent fallback for fresh registrations or AI Tokens purchases, and advises checking get_domain_details first when uncertain. This is unusually complete routing guidance.

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

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

Annotations only declare readOnlyHint and openWorldHint. The description adds substantial behavioral detail: the returned fields, the not_found error path, price_on_request semantics with an explicit 'never imply a price' rule, and available_for_purchase=false meaning the listing is sold and purchase_url is unusable. It remains consistent with readOnlyHint.

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 typical, but the length is earned: the purpose sentence is front-loaded, the return summary is compact, and the two IMPORTANT caveats address high-stakes edge cases. Minor redundancy exists with 'Present price, key attributes, and the purchase link' repeating the return list, but overall it remains well organized.

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

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

Given a single-parameter schema, read-only annotation, and output schema present, the description covers invocation context, error handling, and edge-case behavior. Nothing an agent needs to decide whether to call this tool or to interpret special price/availability results 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% and the only parameter domain is already described as 'The domain to look up, including extension.' The description reinforces the single-domain scope but adds no new parameter format, constraints, or examples beyond the schema, so the 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?

Description uses a specific verb+resource: 'Get the full detail record for ONE specific Atom domain listing.' It explicitly positions itself as the deep-dive after search_brandable_domains or generate_domain_names, and contrasts with check_domain_availability for non-Atom domains, clearly distinguishing it from 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?

Gives explicit when-to-use guidance: after a user picks a name from search_brandable_domains or generate_domain_names, or asks to know more about a particular domain. Also gives an exclusion: if the domain is not an Atom listing, it returns not_found and the agent should use check_domain_availability. This is strong routing guidance.

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

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

Annotations mark the tool as read-only, and the description aligns with that by describing a URL-returning operation rather than a mutating purchase. It adds useful behavioral detail beyond annotations: the URL is served from a real HTTP 402 challenge, the caller should hand the pay_url to mpp_pay rather than decode it, and the expected registrant_contact_required error has a defined recovery workflow.

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?

Though longer than average, every sentence earns its place: purpose, usage conditions, priority ordering, exact-value handling, and error recovery. The main use case is front-loaded, and the detailed fallback instructions are structured clearly with explicit markers like PAYMENT PRIORITY and error-name highlighting.

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

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

Given the tool has one parameter, an output schema, and read-only annotations, the description covers the essential operational context an agent needs: when to choose it, what to do with the returned pay_url, and how to recover from the documented error. No critical usage step appears to be 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?

The single domain parameter is already fully described in the input schema, including the 'including extension' detail. The description adds contextual eligibility requirements like 'already-listed' and 'curated Atom listing', but it does not add new parameter-format semantics beyond the schema. This matches the baseline for high schema coverage.

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: get a real, payable MPP URL to purchase an already-listed Atom marketplace domain via Stripe SPT. It explicitly differentiates itself from get_domain_register_pay_link, which is for fresh unlisted domains, and clarifies its role relative to register_domain's balance-based payment.

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?

Usage guidance is explicit and prioritized: use only when an MPP-native agent's tools are available, only for curated Atom listings, after register_domain reports insufficient funds, and before get_checkout_link as last resort. It also names alternatives and gives a fallback path when link-cli is unavailable.

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 readOnlyHint=true and the description aligns with that. It adds valuable behavioral context beyond annotations: the returned pay_url comes from a real HTTP 402 challenge, the caller should hand it to an MPP pay tool rather than fetching/decoding it, term_years is always server-derived, and the registrant_contact_required error has a defined recovery path.

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 and front-loaded with the core purpose. Each section earns its place: routing to the correct sibling, payment priority, return-value handling, and error recovery. There is no filler or redundancy, and the labeled structure helps an agent parse the key constraints quickly.

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, the description is complete: it explains when to use it, what it returns, how to handle the result, and how to recover from a known error. The presence of an output schema and a single fully documented parameter lowers the burden, and the description covers all essential invocation 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?

The input schema already fully describes the only parameter, 'domain', with 100% coverage. The description reinforces its meaning by specifying that the domain must be fresh and available, not a curated marketplace listing, and clarifies that term_years is never a caller input. This adds contextual semantics 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 action and resource: getting a real, payable MPP URL to register a fresh domain. It explicitly contrasts with get_domain_purchase_pay_link by saying it is NOT for curated Atom marketplace listings, so an agent can distinguish it from the sibling without opening schemas.

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

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

The description gives explicit when-to-use guidance: only when MPP-native tools like link-cli's mpp_pay are available, and as priority 2 after register_domain_spt's in-band payment flow is not viable. It also names the alternative for curated listings and states there is no checkout-link fallback for fresh registrations.

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?

Even though destructiveHint already signals a mutating operation, the description adds crucial context: it spends real money, requires the 'domains:register' scope, charges payment methods, returns quotes before committing, enforces idempotency, and explains the exact error paths and recovery steps. This far exceeds what annotations alone communicate.

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 section carries essential operational guidance for a high-risk financial action. It is front-loaded with the core decision rule, then organized into numbered steps, error handling, and explicit prohibitions. No filler or repetition.

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

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

The description covers prerequisites, the full quote-to-confirm sequence, user communication requirements, idempotency, insufficient funds, card failures, 3D Secure limitations, and registrant contact recovery. Given the tool's complexity and risk profile, the description is complete enough for an agent to execute 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: confirm=false is for quoting, confirm=true requires payment_method, payment_method is ignored at quote stage, and idempotency_key must be reused across both calls. These behavioral constraints are essential and not inferable from the schema alone.

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

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

The description opens with a specific verb and resource: 'Purchase an ALREADY-LISTED Atom marketplace domain.' It clearly distinguishes itself from register_domain by explicitly stating when each applies, so an agent can tell them apart without opening schemas.

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

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

The description gives explicit when-to-use conditions tied to check_domain_availability statuses and get_domain_details, names the alternative register_domain, and even explains that using this tool on a fresh domain will fail with 'not_a_marketplace_listing.' It also provides a mandatory two-step flow with no ambiguity.

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 (destructiveHint, openWorldHint), the description discloses that the tool 'SPENDS REAL MONEY', requires the 'domains:register' scope, follows a mandatory quote-then-confirm flow, reuses an idempotency key to prevent double-charging, and surfaces specific error behaviors (insufficient_funds, card_payment_failed, is_marketplace_listing). This is far beyond 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 long but every sentence carries essential operational guidance for a high-stakes, two-step payment tool. It is structured with a numbered three-step flow, explicit rules, and error-handling notes, all front-loaded after a purpose statement. No filler or repetition; the density is justified by the tool's 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 covers prerequisites, the exact invocation sequence, required user consent messaging, payment method selection, idempotency, error recovery paths, and post-condition (domain appears in My Domains). With an output schema present, no return-format explanation is needed. Given the tool's complexity and the rich sibling set, this is fully complete.

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%, but the description adds substantial meaning: confirm=false produces a quote, confirm=true commits the charge, payment_method is required only at confirmation and must be exactly 'balance' or 'saved_card', and the idempotency_key must be identical across both calls. It also clarifies that term_years is server-derived and should never be passed, enriching parameter understanding 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: 'Register a FRESH domain' directly at the registrar, and explicitly distinguishes a fresh, available domain from an Atom marketplace listing. It also names the sibling purchase_domain as the alternative for marketplace domains, making the tool's unique scope 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 gives an explicit condition: use this ONLY when check_domain_availability reported status 'available' for the exact domain. It also specifies when NOT to use it (status 'premium'/'taken' → use purchase_domain) and how to recover from the 'registrant_contact_required' error by calling create_registrant_contact. Alternatives and exclusions are fully spelled out.

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 only indicate destructive and open-world behavior, so the description carries the burden of disclosure. It goes well beyond: it warns 'SPENDS REAL MONEY', states the required 'domains:register' scope, explains the mandatory three-step protocol, clarifies that payment is captured before registration starts, discloses the refund attempt after a post-payment failure, and documents the expected registrant_contact_required recovery path.

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 highly structured: purpose first, then the mandatory three-step flow, then payment priority, then rules and error handling. Every sentence carries critical operational information, and no filler or repetitive schema restating exists.

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, the description is complete. It covers the multi-call protocol, payment priority, authentication scope, refund behavior, and a known error recovery flow. The output schema handles return-value documentation, so the description does not need to restate that, and the remaining gaps are negligible.

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. The description adds substantial meaning beyond the schema: never pass price or term_years, reuse one idempotency_key across all calls, omit payment_token on the second call to get the challenge, and pass it only on the final call. These are operational semantics that the schema cannot express.

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: 'Register a FRESH domain' via a Stripe Shared Payment Token for users with no Atom balance. It explicitly distinguishes itself from register_domain, which handles already-listed marketplace domains paid from an Atom balance. This gives an agent a clear basis for selecting this tool over 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 explicit when-to-use and when-not-to-use guidance. It names register_domain as the alternative for marketplace domains, names get_domain_register_pay_link as the priority 2 fallback, and explicitly states that get_checkout_link does not apply to fresh registrations. This is exemplary routing guidance.

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

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

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?

The annotations already establish readOnlyHint=true and openWorldHint=false, and the description goes well beyond them. It discloses that results are verified buyable marketplace listings, not fresh registrations, that no login is required, that prices are in USD as the actual buy-now price, and that every returned name is actively for sale on Atom. This is rich behavioral context beyond what annotations 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 more verbose than a typical tool definition, but the length is mostly justified by the strong routing mandate, the explanation of marketplace-specific behavior, and the return format summary. Minor redundancy exists, such as 'verified buyable' and 'actively for sale on Atom' saying similar things, and the final presentation instruction could arguably be folded into the return description.

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 is available and the annotations carry the read-only and closed-world indicators, the description provides all necessary context: what the tool searches, when to use it, what results contain, that no login is needed, and which sibling tools to use for next steps. Nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds a high-level mapping of 'by concept, industry, or style' to the core filters but does not deepen understanding of limit, style enum values, max_price, or extensions beyond what the schema already states. The 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?

States a specific verb and resource: 'Search Atom's curated marketplace of premium, brandable domains by concept, industry, or style.' It clearly differentiates itself as the primary naming tool, which is reinforced by the explicit 'ALWAYS call this' guidance and by naming the alternative paths for appraisal, details, and purchase.

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 explicit when-to-use guidance: 'THE primary tool for ANY naming request' and 'ALWAYS call this before suggesting names... even when the user asks only to suggest a name or brainstorm ideas.' It also explains why (imagination-based names are usually taken) and provides next-step alternatives (get_domain_details, appraise_domain, purchase_domain), making tool selection unambiguous.

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