What Agents Buy

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the aggregated signals, the confidence tiers, and the important limitation that even a clear verdict does not replace reading and signing against the live 402. This is exactly the kind of behavioral 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?

Front-loaded with the use condition, then compactly defines verdicts, confidence tiers, the aggregated factors, and the required live-402 caution. Every sentence adds necessary information and 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?

Even without an output schema, the description explains what will be returned, what the caller should do with it, and how to request more detail. For a 2-parameter read-focused check tool, this is complete and actionable.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds useful usage nuance: url accepts a full URL or bare hostname, and detail:true requests the full read while defaulting to false. That modest extension justifies a 4.

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 the precise trigger (about to pay an x402 API), the resource (a URL or host), and the output (a verdict with defined values). The four verdict categories and confidence tier make the tool's function unmistakable and clearly distinct from the sibling seller/ranking tools.

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

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

Opens with an explicit 'USE WHEN' condition and tells the agent to gate payment on the verdict, with practical follow-up instructions to verify the live 402. It does not name alternatives or give explicit when-not-to-use cases, but the context is clear enough to route correctly.

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?

With no annotations provided, the description carries the full transparency burden. It discloses the ranking criteria (proven-accurate sellers first, then payment-safety, then price), the market coverage (every reachable endpoint), and that results are pre-vetted. It also hints at the read-only nature ('Searches'). While it doesn't detail error handling or limitations, the disclosed behavior is substantive and helpful, meriting a 4.

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 about 70 words but every sentence is purposeful. It is front-loaded with an explicit usage trigger, then explains what the tool does, its coverage, and the recommended next step. There is no redundancy or filler, and the structure guides an agent quickly. This is an efficient, well-organized description.

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

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

Given the tool's complexity (4 parameters, no output schema, no annotations), the description provides a solid foundation: it explains when to use it, what it returns (ranked shortlist), the ranking logic, and the follow-up action. It omits explicit details on return format (e.g., exact fields) and edge cases (e.g., no results), but these are not critical for an agent to invoke the tool correctly. The description is adequate and complete enough for the context.

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

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

Schema description coverage is 100%, meaning all four parameters (task, limit, max_price_usdc, min_reliability) already have detailed descriptions in the schema. The tool description does not add any extra semantic meaning beyond the schema—it does not explain parameter relationships, constraints, or usage nuances. Per the calibration, this warrants a baseline 3.

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

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

The description clearly states a specific verb-resource combination: searches the x402 market for APIs matching a described task and returns a ranked shortlist. It differentiates itself from siblings by explicitly noting it covers every reachable endpoint, not just ones previously used, and names check_before_paying as a distinct next step. The purpose is unambiguous and well-scoped.

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 opens with 'USE WHEN you need an API that does something and want payable options,' providing a clear trigger condition. It also gives workflow guidance (next step: check_before_paying) and notes it covers more than just previously bought endpoints, implicitly contrasting with other tools. However, it doesn't explicitly state when not to use this tool or name specific alternatives for exclusion, 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?

No annotations are provided, so the description carries the full burden. It does disclose the shape of the returned data well — each entry contains three elements (the trap, the cost of learning it, and the recommended alternative). However, it doesn't explicitly state this is a read-only knowledge retrieval with no side effects, and it discloses nothing about result count, ordering, or failure behavior. The content disclosure is solid but the safety profile is implied rather than stated.

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 most important content — when to use the tool — is front-loaded in a clear USE WHEN directive. The description is three tight sentences with minimal waste. The naming-history note '(Formerly named list_traps.)' adds small but legitimate value for agents that may know the old name. Slightly reduced from a 5 because the renaming aside is minor and the middle sentence is a bit 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?

For a simple tool with one optional parameter, no annotations, and no output schema, the description compensates reasonably well by explaining the content structure of each entry. An agent understands what it will receive. It could be more complete by noting whether results are returned as a flat list, but given the low complexity, the description is 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 description coverage is 100% — the single optional 'query' parameter is already documented as an 'Optional filter, e.g. price, delivery.' The description adds nothing about parameters, but at 100% coverage it doesn't need to. Baseline 3 is appropriate.

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

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

The description identifies a specific resource (field notes about payment traps) and the content of each entry (the way an agent loses money, what it cost to learn, and what to do instead). This is specific and useful. However, the verb/operation is left implicit — 'USE WHEN' implies retrieval but doesn't explicitly say 'list' or 'return' — and it doesn't explicitly differentiate from siblings like check_before_paying or rank_sellers.

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 opens with explicit when-to-use triggers: 'writing payment code' and 'before trusting an unfamiliar seller.' This gives an agent two concrete decision points for selecting the tool. It doesn't name alternatives or state when not to use it, which is the only gap keeping it from 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?

With no annotations provided, the description carries the behavioral burden. It discloses the evidence basis ('earned by actually paying it'), the nature of the data (quoted vs charged, arrival), and the demand-shape interpretation (real independent demand vs one wallet). It does not explicitly state side effects or auth requirements, but the 'look up' framing plus 'Returns every...' strongly implies a read-only operation, making the lack of a side-effect warning a minor omission.

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

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

The description is front-loaded with the usage trigger, then delivers a compact list of return contents, then a sibling comparison and legacy note. Every clause earns its place; no filler or repetition. The parenthetical former name adds practical value for agents encountering legacy calls.

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

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

For a one-parameter tool with no output schema, the description is remarkably complete: it explains what data will be returned, clarifies the Organic Demand Score concept, and provides a decision rule for choosing between this tool and its closest sibling. An agent has everything needed to 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?

The input schema already documents the only parameter (host) with a type, example, and description, so schema coverage is 100%. The description adds the phrase 'specific seller host' and ties it to the 'full track record' use case, but it does not add materially new semantic 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?

The description opens with a specific trigger ('USE WHEN you have a specific seller host') and names the resource ('one seller') with a clear verb ('look up'). It enumerates distinct outputs (grades, quoted vs charged, arrival, settlement volume, Organic Demand Score) and explicitly distinguishes itself from sibling check_before_paying, leaving no ambiguity about what this tool does.

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

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

The description gives an explicit when-to-use condition ('want its full track record') and an explicit when-not-to/alternative ('for a quick go/no-go before paying, use check_before_paying instead'). It also notes the former name, helping agents that may have seen the legacy tool reference.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses that data comes from chain logs and includes both historical settlement and live pulse, and it openly warns that registry counters 'can be bought', emphasizing reliability. It does not mention whether side effects occur (likely read-only) or rate limits, but for a read-only query that is acceptable. The transparency is strong for a zero-parameter 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?

The description is compact (about three sentences), front-loaded with the primary use case, and each sentence adds value: trigger, data contents, and a critical caveat. The mention of the merged former tools is a concise clarification. No filler words or redundant phrases.

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 explains the scope (last day settled, live pulse) and lists the components of the pulse (volume, payments with day-over-day change, 7-day series, stablecoin circulation). It lacks explicit output format or pagination details, but given the zero-parameter nature and lack of output schema, the description covers the essentials an agent needs to know about what the call returns and why it is authoritative.

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 no semantic burden on the description. The baseline for zero-parameter tools is 4 per the rubric, and the description correctly omits any mention of parameters since none exist. No additional explanation is needed beyond what is already implicit.

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

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

The description clearly states the exact queries it answers ('how big x402 is, whether it is growing, what settled recently') and specifies the two data outputs (chain-settled amounts and market pulse). It also disambiguates from registry counters by explaining why they are not demand proxies. This is specific and distinctive among 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?

Explicit trigger phrases ('USE WHEN asked how big x402 is, whether it is growing, or what settled recently') tell the agent when to invoke it. It also provides context on why chain data is preferred over registry counters, effectively steering away from a potential misuse. However, it does not name alternative sibling tools or explicitly state when *not* to use this tool in favor of another, missing a direct comparison.

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?

No annotations are provided, so the description must disclose behavioral traits itself. It reveals the ranking methodology (closeness to primary source, primary source cannot be reseller) and notes 'Top rows are the cheapest accurate sellers,' but does not state whether it is read-only, what the output structure is, or any potential side effects. For a ranking tool, it's reasonable to assume read-only, but without explicit confirmation, it's a moderate gap.

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

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

The description is a single, well-structured sentence that front-loads the use condition ('USE WHEN'), then explains the methodology, output, and how to list categories. No wasted words; every clause adds essential information.

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

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

For a tool with two optional parameters and no output schema, the description covers the primary use case, category list, and output hint ('Top rows are the cheapest accurate sellers'). It doesn't describe the exact return format (e.g., shape of each row), but given the simplicity and no output schema, this is 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?

Parameter schema coverage is 100%, so the schema already documents both 'limit' and 'category' with their defaults/enum-like values. The description adds minor guidance (e.g., 'omit to list categories') but this is already in the schema's category description. Thus, the description adds little beyond the schema.

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

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

The description clearly states the tool's purpose: ranking paid sellers by their accuracy against a primary source for categories with objective answers. It lists specific categories and distinguishes itself from generic ranking tools like 'rank_sellers' by emphasizing the accuracy vs. primary source methodology.

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

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

It explicitly opens with 'USE WHEN' and defines concrete conditions (objective right answer, specified categories), plus instructs to omit category to list available ones. This gives agents clear direction on when to invoke this tool over alternatives.

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

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

No annotations are present, so the description carries the full burden of explaining behavior. It does meaningfully explain how each ranking mode is computed and highlights that revenue and real_demand intentionally disagree. It stops short of stating output ordering, pagination, or read-only guarantees, but for a ranking tool the behavioral core 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?

Every sentence earns its place: the trigger phrase, metric definitions, the caveat about disagreement, and the sibling routing. The content is front-loaded and 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 two-parameter ranking tool with no output schema, the description is nearly complete. It explains the metrics, differentiates the tool from its closest sibling, and notes the legacy name. It does not describe the return format or explicitly state ordering, though 'leaderboard' and 'ranks' imply descending order.

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 0%, but the description adds rich semantics for the 'by' enum, explaining exactly what revenue and real_demand measure and why they differ. The 'limit' parameter receives no extra explanation, but its meaning is already clear from the schema's name, default, minimum, and maximum.

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

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

The description opens with a clear verb and resource: 'ranked list of sellers across the market.' It also distinguishes this tool from rank_by_accuracy by explicitly stating the accuracy-ranking alternative, so an agent can tell them apart without reading 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?

The description begins with 'USE WHEN' and explains the two ranking modes with concrete definitions: revenue means raw USDC received, real_demand means organic demand from independent wallets. It also gives an explicit exclusion: for accuracy ranking within a category, use rank_by_accuracy.

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