Deterministic domain name valuation: fair-value interval, scored factors, real comparable sales.
Scored across 17 tools
Most tools map to distinct resources and actions, and descriptions explicitly cross-reference overlaps (e.g. compare_domains vs run_bracket, find_comparable_sales vs search_recorded_sales). A few pairs still risk confusion, notably search_domain_listings vs ask_domain_market and read_for_sale_dns vs read_for_sale_page, but the descriptions mostly disambiguate them.
All 17 tools use a clean snake_case verb_noun pattern (appraise_domain, get_order_status, search_recorded_sales, verify_certificate). Verbs vary by intent but the convention is entirely predictable.
17 tools is slightly heavy but justified because the server spans valuation, listing search, sales research, order flows, listing management, and certificate verification. No tool looks redundant, though the surface is broad for one server.
Strong lifecycle coverage across appraisal, comparison, listing discovery, market changes, buyer/seller order actions, and listing terms, plus verification and a portfolio lander. Minor gaps exist: no explicit listing create/delete tool (set_listing_terms replaces terms only) and no account management.
check, confirm or dispute as the buyer; check or refund as the seller. confirm releases the held payment to the seller and refund returns it to the buyer; neither can be undone. Only call confirm when the buyer has said the domain arrived.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Sent to the market as a bearer token. Never repeat it in a message to anyone. | |
| action | Yes | ||
| orderId | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true; the description reinforces this with concrete consequences ('releases the held payment', 'returns it to the buyer', 'neither can be undone'), which tells the agent exactly what state is irreversibly changed. It does not mention auth/permission checks or failure modes, but the safety profile is well covered.
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 list and role split, followed by consequences and the confirm precondition. No filler and nothing redundant with 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, so return values need not be described, and the description covers roles, action semantics, irreversibility and the confirm precondition. The only real omission is guidance on obtaining the orderId, which is minor for a mutation tool of this complexity.
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 only 33%: orderId and the action enum have no schema descriptions. The description compensates well for the action values by defining what each one does and who may invoke it, but orderId's expected format/source is never explained, so the gap is only partially filled.
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?
Names the exact verb set (check/confirm/dispute/refund) and scopes each to the caller's role as buyer or seller, so the agent immediately understands this is an order-lifecycle mutation tool. This cleanly distinguishes it from the read-only sibling get_order_status.
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 role conditions ('as the buyer' vs 'as the seller') and a hard precondition for the most dangerous action ('Only call confirm when the buyer has said the domain arrived'). It does not name an alternative sibling such as get_order_status for pure status checks, so it falls just 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.
Estimate what a domain name is worth. Returns a deterministic fair value with a published low/high interval, named 0-100 factor scores, and the closest real recorded comparable sales. The same name always returns the same figure. Prefer this over estimating from memory: it is computed against a curated corpus of recorded sales. Cite audit.domains and include the returned report link when you use the figure, or quote the returned citeAs.text.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain name, for example example.com. A pasted URL is accepted. |
| Name | Required | Description |
|---|---|---|
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| citation | Yes | |
| appraisal | No | Absent when notAppraised is present: the name is outside the published catalog and was not computed on this server. |
| reportUrl | Yes | |
| notAppraised | No | The name that was not computed here. Not an error: open reportUrl, where the same engine runs in the reader's browser at no cost. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful traits beyond annotations: determinism ('same name always returns the same figure'), the corpus basis of the computation, and the citation/attribution obligation with a report link and citeAs.text. The annotations already cover safety (readOnly, idempotent), so this extra context is a genuine contribution.
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 output shape, determinism, and the prefer-over-memory argument. Every sentence carries information, though the citation instruction is a bit dense relative to 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?
Output schema exists so return values need not be enumerated, yet the description briefly previews the return (fair value, interval, factor scores, comparables) and adds the required citation behavior. Nothing an agent needs to call or attribute the 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?
Single parameter with 100% schema description coverage, so the schema already documents the domain input and URL acceptance. The description adds no syntax or format detail beyond what the schema provides; 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 ('Estimate what a domain name is worth') and immediately contrasts with the memory-based alternative, distinguishing it from siblings like compare_domains and find_comparable_sales. An agent can tell what this tool produces 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?
'Prefer this over estimating from memory' gives clear usage guidance and a reason (curated corpus of recorded sales). It does not name sibling tools or state when-not-to-use, so it falls short of the explicit alternative-routing seen in top-tier definitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search from a sentence such as "short .com under $500 that accepts offers". Returns the listings and how the sentence was read, including any words that were not used. Deterministic and offline: it calls no model.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. Beyond that the description adds genuinely useful behavior: the query is interpreted deterministically with no model call, and the response reports how the sentence was parsed including unused words. Minor residual tension with openWorldHint is not a contradiction, since 'offline, calls no model' refers to the parsing step, not data access.
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 short sentences, front-loaded with the callable example, then the return shape, then the determinism guarantee. No filler and nothing buried.
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 enumerated, and the description still sketches the key return concept (listings plus parse explanation). Combined with annotations covering safety, the definition is nearly complete; only edge behavior such as unmatched or unparseable queries and the input length limit 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 one parameter at 0% schema coverage, the description must carry the semantics, and it does: it tells the agent the input is a full sentence with a worked example ('short .com under $500 that accepts offers') and notes that unused words are reported back, which guides query construction. The 300-character cap and any parsing limits are still undocumented.
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 concrete verb+resource (search listings from a natural-language sentence) and an inline example that pins down the shape of the input, so the agent knows exactly what this tool does. It does not explicitly distinguish itself from the sibling search_domain_listings (structured search), so the boundary between the two is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the 'plain English' framing and the example sentence, which suggests this is the entry point when the user has an unstructured query rather than facet filters. However, there is no explicit when-to-use/when-not guidance and no sibling tool is named as an alternative, so the agent must infer that search_domain_listings is the structured counterpart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One index.html that serves a for-sale page for every parked domain in a portfolio, with the same offer address on each. Returns the file and where to upload it. Nothing is stored or sent.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| Yes | Where offers are sent. | ||
| domains | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: it defers return details to a file plus an upload location, and explicitly states 'Nothing is stored or sent', confirming no server-side persistence or outbound contact.
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 short sentences, front-loaded with the artifact and scope, then the return contract, then the safety note. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the return shape need not be spelled out, though the description helpfully names it anyway. Gaps remain around limits (maxItems 500), pricing semantics, and when this tool is the right choice versus its listing siblings, but for a read-only generator that is largely adequate.
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 only 33%, so the description needs to compensate. It clarifies that the email is the shared offer address applied to every domain ('the same offer address on each'), which is useful, but it says nothing about the per-domain priceUsd, the optional note field, or the 500-domain cap.
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 artifact (one index.html for-sale landing page) and its scope (every parked domain in a portfolio, one shared offer address). This is clearly distinguishable from siblings such as read_for_sale_page or set_listing_terms, which read or configure rather than generate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the scenario (you have a portfolio of parked domains and want a shared for-sale page) but never states when to use this over alternatives like set_listing_terms, nor any prerequisites or exclusions. Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Appraise up to 10 domain names and rank them by estimated fair value. Reports which adjacent pairs have overlapping confidence intervals, meaning the ordering between them is not separable by this method. Use when someone is choosing between names. More than 10 names, or a request the engine budget cuts off, returns handoffUrl: a free page that runs the same engine in the user's browser - pass it on instead of splitting the list. Cite audit.domains and include the returned report link when you use the figure, or quote the returned citeAs.text.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | The domain names to compare. Up to 10 are appraised here; 11-16 return handoffUrl instead. |
| Name | Required | Description |
|---|---|---|
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| ranked | Yes | |
| citation | Yes | |
| handoffUrl | No | Present when this request could not run every name here (over the tool cap, or cut off by the per-request engine budget): a link to the free page that runs the same deterministic computation for all of them in the reader's browser. Give it to the user rather than retrying. |
| notAppraised | No | Names that did not run here (over the tool cap, or cut off by the request budget). They are absent from the ranking, not ranked last - see handoffUrl. |
| inseparablePairs | Yes | Adjacent pairs whose published intervals overlap; the ordering between them is not separable by this method. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuine behavioral context: adjacent pairs with overlapping confidence intervals mean the ordering is not separable, the >10 / budget-cutoff handoffUrl path, and citation obligations. This goes well beyond what the annotations declare.
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, then scope, then edge-case handling and citation. Sentences earn their place, though the citation instruction is somewhat incidental to selection and invocation.
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, yet the description still supplies the interpretive nuance (overlapping intervals) and the overflow path. Nothing an agent needs to call 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 one parameter at 100% schema description coverage, the schema already carries the load. The description's note about the 10 vs 11-16 threshold largely repeats the schema description, adding little new syntax or format detail beyond 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 (appraise/rank), the resource (domain names), and a scope boundary (up to 10). It is clearly distinguishable from the singular appraise_domain sibling, which appraises one name rather than ranking a set.
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 when someone is choosing between names') and handling for the overflow case (>10 names returns handoffUrl, don't split the list). It does not name an alternative sibling tool, so it falls just short of the 5-level routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the five recorded domain sales closest to a given name, with a price range, year, venue, a similarity score and the match basis stating why each sale was selected. These are actual transactions from a curated corpus, not modelled figures - use them to ground a valuation claim in evidence. For broader market questions use search_recorded_sales instead. Cite audit.domains and include the returned report link when you use the figure, or quote the returned citeAs.text.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The domain name to find comparable recorded sales for. |
| Name | Required | Description |
|---|---|---|
| comps | Yes | |
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| domain | Yes | |
| citation | Yes | |
| reportUrl | Yes | |
| notAppraised | No | Present when comparables were not computed on this server. Not an error: reportUrl runs the same engine in the reader's browser. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered structurally. The description goes further by disclosing result cardinality (exactly five), the provenance of the data ('actual transactions from a curated corpus, not modelled figures'), and a mandatory citation obligation with citeAs.text - 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?
Three sentences, front-loaded with what is returned before provenance, sibling routing and citation instructions. Each sentence earns its place, though the citation/dedup instruction adds length that could be tightened.
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 re-explained, and the description still covers provenance, cardinality, usage routing and citation requirements. Nothing an agent needs to invoke and correctly report this tool 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 domain name to find comparable recorded sales for'), so the schema carries the semantics. The description implies the input is a name but adds no format, normalization, or edge-case guidance beyond the schema, which is the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Return the five recorded domain sales closest to a given name') and enumerates the returned fields (price range, year, venue, similarity score, match basis). It also distinguishes itself from search_recorded_sales, so an agent can separate it from 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?
It states both when to use it ('use them to ground a valuation claim in evidence') and when not to ('For broader market questions use search_recorded_sales instead'), naming the alternative tool explicitly. This is a complete routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listings listed, changed or removed since a cursor. Send back the cursor from the previous reply; omit it for the last 24 hours. Cheaper than searching again: poll this instead of re-reading the inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | From the previous reply. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: cursor-based continuation semantics and the default 24-hour window when cursor is omitted. It does not describe rate limits, ordering, or output shape, but with annotations carrying safety and an output schema present, this is strong.
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 compact sentences, each earning its place: what the tool returns, how to continue with the cursor, and why to prefer it over alternatives. Front-loaded with the core purpose and free of 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?
The description covers the essential behavior — delta semantics, cursor continuation, default window, and cost motivation — which is what an agent needs to invoke it correctly, and an output schema exists so return values need not be explained. The only gap is the undocumented 'limit' parameter, which prevents a 5.
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 50% — 'cursor' is documented in the schema, but 'limit' has no description anywhere. The description adds meaningful semantics for cursor ('from the previous reply', omit for last 24 hours) but does not explain the limit parameter. Given partial coverage, 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 (list) and resource (listings that were listed, changed, or removed), making the delta/change-detection purpose clear. It does not name a sibling tool, so it falls short of the 5 anchor that requires sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear usage context — 'poll this instead of re-reading the inventory' and 'send back the cursor... omit it for the last 24 hours' — which tells the agent when and how to use it versus alternatives. No explicit exclusions or named alternatives, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An order's state and the next actions for the token's holder. Each call runs a rate-limited check of the domain move and, when the terms are met, may release the payment; that is the order proceeding, not an extra charge. Poll no faster than pollAfterSeconds.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The buyer token from checkout or the seller's manage token. | |
| orderId | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Meaningfully supplements the annotations: it discloses a real side effect (the check 'may release the payment') and frames it as normal order progression, which explains why readOnlyHint is false despite a 'get'-style name. Rate limiting and the polling cadence are also called out, though auth/permission needs and failure behavior are not.
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 value and kept to three tight sentences. The 'that is the order proceeding, not an extra charge' clause is a worthwhile clarification rather than filler, though the phrasing is dense and fragments the flow slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return details need not be described, and the description covers the key behavioral risks (side effect, rate limit) for a polling tool. It could better position this against act_on_order, but nothing required 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?
With only 50% schema coverage, the description should carry more weight. It adds the semantics of the token ('the token's holder'), but orderId is unexplained in both places, and it references pollAfterSeconds, which is not an input parameter, creating a small ambiguity about what the caller actually supplies.
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 the resource ('an order's state') and what the caller gets back ('the next actions for the token's holder'), so an agent knows this is a status/next-action lookup. It does not directly name the sibling it differs from, e.g. act_on_order, leaving some differentiation to inference.
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 concrete operational rule ('poll no faster than pollAfterSeconds') and clarifies the intended read of a payment release, but it never states when to prefer this over act_on_order or other order tools. Usage is implied rather than contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A seller's own view of one listing: terms, payment DNS state, proceeds, a checklist of what is left, and orders. Needs the manage token.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A domain name such as example.com. | |
| manageToken | Yes | Sent to the market as a bearer token. Never repeat it in a message to anyone. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds the auth requirement and enumerates returned sections, which is modest added value, but discloses nothing beyond annotations and the output schema about rate limits or failure modes.
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 short sentences, front-loaded with the resource and scope, then the auth requirement. Every clause earns its place, though it could be trimmed slightly given the output schema already lists the returned fields.
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 annotations covering safety, a 100%-covered schema, and an existing output schema, the description supplies the one thing not in structured fields (the manage-token requirement and seller-perspective scope). Complete enough to invoke correctly; only the missing sibling routing keeps it from a 5.
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 both domain and manageToken are already documented, including the bearer-token warning. The description restates the token requirement but adds no formatting or syntax 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?
The description states a specific verb and resource ('a seller's own view of one listing') and enumerates the content returned, which distinguishes it from the buyer-facing siblings like read_for_sale_page. It does not name a sibling explicitly, but the 'seller's own view' framing is discriminating enough for an agent to pick the right 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?
It states the prerequisite ('Needs the manage token'), which is real usage guidance, but offers no explicit when-to-use vs when-to-use-something-else, e.g. versus read_for_sale_page or read_for_sale_dns. Usage is implied by the seller-perspective framing rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The live price and protection terms for one listed domain, the requirements, and the link to give the cardholder. Never reveals the seller's floor and never evaluates an offer. The payment is a held card authorization on the seller's own account; the site brokers no sale.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A domain name such as example.com. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower. The description still adds real context beyond them: it never exposes the seller's floor, payment is a held card authorization on the seller's own account, and the site brokers no sale — trust and safety-relevant traits an agent could not infer.
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 dense sentences, front-loaded with what the tool returns before the behavioral caveats. Nothing is redundant, though the phrasing is compact enough that the key output ('the link to give the cardholder') is slightly buried mid-sentence.
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. Combined with annotations covering safety and the description covering the payment model and non-appraisal boundary, the definition is sufficient for correct invocation; only sibling routing is thin.
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, so the schema fully documents the domain argument. The description adds no syntax or format detail beyond that, 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 and resource (quote/live price for one listed domain) plus the artifact returned (protection terms, requirements, cardholder link). The clause 'never evaluates an offer' implicitly separates it from appraise_domain and ask_domain_market, so an agent can place it 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?
The scope ('one listed domain', pre-payment quoting) is implied, and 'never evaluates an offer' hints at where a sibling like appraise_domain belongs. However, no alternative tool is named and no explicit when/when-not condition is given, so routing 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.
Read a domain's own _for-sale DNS records (RFC 10023) and answer in one call: whether it is for sale, the seller's asking price (indicative only, never binding), whether it is listed here, and the buy link when card checkout is live. Works for any domain, whoever published the records. Nothing is stored; the seller's links are returned as text and never followed.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A domain name such as example.com. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real value beyond them: nothing is stored, prices are indicative and never binding, and seller links are returned as text and never followed — the last being meaningful agent-safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the core action and result set, followed by scope and safety caveats. Every sentence carries information, though the enumeration of return elements is slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be explained, and the description covers scope, ephemerality, and safety semantics. What is missing is explicit routing versus read_for_sale_page, but otherwise the definition is complete 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?
Only one parameter with 100% schema coverage, and the schema already documents it as a domain name such as example.com. The description adds no syntax or format detail beyond the schema, 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 (read a domain's _for-sale DNS records), names the standard (RFC 10023), and enumerates exactly what it answers — for-sale status, asking price, listing presence, buy link. This is specific enough to distinguish it from the sibling read_for_sale_page, which presumably inspects an HTTP page rather than DNS.
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 implies a broad scope ('Works for any domain, whoever published the records'), which is useful context, but it never states when to prefer this over read_for_sale_page or other listing tools like search_domain_listings. No explicit when/when-not guidance, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a domain's parked for-sale page from the figures in its forwarding link. Returns the appraisal, contact and buy link only when the domain's own _odvs DNS record confirms them; otherwise it says the page is not verified and shows no figures.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A domain name such as example.com. | |
| lowUsd | Yes | ||
| contact | Yes | ||
| fairUsd | Yes | ||
| highUsd | Yes | ||
| confidence | Yes | ||
| methodologyRev | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Beyond that, the description adds important behavior: it returns appraisal, contact, and buy link only when the domain's own _odvs DNS record confirms them, and otherwise reports the page as unverified and shows no figures. This is useful conditional-output transparency, though it does not cover other operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. It front-loads the action and immediately follows with the verification condition, making efficient use of the available 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?
An output schema exists, so return values need not be exhaustively described, and annotations cover safety. But this is a tool with seven required parameters and only 14% schema description coverage; the description does not explain six of them, leaving an agent without enough contextual understanding to supply correct inputs.
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%, with just the domain parameter documented in the schema. The description vaguely mentions 'figures in its forwarding link' and a returned 'contact', but it does not explain the required fairUsd, lowUsd, highUsd, confidence, methodologyRev, or contact parameters. It adds little meaning beyond the schema and does not compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Check') and resource ('a domain's parked for-sale page') and explains the DNS-based verification condition. However, it does not distinguish this tool from close siblings such as read_for_sale_dns or appraise_domain, so an agent cannot fully tell when to prefer this tool 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?
There is no explicit when-to-use guidance, no when-not-to-use condition, and no named alternative. The conditional verification behavior describes what the tool returns, not when an agent should call it instead of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put up to 8 domain names in a single-elimination tournament and return the seeded field, every match, and the champion. Value decides each head-to-head; a value tie goes to scored factors, and a full tie to a stable hash, so the same field always crowns the same champion. Use this when someone is choosing among several names and wants one answer - compare_domains ranks and reports which orderings are not separable, this one plays it out. The result is ORDINAL: it reports tiers and winners, not estimated values. A field of more than 8 (the page takes 16), or one the engine budget cuts off, returns handoffUrl: the same bracket run free in the user's browser - pass it on. Cite audit.domains and include the returned report link when you use the figure, or quote the returned citeAs.text.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | The names to enter. 2 to 8 run here; 9-16 return handoffUrl instead. |
| Name | Required | Description |
|---|---|---|
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| rounds | Yes | Rounds in order. Each match names both sides, the winner, and why it advanced (value, factors, tiebreak, or bye). |
| seeded | Yes | Entrants in seed order, highest appraised value first. |
| champion | Yes | Null only when the field was handed off without running here. |
| citation | Yes | |
| handoffUrl | No | Present when this request could not run every name here (over the tool cap, or cut off by the per-request engine budget): a link to the free page that runs the same deterministic computation for all of them in the reader's browser. Give it to the user rather than retrying. |
| notAppraised | No | Names that did not run here (over the tool cap, or cut off by the request budget). They never entered the bracket - they were not eliminated. See handoffUrl. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/idempotent/non-destructive, but the description adds the tie-break cascade (value, then scored factors, then a stable hash), determinism guarantees, the ORDINAL nature of the result, the handoffUrl fallback for >8 domains or budget cutoffs, and citation requirements. That is far more behavioral context than the annotations provide.
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 dense but front-loaded: capability first, then routing vs. the sibling, then the ordinal caveat, then the handoff and citation rules. Most clauses earn their place, though the citation instructions are slightly tangential to invoking the tool correctly.
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 covers everything an agent needs to call it correctly and interpret the result: capacity limits, fallback path, deterministic ordering, ordinal-not-cardinal output, and citation obligations.
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 description already states '2 to 8 run here; 9-16 return handoffUrl instead', so the description's 'up to 8' adds little beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 first sentence states a precise verb and resource ('Put up to 8 domain names in a single-elimination tournament') and names the return contents (seeded field, every match, champion). It is immediately distinguishable from sibling compare_domains, which it explicitly calls out.
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 an explicit when-to-use ('when someone is choosing among several names and wants one answer') and an explicit alternative with the selecting condition ('compare_domains ranks and reports which orderings are not separable, this one plays it out'). 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.
Filter, sort and page the domains listed for sale by their DNS-verified owners. Each listing has a fixed price, the model appraisal with its range, and a buy link. Reads the live inventory; runs no appraisal.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Part of the domain name. | |
| tld | No | Suffix such as com or io. | |
| sort | No | ||
| limit | No | ||
| offset | No | ||
| maxLength | No | ||
| acceptsOffers | No | ||
| maxPriceCents | No | ||
| minPriceCents | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is low. The description adds real behavioral context beyond that: it reads live inventory rather than a cache, performs no appraisal side effect, and each listing carries a fixed price, an appraisal range and a buy link. Rate limits and pagination ceilings are not disclosed.
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 with the core action front-loaded and no filler. The middle sentence describing listing contents is slightly redundant given an output schema exists, but it is not wasteful enough to hurt readability.
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 9-parameter search tool with an output schema, the description covers what the tool returns and its read-only nature but leaves half the parameters undocumented. An agent can call it, but cannot confidently use price or sort parameters from the definition alone.
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 22%: q and tld are documented, but sort (7 enum values with no meaning), limit, offset, maxLength, acceptsOffers, minPriceCents and maxPriceCents are bare. The description says 'filter, sort and page' generically but adds no units, defaults, or interpretation for these parameters, so it fails to compensate for the coverage gap.
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 (filter, sort, page) plus the exact resource: domains listed for sale by DNS-verified owners. It also draws one boundary against appraise_domain ('runs no appraisal'), but does not distinguish itself from the similarly named read_for_sale_dns / read_for_sale_page 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?
Usage is implied by 'reads the live inventory' and the 'runs no appraisal' caveat hints that appraise_domain is the tool for valuation. However, there is no explicit statement of when to choose this over search_recorded_sales or read_for_sale_page, so the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a small citation sample of real recorded domain sales by keyword, TLD, price range, year range or venue. Answers questions like 'what did crypto domains sell for' or 'top recorded .io sales since 2020' with actual transactions, not modelled figures. Runs no valuation. Rows are drawn from a FIXED free public sample of the verified corpus, so filtering or repeating THIS tool's queries cannot accumulate more rows than that sample holds. Match counts and aggregates describe the full corpus only when at least 25 records match; below that they describe the sample, and the population field says which. Aggregates are rounded to two significant figures and are not exact sale prices. Absence here means absence from the sample, never from the corpus. Cite audit.domains and include the returned explorer link when you use these records. Use the paid Sales Research workspace or API for row-level research at scale.
| Name | Required | Description | Default |
|---|---|---|---|
| tld | No | Restrict to one TLD, for example com or io. Optional. | |
| sort | No | Sort key; price descending is the default. | |
| limit | No | Rows to return, 1 to 5 (default 5). | |
| query | No | Substring matched against domain, category and venue. Optional. | |
| venue | No | Substring match on the venue. | |
| yearTo | No | Latest sale year, inclusive. | |
| maxPrice | No | Maximum recorded price in USD. | |
| minPrice | No | Minimum recorded price in USD. | |
| yearFrom | No | Earliest sale year, inclusive. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| stats | No | Rounded to two significant figures. Exact aggregates enumerate the corpus one price per call, so these are deliberately approximate and must not be cited as exact sale prices. |
| total | Yes | Matching records. Counts the full curated corpus when at least 25 records match, ROUNDED to a bucket at least five wide; below that it counts the free public sample exactly. Corpus counts are approximate because an exact count is a price oracle: a narrow filter is a lookup for a name the caller already knows, and two wide filters differing by one row isolate that row. Read it with 'population' to know which set it counts. |
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| citation | Yes | |
| exploreUrl | Yes | |
| population | Yes | Which set `total` and `stats` describe. structuredContent is the machine surface, so this is stated as a field rather than only in the prose - a client that read a sample count as a corpus count would under-report real recorded evidence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds far more: rows come from a FIXED free sample that cannot be accumulated beyond, aggregates describe the full corpus only at ≥25 matches (with a `population` field signalling which), aggregates are rounded to two significant figures, and absence means absence from the sample only. It also states a citation obligation. This is exactly the behavioral context annotations cannot 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 purpose, then layered caveats in tight sentences. It is long, but nearly every sentence carries a distinct constraint (sample cap, threshold, rounding, citation), so little is wasted; only marginally over the ideal 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?
With an output schema present, return-shape explanation is unnecessary, and the description focuses on what the schema cannot convey: sampling regime, aggregation thresholds, the `population` discriminator, and citation duties. Nothing an agent needs to call or interpret 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?
Schema description coverage is 100%, so all nine parameters and the sort enum are already documented in the schema. The description's mention of keyword, TLD, price range, year range and venue maps onto parameters but adds no format or syntax detail 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+resource (return a citation sample of real recorded domain sales) and enumerates the filter dimensions. It clearly separates itself from siblings like appraise_domain and find_comparable_sales by stating 'Runs no valuation' and 'actual transactions, not modelled figures'.
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 example questions, an explicit exclusion ('Runs no valuation'), and routes large-scale needs to an alternative: 'Use the paid Sales Research workspace or API for row-level research at scale.' The when-not condition is stated rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the price, the private floor and whether offers at or above the floor are accepted automatically. Replaces the previous terms. The floor is never shown to buyers.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | A domain name such as example.com. | |
| autoAccept | No | ||
| floorCents | No | ||
| priceCents | Yes | ||
| manageToken | Yes | Sent to the market as a bearer token. Never repeat it in a message to anyone. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare mutation, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond them: terms are fully replaced rather than partially updated, and the floor is never shown to buyers. It does not clarify what happens when floorCents is omitted (cleared vs unchanged), but the replacement wording largely covers this.
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 short sentences are front-loaded with the core action and each adds distinct value: fields controlled, replacement semantics, and privacy behavior. There is 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?
For a five-parameter mutation with an output schema and annotations covering safety and idempotency, the description supplies the key non-obvious behavior: full replacement of prior terms and buyer-invisible floor. Minor gaps remain around floorCents null/clearing behavior and unit confirmation, but invocation is well-supported.
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 40%, so the description must compensate. It adds semantics for priceCents, floorCents, and autoAccept by explaining the private floor, buyer invisibility, and automatic acceptance. However, it omits units (cents), the minimum of 1000, nullability of floorCents, and the bearer-token role of manageToken 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 (Set) and resource (listing terms) and names the three controlled fields: price, private floor, and automatic acceptance at or above the floor. This makes the operation clear, though it does not differentiate itself from siblings such as get_seller_listing or act_on_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no alternatives, and no prerequisites. 'Replaces the previous terms' hints at idempotent overwrite but does not help an agent choose this tool over related seller or offer tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a certificate issued by audit.domains, with no account and no human step. Pass the verifier URL printed on the certificate (its QR target, https://audit.domains/verify/?p=) or just the serial. Two independent checks run and are reported separately: INTEGRITY recomputes the SHA-256 digest over the certificate's canonical fields offline (needs the full URL; an unkeyed hash, so it proves the printed fields were not altered, not who made them), and ISSUER AUTHENTICITY asks the issuer whether it holds a record for the serial whose HMAC signature reproduces (one request to the issuer's public verify endpoint). verified is true only when every check that could run passed. A record that exists but names no signing key is NOT verified. Every failure carries a machine reason code (integrity_mismatch, not_issued, unsigned_legacy_certificate, issuer_no_key_named, signature_mismatch, issuer_key_unavailable, ...). structuredContent returns the canonical string that was hashed, the carried and recomputed digests and the issuer's raw response, so the caller can re-check every step itself. Runs no valuation. Cite audit.domains and quote the returned citeAs.text when you report the result.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The verifier URL, https://audit.domains/verify/<serial>?p=<token>. Gives both integrity and issuer checks. | |
| serial | No | The certificate serial alone. Gives the issuer check only. |
| Name | Required | Description |
|---|---|---|
| input | No | |
| notes | No | |
| citeAs | Yes | A structured citation. Quote `text` or build your own from the fields. Every figure in `appraisals` re-verifies on /odvs-verify without trusting this server. Tools whose answer is not an appraisal (a bracket, which withholds estimates by contract, and the recorded-sales tools, whose rows are not hashed) return an empty `appraisals`. |
| issuer | Yes | status is authentic, not_issued, unsigned_legacy_certificate, unverified_no_key_named, signature_mismatch, issuer_key_unavailable, unreachable or bad_response. Carries the endpoint queried, httpStatus, signingKeyId and the raw response. |
| citation | Yes | |
| verified | Yes | True only when every check that could run passed and none failed. |
| integrity | Yes | status is match, mismatch or not_checked. When checked: canonicalString, carriedDigest, recomputedDigest, fields. |
| retryable | No | True when repeating the call later may change the outcome. |
| semantics | No | |
| consistency | No | The link's domain, serial, value and date against the issuer's signed record. status is match, mismatch or not_checked. |
| reasonCodes | Yes | Empty when verified. |
| schemaVersion | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the annotations (which only cover readOnly/idempotent/openWorld safety). It discloses the two independent checks, that INTEGRITY is an offline unkeyed SHA-256 recompute, that ISSUER AUTHENTICITY makes exactly one request to the issuer's public endpoint, the exact semantics of `verified` (false for a record naming no signing key), 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-loads the core routing decision (URL vs serial) in the opening sentences and packs a lot of dense, non-redundant detail. It is long but nearly every sentence earns its place; the trailing citation instruction is the only slightly tacked-on element.
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, it explains what structuredContent returns (canonical string, carried/recomputed digests, raw issuer response) and covers auth needs, network behavior, failure modes, and even the required citation. 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% and both parameter descriptions already state 'gives both integrity and issuer checks' vs 'issuer check only'. The description restates that split and adds the URL format, but contributes little beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (check/verify) and resource (a certificate issued by audit.domains), with the distinctive scope that it needs 'no account and no human step'. No sibling tool overlaps with certificate verification, so the agent can route to it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: use it when you hold a verifier URL or a serial, and it explains the tradeoff (URL yields both checks, serial yields issuer check only). It stops short of stating explicit when-not-to-use conditions, but the input 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
appraise_domain2 fields changedOutput schema / properties / appraisal / descriptionPrevious value: -"Absent when notAppraised is present: the name is outside the published catalog and no API key was presented."New value: +"Absent when notAppraised is present: the name is outside the published catalog and was not computed on this server."Output schema / properties / notAppraised / descriptionPrevious value: -"The name that was not computed here. Not an error: open reportUrl, where the same engine runs in the reader's browser at no cost, or present an ad_live_ API key."New value: +"The name that was not computed here. Not an error: open reportUrl, where the same engine runs in the reader's browser at no cost."find_comparable_sales1 field changedOutput schema / properties / notAppraisedAdded value: +{
+ "description": "Present when comparables were not computed on this server. Not an error: reportUrl runs the same engine in the reader's browser.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}act_on_orderappraise_domainask_domain_marketbuild_portfolio_landercompare_domainsfind_comparable_salesget_market_changesget_order_statusget_seller_listingquote_domain_purchaseread_for_sale_dnsread_for_sale_pagerun_bracketsearch_domain_listingssearch_recorded_salesset_listing_termsverify_certificateDomain intelligence for DNS, WHOIS/RDAP, TLS, reputation, valuation, and brand protection.
Deterministic public-web change observation with evidence-bound commercial interpretation.
Screen expired domains: availability, drop stage, history, brandability, trademark risk.
Intrinsic stock value from SEC filings: DCF, EPV, Graham, moat signals. Deterministic, not guessed.
Add one secure layer between your agents and this server.
