Atom.com — Premium Domains

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

Goes well beyond the readOnly/non-destructive annotations by defining the two returned numbers, warning against conflating value with quality score, clarifying domain_score is not confidence/probability, and giving presentation guidance ('NEVER describe domain_score as confidence'). This is exactly the behavioral context an agent needs to interpret results correctly.

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?

Front-loads the purpose, then uses tightly scoped bullets for the two return values and presentation rules. Every sentence adds disambiguation or output-interpretation value; nothing is filler.

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

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

Although an output schema exists and would normally remove the need to explain returns, the description still provides critical interpretation guidance that prevents misuse of domain_score. Combined with readOnly annotations and a fully documented single parameter, the definition is complete for correct invocation and presentation.

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?

There is only one parameter and schema description coverage is 100%; the schema already explains that the full domain including extension is required and that any domain works. The description adds no per-parameter syntax or formatting detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Estimate the market value of a domain and explain why'), and the follow-on bullets make clear this is an appraisal tool distinct from lookup/availability/purchase siblings. An agent can identify the tool's function without opening the schema.

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 triggering conditions ('when a user asks what a domain is worth, how much to pay/offer'), which is strong context. It does not name alternative tools or state when not to use this one versus get_domain_details or check_domain_availability, so it falls short of the 5 bar.

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 readOnly/openWorld=false/destructive=false; the description adds the substantive behavioral facts an agent cannot infer: results come from Atom's curated marketplace, every name is verified buyable, each carries a price in USD and an Atom buy-page URL. That materially changes how the agent should present and trust the output.

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?

Front-loaded with the value proposition and the mandatory-use rule, and nearly every sentence earns its place. The trailing enumeration of result fields (domain, price, logo, style_tags, category, url) partially duplicates the existing output schema and could be trimmed.

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

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

For a 6-parameter read-only discovery tool with full schema coverage and an output schema, the description covers what is missing: why to use it over inventing names, how to phrase the concept, how to present results with prices and links. Nothing an agent needs to invoke or apply it correctly is absent.

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 real semantics beyond the schema by telling the agent to express the business as the 'concept' and to pass 'extensions' only when the user stated a preference. It does not, however, explain the style enum values or how limit interacts with server-side capping.

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 ('come up with name ideas') plus the differentiating constraint that every suggestion is a real, verified-buyable premium domain with a price. It also explicitly names the sibling with identical behavior ('Same results as search_brandable_domains'), so an agent can distinguish it from generate_domain_names or the search tool without opening a schema.

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 trigger phrases ('come up with a name', 'suggest names', 'brainstorm names', 'name my company'), an explicit imperative to always prefer it over self-invention with the reason (unverified names are usually taken), and an exclusion rule steering away from a sibling ('use either, not both'). It also says to pass preferred extensions only when the user stated any.

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 cover destructive/openWorld, and the description adds substantial non-annotation context: it spends real money, requires the 'domains:register' scope, payment is captured before crediting, and crediting failure yields no automatic refund. Missing only details on rate limits or what exactly the successful response contains; strong overall.

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?

Front-loads the money/spend warning and scope requirement, then the numbered flow, then the priority rule. Dense with decision-relevant content, though the emphasized caps and repeated 'never assume or pass a price' cost some length.

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 destructive, multi-step payment tool with an output schema present, the description covers the flow, preconditions, side effects, idempotency, and the shape of the intermediate challenge response. Nothing an agent needs to invoke 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 coverage is 100% and already documents all four parameters, so the baseline is 3. The description still adds semantics the schema cannot: price is server-authoritative and must never be passed, the same idempotency_key must be reused across calls, and omitting payment_token triggers the payment_required challenge.

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

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

States a specific verb, resource, price, and payment rail (buy AI Tokens via Stripe SPT), and explicitly contrasts with sibling get_ai_tokens_pay_link as the priority-2 fallback. An agent can distinguish it from every other token-payment tool without opening a schema.

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

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

Gives an explicit mandatory three-call sequence with the exact arguments for each step, plus a documented fallback order and the note that no checkout-link fallback exists. Both when-to-use and when-to-fall-back are 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?

Far exceeds the annotations: it defines each status value, enumerates the returned fields (registrable, price + currency, estimated_value, alternatives[]), and explains that the top-level url means different things per status. It also discloses the downstream routing rules and the expected registrant_contact_required error with the recovery path, none of which is derivable from readOnlyHint/openWorldHint.

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?

Front-loaded well: purpose, examples, then alternatives, then returns. But it spends several sentences on the register_domain / purchase_domain flow and the create_registrant_contact recovery, which is guidance that belongs with those tools and inflates a one-parameter check tool. Some of that text is duplicative of what register_domain and purchase_domain presumably say themselves.

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?

Despite the output schema, the description explains return values and the per-status branching, and it tells the agent exactly which sibling to call next in each case. Nothing needed to call this correctly or act on its result is missing.

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

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

Schema coverage is 100%, so the schema already documents the single 'domain' parameter, and an output schema exists. The description still adds meaning by stressing ONE domain, fully spelled, with extension — constraining the agent away from passing lists or bare labels. Only mildly additive given the schema does the rest.

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

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

States a specific verb and resource (check availability of ONE fully-spelled domain) plus the three outcomes it can return (available, taken, premium). It explicitly distinguishes itself from search_brandable_domains and get_domain_details, so an agent can pick it without opening any schema.

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 concrete trigger examples ("is acme.com available?", "who owns x.io?") and explicit exclusions with named alternatives for open-ended brainstorming and for purchasing known marketplace listings. The rationale for the exclusion (fresh-registration check misleadingly reports listed domains as taken) makes the boundary unambiguous.

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 say readOnlyHint=false and destructiveHint=false. The description adds what actually matters: this is an upsert, not a pure create — existing data is overwritten, so the caller must resend the full field set rather than a delta. It also explicitly states no charge occurs, which is essential context given the surrounding payment-related siblings.

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 definition leads with what the resource is, then the trigger, then the mutation semantics, in priority order. Every sentence carries non-redundant information: the definition, the error trigger, the requiredness rule, the no-charge assurance, and the upsert 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?

An output schema exists, so return values needn't be described, and annotations cover the safety profile; the description still adds the trigger, the no-charge fact, and the overwrite behavior. The only small gap is that it doesn't say what happens on validation failure or partial/invalid input, which is minor for this 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 89%, so the baseline is 3, and the description earns an extra point by clarifying requiredness beyond the schema listing (all required except state and organization, 'state only where applicable') and by reinforcing the full-set resubmission rule that governs every parameter on update. It doesn't restate the zip/phone/country formats, which the schema already handles.

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 gives a specific verb and resource ('Create or update the authenticated user's registrant (WHOIS) contact') and explains exactly what that resource is: the name/address/phone/email a registry requires for registration or marketplace transfer. No sibling tool touches WHOIS contacts, so the boundary against purchase_domain/register_domain is unambiguous from the text alone.

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 names a concrete trigger ('Call this when a tool reports error registrant_contact_required') and ties the tool to the registration/transfer prerequisite that motivates it. It doesn't say when not to call it or discuss any alternative path, but the trigger condition is explicit enough for an agent to act on.

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?

Adds real context beyond the annotations: every returned name is grounded against live availability and Atom premium inventory, ungrounded ideas are filtered out, and the status/price fields are explained. Since readOnlyHint/destructiveHint already cover the safety profile, this is strong, though it omits cost/latency implications of live lookups and any server-side cap behavior on 'count'.

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?

Front-loaded with purpose, then routing, then return shape — a sensible ordering with no filler sentences. The return-format paragraph is somewhat long given an output schema exists, but it carries presentation guidance rather than restating the schema.

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?

An output schema exists, yet the description still supplies the wiring an agent needs: how to treat 'available' vs 'premium' and how to present results. Minor gap: nothing about how extensions or count caps affect outcomes, but the schema covers those adequately.

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 all five parameters (concept, count, style, industry, extensions) are already documented in the schema. The description adds no field-level meaning beyond implying that 'style' surfaces as style_tags in the results, so the baseline 3 applies.

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

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

Opens with a specific verb and resource ('Invent NEW brandable domain name candidates') and immediately states the grounding step that makes the output distinctive. It explicitly positions itself against the sibling 'search_brandable_domains', so an agent can pick between them without reading either schema.

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?

Names both trigger conditions (curated results insufficient, user wants fresh/invented/registerable names) and names the alternative with a preference rule ('For existing curated listings, prefer search_brandable_domains'). This is explicit when-to-use and when-not-to-use 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?

Goes well beyond the annotations: explains that the tool charges nothing by itself (consistent with readOnlyHint), that payment happens out-of-band via a 402 challenge and signed retry, that each status poll waits ~10s server-side, and that funds are credited only once status reports 'completed'. The 'never recompute the price' rule is a non-obvious behavioral constraint that would otherwise cause errors.

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?

Front-loaded with the core purpose and return shape, then the usage trigger, then the follow-up workflow — a sensible ordering. It is on the long side and carries polling mechanics that arguably belong to get_coinbase_payment_status, but every sentence provides actionable constraint rather than filler.

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

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

Despite an output schema existing, the description still describes the two returned URLs at the level an agent needs to act on them, and it covers the full lifecycle from link generation through credit confirmation. Nothing needed to call it correctly and safely 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% for the single 'amount' parameter, so baseline would be 3; the description adds that the price is server-computed and must be presented verbatim rather than derived, which meaningfully constrains how the amount is used. It does not, however, clarify whether 'amount' is the user-supplied target or the server-returned price, leaving slight ambiguity.

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 ('Get a Coinbase checkout link, paid in USDC, that adds funds to the user's Atom account balance') and disambiguates scope from sibling pay-link tools by naming the balance used by register_domain and purchase_domain. It also enumerates the two returned URLs and what each is for, so an agent can pick it apart from get_domain_purchase_coinbase_pay_link without opening either schema.

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

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

Gives an explicit trigger ('Use this when a balance purchase reports insufficient funds and the user wants to top up with crypto/USDC'), the immediate follow-up step (poll get_coinbase_payment_status with the returned payment_code), the stopping condition (stop_polling true / status 'completed'), and the final action (retry the balance purchase). Alternatives are named by tool, not just implied.

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 destructiveHint=false, but the description adds substantial context beyond them: the returned pay_url serves a real HTTP 402 challenge, the amount is server-computed and must never be recomputed or estimated, and the URL must be handed to the pay tool rather than fetched or decoded. That is the kind of operational detail that prevents a costly misuse.

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?

Front-loaded with the concrete outcome and the primary exclusion, and the priority rule is stated before the mechanics. Minor redundancy: the 'hand it over, never fetch or decode it yourself' instruction appears effectively twice in the final two sentences.

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 one-parameter, read-only link-generation tool with an output schema and clear annotations, nothing an agent needs is missing: precondition, priority, price authority, and next action after receiving the URL are all present.

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 single parameter already documents the 5-100000 range and the $0.50 minimum, so the schema does the heavy lifting. The description adds pricing semantics ($0.10/token) and the rule that the price is authoritative from the server, which is meaning beyond the schema but not parameter-specific detail.

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: minting a real, payable MPP URL to top up AI Tokens, including the unit price. It explicitly distinguishes itself from sibling buy_ai_tokens's own payment flow, so an agent can route correctly without opening either schema.

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

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

Gives an explicit precondition (only when an MPP-native agent's tools like link-cli's mpp_pay are present in the session), an explicit priority ordering (priority 2, only after buy_ai_tokens's in-band flow is not viable), and an explicit exclusion plus the note that no checkout-link fallback exists. When/when-not/alternatives are all covered.

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 readOnly/non-destructive annotations: it discloses that nothing is charged, the link is not pre-authenticated, the user must already be logged into atom.com, and that sold or make-offer listings surface 'not_found'/'not_for_sale'. It also names the return payload and expiry, which the annotations cannot express.

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

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

Purpose and the sibling alternative are front-loaded, and every paragraph (priority ladder, auth caveat, error states, returns) carries distinct operational value. It is longer than typical, but the sectioned structure keeps it navigable rather than padded.

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 an output schema already exists, the description still adds the failure modes, the authentication precondition, and the explicit user-facing instructions ('present the price and the checkout link'). An agent has everything needed to invoke it and hand the result to a user correctly.

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

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

Schema coverage is 100% and both parameters are documented there, including the default for term_years. The description adds no extra meaning for 'domain' or 'term_years' beyond the pre-filled-link framing, so baseline 3 is appropriate.

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

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

States a specific verb and artefact ('Generate a pre-filled Atom checkout URL') and immediately contrasts it with the sibling that does the actual purchase ('no-debit alternative to register_domain'). An agent can distinguish it from register_domain and the various pay-link siblings without opening a schema.

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 when-to-use and when-not-to-use: only for buying a premium/marketplace domain, only after register_domain balance is insufficient AND the priority-2 pay-link path is unavailable, with a direct statement that no equivalent exists for fresh registrations or AI Tokens. Alternatives are named and ordered, leaving nothing to inference.

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

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

Discloses genuinely useful behavior not in the annotations: a ~10s server-side wait with re-check, safety of back-to-back calls, the ~15 minute stop_polling cutoff, and the semantics of all four terminal statuses. However, the claim that a call 'complete[s] the purchase / registration / funds credit' describes a state mutation, which conflicts with readOnlyHint=true (and the pure-read implication of destructiveHint=false) — a safety-relevant conflict that caps the score despite otherwise excellent disclosure.

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?

Front-loaded with purpose and side effect, then a clearly labeled POLLING block and an enumerated status list — a structure an agent can parse under time pressure. Slight redundancy between 'safe to call back-to-back' and 'no need to wait between calls', and the status enumeration is dense, but nearly every sentence carries operational 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?

For a two-parameter polling tool with an output schema and full schema coverage, the description supplies the missing operational layer: the polling loop, the stop condition, the timing model, and the per-status follow-up action. Nothing an agent needs in order to call it correctly and react to results is absent.

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, and the description goes beyond it by explaining why no client-side delay is needed ('each call waits up to ~10 seconds server-side and re-checks'), which gives meaning to wait_seconds and to back-to-back invocation. It does not restate the payment_code provenance beyond naming the producing tools, which is adequate.

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

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

States a specific verb and resource ('check a Coinbase (USDC) payment') and names the exact sibling tools that produce the payment_code it consumes, so the agent can place it in the pay-flow without opening any schema. It also states what the call achieves ('complete the purchase / registration / funds credit'), which no sibling name conveys.

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

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

Gives an explicit polling protocol: keep calling while status is 'pending' and stop_polling is false, no delay needed, stop when stop_polling is true and surface user_message verbatim, and re-call later if the user claims payment. Each terminal status ('failed' → offer a new link, 'refunded', 'needs_support') is paired with the action to take, which is exactly the when-to-use/how-to-react guidance an agent needs.

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 say readOnly/non-destructive; the description adds substantial non-obvious behavior: the not_found error condition, the price_on_request rule (price deliberately null, never imply $0 or free), and the available_for_purchase=false meaning the listing is sold and purchase_url is unusable. These are consequential business rules an agent could not infer from structured fields.

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?

Front-loaded with purpose and triggers, then return fields, then the two critical edge-case rules clearly flagged with IMPORTANT. The enumerated return-field list is somewhat redundant given an output schema exists, but the rest of the content earns its space.

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 single-parameter read tool with annotations and an output schema, the description covers everything an agent needs: when to call it, what happens on failure, and how to interpret the two ambiguous result states (price_on_request, already sold). Nothing material 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% for the single 'domain' parameter, so the schema already defines it as a domain including extension. The description reinforces that lookups are for one specific Atom listing (implying exact-name precision rather than a search), which adds modest value 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?

States a specific verb and resource ('Get the full detail record for ONE specific Atom domain listing') and explicitly scopes it as the deep-dive step after search_brandable_domains or generate_domain_names. It also names check_domain_availability as the distinct path for non-Atom listings, so an agent can separate it from siblings without opening any schema.

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 trigger conditions (user picks a name or asks for more about a particular domain) and an explicit negative/fallback path: if not an Atom listing, returns not_found and the agent should use check_domain_availability. Both when-to-use and when-not-to-use are covered.

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 declare readOnlyHint=true and destructiveHint=false, and the description stays consistent while adding substance: 'This tool charges nothing by itself', the domain is only purchased once polling reports 'completed', and the x402_url contract (POST, 402 Payment Required, signed retry) is spelled out. It also discloses that each status call blocks ~10s server-side and that stop_polling/user_message must be surfaced verbatim — details unavailable from annotations.

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

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

The core selection criteria and the x402_url vs checkout_url distinction are front-loaded, and the operational sequence and error branches follow in a usable order. It is lengthy, but nearly every clause is functional; a small amount of the polling prose could be tightened without loss.

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?

Although an output schema exists, the description still characterizes both returned URLs by audience (agent vs human) and covers the full lifecycle: price must be presented verbatim, nothing is charged here, purchase completes only on 'completed' status, and both registrant_contact_required and billing_country_required failures have recovery paths. Nothing an agent needs to call this 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?

With a single parameter at 100% schema coverage, the schema already carries the syntax ('including extension'). The description still adds a real semantic constraint the schema cannot express: the domain must already be listed on the marketplace, otherwise a different tool applies.

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

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

The description names a specific verb and resource (get a Coinbase/USDC checkout link) plus the exact scope constraint: an ALREADY-LISTED Atom marketplace domain. It explicitly separates itself from the sibling that handles the other case (get_domain_register_coinbase_pay_link for a fresh, unlisted domain), so an agent can route without opening either schema.

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

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

It states the selecting conditions directly — 'when the user wants to pay with crypto/USDC, or when an x402-capable wallet is available in this session' — and names the alternative for the unlisted case. It goes further with the required follow-up (poll get_coinbase_payment_status with the returned payment_code) and the two error-code branches with their remediation steps.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructive=false), yet the description adds substantial context: the URL serves a real HTTP 402 challenge, it must be handed to the agent's pay tool rather than fetched/decoded, the price must never be recomputed, and it documents the recoverable 'registrant_contact_required' error with an exact remediation sequence. That is meaningful behavioral depth beyond structured fields, and it does not contradict any annotation.

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?

It is front-loaded with purpose, then usage, then priority, then return handling, then error recovery — a logical ordering where each block earns its place. It is a little long and the link-cli-availability condition is stated twice (once in the first paragraph, once in PAYMENT PRIORITY), which is mild redundancy but not bloat.

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 payment-flow tool with one parameter and an output schema, the description covers everything an agent needs: eligibility, ordering against alternatives, how to handle the returned pay_url, and a concrete recovery path for the expected contact-required error. No gaps an agent would need to guess at.

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% on the single 'domain' parameter, so the baseline is 3, but the description adds real semantics by stressing that the domain must be an already-listed/curated Atom marketplace listing, not an arbitrary domain. That constrains valid input beyond the schema's plain 'the listed domain to purchase' text.

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+resource: 'Get a real, payable Machine Payment Protocol (MPP) URL to purchase an ALREADY-LISTED Atom marketplace domain via Stripe SPT.' It also explicitly distinguishes itself from the nearest siblings (register_domain, get_domain_register_pay_link, get_checkout_link) so an agent can select it without opening any schema.

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

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

It gives explicit when-to-use constraints (only when an MPP-native agent like link-cli is present, only for curated Atom listings), an explicit when-not (fresh unlisted domain → get_domain_register_pay_link), and a full priority ladder (register_domain priority 1 → this priority 2 → get_checkout_link priority 3). Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing downstream consequences: Atom provisions an account for the buyer, the domain lands in the buyer's account, and an account-claim email is sent after payment. It also gives two operational constraints the annotations cannot convey — never estimate or recompute the price, and hand the pay_url (which serves a real HTTP 402 challenge) to the pay tool rather than fetching it.

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?

Front-loaded with the core action and the disambiguating sibling reference, and every sentence carries a decision rule or a hazard warning. The first paragraph is dense (scope, sibling, provisioning behavior, preconditions all in one block), which costs a little readability but no sentence is filler.

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

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

An output schema exists, so the description need not describe the returned pay_url/price — and it correctly focuses on how to handle them instead. Combined with annotations, 10 documented parameters, and explicit routing against three sibling tools, an agent has everything needed to invoke this 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 baseline is 3; the description adds genuine meaning beyond the schema by insisting buyer_email must be the real end buyer rather than the agent platform, and by framing the name/phone/address fields as registrant (WHOIS) contact data. It does not add format or validation detail beyond what the per-property descriptions already carry, so it stops short of a 5.

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 ('Get a real, payable Machine Payment Protocol (MPP) URL to purchase an ALREADY-LISTED Atom marketplace domain') and immediately bounds scope ('WITHOUT an Atom OAuth connection'). It also names the sibling it is not (get_domain_register_pay_link_guest for unlisted domains), so an agent can pick correctly from the sibling list 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?

Gives explicit conjunctive preconditions: use ONLY when (a) there is no authenticated Atom connection (otherwise prefer get_domain_purchase_pay_link) and (b) MPP-native payment tools are available. That is when-to-use, when-not-to-use, and the named alternative in one place.

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 cover safety (readOnlyHint=true, destructiveHint=false), and the description reinforces rather than contradicts them by stating 'This tool charges nothing by itself' and explaining the two returned URLs and the 402/POST signed-retry flow. It goes well beyond annotations by disclosing side-effect timing (domain only registered after status 'completed'), refund behavior, and polling semantics.

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

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

Purpose and the sibling disambiguation are front-loaded in the first sentence, and every subsequent sentence carries operational information (pricing rule, polling, error recovery). It is long, but the length is justified by the multi-step payment workflow rather than padding; a slightly tighter error-handling section would push this to a 5.

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-param tool with full schema coverage, an output schema, and annotations, this is complete: it covers what the tool returns (two URLs), what it does not do (no charge), how to complete the flow, and how to recover from the two documented error states. Nothing essential to correct invocation is missing.

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

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

Only one parameter with 100% schema coverage, so the schema already does the work (baseline 3). The description adds value by constraining the domain to a fresh, available, non-listing domain and noting term_years is derived server-side from the TLD — meaning the agent needn't supply it.

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

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

States a specific verb+resource (get a Coinbase checkout link paid in USDC to register a fresh domain) and immediately disambiguates from the closest sibling by naming get_domain_purchase_coinbase_pay_link for curated listings. The 'FRESH domain, not a marketplace listing' distinction is exactly the kind of boundary an agent needs before choosing a tool.

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 when to use it ('when the user wants to pay with crypto/USDC, or when an x402-capable wallet is available') and names the alternative for the other case. It also provides conditional branches for error codes (registrant_contact_required, billing_country_required) and points to the required follow-up tool (get_coinbase_payment_status).

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/destructiveHint=false and openWorldHint=false; the description goes well beyond by disclosing what is actually returned (a pay_url serving a real HTTP 402 challenge), that the value must be handed off verbatim and never recomputed, that term_years is server-derived, and a specific recoverable error ('registrant_contact_required') with a retry recipe. Minor gap: it doesn't state whether the generated link expires or is idempotent per domain.

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 key distinction and the tool's identity are front-loaded in the first sentence, and the priority/error guidance follows logically. It is dense with parentheticals and ALL-CAPS emphasis, which costs some readability against what is a fairly complex tool, but nearly every sentence carries distinct operational information.

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 payment-link generator embedded in a multi-step flow with an output schema present, the description covers the return value semantics, the handoff contract, the priority against sibling flows, and the registrant-contact recovery path. An agent has everything needed to call it and act on the result 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?

Only one parameter and schema description coverage is 100%, so the schema already defines `domain`; the description adds little beyond it (it clarifies that term_years is not a caller input, which is useful but concerns a non-existent parameter). Baseline 3 for a fully documented single-parameter tool.

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 (get a payable MPP pay URL to register a fresh domain) and explicitly carves out the sibling it is not for: 'an available domain that is NOT a curated Atom marketplace listing — for that, use get_domain_purchase_pay_link instead'. An agent can distinguish it from the other pay-link siblings without opening a schema.

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 conditions ('ONLY when an MPP-native agent's tools are available in this session'), an explicit priority ordering against register_domain_spt's in-band flow, and what to do when priority 1 is unavailable. It also names the non-alternative case ('NOT with register_domain_spt's own payment flow') and states there is no checkout-link 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?

Annotations only declare readOnlyHint/openWorldHint/destructiveHint=false; the description goes well beyond them by disclosing the downstream consequences (Atom provisions a buyer account, the domain lands in the buyer's account, an account-claim email is sent post-payment) and operational constraints (the pay_url serves a real HTTP 402 challenge, hand it directly to the pay tool, never recompute the price). These are exactly the side effects an agent cannot infer from a 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?

Front-loaded with the core action and the sibling exclusions, then transitions to operational cautions; every sentence carries content. The first sentence is long with nested parentheticals and a mid-sentence alternative reference, which slightly hurts scannability for a tool an agent must select 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?

With an output schema present, the description needn't document return values, and it instead covers the pieces an agent genuinely needs: prerequisites, account ownership flow, post-payment notification behavior, and how to hand off the pay URL. Nothing required to invoke 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 ten fields including the buyer_email ownership semantics and the ISO country format. The description reinforces that the buyer email must be the real end buyer rather than the agent platform, but that meaning is already present in the buyer_email schema description, so added value is marginal over the baseline.

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

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

States a specific verb and resource (get a payable MPP pay link to register a fresh domain) and immediately scopes it against two siblings: it excludes curated Atom marketplace listings (directing to get_domain_purchase_pay_link_guest) and excludes OAuth-authenticated sessions (directing to get_domain_register_pay_link). An agent can pick this tool out of a 21-tool sibling list without opening any schema.

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 gating conditions: use ONLY when (a) the session has no authenticated Atom connection and (b) an MPP-native agent's payment tools are available, with the preferred alternative named for each failure case. Both the positive trigger and the exclusions are spelled out rather than implied.

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 flag destructiveHint=true and openWorldHint=true, but the description adds far more: real money is spent, the 'domains:register' scope is required, a mandatory quote-before-charge flow, idempotency_key reuse to prevent double-charging, and specific error contracts (insufficient_funds, card_payment_failed, registrant_contact_required) with the instruction not to silently retry on another rail.

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?

Front-loaded with the critical constraint (real money, correct tool), then structured as a numbered mandatory flow with rules last. Nearly every sentence is load-bearing, though the literal price-breakdown example and the enumerated error catalog make it longer than strictly necessary.

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 destructive, money-spending tool with an output schema already covering return values, the description still covers preconditions, the confirmation UX contract, payment method selection, and every documented failure path including the registrant_contact_required detour. Nothing an agent needs to call 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 coverage is 100%, so baseline would be 3, but the description adds flow-level meaning the schema cannot: payment_method is meaningless at the quote stage and mandatory at confirm, and one client-generated idempotency_key must be reused across quote, confirm, and retries. That is genuine semantics beyond the 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?

States a specific verb+resource ('Purchase an ALREADY-LISTED Atom marketplace domain') and immediately draws the boundary against the nearest sibling, register_domain, including the exact error a fresh domain would yield. An agent can distinguish this from register_domain without opening either schema.

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 entry conditions (check_domain_availability reported 'premium' or 'taken', or get_domain_details confirmed a listing), explicit exclusions ('If the domain is instead fresh/never-listed ... use register_domain instead — never this tool'), and names the alternative tool twice. This is the when/when-not/alternative trifecta.

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 say destructive/openWorld; the description adds what actually matters: it spends real money, requires the 'domains:register' scope, quotes before charging, server-derives term_years, and enumerates failure modes (is_marketplace_listing, registrant_contact_required, insufficient_funds with required/available/top_up_url, card_payment_failed with 3DS not completable here). This is materially beyond the annotation set.

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?

Front-loaded with the highest-stakes constraint (real money, scope, wrong-sibling guard), then a numbered flow, then an error playbook. Dense but nearly every sentence is actionable; the error catalog is long and could be tightened slightly without losing meaning.

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?

A money-moving mutation tool with an output schema; the description covers the quote/commit contract, idempotency, payment rails, fallback contact creation, and equally important, the recovery path for each named error. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds procedural meaning the schema cannot — payment_method must be stated to the user and never guessed, the same idempotency_key must span both calls and retries, and term_years must never be passed. That is real added semantics, though some of it repeats schema text.

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 ('Register a FRESH domain') and immediately scopes it against the sibling: not a marketplace listing, and purchase_domain is the correct tool for premium/taken. An agent can route correctly without opening either schema.

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 gating ('ONLY when check_domain_availability reported status available'), an explicit exclusion with the named alternative and the exact rejection error, plus a numbered mandatory two-step flow. Nothing about when/when-not is left to inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds critical context beyond them: it spends real money, requires the 'domains:register' scope, mandates a three-step payment flow, captures payment before registration, attempts a refund on post-payment failure, and explains the 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 front-loads purpose and exclusions, then structures the mandatory flow as a numbered sequence, which is appropriate for a high-stakes payment tool. There is some repetition around idempotency keys and fallbacks, but the length is largely justified by the complexity.

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

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

Given the destructive, open-world, multi-step payment behavior, the description covers purpose, workflow, payment priority, fallback routing, idempotency, refund behavior, and error recovery. With an output schema present, it does not need to explain return values, and nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful constraints beyond the schema, notably that term_years and price are server-authoritative and must never be passed, and that the same idempotency_key must be reused across the three calls, though some of this repeats schema wording.

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: registering a FRESH domain via Stripe SPT. It explicitly distinguishes this from register_domain for already-listed marketplace domains and from get_checkout_link, so an agent can select the correct 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?

It gives explicit when-to-use conditions: available domain not a curated listing, user with no Atom balance, and payment via Stripe SPT. It also names alternatives and fallbacks, including register_domain, get_domain_register_pay_link, and get_checkout_link limitations.

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, destructiveHint=false, and openWorldHint=false. The description adds substantive context beyond annotations: it queries the actual USPTO register, returns preliminary exact/close matches with status and owner, and clarifies that results are a screen rather than legal advice or a clearance opinion.

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 action and then immediately addresses usage, alternatives, return behavior, and legal limitations. Despite being longer than average, every sentence carries useful selection or interpretation guidance.

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, full schema coverage, annotations, and output schema, the description provides everything needed: what it queries, when to use it, what it returns, and its limitations. No material gap remains for correct tool selection or 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 description coverage is 100%, so the schema already documents all five parameters, including enum meanings and defaults. The description reinforces that the tool screens a brand or domain name and returns exact/close matches, but it does not add parameter-level semantics 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?

The description states a specific verb and resource: run a preliminary trademark conflict screen against public USPTO records. It also clearly distinguishes the tool from web search, memory, and legal clearance opinions, so an agent can identify exactly what the tool is for.

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 says to ALWAYS use this tool for any trademark question about a name, including follow-ups, and explicitly says NOT to answer from web search or memory. This is strong when-to-use and when-not-to-use guidance with named 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 flag readOnly/openWorld/destructive, and the description still adds real behavioral context: no login required, every returned name is verified buyable and actively for sale, and imaginary names are usually taken. It also pre-empts a common confusion by clarifying these are Atom marketplace listings rather than fresh registrations.

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 capability and the 'always call first' directive are front-loaded, and the return-value and next-step guidance follows logically. It runs long, with some reinforcement (the buyable/for-sale point is made twice), but nearly every clause is actionable rather than filler.

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

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

With an output schema present, the description needn't enumerate return values, yet it usefully summarizes results[] fields and the presentation format. Annotations cover the safety profile and the schema covers all params, so the only remaining gap is silent treatment of pagination/capped limits and style-enum semantics, which is minor.

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

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

Schema description coverage is 100% and all six parameters (limit, style, concept, industry, max_price, extensions) are documented inline, so the schema carries the semantic load. The description only mentions 'by concept, industry, or style' at a high level and adds no new filter syntax, enum meanings, or limit/pricing caveats 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 names a specific verb and resource ('search ... marketplace of premium, brandable domains') and scopes it to concept, industry, or style. It also explicitly positions itself against naming siblings by declaring itself 'THE primary tool for ANY naming request,' so an agent can pick it without opening other 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?

It gives a strong, explicit trigger ('ALWAYS call this before suggesting names ... even when the user asks only to suggest a name') and names follow-on tools (get_domain_details, appraise_domain, purchase_domain) with their roles. What it does not do is say when a sibling like brainstorm_names or generate_domain_names would be preferred instead, so the alternative-routing is incomplete at the same-task level.

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