ib_option_chain

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

With no annotations provided, the description carries the full burden. It discloses the local dependency (TWS/IB Gateway) and the return data, which are relevant behavioral traits. However, it does not disclose potential failure modes (e.g., what happens if TWS is not running), absence of side effects, or data latency characteristics, leaving some behavioral ambiguity.

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 concise and well-structured: an opening summary, a one-line list of returned data, a requirement note, and a clear Args block. Every sentence earns its place with no filler or redundancy.

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 data retrieval tool with no output schema, the description covers the essential aspects: purpose, returned fields, parameter formats, and the critical local runtime dependency. It does not discuss sibling tool selection or error handling, but the overall context is sufficiently complete for a simple option chain fetch.

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?

Despite the schema lacking descriptions, the description includes an explicit Args section that fully explains each parameter: symbol (ticker symbol), expiry (YYYYMMDD format), and port (with live/paper port numbers). This adds significant semantic value beyond the bare schema and perfectly compensates for the 0% schema coverage.

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 gets option chain data from Interactive Brokers with real-time quotes, mentioning specific fields like strikes, bids, asks, volume, and implied volatility. It distinguishes itself from generic option chain tools by emphasizing IB and real-time data, though it does not explicitly name sibling alternatives.

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 an important prerequisite ('Requires TWS or IB Gateway running locally') which implies the tool is for local IB setups, but it does not explicitly state when to use this tool over other option-related siblings like option_chain or ib_option_expiries. There is no clear exclusion guidance, so usage context is only implied.

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