Options chain hour by hour: open interest and IV per expiry and strike, the change over 1h and 24h, the ATM IV path

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

With readOnlyHint and openWorldHint already declared, the description adds real value: it discloses the data source (own hourly capture across every listed venue), plan gating (Free = largest strikes, Builder+ = all strikes), and a hard history boundary (recorded from 2026-09-30, so early days have short history). It does not cover payload shape, pagination, or latency, but with annotations carried elsewhere a 3 fits.

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?

A single dense but well-ordered block: trigger first, payload second, plan/history caveats last. Every clause carries content (source, fields, plan limits, history start), though the sentence runs long enough that an agent must parse carefully.

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 read-only analytical tool with a fully described 4-param schema and no output schema, the description covers the trigger, the returned fields, the venue scope, plan-tier limits, and the history truncation caveat. The main remaining gap is a sense of response shape/granularity (row-per-strike-per-hour vs. summary), which is only inferable.

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% and three of four params are enums with their own descriptions, so the schema does the heavy lifting and the baseline applies. The description adds only the plan-constrained meaning of strikes=all and the default-every-expiry behavior, which is marginally useful but largely redundant with the schema.

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 concrete trigger and resource: 'when the user asks how the BTC or ETH option chain moved today or over the last day', plus the exact payload (OI and mark IV per expiry/strike, 1h/24h change, front-expiry ATM IV path). This implicitly separates it from snapshot-style siblings like get_options_snapshot and get_iv_surface, but it never names those siblings explicitly.

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?

Gives an explicit, actionable call condition ('moved today or over the last day'), which is more than most siblings offer. It stops short of naming alternatives or stating when another options tool (snapshot, flow, IV surface) is the better choice.

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