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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context beyond that: each wallet gets its own list (not summed), duplicate addresses are removed, sorting applies inside each wallet's block, and with 'all' chains, a counterparty appears per chain so rows should not be added together. It also warns that a wider date range is rejected, preparing the agent for error handling. 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 long but well-structured: it front-loads the purpose, then breaks down usage, limits, chain behavior, sorting, and ends with a complete example. Each sentence earns its place; there is no filler. It could be slightly tightened (e.g., repeating the 'not added together' point), but the organization is clear and aids comprehension.

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?

Given the tool's complexity (nested filters, multiple limits, sorting options, pagination), the description covers all critical aspects: the exact call shape via example, limits with error behavior, chain family rules, sorting semantics, and the distinction from the single-wallet sibling. An output schema exists, so return-value details are not required. Nothing an agent needs to invoke it correctly 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 description coverage is 100% (the input schema contains extensive descriptions for every parameter). However, the description adds meaning beyond the schema: it provides a concrete example JSON, clarifies that walletAddresses are deduplicated, explains the perPage must cover all wallets (rows stay together), and emphasizes the chain family restriction. These extras go beyond what the schema states, so it earns a 4 rather than the baseline 3.

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 states a specific verb ('Get') and resource ('top counterparties of up to 10 wallet addresses'), and immediately distinguishes it from the sibling tool address_counterparties by clarifying that this is for comparing multiple wallets, not single wallets or entity names. This makes the tool's purpose unmistakable.

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?

It explicitly tells the agent when to use this tool (comparing wallets, shared counterparties, CEX deposit addresses, fund with many wallets) and when not to (single wallet or entity name → use address_counterparties). It also provides concrete limits (max 10 addresses, 90-day range, single chain family) and explains consequences of exceeding them, leaving no ambiguity about invocation conditions.

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