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

Annotations already establish this is a safe, idempotent, closed-world read, so the description's job is to add beyond that — and it does: it discloses that results carry a degraded status flag and a loss sign convention, and that the permission gate is a self-attestation that does not verify a licence. That last caveat is genuinely valuable context an agent could not infer from the schema. It falls short of 5 only because it says nothing about compute cost or limits on the large P&L vector.

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?

Four short sentences with the purpose front-loaded and the permission caveat last, which is the right ordering. The sentence 'Report degraded status and the loss sign convention before the numbers' is compact but slightly cryptic, reading as an output instruction rather than a statement of what the tool does.

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 formatting need not be spelled out, and the description covers the key trust caveats (degraded status, sign convention, licence non-verification). What is missing is enough guidance on the request payload — confidence levels, horizon bounds, and P&L array constraints — for a tool whose only parameter is a nine-field nested object with zero schema documentation.

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 parameter meaning itself. It does explain rights_confirmed semantics precisely ('this does not verify a licence') and implies the request-absent/request-present modes tied to data_mode, but the nine nested TailRequest fields (pnl, confidence, horizon_days, portfolio_value, currency, as_of, source) are left to their self-describing names, including the minimum of two P&L observations and the 1,000,000 cap.

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 first sentence names a specific computation (historical VaR and Expected Shortfall) over a specific input (supplied horizon P&L), which is concrete enough to separate it from attribution, backtest, or model-selection siblings. It does not name a sibling explicitly, so it stops short of a 5, but the purpose is unambiguous on its own.

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 a clear branch condition: omit the request to run the bundled public synthetic energy example, or supply data with rights_confirmed=true and permission. That is actionable when-to-use guidance rather than implied usage. It stops at 4 because it does not name or contrast against any alternative tool for related tail-risk work.

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