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

Richly discloses behavior beyond the annotations: the paid x402/credit rail, the payer argument or x-tollbridge-payer header, the requirement to poll /v1/resolutions/:id until horizon_end, the refund-on-refusal semantics, and the guarantee that it never fabricates a probability. The annotations themselves (readOnlyHint=true, openWorldHint=true, idempotentHint=false) are consistent with an external read that is not idempotent, though the readOnlyHint sits in mild tension with a call that debits a USDC/credit balance.

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?

Badly front-loaded: the critical 'NOT AVAILABLE YET' gate comes after a payment/logistics run-on, and 'After paying, poll /v1/resolutions/:id until horizon_end' is repeated verbatim later in the same paragraph. Refusal taxonomy is restated twice (inline and as a parenthetical list), and the x402/credit rail is re-described in three forms, all of which push the actual purpose out of view.

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 complexity (paid, gated behind 24 hourly observations, refund semantics) the description covers availability, prerequisites, payment mechanics, and refusal codes, and an output schema exists so return values need not be spelled out. What is missing is any statement of what a successful (non-refusal) response actually contains, leaving the agent without a positive-path expectation.

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 only 50% (payer has no schema description), so the description must compensate — and it does, fully specifying payer as a Base 0x… address or the x-tollbridge-payer header fallback. For asset it adds scope ('any symbol the venue universe lists... not only BTC/ETH/SOL') and routes to tollbridge_universe, adding meaning beyond the regex/length constraints.

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 identifies a specific resource — the market-wide liquidation tape for a venue asset — and explicitly distinguishes it from wallet-level data ('liquidations appear only as a marker on per-wallet fills... a single wallet is not the book'). However, it never states in plain terms what the tool returns (a liquidation-risk probability over a horizon), and the opening line is payment logistics rather than purpose, so the agent must reconstruct the intent from 'S02' and the refusal-code framing.

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 gives concrete enabling conditions (operator mounts a Hyperliquid node trade stream at NODE_TRADES_DIR, sets LIQUIDATION_SOURCE=node_trades, and 24 hourly observations must be owned before S02 leaves the default surface) and the consequence when not met (typed refusal, debit refunded). It does not point to an alternative tool to use for liquidation questions when the tape is unavailable, which keeps it short of a 5.

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