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

Annotations only declare readOnly/idempotent/non-destructive; the description goes far beyond by disclosing percent units, the 2y+ WEEKLY bar rollup, the 400-bar cap, the returned coverage and spot_is_proxy flags, and a no-trade-recommendation constraint. These are exactly the behavioral traits an agent cannot infer from structure.

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?

Dense but front-loaded — purpose and fields come first, then units, then the rollup/cap caveats, then the reporting constraint. Every sentence carries information, though the units and rank-vs-percentile clarifications make it longer than strictly minimal.

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 no output schema, the description carries the burden of explaining returns and does so — bar_interval, coverage, spot_is_proxy, and the 400-bar limit are all covered. An agent has everything needed to interpret and report the series correctly.

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 100%, so the structured fields already define range/symbol/aliases, giving a baseline of 3. The description still adds real meaning: it warns that longer ranges return weekly bars and that bar_interval must be read, which materially changes how the enum value should be interpreted.

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 verb+resource (historical option-analytics time series for an underlying) and enumerates the exact fields returned (ATM IV, IV rank/percentile, realised vol, PCR, max pain, 25-delta skew). It explicitly differentiates from sibling get_option_chain by noting this covers ~556 underlyings INCLUDING individual stocks while the chain is index-only.

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?

Provides concrete triggering queries ('is IV high right now', 'IV rank of RELIANCE', 'has volatility been rising') and the condition that selects this over get_option_chain. It stops short of an explicit when-not beyond the index-only contrast, and never references the sibling get_options_analytics, which an agent may confuse with a snapshot counterpart.

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