audit.domains - Domain Valuation

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further by explaining exactly what is destroyed ('confirm releases the held payment to the seller and refund returns it to the buyer, and neither can be undone') and adds a security note that the token is sent to the market as a bearer token and must never be repeated. This is above the annotation baseline.

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

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

Three economical sentences, front-loaded with the action set and role split, then destructive consequences, then the sibling alternative and token safety. Every clause carries distinct information with no 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 return values need not be described. The description covers the destructive/irreversible behavior, the confirm precondition, the correct sibling for read-only queries, and token safety — everything an agent needs to invoke this mutation tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the role-gated enum and the bearer-token warning. The description largely reiterates those semantics (role mapping, irreversibility, token handling) rather than adding new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (take one action), the resource (an order), and enumerates the exact actions available per role ('check, confirm or dispute as the buyer, check or refund as the seller'). It explicitly names the sibling it is not (get_order_status), 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 explicit when-to-use and when-not-to-use guidance: 'Use get_order_status instead to read state and next actions' and a hard precondition 'Call confirm only after the buyer has said the domain arrived.' Role-based action eligibility is also stated, leaving little 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 annotations by disclosing the full state machine (awaiting_payment, delivered, refunded), the polling interval, and the idempotent behavior that later calls return the same stored appraisal. This tells the agent exactly what outcomes to expect and how to react to each, which the readOnly/idempotent hints alone cannot 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?

Three tight sentences, front-loaded with the action and payment gate, then the polling and terminal states. Every sentence carries distinct information with no 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 output schema exists but the description still pre-empts the key return states, and it covers the retry/idempotency behavior an agent needs for correct polling. Nothing material for calling 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% and both parameters are documented as coming from buy_appraisal, so the schema already carries the semantics. The description adds no syntax or format detail beyond that, making 3 the correct 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 (check/return) and resource (a buy_appraisal order's appraisal), explicitly tying it to the buy_appraisal sibling that produced the orderId/orderToken. An agent can distinguish this collector from appraise_domain or quote_domain_purchase 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?

Gives concrete invocation context: poll after buy_appraisal, retry after about 10 seconds while awaiting_payment, and later calls are safe repeats. It does not name an alternative tool or an explicit when-not-to-use, so it stops short of a 5.

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

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

The annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds state-specific behavior the annotations cannot convey: a pending receipt yields retryAfterSeconds with a recovery delay, and a refunded receipt means service credits return to the account. These outcomes materially change what the caller does next.

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?

Four dense sentences, front-loaded with the operation's identity before the constraints and recovery path. Every sentence carries distinct information (identity, exclusions, pending behavior, refund behavior) with no 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 return values need not be spelled out, and the description still covers the essential non-obvious states (pending, refunded) and the recovery route. For a single-parameter, idempotent read tool this is 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% and the operationId schema description already documents persistence and reuse, so the baseline is 3. The description adds marginal value by tying operationId to the recovery action ('using the same authenticated agent connection and operationId'), contextualizing it within the retry flow rather than merely restating 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 ('Read the original purchase-1 receipt') and immediately scopes it by naming the exact identifier used ('operationId'). It actively distinguishes itself from the sibling purchase_appraisal by declaring 'cannot create a purchase,' so an agent can separate reading from buying 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 gives explicit negative guidance ('does not start or resume delivery and cannot create a purchase') and a concrete alternative path for the pending case ('recover with purchase_appraisal using the SAME operationId and original arguments'). Both when-not-to-use and when-to-use-an-alternative are covered, 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?

Beyond the readOnly/idempotent annotations, it discloses genuinely useful traits: determinism ('same name, same figure'), that confidence is an internal 0-100 score rather than a probability, the four possible response modes (cached, catalog, stored, none), and credit-consumption rules. The credit rules are stated repeatedly and are hard to parse, which dilutes but does not negate the added behavioral value.

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 credit/cache rules are stated at least twice nearly verbatim ('Cached answers, keyless catalog figures and public stored intervals use no API credits...' then 'MCP cache hits use no API credits...'), bloating the description with redundancy. The core purpose is front-loaded, but the back half is a tangled wall of authorization, billing and URL detail that obscures the actionable facts.

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 exists, return values need not be spelled out, yet the description still usefully enumerates the response variants including the empty-result case ('no figure but a browser report link, 3 nearest published names... and a next step'). The main omission is that the auth/credit conditions are so muddled that an agent may not reliably know when a call costs credits.

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 a single parameter with 100% schema description coverage, and the schema already documents the domain format including URL acceptance. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The opening states a specific verb and resource: 'Estimate the fair value of one domain name with its low/high interval.' It also distinguishes itself from siblings by routing sales browsing to search_recorded_sales and find_comparable_sales, so an agent can tell what this tool is and is not for. The core purpose is clear despite the surrounding clutter.

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 two explicit alternatives with their purposes ('Use search_recorded_sales to browse sales and find_comparable_sales for just the five nearest sales') and clarifies that a paid purchase is 'a separate paid purchase, not a charge for this MCP lookup,' distinguishing it from purchase_appraisal. No explicit when-not-to-use condition is given, but the routing guidance is concrete.

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, it discloses that the tool is deterministic, offline, calls no model, and runs no appraisal, and it describes the interpretation.source field and the 'words not used' feedback. That is real behavioral context the annotations do not carry, though return format is partly covered by the output schema.

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 routing outcome; every sentence carries information (routing, alternatives, determinism, appraisal note). It is dense but not padded, though a single long paragraph makes it slightly harder to scan.

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?

Covers what the tool does, when to use alternatives, the deterministic/offline nature, and the returned interpretation metadata; with an output schema present, no further return-value detail is required. 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 there is only one parameter, so the schema already documents 'question' with the 300-char limit. The description reinforces the expected sentence form with an example but adds no syntax beyond what the schema provides, 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?

States a specific verb and resource ('Answer one plain-English sentence about the domain market') and immediately distinguishes itself by naming the two sibling tools it routes to. An agent can tell it apart from search_domain_listings and search_recorded_sales 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?

Explicitly says to use search_domain_listings or search_recorded_sales instead 'when you already have exact filters,' giving both the alternative and the selecting condition. It also maps question types to outcomes, so the agent knows what input shape to send.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: nothing is stored or sent, the caller must upload the returned HTML, and there is a 500-domain ceiling. It stops short of describing the returned location format, but the output schema likely covers that.

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 core action, then adds return/upload behavior, the limit, and the alternative in tight succession. Every sentence carries distinct information with no redundancy or 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?

For a generation tool with an output schema, the description covers the essential behavioral facts an agent needs: no server-side persistence, caller-uploads responsibility, the 500-domain bound, and the sibling alternative. Nothing material to correct invocation appears missing.

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

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

Schema coverage is 100%, so the schema already documents email, domains, and note with types and limits. The description reinforces the shared-email concept and the 500-domain cap but adds no syntax or format detail beyond what the schema provides. 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 (generate) and resource (one index.html for-sale page for every parked domain in a portfolio), including the shared offer-email behavior. It explicitly distinguishes itself from the sibling set_listing_terms, so an agent can select it 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?

Names an alternative and the condition that selects it: 'Use set_listing_terms instead to set terms on a domain already listed on this market.' This is clear routing context, though it does not enumerate other conditions (e.g., single-domain scenarios or overlap with read_for_sale_page).

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 this as non-read-only, open-world and non-idempotent; the description goes well beyond that by disclosing the $5 card price vs. the lower stored-appraisal price, that checkoutUrl is a no-sign-in Square page, that orderToken is shown once and is the only proof of purchase, and that undeliverable paid orders are refunded in full.

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 action, price and trigger, then flows into outputs, next steps and the token warning. It is dense and long, but nearly every sentence carries operational weight (pricing, workflow, token handling, refund), so little is wasted.

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 usefully names the returned fields (checkoutUrl, orderId, orderToken) and the required next tool call, plus the refund guarantee. An agent has everything needed to invoke it and handle 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?

There is a single parameter with 100% schema description coverage ('The domain to appraise, e.g. brightcargo.com'), so the schema already carries the parameter semantics. The description adds no extra domain formatting or validation detail beyond what the schema provides, making the baseline 3 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, resource, scope and price: 'Buy a fresh appraisal of one domain, computed on this server, for $5 by card.' This clearly distinguishes it from appraise_domain (free/opened-in-browser appraisal) and appraisal_order_status (order polling).

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

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

Gives an explicit trigger condition ('when appraise_domain answered notAppraised and the user wants the figure returned to you rather than opened in their browser') and names the alternative pricing path for operator-funded agent accounts. It also states the required follow-up call (appraisal_order_status with orderId and orderToken).

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

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

Annotations already declare readOnly/idempotent/openWorld, yet the description adds substantial context: free, no key, one or two DNS/RDAP requests per uncached name, no valuation performed, and the caveat that a registry can still reserve or premium-price an apparently available name. The status taxonomy is explained rather than assumed.

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?

Dense but front-loaded: capability, then the alternativesFor expansion, then the usage directive, then routing, then status semantics. Every clause carries information, though the single long paragraph could be slightly tighter.

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 need not be spelled out, yet the description still defines the four status values and the 5-name limit for dates. Combined with the request/auth behavior notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by enumerating the nine suffixes alternativesFor covers (.com through .xyz) and noting registration/expiry dates are returned only for lists of five or fewer, which the schema does not state.

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

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

Specific verb (check) plus resource (domain registration status), with explicit scope limits (up to 25 names, DNS + RDAP sources). It cleanly distinguishes itself from inspect_domain and appraise_domain by naming both siblings and what they do instead.

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?

States when to use ('Use it before suggesting any name as available: an answer from memory is often wrong') and names two concrete alternatives with their differing purposes. The routing guidance is 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), it discloses cost and access ('free, no key'), the per-name request load ('one or two DNS and RDAP requests per uncached name'), the data source and freshness caveat ('Expiry comes from each registry's RDAP record and a registrar renewal can take a day to show'), and the scope exclusion ('runs no valuation'). That is substantial behavioral context the structured fields do not carry.

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 limit, followed by usage routing and operational caveats; every sentence carries information an agent would otherwise have to guess. It is dense and slightly run-on, but there is no filler to cut.

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 need not explain return shape, and it covers everything else: input limits, flagging rules, freshness caveats, cost, and alternative routing. An agent has all it needs to select and call 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the default window (60 days) is restated with the flag categories it drives (expiring soon, already expired, no longer registered), and the 'up to 25' ceiling is tied to portfolio scale. It stops short of describing the domains input format beyond what the schema already says.

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 concrete verb and resource ('Look up the registry expiry date and registrar of up to 25 domain names ... and list them soonest first') plus the flagging behavior, which is specific enough to distinguish it from every sibling. An agent can tell this is a portfolio-expiry listing tool 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?

Explicitly states the trigger ('when someone asks which domains to renew or what is expiring') and names two alternatives with the conditions that select them: check_domain_availability for names not yet owned, appraise_domain for renewal-worthiness decisions. 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context an agent cannot get elsewhere: deterministic results, credit consumption rules (cache hits free, catalog fallbacks free without a key, one credit on an authorized keyed cache miss), rate limits, server budget, key-scope requirements, and error behavior on rejected keyed runs. This is unusually rich disclosure for a read-only tool.

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

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

Front-loaded with the core action and the sibling alternative before the operational detail, and every sentence carries information (limits, cost, fallbacks, errors). It is dense and long, but the pricing and key-scope sentences earn their place because they affect whether an agent should call it at all.

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, return values need not be explained, and the description covers everything else an agent needs: input cap, sibling routing, determinism, authentication/scoping, credit cost, cache behavior, handoff behavior, and failure modes. Nothing material is missing for a single-parameter read 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%, so the baseline is 3, but the description reconciles a real discrepancy: the schema allows 1–16 items while the description clarifies that only up to 10 are appraised and 11–16 yield a handoffUrl only. That interpretation of the cap boundary adds meaning beyond the raw maxItems constraint.

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 ('Appraise up to 10 domain names and rank them by estimated fair value') with a precise output concept (overlapping intervals flagged as non-separable). It explicitly names the sibling it is not — run_bracket for head-to-head tournaments — so an agent can route between them 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 when-to-use-this vs when-to-use-the-alternative: this tool for ranked fair values of up to 10 names, run_bracket for a single champion from a tournament of up to 8. It also names the boundary condition (>10 names or budget cutoff) and the fallback behavior, 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: cache hits consume no credits, the keyless catalog fallback may be empty and links to a browser report, a default-profile cache miss with an authorized Bearer key can burn one API credit, and rejected keyed runs can error. This is the credit/auth/error profile an agent cannot infer from annotations.

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

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

Front-loaded with the return contract, then alternatives, then cost/auth caveats. Dense and nearly waste-free, though the credit/cache sentence chains several conditions ('subject to allowance, rate limits and server budget') into one long clause that is harder to parse than the rest.

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?

Complete for this tool: return fields are enumerated (and an output schema exists anyway), the sibling routing is explicit, and the cost, auth-header, fallback and error behaviors are all covered. Nothing an agent needs to decide or 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?

There is a single parameter with 100% schema description coverage ('The one domain name to find comparable recorded sales for, such as example.com'), so the schema already does the heavy lifting. The description only indirectly touches the parameter, noting catalog names can still incur a credit on a miss.

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 ('Return up to five comparable recorded domain sales') and immediately disambiguates scope: 'These are transactions from a curated corpus, not modelled figures.' It explicitly contrasts itself with appraise_domain and search_recorded_sales, so an agent can tell it apart 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?

Names the two adjacent tools and the condition that selects each: 'Use appraise_domain for a fair value and search_recorded_sales to browse sales.' It also states the preconditions for a fresh keyed run (authorized write-scope paid key, allowance, budget) versus a free cache hit, which is exactly the routing information 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?

Goes well beyond the annotations by disclosing that despite being a 'check', each call runs a rate-limited domain move and may release payment to the seller, and clarifies that this is the order proceeding rather than an extra charge. That is exactly the kind of non-obvious side-effect context the readOnlyHint=false annotation cannot 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?

Four tight sentences, front-loaded with what is returned and immediately followed by the critical side-effect warning and the sibling routing. No 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 return values need no explanation; the description instead covers side effects, polling cadence, and the alternative tool. Nothing an agent needs to invoke 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% and both parameters are documented there (token as a secret, orderId from checkout). The description adds only the ownership framing of the token (buyer/seller holder), which mildly enriches but does not replace schema content — baseline 3 applies.

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

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

States a specific verb and resource: returns an order's state and the next actions available to the token holder. It explicitly distinguishes itself from act_on_order ('this tool only reports state'), so an agent can route correctly 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 boundaries: use act_on_order instead for confirm, dispute or refund, and poll no faster than pollAfterSeconds. Both the alternative and the operating constraint are named outright.

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, idempotentHint=true and destructiveHint=false, so 'read-only and changes nothing' is largely redundant. What the description adds beyond the structured fields is the authorization requirement ('Needs the manage token') and the scope of the view (seller-side vs public), which the annotations do not convey. It does not discuss rate limits or error behaviour, so it stops short of a 5.

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

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

Three tight sentences: what it returns first, then the sibling routing, then the safety/mutability note. No sentence is filler, and the most decision-relevant content (scope and returned fields) is front-loaded.

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

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

For a two-parameter read tool with an output schema, annotations and full schema coverage, the description supplies the remaining unknowns: auth requirement, seller-side vs public scope, mutability, and sibling alternatives. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema (including the bearer-token secrecy note), so the description adds no parameter syntax or format detail beyond it. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (Read) and resource (a seller's own view of one listing), then enumerates the concrete contents returned: terms, payment DNS state, proceeds, checklist, orders. It also explicitly names what it is not (the public buyer-facing quote, the term-setting tool), so an agent can distinguish it from quote_domain_purchase and set_listing_terms 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?

Names two alternatives and the condition that selects each: use quote_domain_purchase for the public buyer-facing quote, set_listing_terms to change price or floor. It also states the prerequisite (needs the manage token), which is precisely the routing information 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds substantial context beyond them: the exact auth header format (Bearer ad_agent_<token>), the fact that no arguments/credentials are supplied, the response contents, and the crucial caveat that this is a non-reserving advisory snapshot while server-side admission stays authoritative. Only the lack of any pagination/size or rate-limit note keeps it from a 5.

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?

Five sentences, front-loaded with the core action and scope, then auth, then response, then capability limits, then a caveat. Every sentence carries information, though the closing sentence about receipt recovery is somewhat tangential to selecting/invoking the tool.

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

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

With an output schema present, the description needn't enumerate return fields, yet it still summarizes them (scopes, expiry, remaining attempts, credit capacity) and discloses auth requirements, side-effect boundaries, and the authoritative-server caveat. Nothing needed to call this zero-argument read tool 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?

There are zero parameters, so the baseline is 4; the description reinforces this by instructing the caller to 'supply no arguments or credentials', matching the empty schema with additionalProperties=false. No further parameter meaning is possible here.

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 (read/inspect), a specific resource (spending grants), and a precise scope ('belonging to the authenticated agent connection'). This is unambiguous and easily distinguished from every sibling, none of which deal with agent grants.

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

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

The opening sentence gives clear usage context, and the explicit negative list ('cannot create a grant, fund an account, reserve credits, authorize a purchase or raise a limit') effectively tells the agent when NOT to reach for this tool. It never names a specific alternative tool to use instead, so it falls short of a 5.

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

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

Annotation already covers read-only/free/idempotent, yet the description adds real behavioral context: unknown-source handling ('reported as unknown, never as absent'), one request to a cached evidence lookup, no valuation performed, and no key required. That is exactly the extra layer 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 is front-loaded and the alternative-routing sentence comes before the behavioral caveat, which is good ordering. The opening sentence is a long enumerated run-on that would read better as a list, but every clause carries information an agent needs.

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

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

An output schema exists so return values need no explanation. With the data inventory, sibling routing, cost/rate profile, and failure-mode semantics all present, 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?

Schema coverage is 100% and the single 'domain' parameter already documents format and URL-paste acceptance, so the schema carries the burden. The description only alludes to 'one domain name' and adds no format, normalization, or edge-case detail beyond it; baseline 3 applies.

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

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

States a specific verb (gather the public record) and resource (one domain name) and enumerates exactly what comes back: registration/expiry/registrar, registry status, website/email presence, archive history, cert history, Wikipedia/trademark flag, catalog figure. It explicitly separates itself from four named siblings, 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 explicit routing: use check_domain_availability to screen many names, appraise_domain for value, read_for_sale_dns for sale status, with the implicit condition (single-domain deep inspection) stated in the opening clause. 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?

Annotations cover the safety profile (readOnly, idempotent, closed-world), so the description's added value is the provenance detail: prices come from billing sources at deploy time, never from memory, and no valuation is computed. It also imposes a citation obligation (quote citeAs.text). It does not describe latency or pagination, but it meaningfully enriches the annotation baseline.

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 scoping, and every sentence carries information. The opening sentence is dense with stacked clauses, which costs it a little readability, but nothing is wasted.

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 need not restate return fields, and it covers what the schema cannot: pricing provenance, the no-valuation guarantee, equivalence to the REST GET endpoint, and the citation requirement. Nothing an agent needs to call and report this tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The text correctly implies a no-argument call by describing a fixed, server-defined menu.

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 ('Return the full menu of services audit.domains offers callers') and enumerates the payload contents: endpoint, providing tool, price/free, appraisal behavior, rate-limit and budget rules. No sibling tool lists offers or pricing, so the agent can route here unambiguously when pricing is the question.

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 trigger conditions are given: 'Use it when a user asks what can be bought, what something costs, or how to go beyond the free answers.' This is clear situational guidance, though it names no exclusions or competing sibling to avoid calling instead.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, but the description goes further and clarifies the exact mutation boundary: it writes nothing, never publishes and takes no payment, and the seller presses publish after signing in. That resolves the ambiguity of a tool that 'prepares' a listing but does not create one, which annotations alone could not 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?

Purpose, output, sibling routing and the read-only/prerequisite caveats are front-loaded across four tight sentences with no filler. It is slightly dense and the TXT-record sentence runs long, but every sentence contributes information an agent needs.

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

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

An output schema exists so return-value detail is not required, yet the description still previews the sell-page link, payment-record status and post-fee payout. Combined with the sibling pointer and the signing-in prerequisite, an agent has everything needed to call this correctly for a multi-name, non-publishing listing prep.

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 nested parameter documents domain format and priceCents bounds in detail, so the schema carries the load. The description only restates the 1-to-20 cap and the notion of asking prices, adding the TXT-record precondition rather than extra parameter semantics.

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

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

States a specific verb and resource (check up to 20 domains/prices for listing on this market) plus the concrete output (one sell-page link plus payment-record status and estimated payout). It explicitly contrasts itself with the sibling set_listing_terms, so an agent can distinguish the tools 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?

Names the alternative tool and the condition that selects it: use set_listing_terms to change a name already listed, implying this tool is for preparing a new bulk listing. It also states a prerequisite (each name needs an _odvs-pay TXT record naming the seller's Square account), which is exactly the kind of gating condition an agent needs before invoking.

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 it discloses substantial behavior: bearer-token auth via header with credentials forbidden in arguments, one purchase per MCP request, receipt retention, same-identifier retry on lost replies, and the explicit statement that configuration does not guarantee live readiness and the route response is authoritative. This is exactly the mutation/auth/idempotency context an agent needs.

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 credentials lead the description, and the seven sentences are dense with operational constraints rather than filler. It is on the long side, but each sentence carries a distinct rule (retry, budget, limits) that would otherwise be lost.

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 need not describe return values, and it still covers authentication, idempotent retry semantics, enforcement conditions, and explicit non-capabilities. An agent has everything required to invoke this purchase safely.

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 four parameters are already fully documented, and the description largely repeats them ('Supply an explicit operationId, grantId, domain and maxSpendUsd'). Its only added nuance is the reminder that retries reuse the same identifier and that the spend ceiling will not be inferred or auto-raised, which the schema already conveys.

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: buying the current_appraisal service against a prepaid account and a funded grant, with the required identifiers named. However, it never distinguishes itself from the near-identical sibling buy_appraisal, so an agent cannot tell from the text alone which of the two to select.

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 clear context of use (prepaid account plus an existing operator grant) and explicit exclusions ('cannot fund the account, create grants or raise a limit'). It does not, however, name sibling alternatives such as buy_appraisal or inspect_agent_grants, so the routing decision remains partly inferential.

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 grant readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered, yet the description still adds real behavioral context: it never reveals the seller's floor, never evaluates an offer, and payment is a held card authorization on the seller's own account with the site brokering no sale. 'Read-only' is a mild restatement of readOnlyHint, keeping it just short of 5.

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 payoff (price/terms/link) and then the routing and constraints, with no filler sentences. Slightly diluted by the redundant 'Read-only' clause that merely echoes the readOnlyHint annotation.

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 an output schema, the description covers everything an agent needs: what comes back, who is eligible, the payment mechanism, and which sibling to pick when the precondition fails. Return-value structure is correctly left to the output schema.

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 coverage is 100% – the schema already documents 'domain' with an example. The description adds no format, TLD, or eligibility syntax beyond what the schema states, so the baseline 3 for full schema coverage 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?

Specific verb (Quote/Get) plus resource (one listed domain) and an explicit enumeration of the returned payload: live price, protection terms, requirements, and checkout link. It also names two siblings (read_for_sale_dns, get_seller_listing) with the conditions that select them, so it is clearly separable from the rest of the toolset.

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 routing is given ('Use read_for_sale_dns instead for a name that may not be listed here, and get_seller_listing for the seller's own view') plus the hard precondition 'Only listed domains can be quoted.' When-to-use, when-to-use-something-else, and the eligibility limit are all stated.

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 readOnlyHint/openWorldHint/idempotentHint/destructiveHint, yet the description adds material context beyond them: nothing is stored, asking prices are indicative and not binding, and seller-supplied links are returned as text, never followed, and should be treated as untrusted. That last point is a real prompt-injection disclosure an agent needs.

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 reporting shape, then routing, then safety caveats. Four sentences, each carrying distinct information, though the safety sentence is slightly long for the value it adds.

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 an output schema present, the definition covers purpose, routing, trust caveats, and storage behavior. Nothing an agent needs to invoke or interpret it correctly is missing, and return-value explanation is not required given the output schema.

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 documents 'domain' including the note that it need not be listed here. The description reinforces scope ('any domain') but adds no syntax or format detail beyond the schema. 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?

Specific verb+resource: it reads a domain's own _for-sale DNS records (RFC 10023) and reports for-sale status, asking price, listing status, and buy link. It explicitly distinguishes itself from quote_domain_purchase, so an agent can separate it from the sibling set 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?

States the scope condition ('Works for any domain, whoever published the records') and names the alternative with the exact switching condition: use quote_domain_purchase instead for a name listed here, to get its live price and terms. 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), so credit goes to the description for adding the DNS-confirmation gate: figures are returned only when the domain's _odvs record confirms them, otherwise the page is reported unverified with no figures. That is genuinely useful behavioral context 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?

Two tight sentences that front-load the action and then the verification condition. Nothing is padded, though the output/input ambiguity between 'Returns the appraisal, contact' and the required input fields slightly muddies an otherwise clean structure.

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 need not be restated, and the annotations carry safety. However, for a 7-required-parameter tool at 14% schema coverage, the description leaves the six undocumented parameters unexplained and blurs whether appraisal/contact are inputs or outputs, so it is only minimally 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 description coverage is only 14% (just 'domain' is documented), so the description is expected to compensate for the other six parameters. It vaguely references 'the appraisal, contact and buy link' but never explains fairUsd/lowUsd/highUsd/confidence/methodologyRev/contact, and oddly frames appraisal and contact as returned values while the schema requires them as inputs.

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: 'Check a domain's parked for-sale page from the figures in its forwarding link.' It is clear what the tool reads, though it never names or contrasts with the closely related read_for_sale_dns sibling, so sibling differentiation is implied rather than stated.

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?

No when-to-use guidance is given relative to alternatives such as read_for_sale_dns, appraise_domain, or quote_domain_purchase. The only framing is the verification condition, which describes behavior rather than when an agent should choose this tool.

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

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

Annotations only declare readOnly/idempotent/openWorld; the description adds far more: determinism ('the same field always crowns the same champion'), credit consumption ('one API credit per name'), auth requirements (Authorization: Bearer ad_live_..., write-scope key), cache-hit economics, keyless fallback behavior, and honest failure modes ('Rejected keyed runs can return an error'). This is exactly the beyond-annotation context the bar asks for.

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 alternative, then behavior — a sound order, and nearly every sentence carries operational signal. It is dense and billing-heavy toward the end, where the credit/allowance/rate-limit caveats stack up and could be tightened, but nothing is truly wasted.

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 names the returns (seeded field, matches, champion) and covers auth, cost, budget cutoffs, cache behavior, and error cases. For a compute tool with a monetization surface, an agent has everything needed to call it and anticipate the result.

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's tiered behavior (2-8 vs 9-16) is already documented in the schema description. The prose repeats rather than extends that, so baseline 3 is correct — no added syntax, format, or edge-case detail beyond the structured field.

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+output: 'Run a single-elimination bracket of 2 to 8 domain names and return the seeded field, every match and one champion.' It also names the sibling it is not (compare_domains) and the exact distinction (ordinal tiers vs estimated values), so an agent can separate it from the ~25 other tools here 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 routing: 'Use compare_domains instead when you need estimated values or want to know which orderings are not separable.' It also gives boundary conditions (2-8 run here, over 8 or budget cutoff returns handoffUrl) and the keyed vs keyless paths, so the when/when-not decision is fully specified.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered; the description still adds value by stating it reads live inventory, runs no appraisal, changes nothing, and returns an empty list on no matches. The main behavioral gap is that polling cadence/rate expectations for the changes mode are not described.

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 scope, then progressively adds mode behavior, alternatives and guarantees in a compact paragraph with no filler. It is slightly dense for a single sentence-chain, but every clause carries 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?

With 11 optional parameters, an output schema present, and full annotation coverage, the description covers the essentials: what it searches, how to page/poll, what a listing contains, and that it is a pure read. Minor gaps remain around paging interaction between offset and cursor, but nothing needed 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% and the schema already explains every parameter, including cursor semantics for mode=changes and the cents units for price bounds. The description's mode/cursor discussion largely restates what the schema provides, so it lands at the baseline rather than adding new parameter meaning.

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 set (filter, sort, page) over a specific resource (domains listed for sale by DNS-verified owners), including the distinctive scope that these are verified owner listings with fixed prices and appraisals. It names the sibling tools it is not (ask_domain_market, quote_domain_purchase), so an agent can disambiguate 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 routing rules: use ask_domain_market for a plain-sentence search, quote_domain_purchase for the live terms of a single listing, and switch to mode=changes with polling instead of re-searching. The when-to-use and when-to-use-something-else conditions are both 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 declare read-only/idempotent/closed-world; the description goes well beyond them by disclosing the fixed-sample ceiling of 5 rows, that aggregates describe the full corpus only at a 25-record threshold (governed by the population field), two-significant-figure rounding, and the meaning of an empty result. These are exactly the non-obvious traits an agent would otherwise misread.

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 action and its sample limitation are front-loaded, followed by alternative routing and then the aggregation/empty-result caveats. Every sentence carries distinct, decision-relevant information rather than restating table stakes.

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 full annotations, 100% schema coverage and an output schema handling return values, the description still supplies the interpretive context an agent needs (sample vs corpus, threshold behavior, rounding, empty-result semantics). Nothing required to select or 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 description coverage is 100%, so all nine parameters are already documented, and the description largely restates the filter set (keyword, TLD, price, year, venue). It adds only marginal guidance — the hard cap of five rows — beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return ... recorded domain sales') plus the exact scope (up to 5 rows from a fixed public sample) and the filter dimensions. It names the siblings it is not — find_comparable_sales and appraise_domain — so an agent can distinguish 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?

Explicitly routes to alternatives by task: find_comparable_sales for sales nearest one name, appraise_domain for a value, and the paid workspace/API for row-level research at scale. It also states the negative case ('Runs no appraisal') and warns that re-querying cannot exceed the sample.

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 idempotent/non-destructive, but the description adds critical behavioral context beyond them: the write is a full replacement of prior terms, it hits the live listing, it requires the manage token, and the floor is never shown to buyers. This is exactly the kind of consequence disclosure that prevents accidental data loss.

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?

Four tight clauses, front-loaded with the replacement semantics that matter most, and every sentence carries load (scope, replace behavior, idempotency, auth, visibility, alternative).

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, return values need not be described. The description covers the mutation's destructive scope, auth requirement, idempotency, and buyer-visibility of the floor, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds buyer-visibility semantics for the floor and frames autoAccept as tied to the floor rule, giving meaning the schema fields alone do not convey.

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 ('Set a listing's asking price, private floor and auto-accept rule') and immediately names the read-only sibling to use for inspection. An agent can distinguish it from get_seller_listing 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?

Explicitly directs the agent to use get_seller_listing to read current terms first, and gives a precise call pattern ('send every field you want to keep'). Both when-to-use and the alternative tool are stated.

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 readOnly/idempotent/openWorld annotations, it discloses the screening cap (up to 60), the return cap (up to 12 plus taken names), per-call request costs (one DNS per uncached candidate, one RDAP per free-looking one), that no key is required, and the important caveat that 'looks available' is a registration fact, not a price — a registry may reserve or premium-price.

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 usage routing, then constraints — every sentence carries information. It is dense and somewhat long, and 'Read-only, free, no key' partly restates the readOnlyHint annotation, but there is little true waste.

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 a full output schema present, return values need not be described, and everything an agent needs to invoke correctly — inputs, screening behavior, cost model, and the availability-vs-price caveat — is covered.

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, but the description adds semantics the schema does not: how keywords are transformed (joined, paired, with brand prefixes/suffixes like get/try/hq), the relationship between keyword count and the 60-candidate screen, and the determinism of candidate ordering for cursor reuse.

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+resource: build domain-name candidates from keywords and screen them against DNS/RDAP, returning available ones. It explicitly distinguishes itself from check_domain_availability and appraise_domain by name, so an agent can route correctly 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?

States the triggering scenario (a name for a business or project) and names two alternatives with the condition that selects each: check_domain_availability for names already in mind, appraise_domain for valuation. No ambiguity about when to pick this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: it makes one network request to the issuer's public endpoint, defines the verified semantics (true only if every runnable check passed, no-signer means not verified), and enumerates failure reason codes.

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 two checks, then the verified semantics and reason codes. Dense but every sentence carries information; the closing 'Runs no valuation' earns its place as a disambiguator against appraisal siblings, though the passage is slightly long.

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 need not be explained. The description still covers the semantics an agent needs to interpret results (verified flag behavior, no-signer case, reason codes) and the two input modes, leaving no meaningful gap.

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 both url and serial, including the exact URL format and that serial runs issuer-only. The description reinforces that integrity needs the full URL but adds no syntax or meaning beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (verify/check) and resource (audit.domains certificate) and decomposes it into the two concrete checks it performs. It also distinguishes itself from sibling tools by noting 'Runs no valuation', which separates it from appraise_domain and the appraisal/purchase 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?

Clearly explains the two invocation modes: a full verifier URL runs both the integrity and issuer checks, while a serial alone runs only the issuer check. It doesn't name a sibling alternative or an explicit when-not-to-use, but the mode-selection guidance is clear and directly actionable.

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