Agent Data Tools: Prices and DeFi

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

Annotations declare openWorldHint=true and readOnlyHint=false but give no reason; the description supplies the non-obvious operational context behind that: a $0.002 USDC-on-Base charge per successful call via x402, and that the quote is an exchange average with a timestamp. It omits failure/refund handling and any rate limits, so it adds real value without being exhaustive.

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

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

Three sentences, front-loaded with the return payload, then usage, then cost. The currency enumeration is precise rather than padding, and nothing is repeated from the schema or annotations.

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 burden of describing the return: seven fiat prices, sats per USD, and the price time. Combined with the payment disclosure, an agent has everything needed to decide and call correctly.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there is no parameter semantics for the description to clarify or omit.

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

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

States exactly what the tool returns: current BTC spot price in seven named fiat currencies, averaged across major exchanges, plus satoshis-per-USD and a timestamp. The Bitcoin-only, exchange-averaged scope distinguishes it from generic siblings like price_token/price_tokens and from fx.

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 three concrete use cases (sats/fiat conversion, valuing a Bitcoin or Lightning payment, pre-trade price check), which is clear when-to-use guidance. It does not state when NOT to use it or name an alternative (e.g. price_token for non-BTC assets), so it falls short of the explicit-alternatives bar.

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

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

The annotations are sparse, and the description compensates heavily: null for unsupported reads, 502 for RPC transport failure, ownership renunciation requiring a confirmed zero owner, empty slots not implying uninitialized proxies, and not-applicable for EOAs. It also discloses the $0.02 USDC x402 cost, which annotations cannot express and which materially affects invocation.

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 edge-case and cost notes, with no filler sentences. It is dense and telegraphic in places (several clipped clauses), but every sentence carries actionable 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 carries the return-value burden and does so: it explains null, 502, and not-applicable outcomes, plus scope limits. Combined with the cost disclosure, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single address parameter is already fully documented in the schema (0x-prefixed 20-byte hex). The description adds no further address semantics, 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 a specific resource (Base contract) and the precise analytical method (bytecode, EIP-1967 slot and zero-supply heuristics), which distinguishes it from generic reads like base_is_contract. It never explicitly names a sibling it competes with, so an agent must infer differentiation, but the capability 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?

"Use before approving or calling an unfamiliar Base contract" gives a concrete trigger condition, and "Not a full security audit" marks a boundary for when this is insufficient. No alternative tool is named for that gap (e.g. wallet_audit, token_report), so routing is left to inference.

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

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

Annotations already disclose readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds crucial behavioral context not in the annotations: the exact cost ($0.002 in USDC on Base per successful call) and payment protocol (x402), plus the data source (ECB) and what the response contains (rates, converted amounts, applicable date).

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 what the tool does, followed by usage guidance and cost information. It is efficient with no redundant sentences, though the cost sentence could be considered slightly separate from the core purpose.

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

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

With no output schema, the description explains the return values (rates, converted amounts, date the rates apply to) and the payment model. Annotations cover the safety profile, and the description fills in the remaining behavioral and data-source details. An agent has everything needed to call 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 the input schema already documents all three parameters thoroughly. The description restates that a base currency is required and target currencies and amount are optional, but adds no new semantic detail beyond the schema (e.g., no format hints or default behavior clarification beyond what is already in the schema).

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

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

The description clearly states the resource (foreign exchange rates from the ECB for ~30 major currencies) and the operation (give base currency, get rates and converted amounts). It does not explicitly distinguish itself from any sibling tool, though its domain is unique among the provided siblings.

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

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

It gives clear usage contexts: 'Use for currency conversion, invoice and price calculations, and reporting in another currency.' It does not state when not to use the tool or name any alternatives, but it provides enough context for an agent to select it confidently.

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 behavior beyond the annotations: 404 on missing pairs, 502 on upstream failure, null for unavailable fields, a stated source and retrieval timestamp, and a $0.03 USDC x402 payment cost per successful call. The only tension is that annotations set readOnlyHint=false for what is framed as a lookup; the per-call payment plausibly explains the non-idempotent flag, but the description never reconciles it.

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 scope are front-loaded, followed by error, cost and null-handling details in a compact clause chain. It is information-dense rather than padded, though the run-on enumeration of returned fields is slightly harder to scan than separate sentences would be.

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 lists the returned fields, the source/timestamp metadata, the null convention for missing data, and the failure modes (404/502). An agent has everything needed to call it and interpret results, including cost.

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 'address' parameter is fully documented as a 0x-prefixed 20-byte hex DEX pair address on Base. The description adds little beyond that ('example values are illustrative'), so the baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (Base DEX pair lookup via DexScreener) and enumerates the exact fields returned: verified pair identity, tokens, liquidity, volume, trades, pair age. It also draws a boundary against neighboring concerns ('No pool-security or investment-risk assessment'), which separates it from siblings like contract_risk, token_report and trade_insight.

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?

'Use to check a pair's liquidity before trading' gives a concrete triggering scenario, and the explicit exclusion of security/risk assessment tells the agent when this tool is the wrong choice. It stops short of naming the alternative tool to use instead, so it is clear context without full routing.

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

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

Adds substantial context beyond the annotations: fixed gas-unit assumptions (100k/250k/180k), exact priority-fee multipliers per preset, HTTP 400-without-charge on invalid input, and a $0.04 USDC x402 cost per successful call. The readOnlyHint=false is consistent with a charged remote call, not a contradiction.

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?

Dense and front-loaded: purpose first, then assumptions, validity, exclusions, and cost. Every sentence carries distinct information 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, yet the description covers pricing, invalid-input behavior, estimation assumptions, and scope limits. For a single-parameter tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds real meaning the enum alone lacks by defining each preset ('high-mev' = 3x priority fee, 'low-gas' = half). This is beyond a baseline 3 because it explains the numeric effect of each option.

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 ('Estimates Base gas costs from current fees and priority-fee presets') and, despite the name mev_simulator, explicitly disclaims simulation/MEV measurement. It does not, however, distinguish itself from the sibling base_gas, leaving one ambiguity for the agent.

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 use case ('Use to budget gas for a Base transaction') and declares when it is not applicable ('No transaction simulation, mempool observation, or MEV/sandwich-risk measurement'). No alternative sibling is named, so routing versus base_gas is left to inference.

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

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

Beyond the annotations it discloses the data source (deepest Uniswap v3 pool, live chain read), the return payload (pool, fee tier, quote-token reserve, thin-liquidity flag), failure semantics ('No pool returns 404, uncharged'), and a concrete cost model ($0.002 USDC on Base via x402). The readOnlyHint=false is consistent with the description, since a paid x402 call moves USDC on-chain, so no contradiction arises.

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?

Five short sentences, each carrying distinct information: what, source, return shape, price semantics, failure/billing. The key scoping facts (chains, pool source, spot-not-TWAP) are front-loaded 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?

With no output schema, the description compensates by enumerating the returned fields and the 404 failure mode, plus the payment requirement an agent must satisfy before calling. Nothing material for correct invocation is missing for a two-parameter lookup tool.

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

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

Schema description coverage is 100%: 'chain' has an enum with defaults documented and 'address' is described as a 0x ERC-20 contract address. The description adds pricing context (quote tokens USDC/WETH) but no parameter-level syntax or formatting detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource with full scope: 'USD price of any ERC-20 token' on four named chains, sourced from the deepest Uniswap v3 pool against USDC or WETH. This clearly separates it from siblings like token-info, token-report, contract-risk and the per-chain *_token-info tools. An agent can select it 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?

Gives explicit positive triggers: 'Use to value a token or check a quote before a swap or payment.' It also implicitly rules out time-series needs via 'Spot price, not a time average.' It does not name which sibling to use instead (e.g. token-report for deeper analysis), so routing guidance stops one step short of a 5.

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

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

Adds rich behavior beyond annotations: live on-chain reads, spot (not time-averaged) prices, graceful handling of pool-less tokens via 'unpriced' instead of failing, plus a specific cost ($0.005 in USDC on Base via x402). The x402 payment explains why readOnlyHint=false despite the read-like operation.

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 chain scope are front-loaded, and each sentence carries distinct information (mechanism, edge-case handling, pricing caveat, cost). Dense but slightly long, with the pricing/payment detail repeated across two sentences.

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

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

With no output schema, the description proactively explains return content (pool, reserve, thin-liquidity flag, unpriced bucket) and the cost model. An agent has everything needed to call and interpret the result 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 parameters (addresses, chain) are already documented, and the description's 'up to 20 tokens' merely echoes the 1-20 schema constraint. No additional format or syntax 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 verb (price in USD) plus resource (ERC-20 tokens), with scope (up to 20, four named chains) and mechanism (deepest Uniswap v3 pool vs USDC/WETH). This differentiates it from the singular sibling price_token and from report/audit tools at a glance.

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 concrete when-to-use ('value a basket of tokens or refresh a watchlist in one paid call'), which the plural batch scope supports. It does not explicitly name price_token as the singular alternative or state when-not to use, so it stops short of full routing guidance.

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

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

Annotations declare destructiveHint=false and openWorldHint=true, but the description adds information annotations cannot convey: a $0.01 USDC cost on Base, charged per successful call, settled via x402. It also discloses what is inspected (EIP-1967 and minimal-proxy detection, bytecode scanning for mint/pause/blacklist/fee-setter). The readOnlyHint=false annotation is not contradicted, since the call settles a payment.

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?

Three front-loaded sentences in a logical order: what is returned, when to use it, what it costs. Each sentence earns its place and the cost/warning is not buried. The return-value enumeration is dense but justified given there is 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 description must carry the return payload, and it does so comprehensively (fields, ownership/renouncement, pause state, proxy implementation/admin, bytecode heuristics). Combined with the usage context and the payment disclosure, 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?

There is a single parameter with 100% schema description coverage ('Token contract address on Base (0x...)'), so the schema already carries the semantics. The description corroborates the Base/ERC-20 scope but adds no format, validation, or edge-case detail beyond it. 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 precise verb-and-resource ('Live on-chain facts for any ERC-20 token on Base') and enumerates the exact data returned (name, symbol, decimals, supply, owner, renouncement, pause, proxy detection, bytecode heuristics). It is far more specific than the bare tool name 'token', but it never distinguishes itself from the sibling 'token-report', so an agent cannot tell them apart on 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?

It gives a clear use context: 'token due diligence and rug-pull or honeypot screening before a swap.' That is a genuine when-to-use signal, but there are no exclusions or named alternatives (e.g. token-report, contract-risk, liquidity-pool-audit), which are exactly the tools an agent would weigh against this one.

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 annotations, it discloses meaningful behavior: the data sources (heuristic screen + DexScreener), that retrieval time is returned, that evidence can remain 'unknown', that a mint selector is not proof of callable minting, and a firm price of $0.02 USDC on Base via x402. That cost/payment detail is exactly the kind of extra context annotations cannot carry. It stops short of describing return shape or failure/refund 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?

Purpose is front-loaded, then limits/caveats, then usage, then cost. The sentences are dense but each carries distinct information; the heavy caveat run is slightly repetitive ('not a safety guarantee', 'illustrative examples are not live quotes') but nothing is wasted.

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

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

With no output schema, the description must carry return-value semantics, and it does at a summary level: source, retrieval time, owner/paused/proxy facts, selector checks, and their epistemic limits. An agent knows what it will get and what it cannot conclude, though it lacks field-level detail and pagination/error handling notes.

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 single 'address' parameter is already documented as a Base contract address (0x...). The description reinforces the Base-token scope but adds no format, validation, or edge-case guidance 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 opening sentence names a specific verb+resource: heuristic screening of a Base token combined with DexScreener market data, and the body scopes what it returns (owner, paused, proxy facts, selector checks). It is clear what the tool does, though it never explicitly distinguishes itself from near-neighbors such as contract_risk 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 a concrete trigger: 'Use before swapping into an unfamiliar Base token.' That is real when-to-use guidance, but there are no explicit exclusions ('do not use for known/verified tokens') and no named alternative tool for overlapping screening needs.

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 annotations by disclosing scope limits (no buy/sell recommendations, no calibrated confidence, no holder-concentration evaluation), the nonce caveat, and the $0.05 USDC x402 cost per successful call. The readOnlyHint=false is not explained (likely due to the payment side effect), leaving a minor gap.

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

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

Front-loads what the tool combines, then proceeds through limitations, usage, and cost in a logical order. Dense but each sentence carries distinct information, though the enumerated capabilities make it slightly long.

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 explains what is returned ('the underlying indicators separately') and what is deliberately excluded. An agent has enough to decide and call it, though the exact return structure is left implicit.

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 both parameters are fully documented in the schema, so the description carries no additional parameter burden. It adds no syntax or format meaning beyond what the schema already provides, making the baseline 3 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 (combines) and enumerates the exact resources aggregated: Base token-report risk tier and flags, DEX market data, and wallet-audit risk tier, flags, nonce, and native balance. This clearly distinguishes it from siblings like wallet_audit, token_report, and liquidity_pool_audit, which each cover only one slice.

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 'Use as one input before a Base trade,' giving clear context for invocation. It does not, however, name a specific alternative tool or state when-not to use it versus composing the sibling tools directly.

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

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

With annotations present, the bar is lower, yet the description adds substantial context beyond them: it discloses the cost ($0.02 USDC on Base per successful call, paid via x402), which also explains the readOnlyHint=false annotation; it states per-token risk is unknown because token contracts are not audited; and it clarifies that the EOA nonce counts outgoing transactions only. These are exactly the kind of operational caveats structured fields 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?

The return payload is front-loaded and every sentence contributes (payload, limitations, address-type caveat, use case, cost). It is dense but not padded, though the six sentences push toward the longer side for a one-parameter tool.

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 must describe return values — and it does comprehensively (risk tier, flags, balances, nonce, address type). It also covers cost, model limitations, and risk-tier basis, leaving nothing an agent needs to invoke it correctly unstated.

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

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

There is a single parameter with 100% schema description coverage ('Base chain wallet address, 0x-prefixed 20-byte hex'), so the schema already carries the semantics. The description adds no format or constraint detail for the address parameter. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names the exact resource and payload: a heuristic high/medium/low risk tier, named flags, ETH balance, four specific token holdings (USDC, WETH, cbBTC, DAI), and the Base nonce. This is a specific verb-plus-resource statement. It does not, however, explicitly differentiate itself from near siblings like wallet, wallet_portfolio, check_counterparty, or sanctions_check, which leaves some routing ambiguity.

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 concrete use case — 'Use to screen an address before paying it' — which is clear actionable context. It stops short of naming when-not-to-use or pointing at the alternative screening tools (check_counterparty, sanctions_check), so it is 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?

Discloses behavior well beyond the annotations: it is a live on-chain read, pricing comes from each token's deepest Uniswap v3 pool, the return includes holdings, a total and anything that could not be priced, and the call costs $0.005 USDC on Base via x402. The paid-call mechanic usefully explains the readOnlyHint=false / idempotentHint=false annotations rather than contradicting them. Minor gap: no explicit note on rate limits or failure/refund behavior for failed calls.

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 resource and value proposition, and each sentence adds information (scope, exclusions, usage, price). The parenthetical token list is slightly dense and run-on, but nothing is wasted.

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

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

With no output schema, the description still covers the return shape ('holdings, total and anything that could not be priced'), chain coverage, token coverage limits and the payment requirement, which is enough for an agent to call it correctly. Coverage of pricing staleness/rounding is the only material 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 the schema already documents address, chain enum values and the comma-separated token list; baseline 3 applies. The description adds useful context on the token parameter (up to 20 addresses, only the common tokens are included by default) but no syntax 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 the specific resource (wallet USD value) and enumerates scope precisely: four chains, native ETH plus named major tokens, up to 20 user-added tokens, priced from deepest Uniswap v3 pools. It explicitly rules out the adjacent resource ('Not a full token inventory') and is clearly distinguishable from sibling token-balance and plain balance 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 an explicit use context ('check what a wallet is worth before trading, lending or paying') and an implicit negative condition ('Not a full token inventory'), which steers agents toward wallet-audit/token-balance when coverage is needed. It does not name those alternatives outright, so it falls short of a full when/when-not statement.

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