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

Annotations declare readOnlyHint and openWorldHint, but the description adds substantial billing and error behavior: $0.01/call via x402 or card key, first 25 free, failed calls free, and that repeats are not free (consistent with idempotentHint=false). For a paid, open-world tool this is exactly the extra context an agent needs before invoking 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 purpose and return fields, followed by routing, error, and pricing details. Slightly dense and includes some reinforcement of annotation semantics ('Reads or computes only and changes nothing'), but no sentence is truly wasted.

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 one-parameter read tool with no output schema, the description covers what data is returned, how to request a specific block, the not-found behavior, pricing, and the alternative for gas fees. Nothing an agent needs to call it correctly appears to be 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% and the schema already documents 'Block number, or "latest" (default)'. The description still adds some value by clarifying 'any block by decimal number' and giving a concrete example ('number=latest'), though it does not go much 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 ('Latest block number and block details on Polygon PoS') and enumerates the exact fields returned (hash, timestamp, tx count, gas used/limit, base fee, producer). It also names the sibling it is not ('for current fees use polygon_gas'), so an agent can distinguish it 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?

Explicitly names the use cases ('timestamps and confirmation counts') and the alternative for a competing need ('for current fees use polygon_gas'). It also documents the not-found case ('A block that does not exist yet returns 404, uncharged'), which is the kind of edge guidance that prevents bad calls.

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