ib-gateway-mcp

Stream market depth

subscribe_market_depth

Read-only

Start streaming live Level II order book depth for a contract, with bids and asks at multiple price levels, to track market liquidity and venue pricing.

Instructions

Start streaming the order book (Level II market depth) of one contract.

get_subscription_data returns `bids` and `asks` as levels (position 0 is the best
price) with price, size and market maker or venue. IBKR allows only 3 depth
streams at a time by default; this server refuses a 4th (unsubscribe one first).
One depth stream per contract: subscribing again returns the same handle with its
original rows and smart_depth. Needs live data (not available when
set_market_data_type chose delayed) and a Level II (depth of book) subscription
for the exchange; get_depth_exchanges lists exchanges that offer depth. Errors:
309 (depth limit), 10092 (no depth for this contract and exchange), 354 (no
subscription).

Input Schema

TableJSON Schema

Name	Required	Description
`rows`	No	Price levels per side of the book.
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.
`smart_depth`	No	Aggregate the book across all exchanges (each level names its venue). False shows the book of the contract's exchange only.

Output Schema

TableJSON Schema

Name	Required	Description
`key`	Yes	What it streams for: the contract id plus parameters.
`kind`	Yes	What streams: quotes, depth, tick_by_tick, realtime_bars, bars, scanner, news_bulletins, news or display_group.
`contract`	No	The instrument, when there is one.
`created_at`	Yes
`idle_ttl_s`	Yes	Seconds without a read before it is cancelled.
`deduplicated`	No	True when an identical stream was already open and its handle was returned instead of opening a second one.
`subscription_id`	Yes	Handle for get_subscription_data and unsubscribe.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations (readOnlyHint: true, openWorldHint: true) cover safety, but the description adds valuable behavioral context beyond them: the depth limit and server refusal, the idempotent resubscription behavior ('One depth stream per contract: subscribing again returns the same handle with its original rows and smart_depth'), and the prerequisites for live data and Level II subscription. Error codes (309, 10092, 354) further disclose failure modes. No contradiction with annotations.

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 dense but every sentence earns its place: purpose in the first sentence, data shape reference, limits, idempotency, prerequisites, and error codes. It is front-loaded with the core action and structured as a compact paragraph followed by error list, maximizing information per word.

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 that the tool has an output schema and rich annotations, the description fully covers the calling context: prerequisites (live data, Level II subscription), capacity limits, idempotency, and error handling. It also references the sibling get_depth_exchanges and get_subscription_data, completing the mental model for an agent deciding to use this tool.

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

Parameters3/5

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

The input schema describes all three parameters (contract, rows, smart_depth) with high detail, including defaults and constraints, so schema coverage is 100%. The description adds no new parameter-level meaning beyond noting that rows and smart_depth persist when resubscribing, which is more behavioral than semantic. A baseline 3 is appropriate since the schema does the heavy lifting.

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 description opens with 'Start streaming the order book (Level II market depth) of one contract,' giving a specific action, resource, and scope. It distinguishes itself from sibling streaming tools like subscribe_quotes and subscribe_bars by naming the exact data type (order book depth) and later referencing get_subscription_data as the counterpart that reads the stream.

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?

Provides explicit when-to-use and constraints: 'IBKR allows only 3 depth streams at a time by default; this server refuses a 4th (unsubscribe one first),' and 'Needs live data (not available when set_market_data_type chose delayed) and a Level II (depth of book) subscription.' It also routes the user to get_depth_exchanges to find eligible exchangeshare and lists error codes for troubleshooting, leaving nothing to inference.

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

Deploy Server