MCP tools reference

Generated by scripts/docgen/mcp-tools. Do not edit by hand — run make docs-regen after changing internal/mcp/tools.go.

These are the tools ibkr mcp exposes to MCP clients (Claude Code, claude-desktop, any other MCP host). Each entry lists the tool name an LLM picks against, the description the LLM reads to decide whether to invoke, and the parameter schema the LLM binds against.

25 tools total. Listed in registration order, aligned with the agent-appropriate CLI commands. Local lifecycle commands such as setup, update, restart, mcp, daemon, and version are intentionally excluded from MCP tools.

ibkr_status

Daemon + gateway health snapshot: connection state, account, server version, members-list source, last-error, background tasks, per-subsystem health for quote/watchlist/scanner/history/chain/gamma/breadth/proposals/opportunities, unhealthy IBKR data farms, and high-level data_quality warnings for degraded gamma or stale regime clusters. Run this first when troubleshooting connectivity or tool-specific slowness ("why is data missing / stale / wrong-account?", "will scanner or gamma be busy?", "are downstream risk reads stale?", "why is the protection or opportunities panel stale?"). subsystems[].status can be ready/computing/unavailable/degraded/disabled and is more specific than the top-level gateway connection — quote/scanner degrade when required market-data readiness has not been observed, history degrades when historical-data readiness has not been observed, and chain degrades when market-data readiness is missing or a security-definition farm explicitly reports trouble, even if the socket is connected; the proposals and opportunities entries turn degraded with blocker codes and the served snapshot's as_of when refreshes keep failing while an older snapshot is still served; opportunities.message also carries active opportunity policy id/version/status/fingerprint when available; data_farms[] is omitted when farms are healthy and only lists farms currently broken/disconnected; data_quality[] means the daemon can serve data but decision surfaces should be interpreted carefully. NOT for portfolio state — use ibkr_account for cash/margin or ibkr_positions for what you own, and NOT for full risk evidence — use ibkr_regime or ibkr_canary.

No parameters.

ibkr_trading_status

Local trading status: whether order entry is disabled, paper-ready, live-ready, or blocked; includes connected-gateway readiness, pinned endpoint/account/client-ID evidence, preview requirement, explicit can_preview and can_write booleans, MCP write mode, live override status, open-order count, and concrete blockers. Use before any order preview/place/modify/cancel request or when the user asks whether ibkr can trade; can_preview/can_write are false while TWS/IB Gateway is disconnected or still handshaking. This tool does NOT place, modify, or cancel orders; it only reports readiness. For portfolio state use ibkr_positions; for account cash/margin use ibkr_account; for market context use ibkr_quote, ibkr_chain, or ibkr_regime.

No parameters.

ibkr_settings

Read ibkr's platform settings and observed state: runtime user preferences such as purge/restore and stock-protection enablement, read-only trading mode/account/build capability, trading safety limits with access/source metadata, and compact observed market-data quality. Use when the user asks what ibkr features are enabled, whether purge/restore or stock trailing-stop protection is available, why a setting is read-only, or what build/channel controls trading writes. This tool is read-only and cannot change settings; there is intentionally no MCP settings write tool in v1. NOT for placing, previewing, modifying, or cancelling orders — use ibkr_trading_status first and ibkr_order_preview only for tokenized previews. NOT for detailed per-instrument quote truth — use ibkr_quote, ibkr_chain, or ibkr_positions rows.

No parameters.

ibkr_orders_open

Read current broker account/mode open-order lifecycle state without placing, modifying, cancelling, or transmitting any broker order. Use after an order preview/place flow to inspect what the daemon believes is still open for the currently connected broker context, or when the user asks for open orders. Results include account/mode scope, latest local event time, and local-journal limitations; paper/test journal rows are intentionally not returned while connected to live, and live rows are intentionally not returned while connected to paper. This tool is read-only and does not place orders; it only reports local journal plus observed broker-callback state. It is NOT an IBKR Activity Statement or complete broker open-order audit, NOT for historical audit across old accounts or modes, NOT for creating a new preview token (use ibkr_order_preview), and NOT for submitting, modifying, or cancelling an order.

No parameters.

ibkr_orders_history

Read bounded local order-journal history for the current broker account/mode without placing, modifying, cancelling, or transmitting any broker order. Use for recent trade-review forensics when the user asks what locally journaled order lifecycle/fill callbacks occurred over a date range. This read-only tool does not place orders; it only reports local journal evidence. Results are bounded by grouped-order limit and per-order event_limit so callback-heavy trailing stops do not flood the context; inspect events_truncated/total_events_count before treating event samples as complete. This is a local daemon journal view only, not an IBKR Activity Statement, trade confirmation, execution report, commission ledger, closed-position ledger, or broker-grade historical audit; it may miss manual orders, other-client orders, broker activity while the daemon was offline, and rows outside the selected account/mode. For currently working orders use ibkr_orders_open; for one order's full audit use ibkr_order_status; for official broker history ask the user for an IBKR Activity Statement/Flex export.

Parameters:

ibkr_order_status

Read one locally journaled order's lifecycle and audit events by order ref, IBKR order ID, or permanent ID. Use when the user asks what happened to a specific order or needs the daemon's latest broker-callback evidence. Results include account/mode scope, latest local event time, and local-journal limitations; not found can mean the id belongs to another account/mode or was never locally observed. This tool is read-only and local-journal based: it does NOT place, modify, cancel, preview, transmit, or confirm an order, and it is NOT an IBKR Activity Statement or complete broker audit. For the open-order list use ibkr_orders_open; for a new tokenized preview use ibkr_order_preview.

Parameters:

ibkr_order_preview

Preview a locally gated stock/ETF or single-leg option LMT, TRAIL, or TRAIL LIMIT order and mint a short-lived local preview token without placing, modifying, cancelling, or transmitting any broker order. Use only after ibkr_trading_status shows the local trading gate is ready. Defaults are order_type LMT, strategy patient-limit, TIF DAY, and outside_rth=false; providing trail fields defaults order_type to TRAIL, or TRAIL LIMIT when limit_offset is present. TIF GTC is accepted for TRAIL and TRAIL LIMIT drafts only — protective stops meant to survive the session close — while LMT stays DAY-only. Stock/ETF TRAIL and TRAIL LIMIT drafts default trigger_method to 2 (IBKR LAST) unless explicitly supplied. Option trails are option-premium based, not underlying-driven, and require explicit expiry/right/strike. This tool validates the local trading gate, pinned endpoint/account/client ID, supported order type, the risk-increasing size caps (max notional and max option contracts bind opening/adding/flipping orders only; reduce-only close/reduce orders are exempt, bounded by the position itself, and the result then omits max_notional), stock short/flip policy, option sell-to-open policy, and broker WhatIf availability, then returns quote inputs, position effect, token_minted, and submit_eligible. For IBKR percent trails, trailing_percent: 2 means 2%, not 0.02. TRAIL LIMIT uses limit_offset; do not send a LMT limit price with broker trail orders. token_minted=true means the local preview artifact exists; submit_eligible=true only when IBKR accepted a non-transmitting WhatIf for the exact draft. If broker WhatIf is unavailable or rejected, submit_eligible=false and compatibility field executable=false. It does NOT submit an order and returns only the redacted preview_token_id, never the raw submit-capable token; broker writes require a separate place/modify/cancel path with its own gated token. For protection proposals use the proposal flow; for market context without token minting use ibkr_quote or ibkr_chain; for holdings use ibkr_positions; for cash/margin use ibkr_account.

Parameters:

ibkr_account

Account-level financials: net liquidation, buying power, cash, margin — all in base currency. Use when the question is about the account as a whole ("how much cash?", "how much margin am I using?", "what's today's P&L?"). Includes daily_pnl (start-of-trading-day to now); when the gateway provides them, pnl_unrealized_total and pnl_realized_total carry the account's TOTAL unrealized/realized P&L from the same reqPnL stream — inception-to-now, NOT a breakdown of daily_pnl (they do not sum to it) — and are distinct from the session-running unrealized_pnl/realized_pnl on the account-updates feed. For multi-currency accounts, also returns currency_exposure: one row per non-base currency holding with net liquidation in that currency, gateway-reported exchange rate, and the base-currency conversion. Useful for attributing P&L between underlying moves and FX moves. NOT for per-position detail — use ibkr_positions to see what you actually own.

No parameters.

ibkr_positions

Open positions: stocks and options separated, plus normalized per-underlying exposure. Use when the question is about what you own ("show me my positions", "what's my exposure to AAPL?", "how much delta do I have?") or when building a held-portfolio dashboard outside market hours. Stock rows separate the IBKR account valuation mark (mark/valuation_mark) from market context: regular_close is the latest completed regular-session close, prior_regular_close is the close before that, and quote_price is the live/pre/post/overnight indication when IBKR supplies one. day_change/day_change_pct compare the account mark to regular_close; do not treat quote_price as the position valuation. Quote context includes data_type, feed_type, quote_price_source, quote_quality, indicative, spread_pct, day/52-week ranges, volume/avg_volume, volume_phase, quote_price_at/quote_price_as_of, warning_details, stale flags, and session_context from the trading calendar. Position money fields are explicit: market_value_ccy, unrealized_pnl_ccy, realized_pnl_ccy, and daily_pnl_ccy are in the contract currency; market_value_base, unrealized_pnl_base, realized_pnl_base, and daily_pnl_base are present when the account base currency and FX rate are known. Non-base rows carry fx_rate as BASE per CCY. daily_pnl_ccy is null when the daemon hasn't yet pre-warmed that contract's reqPnLSingle subscription or the account isn't entitled; never zero-substituted. Option legs include option_bid/option_ask, option_prev_close, and per-leg Greeks (delta/gamma/theta/vega) when IBKR delivers the model-computation tick within budget; outside U.S. option regular hours, options_closed warning_details mean those option quote/model fields are closed-session context, not executable quotes. daily_theta_base converts portfolio theta bleed to account base when every theta-bearing leg has an FX path; mark_outside_bid_ask and warning_details flag option marks away from bid/ask. The by_underlying rows include group_market_value_base, group_market_value_pct_nlv, group_dollar_delta_base, group_unrealized_pnl_base, and group_daily_pnl_base so agents do not need to re-aggregate currencies. The portfolio.exposure_base table is sorted by absolute base-currency market value and is the preferred portfolio map for multi-currency accounts. Top-level effective_delta is a cross-symbol share-equivalent diagnostic; use per-underlying effective/dollar delta for coherent exposure. NOT for cash/margin totals (use ibkr_account), NOT for live quotes on symbols you don't hold (use ibkr_quote), and NOT for option-chain selection or replacement structures (use ibkr_chain).

Parameters:

ibkr_quote

Snapshot quotes for one or more equity / ETF symbols. Returns bid/ask/last, mark, sizes, regular_close (latest completed regular-session close), prior_regular_close, regular close change, quote_price (current live/pre/post/overnight indication), quote-vs-close change, volume, avg_volume, avg_volume_20d, avg_dollar_volume_20d, liquidity_status/source, effective data_type for the legacy selected price, feed_type when the gateway subscription state differs, quote_quality (firm/indicative/wide/prev_close/stale/missing), indicative, spread_pct, volume_phase, warning_details, and session_context when the official market calendar explains stale/frozen/missing data. Use for current quote and close context questions on stocks/ETFs ("what's SPY trading at?", "what was IBM's close and what is overnight quoting?") and quick liquidity gates; for multi-symbol trend/RS screens use ibkr_technical because it batches daily-history calculations. Off-hours, prefer regular_close for the official close that matters and treat quote_price as an indication; gate decisions on quote_quality/spread_pct/data_type/quote_price_at rather than assuming live means regular-session executable. price/price_source are retained for compatibility and mirror quote_price when an indication exists, otherwise regular_close. Stock/ETF IV tick 106 is opportunistic and often null/unavailable; for a real IV read use ibkr_chain expiry IV or an expiry strike grid. US symbols default to SMART/USD. For German/Xetra equities whose ticker collides with the US default route (for example MBG), set market: "de" or explicit exchange/currency. NOT for options (use ibkr_chain with an expiry argument), NOT for historical bars (use ibkr_history), NOT for full technical screens (use ibkr_technical), NOT for the position valuation of something you already hold (ibkr_positions carries account marks plus quote context).

Parameters:

ibkr_watch

Read the user's local ibkr watchlist: symbols they explicitly saved with the CLI via ibkr watch SYMBOL --add. Defaults to a decision-making monitor with close-vs-indication context: regular_close and regular close change, quote_price and quote-vs-close change, currency, day range, 52-week range, volume, average volume, 20-day average volume/dollar volume from daily bars, effective data freshness, quote_quality/spread_pct/volume_phase, warning_details, session context, and optional held-stock context. In pre/post/overnight sessions, regular_close is the close that matters; quote_price is an outside-hours indication. Set include_quotes: false only when the user explicitly wants the saved symbol list without market data (still requires a reachable daemon). This MCP tool is read-only: it does NOT add, remove, clear, create IBKR/TWS watchlists, or place trades. For ad-hoc symbols that are not saved in the watchlist, use ibkr_quote instead; for trend/RS ranking use ibkr_technical.

Parameters:

ibkr_calendar

Official market-session calendar for supported first-release markets: U.S. cash equities (market: "us" / "us-equity"), U.S. listed options regular sessions ("us-options"), and German Xetra cash equities ("de" / "de-xetra"). Use for questions like "is the market open?", "when is the next session?", "is today a holiday or early close?", "why is this quote frozen at 1am ET?", or risk-manager context before a long market holiday weekend. NOT for prices (use ibkr_quote), NOT for broad futures/FX/bonds/Eurex/crypto calendars, and NOT for per-contract SPX/VIX global-hours nuance — v1 is official exchange calendars only and returns unknown outside embedded coverage rather than guessing from weekdays.

Parameters:

ibkr_chain

Option chain — use whenever the user asks about option selection, strike grids, expiry IV, implied moves, or trade-structure liquidity ("AAPL puts", "this Friday's chain", "call wall on SPY"). Two shapes: **omit expiry** to get the expiry list (each row carries ATM IV, iv_source, iv_quality, DTE, and the 1-σ implied move spot × IV × √(DTE/365) — the desk-standard expected dollar move by expiration, used for earnings sizing and strike selection; daemon caches IV results, second call within ~60 s during RTH is instant; warning_details[].code=expiry_iv_unavailable means IV/move is unusable); **provide expiry** (YYYY-MM-DD) for the ATM±width strike grid. For SPX exact-expiry grids, the daemon uses IBKR's classed sec-def strikes and returns trading_class; pass trading_class:"SPX" or "SPXW" only when you need the AM/monthly or PM/weekly class explicitly, otherwise leave it empty for auto-selection. For 3-6 month screening, prefer expiry-list filters such as min_dte:90,max_dte:180 or target_dte:120 instead of all_expiries:true; filters are applied before IV fan-out. Set require_live_iv:true only for live-option-IV preflight/readiness checks: outside U.S. option RTH it returns a fast warning instead of spending the IV fan-out budget, and should not be used to value held option positions. The strike grid leads with tradable_summary and liquidity_summary: live bid/ask leg counts, stale/model-only/subscribe-error/no-quote counts, OI coverage, options_tradable, feed_gap, liquidity_grade, ATM spread, nearest live call/put, tightest live spread, and recommended_structure_hint (stock_only, shares_or_spreads, calls_ok, untradable_chain). Treat options_tradable:false as a hard gate for option structures. The grid also has top-level data_type/session_state/feed_type plus warning_details; outside regular option hours data_type is closed even if the underlying stock feed is live. For SPX/VIX, this does not prove the product cannot trade in GTH/ETH/curb; it means this API response did not deliver a complete quote/OI/IV surface, so frozen bid/ask/last are reference context only, never executable liquidity. Per-leg fields include bid/ask/last, prev_close, IV, delta, OI, as_of, data_status (quoted, prev_close, model_only, no_quote, subscribe_error), iv_status, and oi_status. call_prev_close / put_prev_close are the option contract's own prior close and are stale context, not executable quotes. call_oi / put_oi are option open interest from IBKR ticks 27/28 and stay null when the gateway did not push OI within budget; never treat missing OI as zero. Off-hours, prev_close, frozen quote fields, and model_only legs can be useful context but are not executable quotes. no_iv returns the fast skeleton for the expiry list (DTE only). all_expiries lifts the default 12-expiry cap (nearest 12 normally — back-half LEAPS rarely on the decision path). NOT for stock-level quotes (use ibkr_quote), NOT for historical bars (use ibkr_history), and NOT for held option valuation or portfolio exposure (use ibkr_positions).

Parameters:

ibkr_history

Daily OHLCV bars for an equity / ETF symbol. Use for trend / moving-average / lookback questions ("is AAPL above its 50-DMA?", "what's the 90-day range?"). Non-trading days are skipped, so the row count is typically smaller than days. NOT for intraday bars (not exposed today), NOT for options (use ibkr_chain), NOT for the live current price (use ibkr_quote).

Parameters:

ibkr_technical

One-call technical and relative-strength screen for equity / ETF symbols. Use for weekly stock screening questions such as "is IREN above its 50/200-DMA?", "rank these names vs SPY", "is this extended from the 200-DMA?", or "does this pass liquidity?" Returns price, SMA50/SMA200, percent distance from those moving averages, 21/63/126-trading-bar returns, 63/126-bar RS versus the benchmark (symbol return minus benchmark return), ATR14/ATR%, avg_volume_20d, avg_dollar_volume_20d, trend_state, data_quality, and missing_reasons. Values ending in _pct and return_* are decimal fractions (0.10 = 10%). For German/Xetra equities set market:"de"; for ETF resolver gaps use primary_exchange:"ARCA" or an explicit exchange/currency. Large batches can return partial rows with warning_details, so agents should cap screening batches and drop rows with data_quality != ok. Uses daily bars only; not for live quotes (use ibkr_quote) and not for options (use ibkr_chain).

Parameters:

ibkr_market_events

Read observed market-event flags for held or requested stock/ETF symbols: borrow inventory tightness from IBKR shortable-share data when available, extreme annualized borrow fee from IBKR short-stock availability when observed, Reg SHO threshold-list membership from official Nasdaq files, and active/recent LULD or regulatory/news halts from Nasdaq's trade-halt feed. Use when the user asks whether a held name has market-structure, borrow, threshold, LULD, or halt context that should annotate protection proposals or underlyings. Returns typed flags with status, severity, role, source/as-of metadata, source_health, warning_details, and a semantic fingerprint. Unknown or unavailable data stays unknown/null and must not be treated as inactive; absence of Nasdaq Reg SHO flags is not proof for non-Nasdaq threshold feeds. This tool is read-only and does NOT place, preview, submit, modify, cancel, size, or recommend opening exposure. NOT for current prices (use ibkr_quote), NOT for held position sizing/P&L (use ibkr_positions), and NOT for broad-market regime (use ibkr_regime).

Parameters:

ibkr_scan

Run a market scanner. Three call shapes: (1) preset by name — {preset: "top-movers"} — for the configured shortcuts; (2) ad-hoc — {type: "HIGH_LAST_VS_EMA50", exchange: "STK.US.MAJOR", instrument: "STK"} for US stock breakouts, {type: "MOST_ACTIVE_USD", exchange: "STK.US.MAJOR", instrument: "STK"} for broad liquid activity, or {type: "HIGH_VS_52W_HL", exchange: "STK.EU.IBIS", instrument: "STOCK.EU"} for German/Xetra stocks; (3) empty {} — enumerates the configured presets so the agent can pick one. For common known scan codes such as HIGH_LAST_VS_EMA50, HIGH_LAST_VS_EMA200, HIGH_VS_52W_HL, MOST_ACTIVE_USD, and HOT_BY_VOLUME, call this tool directly and reserve ibkr_scan_params for unfamiliar codes, regional uncertainty, or unsupported-code/location errors. Each row is enriched with last/prev_close/change/change_pct/volume/iv/week_52_high/week_52_low plus instrument_tags and data_type/feed_type/price_at/price_as_of/volume_phase/warning_details via per-row market-data subscriptions the daemon issues automatically (IBKR's scanner protocol returns only rank+symbol). instrument_tags flags known ETFs/leveraged ETPs that IBKR may still return from stock scans; when the user asks for non-ETF single-name ideas, drop rows tagged etf or leveraged_etp. Missing tags mean unknown, not confirmed common stock. Scanner enrichment can be the slowest step because it briefly subscribes to each returned row; use small limit values and stop after one weak/noisy scan instead of stacking rescue scans. Use min_price, min_volume, min_dollar_volume, exclude_penny, and require_live to suppress micro-cap/off-hours noise before the result reaches the agent. Nil fields mean the gateway didn't deliver the corresponding tick within the enrichment window — common off-hours, and IV is nil for symbols without actively-traded options. Ad-hoc rows are capped at 50.

Parameters:

ibkr_scan_params

Discover the scanner catalog this IBKR gateway supports: every scanCode (the type for ad-hoc ibkr_scan) and every locationCode (exchange), plus the instrument types each scanCode applies to. Use this before composing an ad-hoc scan — the catalog varies by gateway version, market-data permissions, and region. Pass instrument: "STK" to narrow scan_types to US stocks or instrument: "STOCK.EU" for European stocks; pass include_raw_xml: true only when you need a field not surfaced in the parsed result (the XML payload is ~200 KB). NOT for actually running a scan (use ibkr_scan — including {} to enumerate configured presets), and NOT for quotes or technicals on known symbols (use ibkr_quote or ibkr_technical).

Parameters:

ibkr_breadth

S&P 500 market-breadth readings for the risk-regime dashboard. Use for questions about the market's internals — "how many S&P names are above their 50-DMA?", "is this a narrow rally?", "what's the new-high/new-low spread?". S&P 500 constituents only — NDX, RUT, sector-specific, or single-stock breadth are NOT supported. Returns three readings every call: pct_above_50dma (the percentage of S&P 500 constituents trading above their 50-day SMA — the tactical signal), pct_above_200dma (the slower companion that catches cyclical tops cleanly), and new_highs_today/new_lows_today (constituent counts of names making fresh 52-week highs/lows), plus the derived net_new_highs_pct. The classic narrow-rally pattern — SPX near highs with net_new_highs_pct near zero or negative — fires when a few mega-caps carry the index while the median name is rolling over. IBKR does not redistribute S&P DJI's S5FI or the equivalent breadth indices on retail subscriptions, so the daemon computes all three locally from the 500 constituent daily closes pulled via IBKR's historical-bar feed (method: constituent-fanout-50/200dma+nh-v2). A once-daily refresh post-close (16:35 ET) slides each name's 200-bar window forward and updates a 252-bar rolling max/min; readers see a cached snapshot. Cold start (no cache yet) takes ~60 min — IBKR's historical-data pacing limit caps the fan-out at ~6 names/min sustained, so the response carries state: "computing" until the cache is built. Pulling 200 bars per constituent instead of 50 doesn't cost more requests; the pacing limit is per-request, not per-bar, so the cold-start budget is unchanged. After cold-start the cache persists across daemon restarts and every subsequent call is instant. Threshold derivation (green/yellow/red) is intentionally left to the consumer; the spec calls those bands user-tunable. Suggested bands: 50-DMA — >55 green / 40-55 yellow / <40 with SPX at highs red. 200-DMA — >60 green / 40-60 yellow / <40 red (calibrated to the post-Mag-7 era; StockCharts' 70/30 default fires red far too often).

Parameters:

ibkr_gamma

Dealer-gamma market-structure snapshot for SPX/SPXW, with SPY as corroborating ETF context when usable. Use for questions like "where is dealer gamma?", "did the signed profile find a zero-gamma crossing?", "is the modeled book long-gamma or short-gamma?", or "where are the largest gamma concentrations?" NOT for portfolio Greeks (use ibkr_positions) and NOT for options chains/quotes (use ibkr_chain / ibkr_quote). SPX is the stable production signal for S&P 500 dealer gamma; a fresh, rankable SPX result remains the main market-structure read when SPY is throttled or unavailable. SPY-only is a labeled proxy, not the canonical S&P dealer-gamma signal. The ready result leads with quality.rankability: rankable means fresh and covered enough to treat as a market-structure signal; context_only means show for awareness but do not treat as the active gamma read; blocked or unavailable means gamma is not a usable signal in this snapshot. quality also carries session key, current session, age/max age, coverage percentages, horizon/skew/derived-IV/concentration gates, blockers, and context notes. Missing 0DTE is disclosed in horizon coverage and warnings but does not by itself make a healthy SPX result context-only when 1-7DTE and term buckets are present; after the expiring SPXW series closes, 0DTE can be absent while the broader SPX surface remains usable. summary then gives primary_statement, zero_gamma_status (crossing, none_in_window, mixed, mixed_degraded, unavailable), regime, confidence, not_advice, and per-index summaries. In combined scope there is no top-level combined zero-gamma price because SPY and SPX use different price scales; read summary.per_index.SPY and summary.per_index.SPX for per-underlying spot, zero, swept range, regime, and GEX leg counts. If SPY cannot produce usable option OI/IV/GEX, the daemon may return a canonical SPX result with warning_details[].code starting spy_unavailable:; that warning is context, not a blocker for rankable SPX. If SPX is unavailable, the daemon may return a degraded SPY proxy with spx_unavailable:; stale SPX fallback is marked with spx_cache_fallback, and failed cache refreshes with refresh_failed:. gamma_total_abs and top_strikes are sign-agnostic concentration/magnitude diagnostics. leg_count means legs with non-zero OI-weighted GEX; priced_leg_count means legs that priced/fit IV but may not have usable OI. Missing OI is unknown, never zero: SPY OI can be absent outside regular option hours, while SPX OI should normally be session-stable and missing SPX OI is data-quality evidence in any session. Non-fatal data-quality issues are in warning_details with {code, scope, severity, message, impact, action}; raw warning tokens are not part of the JSON contract. By default profile arrays are stripped to keep MCP responses compact; set include_profiles: true only when charting the sweep. First call of a NY session may return status: "computing" with progress/ETA; set wait_ms to wait. The signed zero-gamma convention is a regime hint, not advice or a trade level.

Parameters:

ibkr_regime

Broad-market stress-lifecycle snapshot — single-call, non-advisory answer for "how does the market regime look today?", "is this a risk-on or risk-off tape?", "are we close to stress thresholds?", or "give me the daily-check dashboard." Use this when the user wants the market's current evidence balance across equity vol (VIX/VIX3M + VVIX), credit (HYG/SPY + official HY/IG OAS), funding stress (CP/T-bill spread), FX carry proxy, dealer gamma, and S&P 500 breadth. NOT for account/portfolio action, trade selection, hedging, sizing, execution, or a probability forecast — use ibkr_canary when the user needs market weather combined with held portfolio shape, and use ibkr_positions / ibkr_account for held-risk inspection. The compact MCP response leads with fingerprint (semantic identity for the classified regime state), posture (canonical display policy: label, tone, stage, severity, readiness, confidence, and evidence), market-scoped lifecycle (scope: "market", stage, severity, readiness, timing, confidence, evidence[], confirmed_by[], lifecycle fingerprint, and not_execution), source_health[] (per cluster as_of, stale/degraded/partial status, confidence, and semantic-bucket fingerprint stability), summary, data_quality, and composite raw + cluster counts, then the eight indicator rows. Lifecycle stages are quiet, early_warning, confirmed_stress, panic, stabilization, opportunity, or data_quality; isolated noisy red evidence remains visible in lifecycle.evidence and row bands but does not dominate the trigger unless severity, tape, or independent fresh clusters confirm it. posture.tone is the canonical display tone and follows governed severity, not just stage: confirmed_stress with severity:"watch" is watch/amber, while act-grade stress remains stress/red and full risk-off remains risk_off. Per-row fields include raw measurements, status, band, band_reason, thresholds (heuristic + pending_backtest), as_of (label, freshness/source/time/date), streak, and per-scalar *_quality provenance. warning_details gives scoped prose for unavailable/stale/computing/context-only rows with {code, scope, severity, message, impact, action}; do not parse opaque error strings when this field is present. MOVE/rates-vol is intentionally absent until a verified IBKR contract/source exists; do not infer it from ETFs or futures. Methodology prose is omitted from MCP for compactness; use spec_doc or CLI ibkr regime --explain for full threshold notes. Gamma embeds the compact ibkr_gamma envelope with profiles stripped: envelope.result.quality.rankability says whether gamma is fresh and covered enough to be the active market-structure read. Only rankable gamma contributes a band, cluster count, lifecycle evidence, or confirmed_by; context_only, blocked, and unavailable gamma are awareness/data-quality evidence only. In combined scope use envelope.result.summary, per_index.SPY, per_index.SPX, gamma_total_abs, and top_strikes; the signed γ-zero is a regime hint, not a precise level. Expect gamma/breadth to be computing on cold starts and optional fields_missing values when a secondary scalar missed the fetch budget or an official daily file is temporarily unavailable.

Parameters:

ibkr_canary

Live stateless portfolio canary for scheduled checks every few minutes: it combines broad-market weather from ibkr_regime with the user's current portfolio shape. Use when the user asks how current market weather interacts with the held portfolio, whether to watch/stage/defend/rebalance/deploy, or when orchestration needs a stable alert fingerprint for this snapshot. NOT for account-only risk such as margin breach, cash, buying power, or daily P&L in isolation — use ibkr_account or a dedicated account-risk workflow for that. Canary evidence may include margin/P&L facts, but the headline canary action is gated by market confirmation plus portfolio fit. Returns action (stand_down, watch, defend, rebalance, deploy, confirm_inputs), market_confirmation (none, partial, confirmed, blocked), portfolio_fit (low, medium, high, unknown), and input_health (ok, warming, degraded, failed) so agents can explain whether a risk recommendation is market-confirmed or only contextual. Also returns direction, severity, planner_mode_hint (none, stage, defend, rebalance, deploy, confirm_data), and planner_readiness (none, watch, prestage, ready, blocked) so monitor workflows can explain whether the snapshot is actionable, staged, or data-blocked without parsing prose. portfolio.held_stress[] is a bounded positions-only held-underlying stress surface for material names: held-name daily P&L shock, near-expiry held-option delta concentration, and held-name quote/option bid-ask degradation. It is emitted only when an existing held underlying is material and a stress condition is present. signals[] carries stable IDs, direction (defensive, constructive, rebalance, mixed, data_quality), per-signal posture, severity (observe, watch, act, urgent), observed values, thresholds, targets, confidence impact, and blocking degraded or stale inputs. Signals are supporting evidence; do not infer a DEFEND action from account-only or portfolio-only signals when top-level action says otherwise. market_indicators[] lists each regime indicator with status (green, amber, red, context, n/a), as_of, reading, and a short decision comment; context-only gamma appears here as context evidence rather than degraded input health. market.regime_posture is the canonical market-regime display/policy read from ibkr_regime; render its label and tone instead of deriving risk-off from raw cluster counts. fingerprint is the semantic alert identity for monitor dedupe/recovery; source_fingerprints.account, .positions, .regime, and .market_events record the classified input buckets consumed by this canary run; source_health[] records each source's as_of, freshness/degraded/stale/partial status, confidence, max-age cadence, and semantic-bucket fingerprint stability. High-precision policy: market tape is confirmed only by market evidence (SPY/VIX or independent regime clusters), not by margin pressure; DEFEND requires confirmed market pressure, vulnerable portfolio fit, and clean enough input health. Medium/low input health caps the headline at WATCH or CONFIRM_INPUTS. Standalone portfolio limit breaches and held-underlying stress become rebalance/watch context rather than market-stress alerts; stale account or positions snapshots block dependent margin, P&L, exposure, concentration, held-stress, and option signals with explicit blocked_by sources. Context-only gamma is context/unranked evidence, not degraded input health; blocked, unavailable, degraded, or computing gamma/breadth becomes explicit input-health evidence, not a false safe/false red signal. Stale/degraded/partial confirming clusters cannot upgrade market_confirmation to confirmed until refreshed. Works pre-market and after hours by relying on account, positions, regime, and daemon market-event freshness/status metadata; it does not call option chains, scanners, short-interest feeds, paid borrow vendors, or external flow sources, and it refuses to escalate solely on incomplete computed surfaces. This tool is read-only and does NOT place, preview, submit, modify, cancel, draft, size, or select orders. NOT for detailed diagnostics — use ibkr_regime, ibkr_positions, or ibkr_account when you need underlying evidence; use ibkr_positions for held-option warnings such as mark_outside_bid_ask, options_closed, per-leg greeks, quote freshness, and the full by-underlying ledger.

Parameters:

ibkr_rules

Advisory 14-rule daily trading checklist evaluated daemon-side against the live book: per-name exposure cap (with disclosed lower-bound breaches under Greeks gaps), single option-line premium cap (hedge lines get their own higher tier), negative-cash sell-only mode, portfolio extrinsic (theta-rent) budget excluding classified hedge legs, expiry runway on long options, catalyst coverage vs earnings, short options spanning earnings (short calls act; short puts watch, act on assignment notional), pre-earnings size freeze, red-on-green-tape relative weakness, winner-trim into strength, green-day execution nudge, hedge-band integrity (act past twice the band top), exit discipline on long-option loss fences, and non-base-currency FX exposure (watch-only). Rules 3/4/12 thresholds are regime-conditional (calm/early_warning/confirmed sets from the latched regime lifecycle stage; a carried stage evaluates worse-of carried/calm, a never-seen stage uses calm thresholds — both disclosed in row notes). Use when the user asks "what should I fix today?", "which rules am I breaking?", "is my book within my own risk rules?", or wants a daily discipline review. Rows are ranked hardest-first (ranked indexes: act > watch > unknown, then base-currency impact); statuses are pass/info/watch/act/unknown/not_evaluated where unknown means an input was missing (positions pending, earnings unknown, Greeks gaps, FX report absent) — never treat unknown as pass; observed_is_lower_bound marks a breach proven from partial data ("at least X%"). earnings[] shows each name's next earnings date with source (fetched/override/unknown, with estimated and stale flags); input_health[] is the result-level gate (includes the regime_stage row). Advisory only: verdicts never block orders; order previews may carry matching advisory rule_* warnings. NOT for the market-regime × portfolio alert verdict (use ibkr_canary), NOT for executable protective-stop candidates (use ibkr_proposals), and NOT a data source for positions themselves (use ibkr_positions).

Parameters:

ibkr_proposals

Read daemon-owned protection proposals for existing positions. Use when the user asks what protective actions ibkr currently recommends — broker-side trailing stops (TRAIL/TRAIL LIMIT for stocks/ETFs and, when policy opts in, single-leg option premium trails; each row carries the trail spec, computed initial stop, and trail_sizing explanation including dynamic ATR/spread sizing or explicit policy fallback), theta hygiene (close/reduce short-dated options), or single-name risk reduction — or asks why a proposal is blocked (per-row blockers include codes like stock_protection_disabled with remediation text). This tool can return the latest snapshot or request a refresh, but it is read-only: it does NOT preview, submit, place, modify, cancel, transmit, or expose raw preview tokens. For existing holdings use ibkr_positions; for broad risk evidence use ibkr_canary or ibkr_regime; for local order-entry readiness use ibkr_trading_status.

Parameters:

ibkr_opportunities

Read daemon-owned opportunities for existing positions. Use when the user asks whether ibkr sees mechanical portfolio opportunities, especially long option exercise candidates where exercise may beat selling the option bid or reduce an illiquid risk position. Option-exercise rows include post_exercise_risk: before/after underlying share exposure, whether exercise opens/increases/flips/reduces/closes risk, current protection coverage state when available, and whether a protection review is needed after exercise. That context is advisory and does not authorize exercise. This tool can return the latest snapshot or request a refresh, but it is read-only: it does NOT preview exercise, submit exercise, place, modify, cancel, transmit, or expose submit-capable tokens. For holdings and current protection coverage use ibkr_positions; for candidate protective stops use ibkr_proposals; for local broker-write readiness use ibkr_trading_status.

Parameters:

ibkr_size

Fixed-fractional position sizing pegged to live NLV. Pure math against the account snapshot — never proposes or executes an order. Pass an optional target to also get the R-multiple (reward:risk) and breakeven win rate. NOT for drafting an actual order ticket (use ibkr_order_preview after ibkr_trading_status shows readiness), NOT for protective stops on existing positions (use ibkr_proposals), and NOT for account cash/margin context on its own (use ibkr_account).

Parameters: