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

Annotations only declare readOnlyHint, so the description carries the rest of the burden and does so well: it discloses that the sample is a share of the market, stated per bucket and 'never scaled up', and that cascades/largest orders come only from venues that publish them (OKX, Gate). It also explains the 1y baseline methodology (percentile, 'largest since' date, median day), which is behavioral context no annotation or schema conveys.

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 the core resource and scope, and each sentence carries distinct content (contents, sample caveat, use rationale, baseline). It is a single dense paragraph of roughly 110 words, which is heavier than needed; light structuring would improve scanability without losing information.

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?

An output schema exists, so return values need not be spelled out; the description instead supplies the methodology, caveats, and use framing that an agent needs to interpret the numbers correctly. Nothing material for correct invocation or interpretation 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 coverage is 100%, so both defaults and ranges are already documented; baseline is 3. The description adds some framing — the interval drives the timing sample, top_orders is the largest individual liquidations, and hours relates to the 'trailing ~24h' baseline — but it doesn't add format or unit detail beyond the schema, and 'minute-level timing sample' sits slightly oddly against a 5m/15m/1h enum.

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 — 'Liquidation history for one coin's perpetuals' — and enumerates the exact contents: market-wide long/short liquidations in 4h buckets, a 24h venue split, and a minute-level timing sample with detected cascades. It even positions itself against a related signal (inferring liquidations from price/OI), so an agent can distinguish it from derivatives_open_interest and derivatives_flow 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 a clear use condition — 'Use it to say WHEN and WHICH SIDE was forced out, instead of inferring liquidations from price and open interest' — and the rationale (flat OI can hide heavy liquidations). It stops short of naming sibling tools or stating exclusions (e.g., when derivatives_flow is the better pick), so it is strong context rather than a full routing rule.

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