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

The annotations declare readOnlyHint=false and idempotentHint=false, but the description explicitly frames this as a read ('read live from the contract', returning metadata only) with no state mutation described. That is a direct conflict for an agent deciding whether the call is safe. Real added context is present — the $0.001 USDC-on-Base x402 cost per successful call and the fact that values come live from chain rather than cache — but the read/write contradiction dominates.

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, no filler: what is returned, when to use it, what it costs. The payload is front-loaded so an agent can match it on the first clause, and the pricing sentence is last where it belongs.

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 it discloses the payment mechanism an agent must satisfy before calling. It omits failure behavior (e.g., what happens for a non-contract or non-ERC-20 address) and any indication of whether the response is cached, but nothing critical to invoking it 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?

Only one parameter, and the schema documents it at 100% coverage ('0x ERC-20 token contract address'), so the schema carries the load. The description adds the chain qualifier ('on Optimism'), which implies the address must be an Optimism contract, but 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?

Names the exact fields returned (name, symbol, decimals, total supply) for a specific resource (ERC-20 contract) on a specific chain (Optimism), and 'read live from the contract' establishes it is a fetch, not a write. The op_ chain prefix plus the metadata-vs-balance distinction separates it from op_token_balance and eth/arb/base/polygon_token_info implicitly, though sibling routing is never stated in words.

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 identify an unknown token address or to format raw token amounts correctly' gives two concrete use cases, which is more than most definitions offer. It stops short of naming alternatives (e.g., price_token for valuation, op_token_balance for balances) or stating 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.