canary ibkr MCP

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.

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`…

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.

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. `protection_coverage` in the alert view and `portfolio.protection_coverage` in the full view summarize stock/ETF stop coverage, unprotected base notional, largest unprotected exposures, and stale `orphaned_order`/`reconcile_required` protective orders; those stale orders are not counted as protection. `signals[]` carries stable…

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 tr…

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 con…

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`).

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. Each `source_health[]` row can carry durable `refresh_state`, `next_attempt`, and a redacted typed `last_failure` (`code`, `stage`, `failed_at`, `retryable`); respect backoff/not-due state and do not parse `notes` for failure classification. 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`).

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`.

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 size caps (max notional binds every equity/ETF order and max option contracts binds every single-leg option order, including apparent close/reduce exits), stock short/flip policy, option sell-to-open policy, and broker WhatIf availability, then returns quote inputs, position effect, `token_minted`, and `submit_eligible`. Because this client cannot prove that a manual TWS order has not already consumed exit capacity, a SELL that appears to close or reduce also needs short/sell-to-open permission under worst-case exposure; if that blocks a genuine exit, use TWS and then reconcile. 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 r…

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`.

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, and rows outside the selected account/mode; broker activity missed while the daemon was offline no longer strands open rows (the journal reconciles against broker open-order snapshots and closes absent rows as `closed_reconciled`), though per-event history for the offline window stays unavailable locally. For currently working orders use `ibkr_orders_open`; for one order's full audit use `ibkr_order_status`. Official broker history now flows into the local reconciliation surface when Flex ingestion is configured — ask the user to run `ibkr recon` — or ask them for an IBKR Activity Statement/Flex export directly.

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. The journal self-reconciles against the broker's actual open-order list after each gateway reconnect and every 30 minutes: journaled orders a complete broker snapshot no longer reports are closed locally with terminal state `closed_reconciled` (final cancelled-vs-filled outcome stays with broker statements), so a cancel or fill missed while the daemon was offline does not linger as a stale open row. Rows whose close-only protective quantity no longer matches the live position carry `reconciliation_kind`, `reconciliation_severity` (critical), `short_risk_quantity`, and `reduce_to_quantity`; triggering such a stop would open an opposite-direction position, and the paired app offers the guided reduce-to-position fix. 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.

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…

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, trail_sizing explanation including dynamic ATR/spread sizing or explicit policy fallback, execution_semantics, stop_risk, and stop_ladder), 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). `execution_semantics` discloses reference side, trigger method, TRAIL market-order conversion, and TRAIL LIMIT non-fill tradeoff; `stop_risk` includes estimated stop loss, % NLV when computable, and a fixed 5% gap/slippage scenario. Estimates are advisory diagnostics, not fill guarantees. 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 coverage of existing open stop orders use `ibkr_positions` with `view:"risk"`; for broad risk evidence use `ibkr_canary` or `ibkr_regime`; for local order-entry readiness use `ibkr_trading_status`.

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).

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[]`, `unconfirmed[]`, `governors[]`, lifecycle fingerprint, and `not_execution`), `source_health[]` (per cluster `as_of`, `max_age_seconds` staleness policy, stale/degraded/partial status, confidence, semantic-bucket fingerprint stability, durable `refresh_state`/`next_attempt`, and redacted typed `last_failure` code/stage), `summary`, `data_quality`, and `composite` raw + cluster counts including `cluster_eligible_red_count` / `cluster_provisional_red_count`, then the eight indicator rows. Lifecycle stages are `quiet`, `early_warning`, `confirmed_stress`, `panic`, `stabilization`, `opportunity`, or `data_quality`. A red row CONFIRMS stress only when its `eligibility.eligible` is true (depth + persistence + cadence-freshness gates); provisional reds (`eligibility.reasons` names the failed gate: depth_below_min, streak_N_of_M, data_not_due, data_overdue) stay visible and never rescue another cluster or…

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 posture, 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?", whether the book breaches the compiled discipline model, or wants a daily discipline review. The compiled model is not itself proof that every threshold has operator approval. 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`, `verified_terminal`, or `unknown`, with estimated and stale flags); exact-contract `terminal_non_reporting` is explicit not-evaluated/exempt, never pass or a symbol-wide exemption, and conflicting or expired terminal evidence stays unknown. If the optional Wall Street…

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.

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`).

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.

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`).

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`.

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`).

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`.

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`.