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

Annotations already mark it read-only and closed-world; the description adds important context beyond that: paid cost of $0.005 USDC, default min_usd threshold, top-40-market coverage, listed output fields, and polling suitability. It stops short of covering rate limits, ordering, or pagination behavior.

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 one dense sentence that front-loads the payment cost and then packs in scope, default threshold, return fields, and polling guidance. It is efficient, though the single-sentence form makes some details harder to scan.

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?

It covers the paid nature, data universe, default threshold, return fields, and polling intent, which is substantial for a read-only paid tool. But with no output schema and only 17% schema coverage, the missing parameter semantics and lack of format or rate-limit detail leave gaps for a 6-parameter tool.

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 only 17%, with only api_key documented in the schema. The description supplies the min_usd default ($100k) and implies a window concept, but leaves coin, side, limit, and the window enum values unexplained; side, USD size, price, and taker address are presented as output fields rather than clarified filter parameters.

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 names a specific dataset: large taker orders on Hyperliquid perps across the top 40 markets, including side, USD size, price, taker address, and net whale buy/sell per coin. This distinguishes it from generic price or netflow siblings, though it does not explicitly name an alternative tool.

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 phrase 'Built for polling' signals a monitoring use case, and the default $100k threshold implies whale-alert usage. However, it does not state when to use this instead of siblings like whale_netflow or price_moves, nor does it give exclusions.

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