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

Annotations already declare read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the premium/API-key gate, the free-key path, x402 pay-per-call, and a disclaimer that output is analytics rather than advice. It stops short of cost details or rate limits.

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-loading the premium/access notice lets an agent resolve the paywall before reading the analytics detail, and every clause maps to actual output content. The bracketed preamble is somewhat dense but earns its place.

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?

With an output schema present, the description needn't document return values, and it does cover the access prerequisite and analytic scope. The only gap is mild ambiguity around the 'mirror' shocks and how stress results are presented across multiple positions/dexes.

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 100%, so the schema already explains address, dex (including 'all' and HIP-3 builder dexes), and shocks. The description restates the default shock ladder (-5/-10/-20% plus mirror), which adds slight value, but says nothing about the dex parameter. Baseline 3 applies.

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 states a specific verb+resource ('Risk report for a perp address') and enumerates the exact metrics returned: liquidation distance, effective leverage, HHI concentration, stress scenarios, and Sharpe of realized PnL. It does not distinguish itself from a close sibling like hl_trader_report, leaving some ambiguity about which report to pick.

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 access requirement is well handled – it says to call hl_request_free_key first for a free key or pay per call via x402. But there is no guidance on when to use this versus hl_trader_report or hl_get_account, so the choice between risk-oriented and account/performance-oriented tools is left to inference.

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