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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds valuable scope limits beyond that: it is a deterministic linear shock, not a liquidation or probability model, capping at 20 exposures and warning that symbols are scenario labels, preventing misinterpretation as a risk-of-ruin model.

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?

Three short, front-loaded sentences that each carry information: what it computes, how scenarios are labeled, and what it deliberately is not. No filler, though the 'symbols' wording is a small ambiguity cost.

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?

No output schema exists, so the agent must rely on the description for return values; the mention of P&L, equity, and concentration is a useful but thin sketch of outputs. With 0% parameter coverage, a two-parameter input object with a nested positions array is only partially explained, leaving the definition adequate but incomplete.

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%, so the description must carry the full burden. It mentions '20 exposures' and references equity, but it never explains the required fields (asset, side, notional_usd, price_change_pct) or the optional venue/cost_usd fields, and it confusingly calls them 'symbols' when the schema field is 'asset'.

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 action (applying caller-input linear shocks) and resource (crypto portfolio exposures), and names the outputs it produces: P&L, equity, asset/venue concentration. It is clearly distinguishable from siblings like venue_concentration or crypto_exit_check, though it does not explicitly name an alternative.

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 phrase 'caller-input linear shocks' and 'Symbols are scenario labels' implies this is a what-if scenario tool rather than a probability/liquidation model, which helps an agent pick it over crypto_exit_check. However, there is no explicit when-to-use/when-not statement or named alternative.

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