tailrisk_return_level

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds conceptual context (POT quantile equivalence to VaR) and lists the output fields, which is useful but largely mirrors an existing output schema. No contradiction exists between description and annotations.

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 compact paragraphs with zero filler: core purpose front-loaded, a single sentence of routing guidance, and a Returns stanza. Every sentence earns its place and the VaR-equivalence explanation is the highest-value content positioned early.

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?

Complete for a read-only, idempotent estimation tool: purpose, routing, sibling differentiation, and output format are all covered. The parameters are exhaustively documented in the schema and an output schema exists, so the description isn't required to restate them. Minor gap: no mention of edge cases like insufficient data or threshold validity, though the schema's constraints partially cover this.

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?

The input schema is richly documented - every parameter (tail, values, threshold, return_period, threshold_quantile) carries a clear description, so the schema does the heavy lifting despite the 0% coverage signal suggesting otherwise. The description bolsters this by explaining what equivalent_var_confidence means via the VaR-equivalence framing, adding interpretive value beyond the raw field names.

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-resource pair ('Estimate the level exceeded once per return period') and immediately distinguishes itself from the sibling tailrisk_var_es by explaining the vocabulary mapping ('a 100-period return level equals the 99% VaR'). An agent can tell this from Var/ES and fit_gpd without opening schemas.

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?

Explicitly states when to prefer this tool: 'Use it when the question is phrased as a 1-in-N event rather than a confidence level.' This gives clear routing against VaR phrasing. It does not, however, name the exact sibling tool (tailrisk_var_es) to switch to, nor state explicit when-not cases, only the positive trigger condition.

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