ib-gateway-mcp

Option chain

get_option_chain

Read-only

List option expirations and strikes for any underlying without needing a market data subscription. Get trading classes, multipliers, exchanges, and available strikes to explore options before quoting.

Instructions

List the option expirations and strikes available on an underlying (no prices).

Returns one entry per trading class (e.g. SPX monthly and SPXW weekly), with its
multiplier, the exchanges listing it, all expirations (YYYYMMDD) and all strikes.
Strikes are the union across expirations: not every strike exists for every expiry,
so qualify_contract a specific option before quoting it. This is the cheap way to
explore options; it needs no market data subscription and has no pacing concerns.
For US stock and index options pass exchange SMART: IBKR lists a chain per options
exchange, and chains that differ slightly are not merged, so the full answer can be
long. Quotes and greeks come from the options and market_data tools.

Errors: not_found when the underlying is unknown or has no listed options (or none on
`exchange`); invalid_request when `underlying` is itself an option or combo (also when
given by the con_id of one).

Input Schema

TableJSON Schema

Name	Required	Description
`exchange`	No	Only return chains listed on this exchange, e.g. SMART or CBOE. Omit for all exchanges (identical chains are merged anyway).
`underlying`	Yes	The instrument the options are on: a stock (symbol, sec_type STK), an index (sec_type IND with its exchange, e.g. SPX on CBOE) or a future (sec_type FUT with exchange and contract month), or its con_id.
`fut_fop_exchange`	No	For futures options: the exchange they trade on, e.g. CME. Omit to use the future's own exchange (for stocks and indexes: all exchanges).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`chains`	Yes
`underlying`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses important behavioral traits: strikes are the union across expirations and not every strike exists for every expiry, so qualify_contract must be used before quoting. It also covers exchange merging behavior, cost characteristics (no subscription, no pacing concerns), and specific error conditions (not_found, invalid_request). No contradiction with annotations found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: it starts with the core purpose and the critical 'no prices' caveat, then covers output shape, usage notes, and errors in separate digestible blocks. Every sentence earns its place, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations already cover the read-only safety profile and an output schema exists, the description supplies all remaining essential context: underlying kinds, exchange behavior, subscription behavior, the need to call qualify_contract before quoting, and error conditions. Nothing important for selecting or invoking the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters richly, so the baseline is 3. The description adds operational meaning beyond the schema by recommending SMART for US stock/index underlyings and explaining why exchange-specific chains are not merged, which adds useful context beyond what the schema says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: 'List the option expirations and strikes available on an underlying (no prices).' The description goes further to distinguish the tool from pricing tools by explicitly saying 'no prices,' and explains it returns one entry per trading class with multiplier, exchanges, expirations, and strikes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear when-to-use guidance: 'This is the cheap way to explore options; it needs no market data subscription and has no pacing concerns.' It also tells callers to pass exchange SMART for US stocks/indexes because IBKR lists a chain per exchange and chains are not merged, and it routes quote/greek needs to the options and market_data tools.

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

Deploy Server