Historical Aerodrome cash flows and holdings

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: it verifies protocol logs against receipts and ERC-20 transfers, returns gaps, and follows a specific retry pattern (PARTIAL → retry same page, else nextFromBlock). It also states the scope remains unchanged, which is important for pagination. This goes beyond the annotations and provides transparency about how the tool behaves during a multi-page walk. No contradiction with annotations.

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?

The description is four sentences, each carrying distinct value: scope, verification behavior, outputs, and exclusions/pagination. It is front-loaded with the primary action and immediately states the resource and its boundaries. No filler or repetition; every clause earns its place. This is exemplary conciseness.

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?

The description covers the tool's scope, verification, outputs, pagination, and exclusions. The output schema and annotations already provide return types and safety profile. However, it does not explicitly explain the wallet parameter (beyond the 'configured wallet' mention in tokenIds schema) or the exact meaning of blockSpan, though these are secondary. For an agent, the description gives enough to call the tool correctly across pages, but a tiny bit more on the wallet override and blockSpan would push it to a 5.

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 67% (4 of 6 parameters have descriptions). The description adds contextual meaning by tying parameters to the tool's behavior: 'selected veNFT rebases' relates to tokenIds, 'explicit voting-pool reward receipts' to pools, and 'fixed toBlock'/'nextFromBlock' to toBlock/fromBlock. It also clarifies that history is paginated by block (complementing fromBlock's schema description). While it doesn't elaborate on blockSpan or wallet (both lacking schema descriptions), the description does not duplicate schema info and provides a cohesive usage model. Given the high coverage baseline of 3, the added context justifies a 4.

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 opens with a specific verb and resource: 'Read a bounded Base block page of wallet escrow deposits/withdrawals, selected veNFT rebases and explicit voting-pool reward receipts.' It further clarifies outputs (per-token page sums, event links, gaps, holdings at fixed toBlock) and explicitly excludes lifetime discovery, LP accounting, cost basis, and net profit, which distinguishes it from sibling tools like aerodrome_wallet_rewards, aerodrome_wallet_snapshot, and aerodrome_wallet_report. This is a precise and unambiguous statement of purpose.

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?

The description gives clear usage boundaries: it is for a bounded page of history, not lifetime discovery, and explicitly excludes LP accounting, cost basis, and net profit. It also provides pagination guidance: 'On PARTIAL retry the same page; otherwise continue with nextFromBlock and unchanged scope/toBlock.' While it doesn't name specific alternative tools, the exclusions implicitly route the agent to other tools for those tasks, and the pagination instructions are concrete. This is more than minimal guidance, though it stops short of explicitly naming siblings.

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