What Agents Buy

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It details the return structure (verdict, confidence tier, payment history) and explains that the tool folds multiple safety signals (live price, payTo honesty, phantom paywalls, delivery receipts, wash/real-demand) into that one verdict. It even warns that no verdict substitutes for reading the live 402, demonstrating transparency about the tool's limitations and the need for additional verification.

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 most critical usage condition ('USE WHEN...') and then logically expands on outputs and caveats. However, it is verbose—phrases like 'the same decision as a colour, for display' and the parenthetical '(Formerly named preflight.)' add length without essential value. It could be tightened without losing meaning, so it earns a 4 rather than a 5.

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

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

The tool has no output schema, so the description must explain return values—and it does comprehensively. It names the verdict field, enumerates all possible verdicts, explains the confidence tiers, mentions payment history, and provides usage guidance (pass detail:true for full read) plus a critical caveat about still checking the live 402. This covers all information an agent would need to decide and interpret the tool's result, making it fully complete for a tool of moderate 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?

The input schema already fully describes both parameters (url and detail) with 100% coverage, so the baseline is 3. The description adds no new semantics beyond the schema: it echoes 'Pass detail:true' which the schema already states as 'Include the full payment-safety detail (live-402 honesty, demand shape, grades). Default false.' Since the schema covers everything, the description does not enrich parameter understanding.

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 trigger condition ('USE WHEN your agent is about to pay an x402 API') and states the tool's purpose: determining whether a payment is safe and worth it. It additionally enumerates the exact verdicts returned (CLEAR, HOLD, ABORT, UNRATED), making the tool's output unmistakable. This strongly differentiates it from sibling tools like known_payment_traps or rank_sellers, which focus on other aspects of API discovery and evaluation.

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 invocation condition ('USE WHEN your agent is about to pay an x402 API'), which is strong guidance on when to call it. It also instructs the agent to still read the live payTo and amount after getting a verdict, clarifying that this tool does not substitute for final verification. However, it does not explicitly contrast this tool with siblings or state when NOT to use it (e.g., if no payment is imminent), 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 present, so the description carries the behavioral disclosure burden. It adds real behavior: search covers 'every reachable endpoint, not just ones we have bought from,' and results are ordered by proven accuracy, then payment-safety, then price. It does not explicitly say this is a read-only, non-charging operation, but 'searches' plus the later check_before_paying step implies no payment happens here.

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 and front-loaded: the 'USE WHEN' trigger comes first, then search behavior, coverage scope, and the required next step. Every sentence contributes actionable guidance, with 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?

Given that there is no output schema, the description supplies the most important return context: a ranked, pre-vetted shortlist with ordering criteria. It also closes the loop with check_before_paying. It could state the exact return shape more explicitly, but the combination of schema-covered parameters and workflow guidance is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the parameter details are already handled by the schema. The description adds search-ranking context and the next-step workflow, but it does not add extra meaning to parameters like task, max_price_usdc, or allowed_verdicts beyond what the schema already says. A baseline score of 3 is appropriate.

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

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

The description is clear about the action and resource: it "Searches the whole x402 market for what you describe and returns a ranked, pre-vetted shortlist." It does not explicitly contrast itself against sibling tools like rank_sellers or rank_by_accuracy, but its focus on finding payable APIs and the check_before_paying next step give it a distinct role.

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

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

It front-loads an explicit trigger: 'USE WHEN you need an API that does something and want payable options.' It also gives a follow-up workflow: 'Next step: check_before_paying on your pick.' However, it does not state when not to use this tool or whether siblings like rank_sellers should be preferred in other conditions.

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.