ib-gateway-mcp

Stream a market scan

subscribe_scanner

Read-only

Subscribe to a market scanner that continuously updates rankings and returns a handle for reading current rows, checking errors, or canceling the scan.

Instructions

Keep a market scan running so its ranking follows the market; returns a handle.

Takes the same arguments as run_scanner. Read the current rows with
get_subscription_data(subscription_id): rows (best first), updated_at, no_matches
(nothing qualifies right now) and error. Stop it with unsubscribe; it is also
cancelled after the idle time in idle_ttl_s without a read. The same scan asked
for twice returns the existing handle (deduplicated=true).
Limits: at most 50 rows; IBKR allows 10 scanner subscriptions at a time.
Errors: ib_api_error when IBKR rejects the scan (check the codes with
get_scanner_parameters); subscription_limit when no slot is free.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`rows`	No	How many rows to return (1-50).
`filters`	No	More filters as tag: value, with tags from get_scanner_parameters section="filters", e.g. {"avgVolumeAbove": 100000}.
`scan_code`	Yes	What to rank by, e.g. TOP_PERC_GAIN or MOST_ACTIVE.
`instrument`	No	Instrument type, e.g. STK (US stocks) or FUT.US.	STK
`above_price`	No	Only prices above this.
`below_price`	No	Only prices below this.
`above_volume`	No	Only volume above this.
`location_code`	No	Market or exchange, e.g. STK.US.MAJOR or STK.NASDAQ.	STK.US.MAJOR
`market_cap_above`	No	Only market capitalization above this.
`market_cap_below`	No	Only market capitalization below this.

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.5/5.0

Behavior5/5

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

Beyond annotations, the description discloses lifecycle details: deduplicated handles, idle TTL cancellation, the 50-row cap, IBKR's 10-subscription limit, and specific error types. This is rich behavioral context for a streaming tool.

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-organized: purpose first, then reading data, stopping, deduplication, limits, and errors. Every sentence adds useful operational information without padding.

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 output schema exists and parameters are fully documented, the description covers the remaining usage-critical aspects: subscription lifecycle, how to retrieve data, cancellation, deduplication, limits, and error handling. Nothing needed for correct invocation is missing.

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?

Schema description coverage is 100%, so every parameter is already documented. The description adds matching-argument context with run_scanner and a row limit note, but it does not need to repeat parameter meanings; baseline 3 applies.

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 starts with a specific action and resource: 'Keep a market scan running so its ranking follows the market; returns a handle.' It clearly distinguishes this subscription tool from a one-shot scanner by referencing run_scanner's arguments while emphasizing the persistent handle returned.

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

Usage Guidelines4/5

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

It gives clear workflow guidance: read results with get_subscription_data(subscription_id), stop with unsubscribe, and be aware of idle-time cancellation. It references run_scanner only for argument compatibility, not explicit when-not-to-use, so it stops short of a 5.

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

Deploy Server