Hearth: x402 Pay-Safety & Discovery

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

The description goes far beyond simple functional behavior, detailing operational constraints like input limits (up to 2,000 chars prompt), token limits (600 output), and the specific payment protocol required. This is vital operational context not found in the 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?

While dense, every sentence provides unique and high-value information (pricing, token limits, payment mechanism, usage goal). The description is highly efficient, prioritizing critical operational facts at the start.

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 integrating a payment/LLM service, the description is fully complete. It covers function, constraints, financial terms, and the necessary integration requirements (payment handling), leaving no major gaps for the AI agent to encounter during execution.

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?

Since schema coverage is 100%, the baseline is high. The description reinforces parameter semantics by specifying the functional roles of `prompt` and `system` messages within the context of a cost-optimized completion service.

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 immediately establishes the tool's purpose: cheap LLM chat completion. It clearly defines the resource (LLM completion) and differentiates itself from standard proxies by highlighting its low flat fee.

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 provides critical usage context by defining the cost ($0.002) and the required payment mechanism (USDC on Base via x402), making it clear when this specific, cost-optimized tool should be used.

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 the safety profile (readOnlyHint, openWorldHint), but the description adds critical behavior an agent could not infer: missing values return null, the 20-field cap, an output example, and the $0.02 USDC x402 payment requirement passed via _meta. The payment/auth disclosure is exactly the kind of operational context annotations 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 with the verb and purpose, then examples, limits, output shape, and pricing in a compact paragraph. The inline output example is slightly verbose but earns its place by removing ambiguity about the return shape.

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 an example return object; with two required params, it explains both their format and edge-case behavior. Pricing and the payment channel are also disclosed, so 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; the description earns above that by giving concrete field-name examples ('fields=name,price,currency,availability') and restating the comma-separated max-20 convention plus null behavior for absent fields.

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 ('Extract structured JSON from a web page') and immediately clarifies scope ('Fetch a public web page and extract the fields you name'). An agent can distinguish this from ai_summarize or the chain-query 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?

The description establishes clear context — public http(s) pages, up to 20 named fields — which tells the agent when the tool applies. It stops short of explicitly naming an alternative (e.g., ai_summarize for prose) or stating exclusions, so it lands at 4 rather than 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 already declare readOnlyHint and openWorldHint, yet the description still adds genuinely non-obvious behavioral context: the tool is paid ($0.015 USDC on Base via x402) and the payment must be supplied in _meta["x402/payment"], which an agent cannot learn from annotations or schema. The "public" constraint further signals it will not work on gated content. Minor gap: no disclosure of fetch-failure, non-HTML, or rate-limit behavior.

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 verb and resource, then output shape, then the concrete example, then pricing. Dense but every element earns its place; the lack of an output schema makes the example payload and payment note worth the length. Slightly run-on in the opening sentence.

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

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

With no output schema, the description compensates by giving an explicit example response shape, and it covers the payment/auth prerequisite that would otherwise be a silent failure mode. It stops short of describing edge-case behavior (unreachable URLs, paywalled or JS-heavy pages) or the effect of the `focus` parameter, which for a paid call is a meaningful omission.

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 `url` and `focus` are already documented in the schema, making 3 the baseline. The description reinforces the URL requirement and shows a URL in the example output, but says nothing about `focus` — arguably the parameter where extra meaning (how a focus question steers the summary) would have most 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?

States a specific verb and resource ("Fetch a public web page and return a concise summary") and enumerates the exact output shape: title, 3-7 key points, TL;DR paragraph, entities. It does not explicitly differentiate from the sibling ai_extract, so the agent must infer that summarization differs from structured extraction, but the phrase "gist of a URL" helps.

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?

"Good for research agents that need the gist of a URL cheaply" implies a use case, and "public web page" implicitly excludes authenticated/private URLs. However, no explicit when-to-use vs. when-not, and the obvious alternative (ai_extract) is never named, leaving the routing decision 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=true and openWorldHint=true, so the safety profile is covered. The description adds substantial context beyond annotations: the output shape, an example response, the price and payment mechanism, and the fact that it returns both a summary and structured facts. This is strong behavioral disclosure for an AI-powered, paid, read-only lookup.

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 and then adds return format and pricing details. The example output is somewhat lengthy, but it earns its place by illustrating the summary-plus-facts return shape that is not captured in 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?

There is no output schema, so the description carries the burden of explaining returns; it does so with a clear example and a statement that it returns a summary plus structured facts. Combined with the pricing and payment requirement, an agent has enough context to invoke 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 description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the supported chain values and implies the hash identifies the transaction, but it does not add much syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Explain a transaction in plain English (AI)' and specifies the supported chains. It is clearly distinguished from siblings like base_tx_status or token_transfers because it produces a natural-language summary rather than raw status or transfer lists.

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

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

The description makes the tool's purpose and supported chains clear, and it explains that payment is required via x402 in _meta. However, it does not explicitly say when to choose this over base_tx_status, token_transfers, or evm_block, nor does it state exclusions such as unsupported chains or failed lookups.

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 read-only/open-world annotations, the description discloses determinism, no LLM involvement, decimal application, and crucially that the tool is paid via x402 with a specific price and payment meta field. It does not cover error behavior, but the non-obvious payment requirement is well surfaced.

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 core operation is front-loaded in the first sentence, followed by useful defaults, output example, and payment details. There is slight repetition between the first two sentences, but information density is good.

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 example output effectively documents the return shape and applied decimals. Payment and chain/token defaults are included; only edge-case or error behavior is left unaddressed.

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 chain, token, and wallet parameters. The description reinforces defaults and supported chains but adds limited parameter-specific 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?

The description states a specific verb and resource: fetching ERC20 token balances for a wallet via balanceOf. It names the supported EVM chains and default token, which distinguishes it from sibling tools like solana_balance and wallet_portfolio.

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 intended use case is clear: read a single ERC20 token balance across several EVM chains, defaulting to Base and USDC. It does not explicitly compare against alternatives such as wallet_portfolio or token_price, but the context is sufficiently clear for correct 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 only declare readOnlyHint and openWorldHint, so the description's disclosure that the tool is deterministic with no LLM, plus the required $0.004 USDC x402 payment passed in _meta['x402/payment'], adds genuinely useful behavioral context an agent cannot get from annotations. It stops short of describing failure behavior, e.g. what happens for an EOA address where isContract would be false.

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, followed by scope, behavioral notes, a concrete example and pricing — all sentences carry information. The inline example output is bulky but justified because no output schema exists.

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 returned fields and giving a full example response, and it discloses the payment requirement and supported chains. Only edge-case behavior (non-contract addresses, missing metadata) is left unaddressed.

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 worked example supplies a canonical checksummed address and shows chain="base" in use, clarifying expected formats and the default. Chain values are already listed in the schema, so the added meaning is modest.

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 precise resource and enumerates exactly what is returned (name, symbol, decimals, total supply, bytecode presence), which sharply bounds the tool's scope and implicitly separates it from token_price or token_safety. It never explicitly names a sibling, 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?

Usage is only implied: it says the tool works for a token contract on Base, Ethereum, Arbitrum or Optimism, from which an agent can infer when it applies. There is no explicit 'use this instead of token_price/token_safety/contract_abi' routing guidance, which would be valuable given several overlapping siblings.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds the material commercial and behavioral facts an agent cannot get elsewhere: it costs $0.004 USDC on Base via x402, payment must be passed in _meta["x402/payment"], and the operation is deterministic. It also gives a concrete example output object so the response shape is known.

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?

Content is dense and front-loaded with purpose, then return fields, then pricing. The opening two clauses are redundant ('Transaction status on Base. Status of a transaction on Base, Ethereum...'), costing a sentence that could be merged.

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 inline example output carries the return-value burden well, and the chain coverage, status values, determinism, and x402 payment mechanics cover everything an agent needs to invoke this 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% and both parameters are documented there, so the baseline of 3 applies. The description repeats the chain list and shows hash in the example output but adds no syntax, format, or default 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?

Names a specific verb+resource (transaction status) and enumerates exactly what is returned: pending/success/failed, block, confirmations, from/to, gas used, log count. The phrase 'Deterministic, no LLM' implicitly separates it from the sibling ai_tx_explain, 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?

Usage is only implied: 'Deterministic, no LLM' hints this is the raw-data path versus ai_tx_explain's interpretation, and the supported-chain list scopes it. There is no explicit when-to-use/when-not statement or named alternative, leaving the agent to infer the 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?

Beyond annotations, the description adds important behavioral context: deterministic/no-LLM execution, a concrete example output, and an explicit payment requirement via x402 in _meta. It does not cover error behavior or rate limits, but it materially improves transparency for an annotated read-only tool.

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

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

The description is front-loaded with the core purpose and output fields, and the example and payment note earn their place for a paid tool without an output schema. There is minor redundancy around 'on Base' versus the multi-chain support, but overall it is 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 simple two-parameter read tool with no output schema, the description supplies the returned fields, an example response, supported chains, and payment instructions. It is nearly complete, though it could clarify error behavior or whether payment is required for non-Base chains too.

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 chain and address parameters are already documented in the schema. The description repeats the supported chains but adds no new syntax, format, or constraint details beyond what the schema 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 description states a specific resource and scope: a wallet snapshot returning native ETH balance, nonce, and contract status across four chains. This clearly distinguishes it from sibling tools such as base_erc20_balance (token balances) and wallet_portfolio, since it is explicitly limited to native ETH and contract/nonce metadata.

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

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

The description implies when the tool is useful by listing the returned fields and supported chains, but it does not explicitly say when to prefer it over alternatives like base_erc20_balance, wallet_portfolio, or solana_balance. No exclusions or routing guidance are provided.

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 readOnly/openWorld annotations: discloses the ~5,000-block (~3h) lookback window, the exact labeling sources, the deterministic/no-LLM nature, and critically a $0.012 USDC x402 payment that must be supplied in _meta['x402/payment']. That payment requirement is exactly the kind of behavioral detail annotations cannot 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?

The leading capability enumeration is front-loaded and useful, but the inline example output is long, eats a large share of the text, and is visibly truncated mid-string ('"walletType":"' then cuts to pricing), which reads as an editing error rather than an intentional summary.

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 correctly takes on the job of describing return values, and it does so with concrete field names and a sample. The truncated example and the absent sibling comparison keep it from being fully complete.

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

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

Only one parameter and the schema already documents it at 100% coverage ('EVM address on Base'). The description repeats the Base/EVM context but adds no format, checksum, or validation 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 resource and enumerates exactly what the profile returns (holdings with USD, nonce, EOA/contract, ERC20 flow over ~5,000 blocks, labeled counterparties, walletType). However it never distinguishes itself from closely named siblings like base_wallet or wallet_portfolio, so an agent must guess which 'wallet' tool to pick.

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?

'One-call Base wallet profile' implies this is the consolidated alternative to narrower tools, and 'Free public data, deterministic, no LLM' hints at when it beats ai_* siblings. But there is no explicit when-to-use vs. base_wallet/base_erc20_balance/wallet_portfolio 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?

Beyond the readOnly/openWorld annotations, the description discloses the traits an agent must actually know before calling: deterministic, no LLM, public-data-only sourcing, the exact set of sources (homepage, MX records), and critically the paid-call mechanics — $0.01 USDC on Base via x402 with the payment passed in _meta["x402/payment"]. It also supplies a concrete example response showing sparse fields such as emails:[] can come back empty.

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 and field list are front-loaded, followed by sourcing guarantees, an example, and the payment note — a logical order with little waste. The inline example payload is lengthy for the value it adds, so it is dense rather than wasteful, but not maximally tight.

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, and the example output covers the return shape, so return values need no further explanation. Combined with the payment/transport requirement and the data-source guarantees, an agent has everything needed to call 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?

There is only one parameter with 100% schema coverage, so the schema already defines it. The description adds a small but real amount: the example uses a bare "stripe.com" with no scheme or path, which signals the expected input format. It does not explicitly say whether a full URL is accepted or rejected, keeping it short of 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 ("Company / domain enrichment from its website") and then enumerates the exact extracted fields: name, description, socials, emails, phones, language, tech hints, mail provider, key pages. No sibling (github_repo, social_hn, token_safety, etc.) does full-domain company enrichment, so the boundary is unambiguous.

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

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

Usage is only implied: the agent infers it should be used when it has a company domain and wants firmographic/contact data. There is no explicit statement of when to prefer it over alternatives, no exclusions (e.g., personal domains or sites without a homepage), and no note on failure behavior for unenrichable domains.

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

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

Without annotations this would be thin, but beyond readOnlyHint/openWorldHint the description discloses the critical non-obvious traits: it costs $0.004 USDC on Base via x402 paid through _meta["x402/payment"], it is deterministic, it follows EIP-1967 proxies, and it returns unverified contracts with isContract/verified flags rather than erroring. Nothing contradicts 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?

The core capability is front-loaded, followed by output shape and price, and every element serves a purpose. The second sentence is a dense run-on that could be split, keeping it from a 5.

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

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

With no output schema, the inline example output is exactly what an agent needs to parse results (chain, verified, match type, proxyImplementation, functions/events, abi). Combined with chain coverage, the payment mechanism, and determinism, an agent can call and interpret this 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% and the schema already documents the chain enum values and its base default, so the description adds little parameter-level meaning beyond restating the chain list. Baseline 3 is appropriate.

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

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

The description names the specific resource (contract verification status and ABI) and enumerates exactly what is returned: name, compiler, full ABI, function/event signatures, and EIP-1967 proxy implementation. It is clearly distinct from siblings like base_token_info or token_safety, though it never explicitly contrasts itself with them.

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 supported chains and the 'Deterministic, no LLM' note imply when this tool fits (structured on-chain lookups rather than inference-based siblings like ai_extract), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative.

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: it discloses the exhaustive fee-tier scan, the exact returned fields, determinism ('no LLM'), and a concrete x402 payment requirement with the required _meta key. That payment/auth detail is exactly the kind of operational context annotations cannot 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 purpose, then scope, returns, constraints, and an example — every block is useful. The embedded JSON example is verbose but earns its place since there is no output schema, though it makes the description dense.

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

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

With no output schema, the example response fully covers the return shape (amountOut, price, feeTier, gasEstimate, venue). Supported chains, tokens, price, and payment mechanism are all present, so 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 all four parameters are already documented with defaults (base) and accepted token forms. The description restates the token list and chains but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('DEX swap quote (Uniswap v3)') and immediately scopes it: single-hop, four named chains, all fee tiers. An agent can distinguish it from token_price or the ai_* 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?

Usage is only implied — the phrase 'for swapping amountIn of tokenIn to tokenOut' suggests it is a pre-trade quote, and 'Read-only quote; no swap is executed' clarifies the boundary. But there is no explicit when-to-use/when-not guidance and no named alternative (e.g. token_price for a simple spot price).

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, the description adds materially new behavior: deterministic output with no LLM involvement, a concrete price ($0.001 USDC on Base), and the exact payment plumbing (_meta["x402/payment"]). These are things an agent must know before calling and cannot get from annotations or schema. It does not cover failure behavior for invalid block numbers.

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 in the first sentence, followed by return fields, then payment terms. The embedded example JSON is verbose but justified since there is no output schema. Every sentence carries 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?

With no output schema, including a full sample response object (chain, number, hash, timestamp, iso, txCount, gasUsed, gasLimit, baseFeeGwei) is the right compensation, and the paid-call mechanics are spelled out. Minor gaps remain around error handling and what 'deterministic, no LLM' implies for caching, but nothing blocking prevents a correct 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 both parameters (chain enum, block number) are already fully documented in the schema. The description restates the chain list and the 'latest' default without adding format or edge-case meaning. 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?

Opening sentence states a specific resource and retrieval mode (latest block or by number), and the second sentence enumerates exactly what is returned across four named chains. It reads clearly as a block-fetch tool, though it never explicitly distinguishes itself from the sibling evm_gas, which covers overlapping gas/base-fee territory.

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

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

Usage is only implied: 'latest block or block by number' plus the default of 'latest'. There is no statement of when to prefer this over evm_gas, base_tx_status, or ai_tx_explain, and no exclusion conditions. An agent must infer the routing decision from sibling names alone.

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 read-only/open-world, but the description adds what an agent actually needs: deterministic/no-LLM behavior, a concrete price ($0.003 USDC on Base via x402) with the exact payment mechanism (_meta["x402/payment"]), a cost comparison, and a literal example response payload. That is substantial behavioral disclosure 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 with the core capability and the cost rationale before the example and price details. There is mild redundancy between "Batch: up to 10 blocks in one call" and "Batch block lookup: latest block plus up to 10 block numbers," but every other sentence (pricing, payment field, example) carries real 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 supplies an inline example output covering all returned fields, plus payment requirements and cost tradeoffs. An agent has everything needed to invoke this 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 both parameters are already documented, and the description mostly restates them (chain options, comma-separated numbers, max 10, omit for latest). It adds the useful framing that the response includes the latest block alongside the requested numbers, but no new syntax or edge-case detail.

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 (batch block lookup) with explicit scope: latest block plus up to 10 comma-separated block numbers across four named chains. It also implicitly separates itself from the single-block sibling evm_block by advertising batching and cost savings.

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?

"Batch: up to 10 blocks in one call" plus "Costs less than 10 single calls" makes the selection condition clear: use this when fetching multiple blocks. It stops short of explicitly naming evm_block as the alternative for single-block lookups, so the routing is strongly implied rather than spelled out.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses two non-obvious behavioral facts: the tool is deterministic with no LLM involved, and it is a paid call ($0.001 USDC on Base) requiring a payment passed in _meta["x402/payment"]. It does not say what happens if payment is missing or invalid, which keeps 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?

The purpose and chain scope are front-loaded in the first sentence, with cost and payment mechanics last. The inline JSON example is somewhat lengthy but earns its place because no output schema exists.

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 single-optional-parameter read tool, the description covers what it returns (via the example payload), which chains it covers, that results are deterministic, and how payment works. There is no output schema, yet the sample output substitutes for one adequately.

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 only one parameter and schema coverage is 100%; the schema already lists base/ethereum/arbitrum/optimism, and the description merely restates that chain set and the default. Under the high-coverage rule this lands at the baseline of 3 with no added syntax or constraint detail.

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

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

The description opens with a specific verb-and-resource pairing ('Gas price and fee estimate') and immediately enumerates the exact returned fields (gasPrice, baseFee, priorityFee, EIP-1559 maxFee, transfer cost). It also scopes the supported chains, which cleanly separates it from siblings like evm_block or token_price.

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

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

It states the supported chains and that 'base' is the default, which implies the intended usage context (estimating transaction fees on a given EVM chain). However, it never says when to prefer this over a sibling such as evm_block, nor any exclusion or prerequisite for calling 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 already declare readOnlyHint and openWorldHint. Beyond that, the description adds valuable context: the tool is deterministic with no LLM, it costs $0.003 USDC on Base via x402, and payment must be passed in _meta['x402/payment']. It also includes an example output shape.

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, followed by return fields, an example, and pricing. The example JSON is somewhat long but useful for understanding the output, and every section contributes relevant 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?

There is no output schema, so the description compensates by listing return fields and providing an example output object. It also covers the non-obvious payment requirement and confirms the operation is deterministic and read-only.

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 'repo' parameter, which is documented as 'owner/name'. The description does not add new parameter constraints, but the example output shows the expected repo format as 'coinbase/x402', reinforcing the schema.

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

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

The description gives a specific verb and resource: 'GitHub repo stats and latest release', then enumerates the snapshot fields. It does not explicitly contrast with sibling tools, but none of the listed siblings overlap, so the purpose is still clear.

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 describes what the tool returns but gives no explicit when-to-use, when-not-to-use, or alternative guidance. An agent can infer that this is for fetching GitHub repository metadata, but no routing guidance is provided.

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 readOnly and openWorld, but the description adds genuinely non-obvious behavior: it is deterministic with no LLM, and it is a paid x402 endpoint costing $0.004 USDC on Base with payment passed in _meta['x402/payment']. That payment requirement is critical context an agent could not infer from the schema or 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?

The scope statement is front-loaded and the payment detail is placed last where it belongs. The opening two fragments ('Crypto market overview: total cap, dominance, trending.' and 'Crypto market snapshot: ...') are partly redundant, though the inline example output earns its space given no output schema exists.

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 full example response showing every field an agent will receive, plus the payment mechanics and determinism guarantee. Nothing an agent needs to call this 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% and the single optional 'trending' parameter is fully documented there with its 1-15 range and default of 10. The description adds nothing beyond that, 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?

The description states a specific resource and scope: a market-wide snapshot covering total cap, 24h volume, dominance, active coins and trending coins. This clearly separates it from single-asset siblings such as token_price or base_token_info, though the description never names those alternatives explicitly.

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

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

Usage is only implied by the content shape ('market overview' vs. per-asset tools). There is no explicit when-to-use statement, no when-not-to-use, and no mention of how it relates to wallet_portfolio or token_price.

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, and the description adds important behavior: on-chain, deterministic, no LLM, plus payment requirements via x402. It also provides a sample output, though it does not discuss failure modes or latency.

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 and mostly efficient, with purpose, examples, determinism, output sample, and payment details. The opening 'ENS / Basename resolve' is slightly redundant with the tool name, but the rest 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?

For a simple one-parameter read-only resolver, the description covers purpose, input forms, output example, execution model, and payment requirements. An agent has enough information to invoke it correctly without an output schema.

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 single input parameter is already documented. The description adds useful semantics beyond the schema by showing both accepted input forms and the bidirectional resolution behavior.

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/resource: resolve ENS/Basename names to addresses and addresses to primary ENS names. It gives concrete examples for both directions, making the tool's purpose immediately clear. No sibling tool appears to overlap directly.

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 clearly explains the two supported input forms and what each returns, which tells an agent when this tool is appropriate. It does not name alternatives or explicit exclusions, but there are no obvious sibling alternatives for this capability.

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 three things an agent cannot infer: IPFS/Arweave URIs are resolved to gateway URLs, output is deterministic (no LLM), and the call is paid ($0.007 USDC on Base via x402, payment passed in _meta["x402/payment"]). The payment prerequisite in particular is critical and would otherwise cause silent failures.

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 a two-word purpose followed by capability, chain scope, resolution behavior, and payment terms. The inline example output is long but earns its place because no output schema exists. The pricing sentence is dense but functional rather than 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 three simple parameters, full schema coverage, and no output schema, the description covers the essentials: return shape via example, URI resolution, chain options, and payment mechanics. It stops short of stating failure modes (non-contract address, unreachable IPFS, unsupported token standard) or whether metadata is cached.

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 contract, tokenId and chain are already documented, including the base default. The description only echoes the chain list and shows tokenId as a string in the example; it adds no format or constraint details beyond the schema, so the baseline 3 applies.

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

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

The description names the resource (NFT metadata) and precisely enumerates what is returned: tokenURI plus resolved JSON fields (name, description, image, attributes) for ERC-721/ERC-1155 tokens on four named chains. It is far more specific than a title restatement, but it never names the closest sibling (nft_owner) to draw the metadata-vs-ownership boundary.

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 scopes applicability by token standard (ERC-721/ERC-1155) and by supported chains, which implicitly tells the agent when the tool is valid. However, there is no explicit when-to-use statement, no exclusion, and no pointer to an alternative such as nft_owner or contract_abi.

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 critical context beyond them: determinism/no LLM, a concrete example return shape, and an explicit payment requirement (x402, $0.0025 USDC, passed via _meta["x402/payment"]). The paid-call auth/payment detail is exactly the behavior an agent cannot get from 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?

One dense paragraph: purpose and chains first, then determinism, then output example, then price. Every element (including the example and the payment note) carries information the agent needs, with 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, and the description compensates with an inline example response covering chain, contract, tokenId and owner. Combined with the payment details and chain coverage, 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 chain, tokenId (decimal), and contract. The description repeats the chain list without adding format or constraint detail, 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 the specific verb+resource ('Current owner of an ERC-721 token') and names the exact underlying call (ownerOf), plus the supported chains. This is unambiguously separable from sibling tools like nft_metadata or token_safety.

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

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

Usage is implied by naming the ERC-721 ownerOf semantic and the supported chains, which tells an agent what the tool can answer. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. nft_metadata for attributes), so routing relies on 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?

Adds substantial context beyond the readOnly/openWorld annotations: pricing at $0.25 USDC via x402 with the payment passed in _meta['x402/payment'], a free sample endpoint, and the no-charge policy when a token can't be analyzed. It also discloses the dual nature of the response (facts plus AI write-up) so the agent can audit reasoning.

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 lead sentence is well front-loaded, but the body is a single dense run-on that packs an entire feature list into one block. The trailing example output is truncated and garbled ('facts':{'to. Price: $0.25 USDC…), which costs clarity even though the example itself 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 compensates fully by enumerating every returned field family and pasting a concrete sample JSON with schema id, verdict, riskScore, keyRisks, greenFlags, verifyNext, and facts. Billing, failure policy, and a free trial path are all covered, leaving nothing an agent needs before calling.

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%, with chain defaults and allowed values already documented in the schema. The description adds nothing about parameter behavior (e.g., what happens with an unsupported chain or a non-contract address), 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?

Opens with a specific verb+resource: a 'full token / contract due-diligence report (risk score + AI analyst write-up)' for an ERC20 on Base/Ethereum/Arbitrum/Optimism. The enumerated contents (honeypot/tax/mint scan, holders, LP locks, price, AI verdict) make it clearly distinguishable from lighter siblings like token_safety or base_token_info.

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 trigger conditions: 'before you buy, list, accept or integrate it,' and positions it as one-call full due diligence. It does not name the cheaper alternatives (token_safety, base_token_info, token_price) or say when the full report is overkill, so the routing guidance is strong but not complete.

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 and openWorld annotations, the description discloses important behavior: the tool combines public data sources, returns an AI analyst profile plus underlying facts, includes no private labels, and is paid via x402 USDC on Base. It also mentions a free sample endpoint and the exact payment metadata field.

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 long but front-loaded with the tool's purpose and then organized into concrete data components, output format, example, and payment details. Given the tool's complexity and lack of an output schema, every section adds useful invocation or interpretation value.

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

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

The description compensates for the absence of an output schema by showing a representative output object with schema name, riskLevel, profile, evidence, recommendation, and facts. It also covers payment requirements and data-source limitations, making it complete enough for an agent to call and interpret results.

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 only one parameter and the schema already describes it at 100% coverage as an EVM address. The description reinforces the EVM address scope but does not add format, validation, or syntax details beyond what the schema 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 description clearly identifies the resource as a wallet/counterparty intelligence dossier and enumerates the exact components included: security flags, multi-chain holdings, account age, ENS, transfers, counterparties, and x402 seller status. It is easy to distinguish from a simple balance lookup, though it does not explicitly name sibling tools such as base_wallet_profile, wallet_portfolio, or x402_precheck.

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

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

The description gives clear usage context: use it before paying, accepting funds from, or trading with an EVM address. It does not explicitly state when not to use it or name alternative tools for narrower checks, so the routing guidance is strong but not exhaustive.

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 description says the tool buys APIs, pays the seller from Hearth's wallet, charges $0.01, and requires x402 payment in _meta. That is a financial side effect, but annotations declare readOnlyHint=true. This is a direct contradiction, overriding the otherwise rich behavioral detail.

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

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

It is front-loaded with the core purpose and includes a helpful output example, but the body is a dense run-on with long parenthetical lists and repeated pricing details. It is information-rich but not crisply structured.

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 complex paid routing tool, the description covers intent classification, seller ranking, precheck rules, payment mechanics, pricing, free preview, and an example output. Even without an output schema, the return shape is illustrated well enough for an agent to understand what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema: q is natural-language intent, params are passed to the seller as GET/POST input, url selects a specific seller, and category overrides classification.

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: buy any x402 API through Hearth. It clearly explains the orchestration flow (classify intent, rank sellers, precheck, pay, return response), though it does not explicitly distinguish itself from route_plus.

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 usage context: describe what you need via q, optionally specify a seller URL, params, or category override, and notes a free preview endpoint. It lacks explicit when-not guidance or named alternatives such as route_plus or x402_discover.

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 and openWorld; the description adds substantial behavior the agent could not otherwise know: flat $0.06 price covering sellers up to $0.05, no charge without a result, the pay-safety precheck rules (only 'pay', payTo must match verified listing, canonical USDC on Base), the ranking signals used, and how payment is passed via _meta['x402/payment']. It also surfaces that funds move from Hearth's wallet — a real financial side effect that the readOnlyHint alone would not 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?

The purchase-and-pricing facts are front-loaded correctly, but the middle becomes a dense run-on enumerating ranking internals ('nightly free liveness probes', '402index reliability, vet402 verdicts', 'rankScore') that do not help an agent select or call the tool. The example output earns its space since no output schema exists.

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 paid, open-world tool with no output schema, the description supplies an example response shape, the price and charge policy, the payment handoff, and a free alternative endpoint — enough to call it confidently. Remaining gaps are failure semantics: what happens if the seller fails or the precheck rejects, and whether a retry is billed.

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 four properties are already documented; the description still adds meaning by enumerating the intent categories the classifier assigns, which explains what happens when 'category' is omitted. It also documents a de facto parameter absent from the schema (_meta['x402/payment']), which is genuinely useful invocation knowledge.

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 sentence gives a concrete verb and resource: 'Buy any x402 API through Hearth', then explains the mechanism (classify intent, rank sellers, precheck, pay, return response + provenance). An agent knows exactly what the tool does. However, it never differentiates itself from the near-identically-named sibling 'route', nor from x402_discover/x402_precheck, so the buyer-vs-browser distinction must be inferred.

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

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

There is no explicit when-to-use statement, no exclusions, and no named alternatives despite 32 siblings including 'route', 'x402_discover', 'x402_precheck', and several native capabilities (ai_chat, ai_summarize) that overlap. The only guidance-adjacent content is the free preview URL and the note that it is not charged unless a result is returned. Usage is implied by the verb 'buy', not 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?

Goes well beyond the readOnly/openWorld annotations: discloses determinism ("no LLM"), the exact result fields, and — critically — that the call is paid ($0.003 USDC on Base) and requires payment passed in _meta["x402/payment"]. That payment/auth requirement is behavioral information no annotation or schema conveys.

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 purpose and use case, then supporting detail. The embedded example JSON is long but earns its place since there is no output schema; the pricing sentence is compact and essential.

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 inline example return shape (q/count/hits with title, points, comments, author, createdAt, hn) fills exactly that gap, and the payment instruction covers the non-obvious invocation 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 coverage is 100%, so q/n/sort/type are already documented. The description only restates ordering semantics ("newest or most relevant first") and result fields, adding little beyond what the schema says. Baseline 3 is appropriate.

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

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

Opens with a specific verb+resource ("Hacker News search") and immediately scopes it to stories and comments. No sibling tool covers social/news search, so the boundary is unambiguous from the description alone.

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?

"Good for tracking mentions of a product, company or topic" gives a clear use context an agent can match against a user request. It stops short of stating when NOT to use it or naming an alternative source, so it's 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 already declare readOnlyHint and openWorldHint, while the description adds useful operational details: deterministic execution, no LLM, an example response, and the x402 payment requirement via _meta. It does not cover errors or rate limits, but it adds substantial context beyond 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?

The description is front-loaded with purpose and then provides example output and payment details without filler. There is slight redundancy between 'Solana SOL balance' and 'Native SOL balance,' but it 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 simple read-only balance lookup, the description supplies the example return shape in place of an output schema and explains the payment mechanism. Combined with annotations covering safety, it is complete enough for an agent to 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?

The single address parameter is fully documented in the schema as a base58 Solana address. The description's 'any Solana address' and example corroborate this but do not add format or semantic detail beyond the schema, 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 resource and scope: native SOL balance for any Solana address. It distinguishes itself from EVM siblings by chain, though it does not explicitly name alternative 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 intended use is implied by 'native SOL balance' for a Solana address, but there is no explicit when-to-use guidance, exclusions, or named alternative such as wallet_portfolio. Payment instructions are present but do not clarify 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?

Goes well beyond the readOnly/openWorld annotations: it discloses sampling windows (top 25 holdings, last 100 signatures, last 15 transactions), determinism ('no LLM'), data provenance ('Free public data'), and the x402 pricing/payment mechanism in _meta. The payment sentence is garbled at the tail ('co. Price: $0.012 USDC...'), which costs it the top mark but the substance 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?

It is front-loaded with a strong summary sentence, but the body is a single run-on sentence crammed with parenthetical lists, and the trailing pricing fragment is malformed. The example output earns its space, but the middle section could be broken up for readability.

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

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

With no output schema, the description carries the full burden of describing returns and does so with an inline JSON example covering balance, holdings, activity, programs, and counterparties. Only the truncated pricing text leaves an agent slightly uncertain about the payment details.

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

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

Schema coverage is 100% and the single 'address' parameter is already documented as base58 in the schema, so the baseline of 3 applies. The description's example output reinforces the shape of the address but adds no new constraints, formats, or validation rules.

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 ('One-call Solana wallet profile') and enumerates exactly what is aggregated: holdings with USD values, activity stats, labeled programs, counterparties, and a wallet-type classification. This clearly separates it from narrow siblings like solana_balance or token_transfers without needing to name them.

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 phrase 'one-call Solana wallet profile' and the enumerated coverage imply this is the comprehensive option versus point tools like solana_balance, but no sibling is named and no condition is given for when to prefer it. There is also no guidance on when-not to use it (e.g., for a bare balance check).

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 and openWorldHint annotations, the description discloses that data is aggregated from public DeFi price feeds, deterministic and LLM-free, and that access is paid via x402 using _meta["x402/payment"]. The example output also exposes the returned fields and confidence value, adding substantial behavioral context.

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

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

The main purpose and chain/address behavior are front-loaded, and the example output earns its space by showing return fields. The payment sentence is important but slightly awkwardly appended, keeping it from being maximally tight.

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

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

For a simple two-parameter price lookup with no output schema, the description supplies an example response, names the returned fields, explains native ETH behavior, and discloses the x402 payment requirement. That is enough for an agent to call and interpret 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 description coverage is 100%, and the two parameters are already explained in the schema. The description repeats the chain options, Base default, and address omission for ETH, but adds no meaningful syntax or 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?

The description states a specific resource and function: current USD token price on Base, Ethereum, Arbitrum, or Optimism, with native ETH when no address is supplied. It clearly conveys the core operation, but it does not explicitly differentiate itself from nearby siblings such as dex_quote or base_token_info.

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 useful invocation context: default chain is Base and omitting address requests native ETH. However, it does not say when to prefer this tool over alternatives like dex_quote, base_token_info, or token_safety, so usage guidance remains implied rather than explicit.

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 supply readOnlyHint and openWorldHint; the description goes far beyond them by disclosing the data provenance ('goplus+onchain'), determinism ('no LLM'), the exact return shape via a sample JSON, and a non-obvious operational requirement — a $0.009 USDC x402 payment passed in _meta['x402/payment']. That payment requirement is critical and would be missed without the description.

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 and risk list come first, then usage trigger, then determinism, then the concrete sample output, then price. The sample JSON is long but earns its place because there is no output schema, and it resolves return-shape questions in a single glance.

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 embedded example supplies the full response contract (riskScore, verdict, flags, tax fields, holder stats, source). Combined with chain coverage, determinism, and payment mechanics, an agent has everything needed to call this 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%, and the schema already documents both the chain enum (base default, ethereum, arbitrum, optimism) and the address field. The description restates the supported chains and shows an address in the sample output, but adds no new semantics such as whether checks differ per chain or what happens for unsupported tokens. 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 ('Scam check for an ERC20'), then enumerates exactly which risks it detects (honeypot, tax, mintable, proxy, blacklist, holder concentration, LP lock) and which chains. An agent can immediately distinguish it from siblings like base_token_info or token_price, which do not assess risk.

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 before buying or accepting a token.' That is a clear usage context with no ambiguity. It stops short of naming alternatives (e.g., 'use base_token_info for plain metadata'), so there is no exclusion guidance, but the intended moment of use 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?

Beyond the readOnly/openWorld annotations, it discloses the recency limits per chain, the 50-result cap, deterministic non-LLM behavior, and — critically — the x402 payment requirement ($0.0045 USDC via _meta['x402/payment']). That payment/auth detail is exactly the kind of 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, then scope, then limits, then example, then price. The inline JSON example is long but justified since no output schema exists. Slightly dense as a single paragraph but every sentence carries 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 supplies a concrete example response shape plus field meanings, along with chain support, caps, and payment mechanics. An agent has everything needed to call this correctly and interpret results.

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%, so baseline is 3; the description adds value by mapping the blocks parameter to concrete per-chain ceilings and by stating base as the default chain. It doesn't clarify the 'from or to' semantics of wallet beyond the schema's parenthetical, but overall it adds modest 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+resource ('Recent ERC20 Transfer events ... for a token contract, a wallet, or both') and enumerates the decoded fields returned. This distinguishes it clearly from siblings like base_wallet or wallet_portfolio, which are balance/portfolio oriented.

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

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

Explicitly says it works for a token, a wallet, or both, and scopes usage to recent windows (~2,000 blocks on Base/Arbitrum/Optimism, ~500 on Ethereum). It doesn't name an alternative tool for historical or full-history lookups, so an agent must infer that this is recent-only.

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, and the description adds important behavior beyond them: deterministic/no-LLM operation, a $0.008 USDC x402 payment on Base, and the required _meta["x402/payment"] location. It still omits failure behavior when payment is missing or invalid.

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 front-loads the purpose, scope and output structure, and the example output is valuable because no output schema exists. It is somewhat long but each part, including the payment note, 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?

For a multi-chain paid read tool with no output schema, the description supplies the key output shape, per-chain subtotals, total USD, asset coverage and payment requirement. It leaves payment failure modes and exact x402 flow details unstated, but is otherwise complete enough to 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?

There is only one parameter, and schema coverage is 100% with the schema describing it as an EVM wallet address. The description repeats that it takes an address and shows an example, but adds no extra format or validation 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?

The description names the resource and operation clearly: it returns a multi-chain wallet portfolio with USD values for ETH, WETH, USDC and USDT across Base, Ethereum, Arbitrum and Optimism. Its listed chain and asset scope distinguishes it from single-chain siblings such as base_wallet and solana_balance.

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

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

The description frames this as a one-call portfolio endpoint for multi-chain balances, which implies its use case. However, it does not explicitly say when to choose it over siblings like base_wallet or solana_balance, nor when not to use 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?

Adds rich behavioral context beyond annotations: ranking criteria (30-day unique paying wallets, calls per payer, recency), filtering of farmed listings, data sources (Coinbase Bazaar + PayAI), nightly refresh, live 402 probe, price, and payment method. This is far more than the readOnly/openWorld hints 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 purpose and key differentiators, then flows into filters, output, pricing, and an example. The density is high but every sentence earns its place; minor trimming could improve readability.

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

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

Complete for a discovery tool with no output schema: explains ranking, data sources, freshness, return fields, live probing, cost, and payment mechanics. 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 baseline is 3, but the description adds example natural-language queries for q and notes optional maxPrice and network filters. It doesn't expand on n beyond the schema's default, but the added context is useful.

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: 'Find the best x402 API for a task' and explains the ranking basis. It contrasts with the 'free catalog search' but does not explicitly name sibling x402_precheck, leaving some ambiguity for an agent comparing the two.

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?

Implies usage by describing how to provide a task ('Describe what you need...'), but gives no explicit when-to-use/when-not-to-use guidance or alternatives. The contrast with catalog search is informative but not a direct routing instruction.

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 substantial behavioral context: a live unpaid GET-then-POST probe, v1 body and v2 header parsing, the specific detection categories (payTo hijack, v1-v2 mismatch, wallet farming, keep-alive self-payment), the on-chain lookback window (~75h), and the index-vs-live-scan distinction. It also discloses the tool's own payment mechanics ($0.005 USDC on Base via _meta['x402/payment']), which is essential and appears nowhere in the 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?

The verdict and when-to-use are correctly front-loaded, but the body is a dense semicolon chain of internal jargon (Coinbase Bazaar, PayAI, listing-carpet detection) and ends in a corrupted fragment: the example JSON is truncated at 'priceUsd.' before the pricing sentence resumes. Restructuring the example and pruning enumeration detail would improve it.

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-value burden and does so: it names hearth.precheck.v2, enumerates verdict/allow/score/confidence/reasons/signals, and supplies a concrete example object. The truncated example tail is the one real gap, but an agent still knows what will come back and how to interpret 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 all five parameters are already documented, which sets the baseline at 3. The description restates url, payTo, and maxPrice with the same intent already present in the schema ('catch bait-and-switch' mirrors 'flags bait-and-switch pricing') and says nothing about `deep` or `method` beyond the probe description, so it adds marginal value only.

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 up front: 'x402 pre-payment safety check: pay / caution / avoid', with the three-valued verdict scale explicit. It distinguishes itself from siblings by naming the batch variant (/v1/x402/precheck-batch) and by framing the operation as a pre-payment probe, which is distinct from x402_discover or the on-chain wallet 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?

Gives a clear trigger: 'Before your agent pays an unknown x402 endpoint, check it', plus the cost context ($0.005) and required inputs (url and/or payTo). It routes to the batch sibling for volume use. It does not explicitly say when NOT to use this versus x402_discover, so it stops short of a full when/when-not/alternatives statement.

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 readOnly/openWorld annotations: discloses per-call cost ($0.025, $0.0025 each), the x402 payment mechanism via _meta['x402/payment'], USDC on Base, and the exact return shape. This is rich 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-loads the batch purpose and size cap, then price and format. Dense but each sentence adds distinct value; the inline example output is somewhat verbose but substitutes for a missing 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?

With no output schema, the description supplies an example return payload and summarizes the pay/caution/avoid counts, plus pricing and payment transport. An agent has everything needed to invoke and interpret 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 both params are documented. The description adds the JSON-body alternative format for urls, but says nothing about maxPrice semantics — a baseline 3 is appropriate since the schema carries the load.

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+scope: 'Batch x402 precheck: up to 10 URLs in one call' and names the underlying check (hearth.precheck.v2). The 'batch' framing clearly separates it from the sibling x402_precheck single-URL tool.

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

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

Clear usage context: use when checking multiple URLs at once, with the 10-URL cap stated as a hard limit. It does not explicitly say 'use x402_precheck for a single URL', so the routing to the sibling is left to inference from the name.

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?

Far beyond the readOnlyHint/openWorldHint annotations: it discloses the probe mechanics (unpaid GET with POST fallback, so calling it does not charge the seller's endpoint), the grading scale (0-100, A-F, 23 weighted checks), the paid cost and payment channel ($0.1 USDC on Base via _meta["x402/payment"]), and a free alternative. An agent knows exactly what side effects, cost and prerequisites to expect.

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 and audience are front-loaded, which is good, but the middle collapses all 23 checks into a single run-on enumeration whose detail (e.g. 'robots.txt', 'challenge latency') does little to help an agent decide or call the tool. The example output JSON and pricing tail are useful; the check catalogue could be summarized as 'x402 protocol, discovery, trust and pricing checks'.

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 paid, open-world probing tool with no output schema, the description supplies the missing return shape via an inline example, plus cost, payment mechanics and a free fallback. There is no material gap an agent would need to close before calling 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 description coverage is 100%, so both url and method are already documented, including the 'try GET then POST' default. The description mostly restates this ('GET, falls back to POST') and adds only the nuance that the probe is unpaid — marginal value over the structured schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('x402 seller listing audit') and immediately enumerates what is graded (spec compliance, discoverability, buyer trust, fix plan). The audience clause 'For people who SELL x402 endpoints' cleanly separates it from sibling buyer-side tools like x402_precheck and x402_discover.

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?

Clearly establishes who should call it and what input is needed ('Give your endpoint URL'), and points at a zero-cost trial path ('Free sample (score + failed check ids)'). It never explicitly contrasts with x402_seller_scores or x402_precheck_batch, so the routing decision against those siblings is left partly 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 readOnly and openWorld, so the description carries the rest — and it does disclose the material facts: the call costs $0.005 USDC on Base via x402, payment must be passed in _meta["x402/payment"], and a free sample endpoint exists. It also names the upstream data sources feeding each score. It does not cover rate limits or failure behavior, which keeps it off 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?

The purpose is front-loaded in the first clause, followed by data provenance, then price, then a sample call and an example response — a sensible ordering. It is a single dense run-on paragraph, and the embedded JSON example is long, but every element is load-bearing for a paid tool with no 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?

With no output schema, the inline example response and the schema identifier (hearth.seller-scores.v1) are what let an agent parse results, and the description supplies both along with payment mechanics and a free trial path. What is missing is any statement of result ordering/pagination semantics and the boundary against x402_discover, which is the main gap for a 4-parameter, zero-required 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 by the rubric. The description restates the category vocabulary and the q alternative but adds no format, precedence, or interaction rules (e.g. what happens if both q and category are supplied). The example output does clarify what scoreParts mean, which is a small bonus but not a parameter-semantics gain.

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 — ranked x402 seller quality scores — plus the enumeration of the ranking signals (rank score parts, 30d usage, Hearth purchase outcomes, liveness probe, public reputation sources). That is far more informative than the sibling names alone. It stops short of naming which sibling it replaces (x402_discover vs x402_precheck), so an agent must infer the boundary.

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 differentiates the two input modes ("per category (...) or free-text q"), which is genuine either/or guidance. But there is no statement of when to reach for this rather than x402_discover or x402_precheck, and no prerequisites or exclusions. Usage is implied by context rather than declared.

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