P0: wallet balances and EVM reads

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, yet the description adds substantial behavior the annotations cannot convey: cost ($0.001 per call), the x402/MPP payment flow, the guarantee that bad input is refused before any charge, and the P0 bearer-key path that executes the call server-side. It omits rate limits and any error/payment-failure semantics, which keeps it at 4 rather than 5.

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

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

Front-loads purpose, then the return shape, then the payment/auth mechanics in a tight sequence with no filler. It is dense and long for a two-parameter tool – the buy-keys URL plus the P0 explanation could be compressed – but every sentence carries operational information.

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

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

For a paid, read-only data endpoint with no output schema, the definition supplies what an agent needs to call it correctly: chains, defaults, returned fields, price, auth path, and pre-charge validation. Remaining gaps are minor (payment failure/rejection behavior, latency or rate limits), so it is nearly but not 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?

Schema description coverage is 100%, so the enum, default, and number-format details are already fully documented in the schema. The description mirrors the chain list and the 'latest or a given number' choice but adds no syntax or edge-case meaning (e.g., hex formatting, reorg/orphan handling) beyond that. 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 ('need a block header'), enumerates the five supported chains, and lists the returned header fields (hash, parent, timestamp, miner, gas used/limit). That makes it trivially separable from siblings like evm_transaction, evm_receipt, and evm_code 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?

Gives clear when-to-use context ('Use when you need a block header on Base, Ethereum, Arbitrum, Polygon or Optimism') and explains the latest-vs-number selector, plus the two invocation paths (paid URL vs P0 key). It never explicitly names a sibling alternative or an exclusion, so it stops short of the top band.

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 (readOnly, idempotent, openWorld, non-destructive), the description discloses the crucial non-obvious behavior: the default return is an unpaid x402 request (GET /evm/code at $0.002 per call) plus a schema link, and only a P0 access key causes the tool to actually perform the paid call and return data. It also states that bad input is refused before any charge, which is exactly the kind of cost/error semantics an agent cannot infer from 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 a 'Use when' trigger, then the return shape, then pricing and the access-key fork. It is dense but every sentence carries operational information; the parenthetical URL for buying a key is long but necessary for the fallback path.

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

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

For a two-parameter read tool with no output schema, the description covers what comes back, the two invocation modes (payment-request generation vs. direct paid call with a P0 key), the price, and error-before-charge behavior. An agent can act correctly with only this text.

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 enum already enumerates the five chains with defaults, so the schema does the work. The description adds only marginal meaning by naming those chains in prose and implying the address is the subject of the contract check; it adds no format or edge-case detail beyond the schema's pattern.

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 decision the agent needs ('whether an address is a contract') across five named chains, and enumerates the three returned fields: is_contract, bytecode size, sha256 of the bytecode. That clearly separates it from siblings like evm_native_balance, evm_nonce or evm_transaction, which query different on-chain facts.

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 when you must know whether an address is a contract') and implicitly scopes it against the other evm_* siblings through that framing. It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance, but the intended context is unambiguous.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, and the description adds genuinely new behavioral facts: a $0.002 per-call price, a returned payable request URL, an auth mechanism (Bearer p0k_…), automatic price deduction, and pre-charge input validation. The only gap is that it doesn't say what happens when both name and address are supplied, or what a failure of the paid call looks like.

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 two resolution modes are front-loaded and every clause carries information. It is dense and runs long in the middle (endpoint, price, then key-buy URL), but nothing is redundant; the buy URL is long yet operationally necessary.

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 description compensates well by describing the returned resolution data plus the fact that a request object with a schema link is returned in the unauthenticated path. It is only slightly short on error/edge behavior for the paid-call path, which is minor for a read-only 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 coverage is 100%, so the baseline is 3; the description earns more by explaining what each parameter actually triggers — name goes through the Universal Resolver (and surfaces the resolver address), address performs a reverse lookup that is forward-verified. That verification detail is real meaning beyond the schema's pattern/length constraints.

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 pair in both directions ('name to address' via Universal Resolver, 'address to primary name' via reverse record, forward-verified) and names the underlying endpoint GET /evm/ens. An agent can immediately tell this apart from evm_native_balance, evm_code, or the other evm_* 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?

Gives explicit selection conditions between the two modes (use name= for forward, address= for reverse instead of name) and describes the two invocation paths: no key means you receive a paid x402 request to execute yourself; a P0 key means the tool makes the paid call and deducts the price. It also states invalid input is refused before any charge.

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 readOnly, idempotent, openWorld and non-destructive, so this is transparently a safe read. The description still adds substantive behavior: pricing ($0.002 per call), validation-before-charge, the two response modes (returns an x402 request vs. executing the call with a bearer key), and the access-key purchase URL. Those additions are meaningful but the dual-mode return behavior is described ambiguously enough that an agent could misread what it actually receives.

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 use case and dense with decision-relevant facts, with no filler sentences. However it is a single sprawling multi-clause run-on, and the payment/key material is interleaved with the core behavior rather than separated, which costs some 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 still covers what comes back (raw units, decimal amount, symbol/decimals), how payment works, and that invalid input is rejected before charging. For a paid, multi-chain read tool this is enough for an agent to call it confidently.

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 it already documents the chain enum with a default, the token contract pattern, and the wallet address format, so the baseline is 3. The description confirms the one-token/one-chain constraint but adds no new syntax, defaults, or edge-case guidance about the parameters.

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

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

States a specific verb+resource (read one ERC-20 balanceOf/decimals/symbol for one wallet via multicall), enumerates supported chains, and explicitly distinguishes itself from the sibling wallet_balance for multi-token/multi-chain cases. An agent can route correctly 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 an explicit trigger ("Use when you need one ERC-20 balance for one wallet"), an explicit exclusion with the named alternative ("for several tokens or chains at once use wallet_balance"), plus the condition that selects the paid-call path (P0 access key) versus the returned x402 request.

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/idempotent annotations, the description discloses the return payload (wei plus decimal amount, block number, as_of), the cost ($0.001 per call), the error behavior ("Bad input is refused before any charge"), and the two-mode execution model (raw x402 request vs. P0 key where the tool pays and returns data). This is exactly the kind of billing and side-effect 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?

It is a single dense paragraph that front-loads purpose and scope before payment mechanics, and every sentence carries information. The x402/key-buying clause is long and URL-heavy, which slightly hurts scannability, but it is not 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?

There is no output schema, yet the description states what comes back (wei, decimal amount, block number, as_of), what it costs, what happens on bad input, and how to actually retrieve the data in both auth modes. For a two-parameter paid lookup tool, nothing an agent needs to call it successfully 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%, with the chain enum and address pattern already documented in the schema, so the baseline is 3. The description adds only tangential meaning (that the chain determines whether the coin is ETH or POL) and no format or constraint details 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 a specific verb and resource ("native coin balance (ETH or POL) of an address") and enumerates the supported chains. It also explicitly distinguishes itself from the sibling wallet_balance for stablecoins or multi-chain needs, so an agent can route without opening either schema.

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

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

"Use when you need the native coin balance" gives the positive trigger, and "Native coin on one chain only; for stablecoins or several chains use wallet_balance" gives both an exclusion and the named alternative. Nothing about selection is left to inference.

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

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

Annotations only cover read-only/idempotent/open-world; the description adds the critical non-obvious behaviors: the call returns a priced request rather than the data, $0.001 per call, bad input is rejected before any charge, and a Bearer p0k_ key makes the tool perform the paid call and deduct. These are exactly the traits annotations cannot express.

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

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

Front-loaded with the 'Use when' clause, which is good, but the remainder is a long run-on packing pricing, key purchase URL, and referral to an external schema link. The key-purchase URL in particular is verbose operational detail that could be compressed.

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

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

For a tool with no output schema, the description covers the payment model, error handling before charge, chains, and points to a schema link for the response. The actual return payload shape is only reachable via that link, a minor gap.

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

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

Schema coverage is 100% and the enum already lists the chains, so the description adds little per-parameter meaning beyond naming the chains and explaining that both latest and pending nonces are returned. 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 resource and verb: an account's transaction count/nonce, at latest block plus pending nonce, across five named chains. The latest-vs-pending distinction is a real disambiguation an agent can act on.

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 opening 'Use when you need an account's transaction count' plus the tool's own workflow (call the returned URL with an x402/MPP client, or let a P0 key do it) gives clear when-to-use context. It does not differentiate from siblings like evm_transaction or evm_native_balance, which an agent choosing among EVM tools would need.

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

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

The annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds genuinely new behavior: $0.002 per call, the x402/MPP payment handshake, no charge on bad input, and the P0 access key path that makes the paid call itself. That said, the two execution modes are described in a compressed way that leaves unclear what the tool returns by default (a request descriptor/link) versus with a key (the data), which matters for a paid tool.

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

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

The core purpose is front-loaded, but the middle section is a dense run-on that interleaves payment mechanics, the schema link, error handling and the P0 key upsell with a full purchase URL. Necessary information is present but the payment/access explanation could be split into short, scannable statements.

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

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

For a two-parameter read tool with no output schema, the description covers chains, price, payment flow, error behavior and the sibling alternative. The remaining gap is the exact payload returned in each mode, but overall an agent has enough 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% and both parameters carry descriptions including the 0x + 64 hex pattern and the default chain of base. The description only restates the supported chain list and adds no format or semantics 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 the exact fields returned (receipt status, block, confirmations, gas used, effective gas price) across five named chains, plus the underlying endpoint GET /evm/receipt. It explicitly separates this from evm_transaction, which returns from/to/value/input, so an agent can pick between the two siblings 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?

"Use when you need to know whether a transaction succeeded" gives a concrete selection condition, and the description names the alternative evm_transaction with the exact fields that route there. It also states the invalid-input case is rejected before charging, which is a real usage constraint.

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/idempotent/openWorld annotations: it discloses the price ($0.002 per call), the HTTP endpoint (GET /evm/tx), that invalid input is rejected before any charge, that input is truncated to the first 1 KB, and how a P0 bearer key changes behavior (the tool makes the paid call itself and deducts the price). Minor deduction because the two response modes – 'returns the exact paid x402 request' vs 'call that URL … to get the data' vs the keyed mode returning data directly – are worded densely enough that an agent could misread which it will receive.

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 the evm_receipt disambiguation are front-loaded well, but the middle is a run-on sentence chaining price, endpoint, schema link and client instructions, and the payment-mode explanation is split awkwardly across the paragraph. Every fact is arguably useful, yet the payment logistics could be compressed or moved to a trailing clause.

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 compensates by enumerating the returned fields, and for a paid open-world tool it covers auth (bearer key, where to buy one) and billing. The remaining gap is the ambiguity about whether a plain call returns data or merely a payable URL, which matters for a tool whose whole point is a paid fetch.

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 (hash pattern, chain enum with base default) are already fully documented, so the baseline is 3. The description adds the chain roster and the 1 KB input truncation, but nothing about the hash format or chain selection semantics beyond the schema.

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

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

States a specific verb and resource ('a transaction by hash') plus the exact return contents (from, to, value, nonce, gas/fee fields, block, confirmations, method id, input) and the supported chains. It also explicitly distinguishes itself from the sibling evm_receipt, so an agent can pick correctly without opening either schema.

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

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

Opens with an explicit trigger ('Use when you need a transaction by hash'), and names the alternative with its selecting condition: 'to know whether it succeeded (status, gas used, logs) use evm_receipt'. The payment path options (x402/MPP client vs P0 access key) are also spelled out as a decision the caller must make.

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/idempotent/openWorld; the description adds the parts that actually govern behavior: a $0.003 per-call price, the fact that unauthenticated calls return an x402 request payload rather than data, that a P0 bearer key makes the paid call and deducts the price, and that bad input is refused before any charge. Those are exactly the cost and auth traits an agent needs and that no structured field carries.

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 usage condition and the required inputs are front-loaded, and the pricing/auth details follow in a logical order. It is a single dense run-on sentence carrying a long URL and two distinct execution modes, so it could be broken up, but almost every clause 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?

For a paid, open-world lookup with no output schema, the description covers cost, the two calling modes, the auth mechanism, input validation, and where the schema lives. The only soft spot is that 'returns the data' does not say what the verified result looks like, but the paid-request indirection is explained well enough for an agent to act.

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 tx, to, amount, asset, and chain are all documented in the schema itself, and the description adds no format detail beyond restating three names. Worse, it lists only 'tx, to, amount' while asset is also required and chain is optional, which slightly understates the required input set. 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 opens with a specific verb and resource: confirm that a transaction paid at least an amount of an asset to an address. That is far more precise than the sibling evm_transaction or evm_receipt, but it never names those siblings or explains how it differs from them, so the differentiation is left implicit.

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

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

It gives an explicit trigger ('Use when you must confirm that a transaction paid at least an amount of an asset to an address') and even tells the agent which inputs to pass. It does not state when NOT to use it, e.g. when a plain receipt lookup is sufficient, and it offers no explicit routing against the evm_* 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?

Goes well beyond the annotations by disclosing price ($0.002/call), the charge-before/refuse-on-bad-input ordering, the fallback routing behavior, and that a P0 key causes an automatic paid call with a deduction. It also makes clear the output is an unsigned transaction (never signed/sent here). The minor gap is that the response payload shape is only described as 'the data' plus a schema link.

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

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

Front-loads the core purpose, then pricing, then the paid-call variant; each sentence carries a distinct fact. It is dense but not padded, though the x402/MPP client sentence and the long key-purchase URL add bulk that could be trimmed.

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

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

For an eight-parameter, five-required, open-world payment tool with no output schema, it covers chains, cost, validation behavior, auth options, and points to a schema URL. What an agent still lacks is any description of the returned quote fields, but the schema link partly compensates.

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

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

Schema description coverage is 100%, so all eight parameters, including slippage_bps aliasing and the decimals overrides, are already documented in the schema. The description adds no per-parameter meaning beyond the chain list it repeats, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('a DEX swap quote with a ready unsigned transaction'), names the routing providers (Velora/ParaSwap, KyberSwap fallback) and the supported chains. It is unmistakably distinct from every sibling, which are all single-chain read utilities (evm_block, evm_receipt, wallet_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?

Gives clear usage context: request a quote when you need an unsigned swap transaction, and it explains the two invocation modes (call the returned x402 request URL yourself, or supply a P0 key and let the tool pay). It does not name sibling tools as alternatives, but none of them compete for this task.

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/idempotent annotations, it discloses the non-obvious mechanics: the default response is the exact paid x402 request (GET /wallet/balance, $0.003 per call) that must be called with an x402/MPP client, and that a P0 Bearer key makes the tool perform the paid call itself. It also covers failure behavior (rejected input is not charged), which annotations cannot express.

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

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

It is front-loaded with the 'use when' condition, which is good, but one dense paragraph carries usage, output format, pricing, error behavior, alternatives, and auth/key-purchase instructions, with some redundancy ('One wallet across several chains' restates the opening clause). The key-purchase URL in particular adds bulk an agent rarely needs mid-call.

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

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

For a tool with no output schema, a two-parameter schema that is fully documented, and a paid-call wrapper, the description covers everything an agent needs: what it returns, the cost, that the returned payload is a request to be executed, and the access-key shortcut. No material gap remains.

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%, and the description adds meaning the schema lacks by enumerating the token set covered (native, USDC, USDT, DAI, WETH, WBTC/cbBTC) and reiterating the single-wallet/several-chain scoping of `address` and `chains`. It does not add syntax detail beyond the schema's existing 'comma list' guidance.

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

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

The description uses a specific verb and resource (return a wallet's token balances across several named chains and named tokens) and explicitly carves out the sibling cases: evm_erc20_balance for one token on one chain, evm_native_balance for the native coin, wallet_balance_batch for many wallets. An agent can route correctly without opening any schema.

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

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

It gives an explicit 'use when' trigger (one wallet, several chains, one call) plus three named alternatives with the exact conditions that select them. It also states the input-validation precondition ('bad input is refused before any charge'), which is actionable guidance rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context they don't carry: the $0.075 per-call price, that bad input is rejected before any charge, that the default return is an unpaid x402 request body rather than data, and that a P0 key causes the call to be paid and the balance deducted. The only gap is pagination/result-shape detail, minor given the tool returns a request payload or data directly.

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 use case and the sibling alternative are front-loaded, followed by payment mechanics, which is a sensible ordering. It is dense but nearly every sentence carries operative information; the long key-purchase URL is the one element that could be compressed.

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 actually comes back — a paid x402 request body plus a schema link, or the data itself when a P0 key is used. Combined with the pricing and pre-charge validation notes, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates them (25-address cap, chain list). It does add one piece of meaning beyond the schema by naming '0x or ENS names' as accepted address formats, but otherwise leaves the heavy lifting to the schema — baseline 3.

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

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

The description opens with a specific verb and resource: native and stablecoin balances for a list of wallets, capped at 25 addresses in one POST. It explicitly names the sibling wallet_balance as the single-address alternative, so an agent can distinguish the two without inspecting schemas.

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

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

It states the triggering condition (need balances for a list of wallets) and gives an explicit routing rule: 'For one wallet use wallet_balance.' It also explains the two operating modes — raw x402 request construction vs. auto-paying with a P0 key — which determines how the agent should proceed.

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