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

Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, yet the description adds real substance: a scan window of 1-1,000 blocks (default 50), a hard cap of ~100 returned logs, the returned fields, and the billing model with the note that repeats are not free — which explains the non-idempotent hint. The closing 'changes nothing' sentence only restates readOnlyHint.

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 returns, then usage, then the example, then cost. Almost every sentence earns its place, though 'Reads or computes only and changes nothing' duplicates the readOnlyHint annotation and the pricing sentence is dense.

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?

No output schema exists, and the description compensates by naming the returned fields (block, transaction hash, topics) and the 100-log ceiling. Together with the scan-window limits and cost model, an agent has everything needed to call it and interpret results.

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%, so all three parameters are documented upstream; the description repeats the block range/default and clarifies that topic0 is the 32-byte event signature hash, only marginally beyond the schema. The example address is a nice touch but not semantic clarification of usage rules.

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 ('Recent contract event logs on Optimism') and anchors it to the underlying RPC call (eth_getLogs). It names the sibling it is not — op_receipt — so an agent can separate it from the other ~20 op_* tools without opening a 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?

Gives an explicit positive case ('watch transfers or contract events') and an explicit negative case with the alternative to use instead ('for one transaction's outcome use op_receipt'). That is the when/when-not/alternative triad done properly.

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