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

Annotations only declare readOnlyHint=true, so the description carries the rest and does so usefully: it discloses the two-phase payment handshake, the exact metadata key for the signed payment, and the shape of the returned payload. It does not mention rate limits, failure modes, or the fact that the second call's payment terms must match the first.

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 payment instructions are front-loaded and useful, but a ~2KB verbatim dump of a block header is pasted inline. That raw JSON is mostly unreadable noise and crowds out any concise summary of the return shape that would have served the same purpose in a fraction of the space.

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

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

With no output schema, the sample payload does at least ground the agent in the return shape, and the payment flow is fully described. Combined with a fully documented single parameter, an agent has what it needs to make the call correctly; only failure/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% and the single parameter 'block' is already documented in the schema as 'a block number, or latest'. The description restates the same semantics without adding format detail (hex vs decimal, tag options), so it adds nothing beyond structured fields. Baseline 3 applies.

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

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

States a specific verb and resource: an Ethereum mainnet on-chain read that returns the block header for a given block number or 'latest'. Clear on its own, but it never distinguishes itself from the near-identical sibling x402_eth_reads_v1__eth_mainnet_eth_get_block_by_number, which an agent could easily confuse with this one.

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 concrete invocation guidance for the x402 flow: 'Call once with no payment. The result is the payment terms. Retry the same call with the signed payment at _meta["x402/payment"].' That is genuinely actionable and not derivable from the schema. It offers no when-not guidance or alternative-selection criteria against the many sibling chain-read tools.

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