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

Annotations only cover readOnly/openWorld/idempotent, so the payment behavior had to come from the description — and it does: $0.001 USDC on Base per call via x402, unpaid calls return a PaymentRequired object, and the retry path is params._meta["x402/payment"]. That is exactly the non-obvious operational detail an agent cannot infer.

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?

A single dense paragraph with the substantive content (what it returns, which chains) front-loaded and the pricing/payment mechanics trailing. Dense but no filler sentences; the URL endpoint note is marginal but defensible.

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 describe returns, and it enumerates the fields and the denomination (native coin). Payment and error-path behavior are fully covered. It stops short of stating units or freshness/caching, which would matter for a price tool an agent might cache.

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% with an enum, so the baseline is 3; the description earns an extra point by documenting an out-of-schema parameter (the x402 payment _meta key) and restating the all-chains default. It adds no unit or format guidance for the enum values themselves.

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 (gas price, base fee, priority fee, block fullness, transfer costs) with concrete gas units (21k, 65k) and enumerates all eight supported chains. An agent can tell immediately this is a gas-oracle snapshot tool, distinct from price or balance 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 clearly states the default behavior (omit chain for all 8) and the single-chain option, plus the one-line HTTP equivalent. It does not name an alternative or exclusion case, but no sibling tool overlaps in function, so the selection context is effectively unambiguous.

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