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

Beyond the readOnly/openWorld annotations, the description discloses resolution sources (data: URIs, https, ipfs:// via ipfs.io), truncation of strings over 1,000 characters such as on-chain SVGs, the 422-uncharged failure mode, metadataError reporting, and the charging model ($0.01/call, first 25 free, failed calls free). "Each call is charged, so repeats are not free" explains the idempotentHint=false rather than contradicting 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?

Front-loaded with the operation and semantics, then alternatives, then edge cases, then pricing — a logical order. The pricing/credits clause is longer than strictly needed for tool selection, which keeps it off a 5.

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 burden and does: it enumerates the returned fields, describes transformation of long strings, and defines both failure shapes (422 vs metadataError). Nothing an agent needs to call or interpret this tool 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 100%, so the baseline is 3; the description goes modestly further by tying tokenURI lookups to "one ERC-721 token id" and supplying a concrete worked example (contract=0xC364...FE88, tokenId=1) that clarifies address/id formatting. It does not add new constraints beyond the schema's "whole number" and 0x-address notes.

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 scope: reads the tokenURI of one ERC-721 token id on Optimism and the JSON it resolves to (name, description, image, attributes). It also names the adjacent sibling it is not (op_nft_owner), so an agent can pick it without opening 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?

"Use to show or check what an NFT is; for its owner use op_nft_owner" gives explicit when-to-use plus a named alternative with the condition that selects it. Error-path guidance (non-existent token = 422 uncharged, unreachable metadata surfaces in metadataError) further tells the agent what to expect at failure.

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