Tollkit

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

Annotations cover only readOnlyHint/openWorldHint, so the description must carry the rest — and it does: exact price ($0.003 USDC over x402), the fact that failed calls cost nothing, the quote-then-sign payment handshake, and a free tier of the first 3 calls/day. This is exactly the billing/auth behavior an agent needs before invoking.

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?

Well front-loaded: purpose, then pricing, then when-to-use, params, and returns. The labeled sections make skimming easy. It loses a point because the final 'Parameters' and 'Returns' lines duplicate content already stated in the opening paragraph and in 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?

No output schema exists, so the description correctly enumerates the return payload (ground stops, GDPs, delays with minutes/trend/reason, closures). Combined with pricing and optional-parameter behavior, an agent has everything needed to call this correctly on the first attempt.

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 the airport format ('JFK' or 'KJFK') and the payment payload semantics are already documented in the schema. The description largely restates these, adding no syntax, validation, or edge-case detail beyond what the structured fields provide. 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?

States a specific verb+resource (check US airport delays) and pins the source: the FAA's live National Airspace System status, enumerating the exact data classes returned (ground stops, ground delay programs, arrival/departure delays, closures). No sibling tool overlaps this domain, and the first sentence alone differentiates it from weather_forecast, geocode_address, and the crypto/finance 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?

Contains an explicit 'When to use: You need to know if a US airport has delays or a ground stop right now' statement plus the optional-code convention ('leave out to list every airport with delays'). However it names no alternative or exclusion — e.g. it never says when a generic weather or web search would be better, or that it does not cover non-US airports.

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

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

Beyond the `readOnlyHint`, the description provides deep operational transparency. It details the exact components contained in the attestation (SHA-256, IP, TLS certificate, etc.), mandates that the user must store the response (we keep no copy), and specifies the cost structure, all of which are critical for agent decision-making.

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, while long due to the tool's complexity, is perfectly structured. It starts with a clear value proposition, details the mechanism, provides usage guidance, discusses behavioral constraints, and finishes with practical details (cost, alternatives). Every paragraph serves a distinct, valuable purpose.

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 complexity of generating legal/technical proof, the definition is exceptionally complete. It covers not only *how* to call it, but also *why* it is necessary, *what* the output entails, and *what* the cost is, making it fully self-contained for the agent.

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?

Although the schema is 100% covered, the description significantly enhances semantic understanding. For `screenshot`, it provides a critical warning about the output size consequence (55,000 characters of base64), allowing the agent to make an informed cost/utility tradeoff based on the parameter 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 defines the tool's purpose as generating a signed, verifiable proof of a page's content at a specific moment. It achieves maximum clarity by explicitly directing the agent to use alternatives like `read_page` or `screenshot_page` when proof is not required, distinguishing it sharply from sibling 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?

The tool provides multiple explicit use cases (ToS, price, claim) and clear behavioral triggers for its use. Furthermore, it explicitly tells the agent when *not* to use it (i.e., when simple reading or viewing suffices), which is extremely valuable guidance.

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 annotations only covering read-only and open-world behavior, the description adds substantial context: $0.01 USDC per call, failed calls cost nothing, quote-first payment flow, ranking by paying wallets and repeat buyers, cautions, and Tollkit's own-seller disclosure. It also explains why raw call counts are avoided.

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 definition is front-loaded with purpose and then uses labeled sections for pricing, when-to-use, alternatives, parameters, and returns. Every sentence carries useful information, and none are 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?

Although there is no output schema, the description explains the return shape: ranked endpoints, one per seller, with price, paying wallets, repeat buyers, and cautions. Combined with annotations covering safety and open-world scope, the definition is complete enough for an agent 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?

Schema description coverage is 100%, so task, limit, and payment are already fully documented, including the 1-20 range/default and the quote-mechanism for payment. The description repeats the schema's parameter guidance but does not add parameter-specific syntax or constraints beyond what the input schema already provides.

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 specific verb and resource: 'Find the best paid x402 API for a task.' It then distinguishes the ranking methodology from siblings and names two alternatives, so an agent can tell it apart without opening schemas.

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

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

It gives an explicit 'When to use' condition and a 'Use instead' section naming find_service and x402_seller_lookup with their respective scopes. It also explains the quote flow for payment, leaving no ambiguity about when to call with or without payment.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds material context beyond them: cost ('Free'), custody guarantees ('Tollkit never holds anyone's funds or keys'), and the fact that it moves nothing. It also previews the return payload. Missing only deeper operational detail like failure modes when the address is malformed.

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?

Well front-loaded and organized into labeled sections (When to use / Use instead / Parameters / Returns). Slightly wasteful: 'Free.' appears twice and the return payload is described in the opening sentence and again under 'Returns'.

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?

No output schema exists, and the description compensates by stating what is returned (the USDC balance and whether it falls below low_below). Combined with full parameter coverage and the safety profile, an agent has everything needed to invoke and interpret this 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 all three parameters are already documented in the schema, including defaults and the enum. The description restates them (address 'the wallet you pay from', network default base, low_below default 1) with only slight added framing, 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 with scope: 'Check how much USDC is left in your own wallet on Base.' It explicitly contrasts itself with the sibling 'wallet_balance for any wallet, chain or token,' so an agent can route correctly without opening either schema.

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

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

Provides an explicit 'When to use' trigger (you pay for tools from a wallet and want to know if it's running low) and an explicit 'Use instead' alternative (wallet_balance) with the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint; the description adds real value on top by specifying that exactly one unpaid request is sent, that nothing is paid or changed, and that the tool returns facts and named signals without scoring or recommending. It omits rate-limit or failure behavior, keeping it out of the top band.

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 content is front-loaded and organized under When to use/Parameters/Returns, but 'Free' and 'nothing is paid' are restated three times and the Returns section largely duplicates the opening paragraph. It is readable but carries visible 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?

With no output schema, the description compensates by enumerating the return contents (price, network, pay-to wallet, listing comparison, named signals). Only minor gaps remain, such as response format or failure handling for unreachable or non-x402 endpoints.

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% for the single url parameter, so the schema already carries the semantics and baseline is 3. The description repeats that url is the endpoint and adds that one unpaid request is sent, but no format or syntax detail beyond the schema's example.

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 a specific verb (probes) and resource (any x402 endpoint) and states the exact scope: what it charges, to which wallet, on which network, versus the Bazaar listing. This is clearly distinguishable from siblings such as x402_seller_lookup or find_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?

An explicit 'When to use: Before paying any x402 endpoint' plus a note that it works for services unrelated to Tollkit gives an agent a clear trigger condition. It does not name alternative tools or state when-not to use it, so it stops short of a 5.

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

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

Annotations cover only readOnlyHint and openWorldHint, so the description's disclosure of cost ($0.03 USDC per call over x402), the failed-calls-are-free guarantee, and the quote-then-sign payment flow adds genuinely useful context an agent cannot get from structured fields. It stops short of stating data freshness/latency or rate limits, so it is strong but not exhaustive.

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 purpose with clearly labeled sections ('When to use', 'Use instead', 'Parameters', 'Returns') that make it scannable. The only flaw is redundancy: the 'Returns' section restates the same list of outputs already itemized in the opening sentence, adding length without new 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 no-output-schema tool, the description covers purpose, scoping, the competing sibling, cost and payment mechanics, parameter requirements, and return shape. An agent has everything needed to decide to call it and to invoke it correctly, including how to handle the first unpaid call.

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 baseline is 3, but the description adds real meaning the schema lacks: the schema declares zero required parameters, whereas the text clarifies 'ticker or cik (one is required)', resolving an either/or ambiguity. It also explains the purpose of the payment parameter (omit for a quote, sign and re-call).

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

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

The opening states a specific verb and resource ('Run due diligence on a US public company in one call') and enumerates exactly what is computed (profile, revenue/profit growth, margins, leverage and cash ratios from SEC filings, key filings, 8-K summaries). It also names the sibling it is not: company_snapshot. An agent can distinguish it without opening any schema.

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

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

It gives an explicit when-to-use condition ('You are evaluating a US public company and want the analysis done') and a named alternative ('Use instead: company_snapshot for a quicker, cheaper overview'). The pricing/payment flow is also spelled out as a procedural step, leaving nothing to inference.

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

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

Annotations give readOnlyHint and openWorldHint, but the description adds operational behavior they cannot express: the $0.006 USDC x402 cost, that failed calls are free, and the two-step quote-then-sign flow via the payment parameter. That is exactly the kind of billing/auth context an agent needs before invoking a paid tool.

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

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

Front-loads the core purpose, then cleanly segments payment, when-to-use, alternatives, parameters and returns. Every sentence carries information; no filler or restatement of the name.

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 no output schema, the description compensates by summarizing the return shape (profile, filings[] with links, key financials for two fiscal years plus the latest quarter). Combined with the payment flow and alternatives, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema omits: it clarifies that ticker or cik is required (the schema declares zero required properties), documents the filings range 1-40 with default 8, and gives an example form type. Useful disambiguation beyond the field-level descriptions.

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 ('Get a one-call snapshot of a US public company from SEC EDGAR') and enumerates exactly what the snapshot contains: profile, recent filings with links, and named financial metrics. It explicitly differentiates itself from siblings company_due_diligence, sec_company and sec_financials, so an agent can select it without opening other schemas.

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

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

Contains explicit 'When to use' and 'Use instead' sections naming three alternatives with the exact conditions that select each (due diligence for growth/margins/leverage/8-Ks; sec_company or sec_financials for a single part, noted as cheaper). Nothing is left to inference.

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

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

Annotations only cover readOnlyHint and openWorldHint, and the description goes well beyond that: flat $0.04 cost, full charge on partial success, no charge when all URLs fail, duplicate de-duplication and non-billing, and the distinct payment mechanics (one EIP-3009 signature/settlement/round trip for the whole set vs one per URL). It also states it returns full per-URL data and does not rank or pick a winner.

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 and scannable, but there is real duplication: the return format ('one entry per URL in order, each ok/error') is stated twice and the when-to-use guidance is repeated in a trailing block. The content is useful but would benefit from trimming.

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

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

An output schema exists, yet the description still covers cost, billing edge cases, ordering, and error tolerance for dead URLs. For a paid batch tool with these stakes, 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?

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema does not: a single payment payload covers the whole batch, and duplicates are removed before billing. allow_redirect is deferred to the sibling tool by both schema and description, which is a minor 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 and resource — pricing one product across several stores — with a hard scope of up to 5 URLs in one call and one payment. It explicitly distinguishes itself from get_product_details, so an agent can choose between them without opening either schema.

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

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

Gives an explicit trigger ('USE THIS WHENEVER YOU HAVE MORE THAN ONE URL'), enumerates the qualifying scenarios, and names the alternative plus its condition ('Use instead: get_product_details for a single URL'). Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries real added weight: it states the cost ($0.003 USDC per call over x402), that failed calls are free, and the two-step payment flow (call without `payment` to get a quote, then sign and call again). That is substantive auth/cost context an agent needs before invoking. It stops short of describing latency, caching, or partial-failure behavior, so it is strong rather than exhaustive.

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?

Usage and alternative routing are well front-loaded, but the payload contents are enumerated twice — once in the opening sentence and again in the 'Returns:' sentence — which is pure duplication. The cost and payment details are the only novel content in the middle block; trimming the repetition would make this much tighter.

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

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

There is no output schema, so the description is right to enumerate the returned fields in detail, and it does so thoroughly enough for an agent to know what it will get. The payment prerequisite and its quote-first workflow are also covered. The only gap is that quantities/shape of the aggregates (e.g. how many gainers/losers, formatting of the index) are unspecified.

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 optional parameter with 100% schema description coverage, so the baseline is 3. The description reinforces the quote/payment workflow already documented in the schema, but adds no syntax or format detail beyond it. The line 'Takes no parameters' is a slight overstatement given the optional `payment` field, though it is defensible as 'no required parameters'.

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 a specific verb ('Get') and an enumerated resource (Fear & Greed, BTC/ETH/SOL perp data, funding extremes, gainers/losers, Hyperliquid totals) rather than a vague 'market data'. It also explicitly distinguishes itself from siblings by naming perps_market and crypto_news as the alternatives for narrower or adjacent needs.

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?

Contains an explicit 'When to use' clause ('you want the state of the crypto market in one call, for example before deciding anything else') and an explicit 'Use instead' clause routing to perps_market for specific coins/more markets and crypto_news for headlines. Both the selection condition and the alternatives are stated, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description adds the x402 pricing model ($0.004 USDC per call, failed calls free) and the quote-then-sign payment flow, which is essential behavioral context. It also discloses the two-step payment dance and the 'not advice' boundary on the AI read.

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

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

Front-loaded with the core action and cleanly sectioned (When to use / Use instead / Parameters / Returns). The Returns line largely repeats the field list already given in the opening sentence, which is minor redundancy rather than bloat.

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?

No output schema exists, so the description carries the return shape (articles[] fields plus mood/summary/themes) and does so explicitly. Combined with the payment and routing guidance, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters (including the enum and min/max on num) are already documented. The description's parameter lines restate the same defaults and ranges without adding syntax, format, or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb+resource (get recent crypto news) and immediately scopes it (up to 10 articles from the past hour/day/week), then names the sibling it is not — web_search for non-crypto and crypto_market_pulse for numbers. An agent can distinguish it from all 38 siblings 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?

Explicit 'When to use' clause plus a 'Use instead' clause routing to web_search and crypto_market_pulse by condition. Nothing about tool selection is left to inference.

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

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

Annotations only say readOnly/openWorld; the description adds the pricing model ($0.002 USDC per call via x402), that failed calls are free, the three-free-calls-per-day limit, the two-step quote/sign flow, the data provenance (ECB, published free), and the important caveat that rates are informational and not valid for transactions.

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 capability, then cleanly sectioned as 'When to use', 'Parameters', and 'Returns'. The payment block is longer than strictly necessary and the 'for information only, not for transactions' caveat is repeated verbatim at the start and end.

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?

Although there is no output schema, the description names the return values (rate, converted amount, ECB date used) and fully covers the auth/payment path. An agent has everything needed to invoke this correctly, including what happens on failure and without payment.

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 from/to/date/amount/payment are all already documented. The description restates the same facts, adding only the '30 supported' currency count and the default amount of 1; it does not enumerate the supported codes or add format detail 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 and resource plus scope: 'Convert between currencies at European Central Bank reference rates (30 currencies)'. The ECB-rate and fiat-currency framing clearly separates it from crypto siblings like token_price and crypto_market_pulse.

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?

Provides an explicit 'When to use' line and an unusually clear payment workflow (call without `payment` for a quote, sign and call again; first 3 calls/day free). It does not name an alternative tool for adjacent needs (e.g., crypto conversion), so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely new behavior: no payment occurs, results are live-checked, and ordering is by live price quote then distinct paying wallets with no paid placement. It does not enumerate rate limits or failure modes, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then cleanly sectioned into when-to-use, alternatives, parameters and returns. Slightly long, but each section carries distinct routing or behavioral 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?

No output schema exists, and the description compensates by describing the return shape (live-check status, price, network, recipient, paying wallets). Combined with the ranking rule and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates them with only a marginal addition ('how many to check live'), 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 and resource ('searches Coinbase's public x402 discovery index for services that do a task') plus the live-check scope. An agent can distinguish it from best_x402_tools and check_service without opening either schema.

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

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

Explicit 'When to use' condition ('you need a paid API for a job and don't know which seller has it') and 'Use instead' routing to two named siblings, each with the condition that selects it.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context the annotations cannot carry: the x402 pricing ($0.002 USDC/call), that failed calls are free, the quote-then-sign payment flow, the 3 free calls/day allowance, and that a non-match is refused free. This is exactly the extra behavioral detail an agent needs before paying.

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?

Well front-loaded: purpose first, then cost, then when-to-use, alternative, parameters, and returns. However, the opening sentence already enumerates the full return field list (address, ZIP, county, FIPS, state, census tract) and the trailing 'Returns:' line repeats it verbatim, which is wasted text.

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, no-output-schema geocoder with light annotations, the description covers the purpose, the exact return fields, payment/quote mechanics, cost, input constraint, and failure handling. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a meaningful constraint beyond the schema ('US street addresses only (with a house number)') and ties `payment` to the quote workflow. It stops short of full added value but meaningfully supplements 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 and resource ('Turn a US street address into latitude and longitude') and enumerates the exact outputs plus the data source (US Census Bureau geocoder). It explicitly scopes to US street addresses with a house number, and names a sibling alternative, so an agent can distinguish it from weather_forecast without opening either schema.

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

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

Contains an explicit 'When to use' line and a 'Use instead' line routing to weather_forecast when only weather is needed. The payment precondition (call without `payment` to get a quote) is also spelled out, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description carries the real burden and does: it discloses the $0.01 x402 payment workflow, the no-account/no-gas model, headless-browser rendering, free-of-charge refusal on cross-page redirects, uncharged failed extractions, 300-second caching with `cached: true`, and the declared-vs-inferred provenance distinction. This is exactly the context beyond annotations that changes how an agent calls 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?

Front-loaded and well-sectioned with headers, but the trailing 'When to use / Use instead / Returns' block repeats content already stated in the body (the single-URL condition, compare_products, try_it_free, and the field list). That duplication costs it, though the middle sections are dense and earn their 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?

Given a paid, mutation-free, open-world extraction tool with an output schema, this covers every decision point an agent needs: when to use it, when not to, cost and payment mechanics, failure/refund behavior, caching, and provenance semantics. The output schema exists, so the return-value restatement is a bonus rather than a gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: it spells out the two-call payment dance (call without `payment` to get requirements, sign, base64-encode the x402 payload, call again with it) and the rationale for `allow_redirect` matching the schema note. It reinforces rather than merely restates, though it does not add syntax the schema lacks.

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

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

Opens with a specific verb+resource+scope: 'Find out what a product is and what it costs, from its page URL.' It explicitly differentiates from siblings by naming compare_products (2-5 URLs), read_page/page_brief territory (prose rather than fields), and try_it_free, so an agent can route without opening any schema.

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

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

Gives explicit USE THIS WHEN conditions ('URL of ONE specific product — store listing, marketplace item, manufacturer's page'), an explicit DO NOT USE list (search/category pages, login/paywalled pages, non-product pages, private/internal addresses), and names alternatives with the condition that selects them (compare_products for 2-5 URLs, try_it_free to preview).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by stating the operation is free (cost transparency, twice) and enumerating what comes back: prices per tool, the payment network and recipient, and tool return descriptions. It stops short of noting rate limits or caching, but is solid for a read-only info call.

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 and scannable with labeled sections, but it repeats itself: 'Free.' appears twice, the first sentence's summary is restated in 'When to use' and again in 'Returns', and the try_it_free routing appears in both the opening and the 'Use instead' line. Roughly a third of the text is redundant.

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 no output schema and no parameters, the description carries the burden of describing the payload, and it does: prices per tool, payment network and recipient, and what each tool returns. An agent knows the shape of the result and when to prefer the sibling.

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?

Zero parameters, so per the rubric the baseline is 4. The description correctly implies the tool is self-scoped to 'this service' with no arguments, which aligns with the empty 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 resource and its contents: 'Price, network, and what this service returns', plus 'prices, network and endpoints in machine-readable form'. It explicitly contrasts with the sibling try_it_free, so an agent can distinguish the two 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?

Provides explicit 'When to use' and 'Use instead' lines, naming try_it_free and the condition that selects it (wanting real sample output rather than a description). Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior the agent could not otherwise know: $0.002 USDC per call via x402, failed calls free, quote-then-pay flow, a 3-call/day free tier requiring no wallet, and that private/reserved addresses are refused at no cost. It also discloses accuracy limits (city-level, not street address) and the data source/license.

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

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

Purpose, data source, pricing, when-to-use, parameters and returns are all present and reasonably front-loaded. It loses a point for redundancy: 'City-level accuracy, not a street address' is repeated verbatim in the Returns line, and the attribution/license sentence is of marginal value to tool selection.

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 no output schema, the description carries the return contract and does so (country, region, city, continent, approximate lat/long at city level). Combined with the payment/free-tier mechanics and the private-address refusal case, an agent has everything needed to invoke this correctly on the first try.

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 both parameters are already documented, making 3 the baseline. The description adds meaning beyond the schema by noting that the `ip` value may be IPv4 or IPv6 and that private/reserved addresses are rejected free, and by explaining the omit-payment quote round-trip for the `payment` field.

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

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

States a specific verb and resource: 'Find where an IP address is', enumerating the returned fields (country, region, city, continent, coordinates) and covering IPv4/IPv6. The resource 'IP address' implicitly separates it from geocode_address, but no sibling is named or contrasted explicitly, so it falls short of a 5.

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 'When to use: You need roughly where an IP address is' statement plus concrete payment-flow guidance (call without `payment` to get a quote; first 3 calls/day are free; failed calls cost nothing). It does not, however, address when to prefer this over the adjacent geocode_address tool, so it stops at clear-context-without-exclusions.

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

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

Annotations only cover readOnly/openWorld, but the description adds the critical unseen behavior: per-call cost ($0.007 USDC over x402), that failed calls are free, and the two-step payment flow (call without `payment` to get a quote, then sign). It also discloses truncation behavior ('says when the page was longer than the part summarized'). This is substantial 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?

Front-loaded purpose sentence, then labeled blocks (pricing, When to use, Use instead, Parameters, Returns). Dense but every line carries distinct information; 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?

No output schema exists, yet the description enumerates the return fields (summary, title, final_url, truncation note). Combined with the payment flow, parameter range, and sibling routing, 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?

Schema description coverage is 100%, so the schema already documents url, payment, and max_words including the range and default. The description largely restates those facts, adding only mild emphasis on the quote flow. 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?

States a specific verb and resource ('Read any web page in a real browser and get a summary'), plus the concrete outputs (title, final URL). Explicitly names sibling tools it is not (read_page, read_pages), so an agent can distinguish it without opening schemas.

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

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

Gives an explicit condition ('You need the gist of one page, not its full text') and names the alternatives with their selecting conditions ('read_page for the full text; read_pages for several pages'). No inference required.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds the costly details an agent cannot get elsewhere: the 25 MB / 300-page ceiling, refusal of text-layer-less PDFs at no charge, $0.005 USDC pricing under x402, failed calls being free, and the three-free-calls-per-day quota. The quote-then-sign payment handshake is also spelled out, so no annotation contradiction exists.

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 cleanly sectioned into pricing, 'When to use', 'Use instead', 'Parameters', and 'Returns'. It runs long for a three-parameter tool and repeats the 'scanned PDFs without a text layer are refused at no charge' clause in both the intro and the Returns section, which is the only wasted text.

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?

There is no output schema, so the description correctly enumerates the return shape (title, author, page_count, pages_read, ordered pages[] of text). Combined with the stated size/page limits, refusal behavior, and the x402 payment/quota mechanics, an agent has everything needed to call this correctly on the first attempt.

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 a baseline of 3 is warranted, but the description adds useful framing: url must be an absolute http(s) PDF link, max_pages is bounded 1–300 with a default of 50, and the payment parameter's workflow (omit it for a quote, sign and call again) is explained in prose rather than left to the field blurb.

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

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

Opens with a concrete verb+resource ('Read a PDF from a URL as text, page by page') and enumerates what comes back (title, author, page count). It explicitly distinguishes itself from the closest sibling by naming read_page for ordinary web pages, so an agent can pick correctly without opening a schema.

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

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

Contains an explicit 'When to use' condition (the link is a PDF — filing, paper, contract, manual) and an explicit 'Use instead' alternative (read_page for ordinary web pages). The limits section also tells the agent when the tool will refuse (scanned PDFs, >25 MB, >300 pages), which is actionable routing information.

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

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

Beyond readOnlyHint/openWorldHint, the description discloses metered pricing ($0.001 USDC per call via x402), that failed calls are free, the two-step quote/payment handshake, the sign convention for funding, and the not_found error shape. This is rich behavioral context the annotations do not provide and there is no contradiction with them.

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 one-line summary followed by clearly labeled sections (When to use, Use instead, Parameters, Returns), which is easy to scan. It runs long and restates several schema-level parameter details, so it isn't maximally tight, but no sentence is wasted.

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

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

With no output schema, the description supplies a Returns breakdown covering every returned field, plus error handling and the payment lifecycle. For a 5-parameter, 0-required, open-world read tool, 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the funding sign convention, that sort/limit only apply when coins is omitted, and that funding_hours requires exactly one coin (and pulls history). Some parameter text is redundant with the schema, which keeps it from a 5.

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 ('Hyperliquid perpetuals') and enumerates exactly what data is returned: mark/oracle price, funding, open interest, volume, leverage. It explicitly distinguishes itself from siblings crypto_market_pulse and token_price, so an agent can route without opening either schema.

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

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

Contains dedicated 'When to use' and 'Use instead' sections naming two concrete alternatives and the condition that selects each. It also clarifies the payment flow (call without payment to get a quote) and the coins-vs-top-markets branch, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds material context the annotations cannot: $0.01 USDC per call over x402, failed calls are free, and the two-step quote-then-pay flow via the `payment` parameter. It stops short of saying whether results are cached or how stale the on-chain reads can be, so not a full 5.

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

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

Purpose is front-loaded and the labeled When/Use-instead/Parameters/Returns blocks scan well. However 'Facts, not advice' appears twice and the Returns summary largely repeats the opening sentence's output list, which is avoidable duplication.

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 read-only, five-parameter tool with no output schema, the description covers everything an agent needs: what comes back, the payment handshake, chain defaults, and the one required field. Nothing material is left to inference.

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 goes slightly beyond by grouping the parameters into a usage narrative (amount_usd drives price impact against pool depth, wallet drives holdings display) and reminding that token is required. Much of that overlaps the schema text, which caps it at 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 a specific verb and resource ('pre-trade check of a token on Base, Ethereum or Solana') and enumerates the concrete outputs: price, liquidity, chain warnings, price impact, holdings, web results. It also names the sibling token_check as the non-trading alternative, so the agent can separate the two without opening either schema.

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

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

Explicit 'When to use' line ties it to the moment right before a trade with a sizing question, and an explicit 'Use instead: token_check when you aren't trading yet' exclusion. Both the positive and negative conditions are stated.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds the critical non-structured behavior: $0.002 USDC per call over x402, failed calls are free, and omitting `payment` returns a quote that must be signed and resubmitted. That payment/auth handshake is exactly the kind of trait annotations cannot express.

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

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

Front-loaded and clearly partitioned into purpose, pricing, when-to-use, alternatives, parameters and returns. Slight redundancy: return contents (first/last/high/low/percent change) appear in both the opening paragraph and the 'Returns' line, costing a little space without new information.

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

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

With no output schema, the description compensates by describing the return payload precisely (points[] with time, price_usd, Chainlink round, plus first, last, high, low and percent change) and covering the paid-call flow end to end. An agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the asset must have a Chainlink USD feed (narrowing valid symbols), points are 'evenly spaced' prices, and the payment quote-then-sign flow is restated in prose. It stops short of explaining edge cases such as what happens when fewer than `points` rounds exist in the window.

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 (past USD prices for a crypto asset) with concrete scope: up to 365 days, up to 100 points, sourced from Chainlink's on-chain Ethereum feed. It explicitly distinguishes itself from the sibling token_price, so an agent can route correctly without opening either schema.

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

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

Includes explicit 'When to use' (trend, high/low, change over a period for a major asset) and 'Use instead' naming token_price for the current price of any token, including those without a Chainlink feed. The condition that selects the alternative is spelled out, not inferred.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing JavaScript rendering in a real browser, a 50,000 character cap, per-page pricing over x402, that failed/empty pages cost nothing, and that omitting payment yields a quote. These are exactly the operational facts an agent needs and none are in the structured fields.

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 capability and organized under clear labels (When to use, Use instead, Parameters, Returns), so it scans well. It is dense with pricing and constraint detail, but nearly every sentence carries decision-relevant information rather than 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?

With no output schema, the description compensates by spelling out the return fields (title, final_url, text, text_length, truncated) and the truncation limit. Pricing, free-tier, failure-cost and JS-rendering behavior are all covered, leaving no material gap for calling the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real constraint meaning: url must be absolute http(s), public, with no logins and no private addresses, and it explains the payment/quote round-trip beyond the schema's one-line note. It stops short of 5 only because the parameter notes largely restate and lightly extend 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 and resource ('Read any public web page') and immediately defines the output ('visible text... navigation and boilerplate stripped, plus the title and final URL after redirects'). It differentiates itself from the many siblings by naming the exact output form and the JS-rendering behavior, so an agent can distinguish it from read_pages, page_brief, pdf_to_text and screenshot_page 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?

Has explicit 'When to use' and 'Use instead' sections naming the alternative tool and the condition that selects it (read_pages for 2-5 URLs, page_brief for summaries, pdf_to_text for PDFs, screenshot_page for appearance, attest_page for proof). Nothing is left to inference.

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

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

With readOnlyHint/openWorldHint already declaring the safety profile, the description still adds real behavioral context: real-browser JS rendering, 20,000-character per-page truncation, parallel reads where one failure doesn't stop others, per-call $0.008 x402 pricing, failed-calls-are-free, and the quote-then-pay flow via the payment param. This is far beyond what annotations convey.

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

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

Front-loaded with the core action and scoped well, with labeled When/Instead/Params/Returns sections. Slight redundancy: the 20,000-character truncation and per-page failure behavior are stated twice (opening paragraph and Returns), which costs a little tightness.

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?

No output schema exists, so the description carries the returns burden and does so fully: pages[] in input order with ok, title, final_url, text (or failure reason), plus pages_read/pages_failed and the billing condition. Pricing and the quote flow are also covered, leaving no gap 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 coverage is 100%, so the baseline is 3, but the description adds meaning: urls must be 1-5 absolute http(s) URLs read in parallel, and it explains the payment parameter's quoting workflow beyond the schema's terse 'omit to receive a quote'.

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 a specific verb and resource ('Read several web pages at once'), quantifies the batch (up to 5 URLs), and explicitly contrasts itself with read_page and search_and_read so an agent can distinguish it from siblings without opening schemas.

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

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

Has an explicit 'When to use' line ('You picked 2-5 pages to read, for example from web_search results') plus a 'Use instead' line naming read_page for a single URL and search_and_read for question-only flows. When, when-not, and alternatives are all present.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds rich behavioral detail beyond them: cost ($0.003 USDC per capture), no charge for failed loads, first 3 calls/day free, image size (50-150 KB base64), and the quote-then-sign payment sequence.

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 capability and organized into labeled sections, making it easy to scan. It is somewhat repetitive ('see a page's layout' appears in the opening and again under 'When to use'), costing a bit of tightness.

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 no output schema, the description fully covers return values (JPEG base64, sha256, title, final_url), pricing behavior, and the payment workflow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates url constraints (absolute http(s), public) and the payment quote flow, which the schema already conveys, adding little beyond the structured fields. 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 names a specific verb and resource ('Capture how any public web page looks') and specifies the concrete output: a 1280x800 JPEG from a real browser with SHA-256, title, and final URL. It clearly distinguishes itself from siblings by routing to read_page and attest_page.

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 'When to use' and 'Use instead' sections name the exact alternatives (read_page for text, attest_page for signed evidence) and the conditions that select each. The x402 payment flow ('Call without payment to get a quote') and the free-call tier add actionable context.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds substantial behavioral context: x402 pricing ($0.005 USDC/call), that failed calls are free, the payment-quote handshake, the 12,000-character read cap, and the skip-to-next-page fallback. This is exactly the kind of cost/auth/failure behavior annotations cannot express.

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

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

Front-loaded with the core capability and organized into When-to-use / Use-instead / Parameters / Returns sections. Slightly redundant – the return payload (results plus full page text) is described both in the opening sentence and again in the 'Returns' line.

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 no output schema, the description still explains the return shape (ranked results plus full text of top pages, char cap) and the payment flow. For an 8-parameter open-world tool, 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?

Schema description coverage is 100%, so the schema already documents every parameter. The description restates the filter families and defaults (num 1-3 default 3) without adding syntax or semantics 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?

States a specific compound verb and resource: search the web AND read the top 1-3 pages, rendered in a real browser. It explicitly differentiates from siblings web_search and read_pages, so an agent can route correctly without opening schemas.

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

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

Contains an explicit 'When to use' clause and a 'Use instead' clause naming web_search and read_pages with the selecting condition ('snippets are enough', 'want to choose which pages'). Nothing is left to inference.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the x402 pricing model ($0.002 USDC per call), that failed calls are free, the quote-then-pay flow via the payment parameter, and a free daily-tier limit. These are operational facts an agent cannot get from annotations or schema alone.

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

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

Front-loaded with the core purpose, then clearly sectioned into pricing, when-to-use, alternatives, parameters, and returns. Slightly repetitive restating parameters already in the schema, but no filler sentences.

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 no output schema, the description fully covers the return shape (fields and filings[] with form/date/link), the payment prerequisite, and the ticker-or-CIK input requirement. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the payment quote flow. The description adds only example form values (10-K, 10-Q, 8-K, 4) and restates the limit range, which is marginal added value; baseline 3 applies.

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

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

Specific verb+resource: 'Look up a US public company in SEC EDGAR by ticker or CIK' with an enumeration of exactly what is returned (name, exchange, industry, state, FY end, filings with links). It explicitly differentiates itself from the three sibling SEC/company tools, so an agent can pick it without opening schemas.

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

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

Contains explicit 'When to use' and 'Use instead' lines naming the exact alternatives (sec_financials for numbers, company_snapshot for profile+numbers, company_due_diligence for ratios and 8-K summaries). Routing is unambiguous.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely new behavioral context: a $0.004 USDC x402 price, that failed calls are free, and a two-step quote-then-sign payment flow via the optional `payment` parameter. It does not cover latency or data freshness, so not a full 5.

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

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

Front-loaded and well-sectioned with When/Use/Parameters/Returns headers, but the Returns section repeats the opening field list almost verbatim (revenue, operating and net income, diluted EPS, assets, liabilities, equity, cash, operating cash flow, shares), which is wasted 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?

With no output schema, the description carries the return-shape burden and does so, listing the fields and their coverage window (4 fiscal years plus latest quarter, each tied to its filing). The payment mechanic is also explained end to end.

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

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

Schema coverage is 100%, so the schema documents cik, ticker and payment, making 3 the baseline. The description earns above baseline by stating 'ticker or cik (one is required)' — a constraint the schema does not enforce, since the required array is empty — and by hinting at the quote flow for `payment`.

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 names a specific verb (Get) and resource (US public company financials as filed with the SEC) and enumerates the exact line items returned, so an agent knows precisely what it gets. It also distinguishes itself from siblings by naming company_snapshot and company_due_diligence as different scopes.

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 'When to use' plus a 'Use instead' clause that names two alternative tools and the condition under which each is preferable. Nothing about 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.

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that — the $0.004 USDC x402 cost model, that failed calls are free, the quote-then-sign payment flow via the `payment` param, and a free tier of 3 calls/day. This is exactly the kind of cost/auth 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 the core purpose and payment terms, and organized into clear labeled sections. Mild redundancy: the warning list (owner, upgradeable, mint/pause/blacklist/fees, Solana mint/freeze authority) is stated twice, once inline and again under 'Returns'.

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 no output schema, the description fully covers the return contents in plain language, plus payment flow and free-tier limits. An agent has everything needed to quote, pay, call and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all three params including the chain enum and default. The description restates token/chain meaning and defaults, adding little beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check a token') plus scope (which chains, what is returned: identity, USD price, liquidity, chain-read warnings). It distinguishes itself from siblings by explicitly contrasting with token_info and pretrade_check.

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 'When to use' trigger (before buying, accepting or sending an unfamiliar token) and a 'Use instead' section naming pretrade_check for sized trades and token_info for basics only, with the differentiator for each. No inference required.

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

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

Annotations only declare readOnlyHint and openWorldHint. The description adds information they cannot carry: the x402 payment model ($0.002 USDC per call, failed calls cost nothing, first 3 calls/day free, call without `payment` to get a quote), data freshness ('read live from the chain'), and the limits of what is returned versus crypto_market_pulse.

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 verb/resource, then pricing, routing, params and returns in a scannable order. It loses a point for mild duplication: 'Use it to confirm what an address actually is before acting on it' and 'When to use: ... before acting on it' say the same thing twice.

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?

No output schema, but the description enumerates the return fields itself, and it covers the payment/quote flow, chain options and sibling routing. Nothing needed to invoke 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 the baseline is 3. The description restates the token and chain parameters (including the 'base' default) but says nothing about the `payment` parameter beyond the separate pricing paragraph, adding marginal meaning over 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 and resource ('Look up a token on Base, Ethereum (ERC-20 contract) or Solana (SPL mint)') and enumerates the exact fields returned (name, symbol, decimals, total supply, Solana authorities). It also names the sibling tools it is not (token_check, token_price), so an agent can route 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?

Contains an explicit 'When to use' line ('You have a token address and need to know what it is before acting on it') and an explicit 'Use instead' line directing safety/liquidity queries to token_check and price queries to token_price. Both the trigger and the alternatives are spelled out.

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

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

Annotations cover only readOnlyHint and openWorldHint, so the description carries real weight and does: it discloses the data source and pool type, the thin-liquidity trust caveat, the x402 pricing ($0.001 USDC per call, free failures, 3 free calls/day), and the quote-then-pay flow. This is exactly the behavioral context an agent needs before spending money.

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 answer and cleanly sectioned under 'When to use', 'Use instead', 'Parameters', and 'Returns'. It is on the long side for a three-parameter tool, and the Returns paragraph partly repeats the liquidity/thin-pool detail already stated in the opening sentence, costing a point.

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 no output schema, the description compensates by enumerating the return fields (price_usd, pool, liquidity, thin_liquidity flag), the chains, the pricing model, and the quote/pay workflow. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so 3 is the baseline and the description's parameter section largely restates the schema ('SOL' on Solana, chain default). It earns one step above baseline by explaining the payment round-trip — omit `payment` to receive a quote, then sign and call again — which the schema only implies.

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 ('Get a token's current USD price'), names the supported chains, and discloses the non-obvious methodology (deepest on-chain pool via Uniswap v3 / Orca Whirlpools rather than a price API). It is clearly distinguishable from price_history, token_check, and crypto_market_pulse.

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?

Has explicit 'When to use' and 'Use instead' sections that route the agent to three named alternatives with the conditions that select each (past prices, price plus safety warnings, BTC/ETH/SOL batch). Nothing is left to inference.

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

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

The annotations already mark it read-only and open-world, and the description adds important behavioral details: per-call pricing, free failed calls, quote behavior, and a free daily allowance. It also discloses what is returned even without an output schema.

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

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

The description is front-loaded with purpose and return contents, followed by concise payment and usage notes. There is some repetition between the opening sentence and the final Returns line, but the structure remains 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 lookup tool with no output schema, the description is complete enough: it covers chains, hash formats, return fields, pricing, and payment flow. An agent has what it needs to decide whether and how to call it.

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

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

Schema coverage is 100%, so the schema already documents the parameters well. The description still adds useful semantics by clarifying hash formats, chain defaults, and the critical constraint that the chain must match the hash.

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: look up a transaction on Base, Ethereum, or Solana. It also spells out the core outcome and return contents: success status, time, sender, fee, and token movements. This is clearly distinguishable from sibling tools such as wallet_balance or token_check.

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 says when to use the tool: when you have a transaction hash and need to know if it went through and what moved. It also explains the payment/quote flow, but does not name alternatives or explicit when-not 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?

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantive context beyond them: zero cost, zero arguments, the fixed sample limitation, and the guarantee that the output shape and code path are identical to get_product_details. That is meaningful behavioral disclosure the structured fields do not carry.

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

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

Front-loaded and largely disciplined, with the core value proposition in the first two sentences. There is mild redundancy — the 'When to use'/'Use instead'/'Returns' block restates points already made in the opening paragraphs — but it stays scannable and short.

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 zero-argument preview tool, the description covers what it does, why it exists, what it costs, what it returns (mirroring get_product_details, with an output schema backing that up), and why the page cannot be chosen. Nothing an agent needs in order 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?

Zero parameters, so the baseline is 4; the description affirmatively confirms 'It takes no arguments,' which removes any ambiguity. There is nothing more to document, but it doesn't need to go beyond that confirmation.

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 ('run a real extraction against one fixed sample product page') plus the key constraint (no arguments, fixed page). It explicitly contrasts itself with get_product_details, so an agent can distinguish the free preview from the paid sibling without reading either schema.

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

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

Gives explicit when-to-use ('Before paying, to see exactly what get_product_details returns'), an explicit when-not-use with reasoning ('pointing a free endpoint at arbitrary URLs would just be the paid tool with no toll'), and names the alternative to use instead. All guidance an agent needs to route correctly is present.

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

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

Beyond the readOnly/openWorld annotations, it discloses auth context (free, no account), statelessness (holds no database), and the key behavioral edge case that attestations from other issuers return a clear 'no'. This is exactly the extra 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 and organized with When to use / Parameters / Returns sections. Slightly padded by promotional phrasing ('Free, forever, no account', 'which is the point'), but every structural element earns its place.

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 no output schema, the description compensates by summarizing the return values (signature validity, issuer match, reasons). For a single-parameter verification tool, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the description's parameter note restates the schema text almost verbatim (full attest_page response or just its attestation object). Baseline 3 is appropriate since the schema does the work with no added meaning.

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

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

States a specific verb and resource: hand in an attestation and learn whether the signature is valid and whether this service issued it. It also implicitly separates itself from the sibling attest_page by naming it as the producer of the artifact being checked.

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 'When to use' line gives two concrete triggers: someone handed you an attestation, or you want to check one of your own. No when-not guidance or named alternative tool, but the use case is unambiguous.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing pricing ($0.002 USDC per call over x402), that failed calls are free, the 3-free-calls-per-day policy, and the quote-then-pay flow via the payment parameter. This is exactly the extra 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 what the tool does, then cleanly sectioned into when-to-use, alternatives, parameters, and returns. Some content (chains, tokens, returns) is repeated across the body and the Parameters/Returns sections, but every section is useful.

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 no output schema, the description carries the return shape itself (native coin, USDC/USDT, listed tokens with symbol, decimals, amount), and it covers payment flow, pricing, and alternatives. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents address formats, chain enum, and the 20-token cap. The description largely restates these ('address is required', 'chain: base default', 'tokens: up to 20'), adding only the cross-parameter constraint that the address format must match the chain, which the schema already implies.

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 (checks a wallet's token balances) and scopes it precisely across chains, naming exactly which balances are returned. It distinguishes itself from wallet_portfolio and check_my_balance by naming both.

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?

Has explicit 'When to use' and 'Use instead' sections that route the agent to wallet_portfolio for USD totals and check_my_balance for the caller's own USDC. Alternative selection is fully specified, not inferred.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuine operational context the annotations don't carry: x402 pricing ($0.005 USDC per call), that failed calls are free, and the quote-then-sign flow. It also discloses the thin-pool and oversized-position warning behavior. It stops short of describing latency, caching, or pool-source reliability.

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 pricing, then usage, then parameters and returns in clearly labeled blocks. Slight redundancy: the holdings/total/warnings output is stated both in the opening sentence and again in the Returns line, which costs a bit of 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?

There is no output schema, so the description carries the return contract and does so: holdings[] shape, the USD total, and the warning conditions. Combined with the pricing and payment workflow, 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?

Schema coverage is 100%, so every parameter is already documented in the schema, including the base default, the 20-item token cap, and the address formats. The description restates these (address required, chain default, tokens up to 20) without adding format or syntax meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Value a wallet in USD'), names the supported chains, and enumerates what is produced (per-holding prices, total, warnings). It explicitly differentiates itself from the sibling wallet_balance, so an agent can route without opening either schema.

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

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

Contains an explicit 'When to use' line and a 'Use instead' line naming wallet_balance with the selecting condition ('when amounts are enough (cheaper)'). No inference is required to choose between the two.

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

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

Annotations already mark it read-only and open-world, but the description adds substantial behavioral context: US vs MET Norway data sources, units, NWS alerts, per-call pricing, failed-call cost, quote flow via omitted payment, and the free daily allowance. No annotation contradiction is present.

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 core purpose, then organized into usage, alternatives, parameters, and returns. The pricing and return details earn their place because payment and output behavior are not covered by an output 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?

Given a read-only, open-world forecast tool with no output schema, the description covers data sources, units, alerts, pricing/payment behavior, parameter choices, and return structure. An agent has enough information 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?

Schema description coverage is 100%, so parameter basics are already documented. The description clarifies the lat/lon-or-address choice and summarizes periods as 1-14 twelve-hour periods with default 14, but mostly mirrors the schema rather than adding deep semantics.

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

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

The description states a specific verb and resource: get the weather forecast for lat/lon or a US address, including 7-day day/night periods and alerts. It explicitly distinguishes siblings by naming airport_delays and geocode_address as alternatives for different needs.

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

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

It gives a clear 'When to use' condition and explicitly names when to use other tools instead: airport_delays for flight delays and geocode_address when coordinates are needed for something else. This leaves little ambiguity about tool selection.

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

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

Annotations cover only readOnly/openWorld, but the description adds substantial context beyond them: exact pricing ($0.003 USDC over x402), that failed calls are free, the quote-then-pay flow via the payment param, and the refusal behavior ('very narrow filters can return nothing (refused free)'). This is exactly the behavioral detail an agent needs before spending money.

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 output shape, then filters, pricing, and when-to-use routing. Well-organized with clear sectioning, though it runs long and restates some schema-provided details (num range, freshness enum) that could be trimmed.

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?

No output schema exists, yet the description fully enumerates the return shape (results[] with position/title/url/snippet/date, answer box, applied filters), and all 8 params plus the payment flow are covered. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: that freshness/include_domains/exclude_domains 'can combine' and that very narrow combinations can return empty results. The payment/quote flow and the num default are also restated usefully.

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 ('Search the web and get Google's top results as clean JSON') and immediately distinguishes itself from siblings by naming search_and_read for full text and crypto_news for crypto coverage. An agent can pick this over its neighbors without opening either schema.

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

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

Explicit 'When to use' ('You need sources or facts and don't have URLs yet') and 'Use instead' sections routing to search_and_read and crypto_news with the exact condition that selects each. Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the payment model ($0.10 USDC per call, failed calls free, omit `payment` for a quote), the data provenance (Coinbase's Bazaar catalog), and the refresh cadence (rebuilt weekly). These are operational facts an agent cannot infer from annotations or schema.

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

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

Front-loaded and cleanly labeled with 'When to use / Use instead / Returns', which makes it scannable. However, the seller-field list and the 'rebuilt weekly' fact are each stated twice almost verbatim (opening sentence vs. Returns line), which is avoidable repetition in a short 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?

With no output schema, the description carries the return-shape burden and does so fully, listing every field plus category totals. One optional parameter, zero required, pricing and cadence disclosed — 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 the schema already documents the quote-vs-pay flow for `payment`, so the baseline is 3. The description reinforces the flow with the cost consequence ('Failed calls cost nothing'), which adds meaning about the economics of the parameter rather than just restating its syntax.

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 ('Get the whole x402 market as one dataset') and enumerates exactly what the dataset contains (rank, 30-day calls, revenue, paying wallets, categories, labels, category totals). It explicitly distinguishes itself from x402_seller_lookup and best_x402_tools, so an agent can route without opening any schema.

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

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

Has an explicit 'When to use' condition ('analysing the whole x402 market and want every seller in one file') and a 'Use instead' clause naming the two cheaper alternatives for single-seller or task-scoped queries. This is the full when/when-not/alternative triad.

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

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

Annotations cover read-only/open-world, and the description adds substantial context beyond them: the $0.02 USDC per-call cost, that failed calls are free, the two-step quote-then-pay flow, and the weekly freshness/source (Coinbase Bazaar). This is real operational disclosure with no contradiction of readOnlyHint.

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?

Well front-loaded: what it is, then pricing, then when-to-use, parameters and returns. Slightly redundant since the Returns line restates the opening enumeration, but the labeled sections make the redundancy cheap.

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 no output schema, the description must carry return-shape burden and does: it lists the returned fields, plus pricing, failure behavior, quote flow, and data cadence. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the example hostname and frames the payment parameter as a quote-first workflow with associated cost, giving meaning beyond the schema's bare 'Omit it to receive a quote'.

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 (look up) and resource (x402 seller by hostname) and enumerates exactly what comes back: rank, calls, revenue, wallets, endpoints, categories, competitors. This clearly distinguishes it from the broader x402_market_dataset sibling.

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 'When to use' line states the condition explicitly (you want ONE seller's numbers), which implicitly excludes the dataset-wide sibling. It stops short of naming that alternative or stating when-not-to-use, so it is clear context rather than full routing.

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?

Adds substantial context beyond the read-only and open-world annotations: the 24-hour window, exclusion of giveaways/bots/paid promotion, unverified and potentially coordinated posts, and the warning not to treat it as a trading signal. It also discloses pricing and payment flow.

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 output and caveats, then clearly separates when to use, alternatives, parameters, and returns. Every section is purposeful, and the structure makes scanning easy.

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 no output schema, the description explains the return shape in detail and covers cost, quote behavior, limitations, alternatives, and parameters. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is already 100%, including examples and the either/or relationship between coin and query. The description restates the same parameter guidance and does not add meaningful syntax or edge-case semantics 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 exactly what the tool returns: the mood on X about a coin or crypto topic in the last 24 hours, along with score, post volume, themes, and links. It clearly distinguishes itself from siblings by naming crypto_news for articles and crypto_market_pulse for metrics.

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?

Provides explicit when-to-use guidance ('You want to know what crypto traders on X are saying about a coin right now') and names alternative tools for different needs. It also explains payment behavior, including quote-before-pay and free failed calls.

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