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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral context: it never fetches live data, uses SYNTH or a user-supplied chain, and returns records (strategy_records, Greek units, scenarios, cost assumptions) that should be used verbatim in tables. This goes well beyond what annotations alone communicate and does not contradict them.

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 three tight sentences with no filler. The main output and preference statement are front-loaded, and the remaining sentences add high-value guidance about returned records and data-source behavior. Every sentence earns its place.

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?

For a tool with 10 optional parameters and zero schema-level descriptions, the description covers the output bundle and data-source constraints well, and the output schema handles return-value details. However, it leaves substantial gaps around several parameters and does not name sibling tools for single-chart alternatives, so an agent may still need to infer significant meaning from parameter titles alone.

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, but it only hints at 'up to three' payoff charts (strategies maxItems) and 'SYNTH or a user-supplied chain' (data source options). It does not explain rate, expiry, dividend_yield, source_data, source_text, source_format, or rights_confirmed, leaving most parameters under-specified for an agent.

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 names a specific verb ('Return'), a concrete resource set ('market map, Greek ladder, strategy comparison and up to three requested payoff charts'), and a key differentiator ('ONE widget'). It clearly distinguishes this aggregate reporting tool from individual plot calls without needing to open the schema.

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 explicitly says to prefer this tool for multi-chart reports instead of parallel individual plot calls, and cautions against inventing currency or multipliers when using the returned records. It gives clear context for when to choose it, though it does not name specific sibling tools or state exclusions for single-chart requests.

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