ib-gateway-mcp

Stream IBKR bulletins

subscribe_news_bulletins

Read-only

Subscribe to receive IBKR system bulletins about exchange availability. Get notices when an exchange becomes unavailable or available, with a handle to read each bulletin.

Instructions

Stream IBKR's system bulletins: notices and exchanges becoming unavailable or available.

Returns a handle; read the bulletins with get_subscription_data(subscription_id)
(each has type news, exchange_unavailable or exchange_available, the message and the
exchange). There is one bulletin stream per gateway connection, so calling this
again returns the same handle, and all_messages only counts the first time. Stop it
with unsubscribe; it is cancelled after idle_ttl_s seconds without a read.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`all_messages`	No	Also send the bulletins already issued today, not only new ones.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses critical behaviors: one stream per gateway connection, repeated calls return the same handle, all_messages only counts on first call, and auto-cancellation after idle_ttl_s seconds. This is rich, non-obvious context that materially affects how an agent should invoke and manage the subscription.

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, return-handle usage, event types, stream identity semantics, and cancellation. It is front-loaded with the core purpose and uses compact phrasing without unnecessary 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 simple input schema, rich annotations, and existing output schema, the description covers everything an agent needs to invoke and consume this tool correctly: what it returns, how to read it, how to stop it, and its unusual single-stream behavior. Nothing essential 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 the single optional parameter with 100% coverage. The description adds valuable nuance by linking all_messages to the first-call-only behavior of the stream, which is not present in the schema. This exceeds the baseline but is still limited to one parameter.

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 states a specific verb and resource: 'Stream IBKR's system bulletins' and specifies the content type ('notices and exchanges becoming unavailable or available'). It clearly distinguishes this from sibling tools like subscribe_news by focusing on system bulletins rather than news articles.

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?

The description gives clear lifecycle guidance: returns a handle, read via get_subscription_data, stop via unsubscribe, and notes idle cancellation. It does not explicitly contrast with subscribe_news, but the resource and behavior are clear enough that an agent can infer when to use it.

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

Deploy Server