What Agents Buy

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 discloses the scope ('whole payable market', 'every reachable endpoint'), the ranking algorithm (accuracy first, then reliability, then price), and that the output is a 'pre-vetted shortlist'. It does not mention rate limits, pagination, or authentication requirements, but for a search tool the disclosed behavior is sufficient to set expectations. The description is consistent with the read-only nature of the 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 a tight paragraph of four sentences, each serving a distinct purpose: purpose+output, scope, ranking criteria, and usage workflow. There is no repetition or filler. A slight improvement could be front-loading the key action more explicitly, but overall it is efficient and clear.

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 moderate complexity of the tool (4 parameters, no output schema, no annotations), the description covers the input and behavioral context well but leaves out the output structure. It mentions a 'ranked, pre-vetted shortlist' but does not specify the format or fields of the results (e.g., endpoint URL, seller name, price, reliability score). The absence of pagination or error handling details is acceptable for a search tool, but the output description is vague enough that an agent may not know what to expect from the response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful additional meaning beyond what the schema already provides for parameters like 'task' (example keywords), 'limit' (default 8, max 25), 'max_price_usdc', and 'min_reliability' (default 70). The description reinforces the ranking criteria but does not enrich the semantics of any individual parameter.

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 uses specific verbs ('Search... and get a ranked, pre-vetted shortlist') and clearly identifies the resource ('the whole payable market'). It distinguishes itself from siblings by stating it covers 'every reachable endpoint, not just the ones we have bought from' and that it ranks by accuracy, reliability, and price. The name 'find_api' is generic, but the description eliminates ambiguity and differentiates it from tools like 'list_traps' or 'top_services'.

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 explicitly states when to use this tool: 'Use this to choose who to pay'. It then provides a clear workflow of subsequent steps: 'then call preflight on your pick and read the payTo from the live 402 before signing.' This gives direct guidance on the tool's role in a larger process and implicitly tells the agent not to use it for other purposes (like listing owned services, which would be handled by siblings).

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 provided, so description carries full burden. It discloses what data is returned (grades, pricing, delivery) but does not mention side effects, authorization needs, rate limits, or performance characteristics. The scope is simple (one required param, no write ops), so some gaps are acceptable, but the description could note if this is a read-only operation or requires a key.

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 concise sentences with high information density. The first sentence defines exactly what the tool returns; the second provides critical usage guidance. No filler or redundancy.

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 one-parameter lookup tool with 100% schema coverage and no output schema needed (description lists return fields), this is nearly complete. The only gap is the lack of disclosure about whether the result is cached or real-time, and auth requirements. Still, well above minimal viable for 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 description coverage is 100% for the only parameter 'host', with a clear example format. The description adds context that the host corresponds to an 'API seller' and the purpose of the lookup, which enriches the bare schema. No additional parameters exist to compensate for.

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 specifies the verb 'look up' and resource 'one x402 seller by host', enumerating exactly what data is returned (grades, pricing, delivery status, settlement volume, Organic Demand Score). This clearly distinguishes from siblings like find_api (search) and list_traps (no mention).

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

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

Explicitly states when to use: 'before letting an agent pay an unfamiliar API'. This is a concrete use case that guides the agent away from alternatives like find_api or preflight in this scenario.

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 carry the full burden of behavioral disclosure. The description explains that the tool returns field notes with specific content (each trap, cost, and alternative), which gives the agent a clear expectation of the output structure. It does not, however, disclose whether the operation is read-only (which is obvious from the name 'list') or any other behavioral traits like pagination or performance, but given the simplicity of a list tool with no destructive hint needed, this is sufficient.

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 concise sentences. The first sentence defines what the 'field notes' contain (each trap, cost, and alternative), and the second provides a clear action directive. Every sentence serves a purpose with no wasted words.

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 simplicity (1 optional parameter, no output schema or nested objects), the description is largely complete. It explains both the content of the results and the recommended usage timing. However, it could briefly mention that the tool only returns the notes (no mutation) or that results are sorted by relevance, but these are minor omissions. The description is adequate for the tool's straightforward nature.

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 the one optional parameter 'query' is already described in the schema. The description does not add any additional explanation about the parameter, but the schema itself is clear ('Optional filter, e.g. 'price', 'delivery''). Since coverage is high, the baseline is 3, and the description earns a modest bonus for the sentence about reading before writing payment code, which contextualizes the tool's purpose and indirectly the parameter's use. A score of 4 reflects the added contextual value.

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 that the tool lists specific ways an agent paying an API loses money or is misled, along with costs and alternatives. It's a specific verb+resource combination (list_traps) with a clear domain (API payment pitfalls), which distinguishes it from sibling tools like find_api or market_summary that focus on different aspects of APIs.

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 explicitly instructs the agent to read this before writing payment code, providing clear when-to-use guidance. While it doesn't explicitly say when not to use it or name alternatives, the directive 'Read before writing payment code' implies this is a prerequisite step, and the sibling tools listed are clearly different in purpose (e.g., search_services for finding APIs, not about payment pitfalls).

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, the description carries full burden. It discloses that data is measured from chain logs (not registry counters), explains why registry counters are unreliable, and implies the tool is read-only and provides a latest-day snapshot. This adds meaningful behavioral context beyond the input schema.

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

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

The description is two concise sentences, front-loaded with key information. Every phrase carries weight—no redundancy, no filler. It is efficiently structured for quick agent comprehension.

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 simplicity (no parameters, no output schema), the description covers the returned fields (total USDC, number of payments, services tracked, date) adequately. A minor gap is that 'services tracked' could be clearer (list vs count?), but overall the description is sufficient for an agent to understand what to expect.

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 has zero parameters, so baseline is 4 per guidelines. The description adds no parameter-level detail because none exist. Schema coverage is trivially 100%, so no deduction is needed.

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 that the tool returns data on what settled on Base in the last day, enumerating specific metrics (total USDC, number of payments, services tracked, date). It also distinguishes itself from registry counters, making its purpose unambiguous and distinct from sibling tools like 'find_api' or 'most_accurate'.

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 implicitly indicates it should be used to retrieve recent settlement data from Base chain logs, but it does not explicitly state when to use this tool versus alternatives. No exclusions or usage contexts are provided, leaving the agent to infer applicability.

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?

Without annotations, the description carries full burden. It discloses that only paid sellers are ranked, that the accuracy is against a primary source (not a reseller), and that results are sorted by accuracy then price. It also explains the behavior when no category is provided. This is substantial behavioral 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?

The description is three sentences that each serve a purpose: defining the tool's core function, summarizing the output, and providing a usage tip. No redundant or unnecessary words. Information is front-loaded and efficient.

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 parameters and no output schema, the description is fairly complete. It covers what the tool does, the valid categories, the ranking logic, and how to list categories. It could be improved by clarifying the exact return format (e.g., fields per row) but is adequate given the simplicity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by enumerating the exact valid categories and explaining that omitting the category lists them. It also connects categories to objective ground truth sources, which adds context beyond the schema's simple enumeration.

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 ranks paid sellers by accuracy for specific categories with objective ground truth. The verb 'rank' and resource 'sellers by accuracy' are specific, and the mention of 'cheapest accurate sellers' distinguishes it from sibling tools like top_services which likely rank by other criteria.

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 provides clear context: use this tool when you need the most accurate sellers for categories like crypto-price, stock-price, etc. It also specifies calling with no category to list available ones. However, it does not explicitly state when to use an alternative sibling tool, though the specialization is implied.

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

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

No annotations are provided, so the description carries the full burden. It transparently describes what the tool does: it returns a verdict based on checks like 'live price and payTo honesty,' 'phantom paywalls,' and 'delivery receipts.' It explains the optional 'detail' parameter expands the output. However, it does not mention potential side effects or costs (e.g., does calling this tool make network requests to the URL? Could it trigger payment flows?), leaving some behavioral ambiguity for a safety-critical 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 packed with essential information in a dense but coherent paragraph. Every sentence adds value, and the most critical guidance ('Gate your payment on the light') is front-loaded. However, the prose is dense and could benefit from slight restructuring (e.g., bullet points for verdicts) to improve scannability for an AI agent.

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 (a safety-critical gate for payment), the active presence of siblings, and the lack of an output schema, the description is remarkably complete. It specifies input format, optional detail toggle, all possible verdicts, the checks behind them, and post-invocation actions. There are no obvious gaps that would leave an agent uncertain about how to use or interpret the tool.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds substantial value beyond the schema. It explains how 'url' can be a full URL or bare hostname, and for 'detail', it clarifies that passing true yields 'the full payment-safety read (live 402 honesty, on-chain demand, every grade earned by paying it).' This enriches the schema's basic descriptions, making parameter semantics much clearer.

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 specifies the tool's purpose: it is a 'single call to make before your agent pays an unfamiliar x402 API' and returns one of four graded verdicts (CLEAR, HOLD, ABORT, UNRATED). The verb 'preflight' is paired with a concrete resource (payment-safety check for a URL/host), and the description distinguishes it from sibling tools like 'find_api' or 'search_services' by emphasizing its role as a gate for payment decisions.

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 provides explicit guidance on when to use: 'The single call to make before your agent pays an unfamiliar x402 API' and instructs to 'Gate your payment on the light.' It also advises what to do after the verdict: 'still read the payTo and amount out of the live 402 and sign against those.' This clearly delimits use cases and sets expectations for follow-up actions, effectively distinguishing the tool's role from siblings.

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?

Since no annotations are provided (no readOnlyHint, destructiveHint, etc.), the description carries a heavier burden. It declares the tool returns 'matching services with their grades' but does not disclose any side effects, required permissions, or limits on result set size. This is an adequate but minimal disclosure for a search 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 two sentences: the first states the search criteria, the second the return value. It is concise, front-loaded, and contains no redundant 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?

Given two parameters, no output schema, and no annotations, the description is mostly adequate. It explains input semantics and return type, but could be improved by noting the absence of pagination details or output structure, especially since the tool returns 'services with their grades' which may be complex.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context for the 'query' parameter with examples like 'email', 'price honesty', and explains that 'min_grade' is an optional floor. However, it does not add much beyond what the schema already specifies.

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 it searches a 'graded ledger' by hostname, behaviour graded, or words in the finding's title, and returns services with their grades. This distinguishes it from siblings like 'find_api' or 'get_service', though there is no explicit 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?

The description implies when to use (when searching graded services) and shows the 'query' parameter examples for free text. However, it does not explicitly state when not to use this tool or mention alternatives such as 'top_services' for ranked results.

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, the description carries full burden. It explains the ranking behavior and the two metrics' interpretations, which adds context. However, it does not disclose important behavioral traits such as whether results are sorted ascending/descending, pagination, prerequisites, or error conditions. The description is informative but lacks comprehensive behavioral disclosure.

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

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

The description is three sentences with no wasted words. The first sentence states the core purpose, and the following sentences add valuable nuance about the two metrics. It is appropriately sized and front-loaded.

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

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

Given the tool's simple nature (two parameters, no output schema), the description covers the main purpose and the rationale behind the ranking options. The 'limit' parameter is not described, but its schema (integer with min/max/default) is self-explanatory. The description could explicitly state that results are returned as a sorted list, but overall it is mostly complete.

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

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

Schema description coverage is 0%, so the description must compensate. The 'by' parameter is well explained with definitions of 'revenue' and 'organic_demand'. However, the 'limit' parameter (integer, default 10) is not mentioned at all in the description. Since one of two parameters is fully covered, the description adds moderate value but leaves a 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?

The description clearly states the verb 'Rank' and resource 'sellers' with two specific metrics ('money received' or 'Organic Demand Score'). It also explains the meaning of each metric, distinguishing this ranking tool from sibling tools like 'search_services' or 'get_service'.

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 provides clear guidance on when to use each ranking metric: 'Revenue answers who is busy; organic demand answers whose money comes from many independent wallets rather than one.' It hints that the disagreement is interesting, helping the agent choose. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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