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

No annotations are provided, so the description carries the full behavioral burden. It discloses that events are measured against each coin's own 7-day baseline, that the baseline is fixed even when hours changes, and what each event contains (side, duration, total and peak-minute USD, multiple, mark-price move). It does not describe return format (no output schema) or whether results are sorted, but it adds substantial behavioral context beyond the bare schema.

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 front-loaded with the core definition, then exclusions, then event fields, then market_wide, then the hours parameter. It is dense but every sentence contributes. The ordering could be slightly tighter, but there is no obvious filler.

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?

For a two-parameter read tool with no output schema and no annotations, the description covers purpose, alternatives, event contents, the market_wide concept, and the hours semantics. The only material gap is limit, which is undocumented despite 0% schema coverage. Otherwise an agent has enough to invoke it correctly.

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 0%, and the description does add meaning for hours ('display window; baseline is always the last 7 days') beyond the schema's bare integer default. However, the second parameter limit is never mentioned in the description, leaving one of two parameters undocumented given zero schema coverage. The description partially compensates but does not fully cover both 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 opens with a specific verb and resource: 'Liquidation CASCADES as discrete events: bursts of liquidations detected against each coin's own 7-day normal minute.' It then explicitly distinguishes itself from three sibling tools (get_liquidations_summary, get_liquidations, *_liquidation_map) by naming what each covers instead.

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 an explicit use case ('when did forced selling snowball and what did price do') and then lists four exclusions with the alternative tool named for each: totals, raw orders, open positions at risk. The exclusion of get_liquidations_summary and get_liquidations is unambiguous.

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