Options max pain by expiration

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

The description discloses key behavioral traits beyond the readOnly/openWorld annotations: reproducibility due to 'pure arithmetic', deterministic results ('anyone with the same chain gets the same number'), error conditions for cash-settled indices, and the fact that results describe prior-session positioning. This adds significant value over the bare 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?

The description is a single dense paragraph, but every sentence adds value: it defines the metric, explains the computational invariant, lists additional return fields, justifies the 45-day window, enforces the universe restriction, and notes data timing. No fluff or redundancy; sentence order is logical and front-loaded with the core purpose.

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?

Given the moderate complexity and absence of an output schema, the description provides sufficient context: it names return components (put/call ratio, heaviest strikes, as_of, spot_date), explains per-expiration semantics, states the 45-day horizon, and covers error cases. This is fully actionable for an agent without further structure.

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%, and both parameters have clear descriptions in the schema (symbol and distribution). The tool description adds no new parameter-level details beyond the schema, e.g., it does not explain that the distribution parameter corresponds to the distributionally heavy output mentioned. Thus, baseline 3 is appropriate.

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 clearly states the tool computes 'Options max pain per expiration' with a specific method (from open interest alone), and distinguishes itself from siblings like quantdata_gamma and quantdata_weis_wave by emphasizing it uses no pricing model or volatility assumption. It also specifies unique outputs (put/call ratio, heaviest strikes) and a specific scope (US stocks/ETFs), making it unambiguous.

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 provides explicit usage guidelines: 'Returns every expiration inside 45 days rather than picking one' and 'US listed stocks and ETFs only', with direct alternatives for excluded assets ('use SPY, QQQ, IWM'). It also gives behavioral context about data freshness ('open interest settles overnight'), helping the agent decide when to use this tool.

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