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

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered. The description does add a genuinely useful behavioral fact – that the call costs $0.005 USDC and requires payment or a prepaid key – which is not in the annotations. It says nothing about rate limits, latency, failure modes when payment is missing, or what a response looks like.

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?

A single tightly-packed sentence with the paid-status and the resource front-loaded, and every clause carries actual information about the returned fields. It is appropriately short for a 4-parameter read tool. The cost marker is somewhat clipped ('PAID $0.005 USDC') but reads clearly enough in context.

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?

There is no output schema, so the description correctly enumerates the payload (whale orders, net flow, mark price, 24h change, funding, OI). But for a paid, authenticated tool with an undocumented `min_usd` and an enum `window` with no default, an agent still lacks enough to invoke it confidently. Adequate, with clear gaps.

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 25% – only api_key is documented. The description supplies examples for the required `coin` parameter (BTC, SOL, HYPE), which is helpful, but `window` has an enum with no stated default and `min_usd` is completely unexplained in both schema and description. With low coverage the description needed to compensate and largely does not.

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+resource: whale orders and net whale buy/sell for one Hyperliquid coin, plus mark price, 24h change, funding and open interest. The scope ('one coin') and the example tickers make what it returns concrete. It does not, however, distinguish itself from the sibling tools whale_moves and whale_netflow, so the agent must infer the split.

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 no when-to-use guidance and never names an alternative. With whale_moves, whale_netflow, free_prices and perp_funding all in the sibling list, an agent has no stated rule for choosing this paid tool over them. The only hinted usage signal is the '$0.005 USDC' price, which functions as a cost warning rather than routing guidance.

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