Quantustik MCP Server

Get every market indicator we compute, in plain English, with its contribution. This is the full, dry state of the market: all 18 weighted signals the model composes — breadth, institutional flow, insider clusters, Fear & Greed, VIX, credit spreads, the yield curve, our own forecast, and the rest — each with a plain-English label, its current reading, what that reading means, and exactly how much it moved today's score. Rows are grouped by what they do to the verdict, under `groups`: - "down" — signals pushing the verdict down (bad for the buyer) - "up" — signals pushing it up - "silent" — measured, sitting in normal territory, contributing zero. Load-bearing: this is how you tell a CALM market from a panicking one, and a weak market from a frothy one. - "unavailable" — no data today. NOT the same as "silent"; do not report a missing signal as if it read "fine". `aggregate.arithmetic` gives the sum that produces the score, so the verdict can be checked rather than asserted. `aggregate.how_unusual` says what the score is measured against. This returns the SAME rows, with the SAME wording, that a human sees on the website. Quote them as they are — the labels, meanings and colours are the canonical ones and are not meant to be paraphrased into a different vocabulary. Returns a dict with title, as_of, aggregate, groups, rows, and disclaimer.

Get the whole dashboard market picture in ONE call — the composed snapshot. This is the single-call twin of the market dashboard. The dashboard's market view stitches several readings into one coherent picture; an answer engine that had to make four separate round-trips to reconstruct "what is the market doing right now" would more likely give up or answer from a partial view. This tool returns that whole picture at once, composed from the SAME cached market-regime snapshot the dashboard renders — never recomputed here — so the tool's answer can never silently diverge from what a human sees on the page. ONE SOURCE OF TRUTH. The payload is the composed regime snapshot, read from cache. Every field is produced by the same builder the dashboard reads; this tool adds nothing and recalculates nothing. In particular it carries: - `verdict` / `model_verdict` / `confidence_downgraded` — the single authoritative buying-conditions tier, the pre-downgrade tier, and whether a low-confidence downgrade separated them (see get_market_regime for the full reading of the two gauges). - `headline` — the one-line plain-English summary of the current state. - `score` / `score_rescale` / `buying_conditions` / `score_basis` — the 0-100 buying-conditions score and what it is measured against (it is a trailing z-score, not an absolute health percentage). - `overheating` — the froth CHECK (context within Market Conditions, not a separate metric) as TWO internal legs (0-100 each): how cheaply risk is priced, and how hard the crowd is leaning in. Report both legs; never quote the combined scalar or present these as standalone "Overheating"/"Euphoria" gauges. - `signal_coverage` — "used/total" indicators that fed today's score, so a thin-data reading is not mistaken for a confident one. - `action_plan` — the "what to do about it" overlay, conditioned on the current Market Conditions. Reach for this first when the question is about the market as a whole. Then call get_market_indicators for the full per-signal breakdown, or get_market_regime for the same snapshot with the two-gauge reading spelled out in detail. Returns the composed market snapshot dict (the fields above and the rest of the snapshot) with the educational-research disclaimer embedded — the same disclaimer that travels with every detachable forecast artifact, because this is model-state read out of page context.

Get the current MARKET CONDITIONS for the S&P 500 — ONE metric, not three. This tool (named `get_market_regime` for backward compatibility) returns a single customer-facing metric called **Market Conditions**. Present it as ONE thing. It is NOT "Market Conditions" plus a separate "market regime" plus a standalone "Overheating" and "Euphoria" — those are the internal PARTS of this one metric, and quoting them as separate top-level gauges is the exact confusion this contract exists to prevent. THE HEADLINE is the buying-conditions verdict. THE FROTH CHECK is context that explains it. They are two independent axes internally, but to a reader they are one reading — Market Conditions — described by a verdict plus the froth context that qualifies it. 1. THE HEADLINE — buying conditions: `score` (0-100) and `verdict`. HIGHER IS BETTER FOR BUYING. Computed from a multi-signal ensemble: macro, VIX, breadth, institutional flows, insider activity, sentiment, sector rotation. `verdict` is one of Strong Buy / Buy / Neutral / Caution / Strong Avoid — that is the complete vocabulary; this model emits no "Bull"/"Bear" tiers. It gates swing-signal generation: no BUY signals are emitted in Caution / Strong Avoid conditions. The score is RELATIVE, not absolute: it is a z-score of the composite against its own trailing ~6 months of daily readings. A low score means "among the weakest readings in about six months" — it is NEVER a claim about what percentage of the market is "healthy". `score_basis.detail` says this in plain words; pass it on rather than inventing your own interpretation of the number. 2. THE FROTH CHECK (context, not a separate metric) — the froth check is PART of Market Conditions, reported as `overheating.legs` (TWO internal legs, 0-100 each) and `overheating.state` (their conjunction, in plain English). Present these as component context that qualifies the headline, NOT as standalone "Overheating: N/100" / "Euphoria: N/100" metrics. Leg 1, "How cheaply risk is priced": calm volatility, tight credit spreads. Leg 2, "How much the crowd is piling in": greed, stretched breadth. Froth means BOTH legs are high at once. READ AND REPORT BOTH LEGS. The composite AND-gate scalar is NOT surfaced at the top level — it is a degenerate headline and was demoted deliberately. It survives only under `overheating.composite_gated.value`, labeled as meaningless without both legs: it collapses to ~0 whenever EITHER leg is ~0, so it prints the same "0 — not overheated" for a calm, cheaply-priced market the crowd ignores AND for an outright panic (volatility bid, credit spreads wide). Those are opposite states. `overheating.state.key` tells them apart (`calm_unloved` vs `stressed`); the composite scalar cannot. Quote `overheating.headline` (state label + both leg scores), never the composite number on its own. WHY BOTH: a low buying-conditions score has two completely different causes — FROTH (risk cheap, everyone already piled in) or WEAKNESS (deteriorating internals) — and the composite alone cannot tell them apart. The froth legs are what resolve it. Neither reading is a forecast: do not say a market is due for a correction on the strength of them. QUOTE THE PLAIN-ENGLISH LABEL, NOT THE TIER. `verdict` is the internal tier word; the dashboard shows a human the LABEL for that tier ("Bad time to buy"), never the tier itself. Relay the label — a customer told "Strong Avoid" by an assistant cannot find that phrase anywhere on the page they are looking at, and reasonably concludes the two disagree. VERDICT AUTHORITY: `verdict` is the single authoritative tier and matches what a human sees on the dashboard. `model_verdict` is the tier before the low-confidence downgrade and is diagnostic only; the two differ only when `confidence_downgraded` is true. Checking the market before individual tickers is the recommended decision order — it gates whether BUY signals are emitted at all. For the full explanation of WHY the verdict is what it is — all 18 signals with their live contributions — call `get_market_indicators`. Returns a dict with verdict, model_verdict, score, buying_conditions, score_basis, overheating (with a per-component decomposition), confidence, computed_at, and action_plan.

Get the S&P 500 RISK STATE — a measurement of market risk, not a forecast. THIS TOOL DOES NOT PREDICT ANYTHING. It reports what has already happened and what one published rule holds as a result. Say "measures" and "holds", never "expects" or "signals". The distinction is not pedantry: it is the only reason the fields below can be quoted plainly instead of hedged. THE HEADLINE is `markets.SPY.rule_weight` — the share of the index the rule holds in today's conditions, between 0 and 1. It is NOT a recommended allocation, is not addressed to the person asking, and must never be relayed as advice about their money. "The rule holds 78% of the index" is correct. "You should hold 78%" is not, and is the failure this contract exists to prevent. THE RULE, published in full so it can be checked: 1. Hold the index while it trades 1% above its 200-day average; the state turns off on a close 1% below. 2. A close below only counts when ALL THREE stress conditions agree: corporate borrowing costs above their one-year norm, the 10-year Treasury yield below its level 40 days earlier, and consumer staples ahead of discretionary over 60 days. Returning needs the price alone. 3. Position size is set at each month end from 20-day volatility, targeting a 15% budget, capped at fully invested. `sizing.struck_on` says when. Because it is struck monthly, it will usually disagree with what today's `realised_volatility` alone implies. That is correct, not a bug. WHY THE CONDITIONS EXIST: over 32 years the plain 200-day rule left the market 48 times. Three of those absences avoided a real decline; 43 were roughly three-week dips it sat out for nothing, costing more than the three saved were worth. The conditions cut those 43 to 14 while keeping all three exits that mattered. Do not quote this paragraph: call `get_risk_state_evidence` and read `episodes`, which is where these numbers come from and where they stay current. DEGRADED READINGS ARE HONEST, NOT SILENT. A missing stress input makes an exit PERMITTED rather than blocked, and is named in `stress.degraded_inputs` with a `degraded_note`. If `status` is "unavailable", that is an outage, not a calm market, and must be relayed as such. ALWAYS RELAY THE COSTS WITH THE RETURNS. Call `get_risk_state_evidence` for the committed 32-year run before quoting any historical figure. Never quote a return from memory, and never present the simulated history as a live track record; the rule has never been run forward. Distinct from `get_market_regime`, which scores today's tape from eighteen signals and has no backtested return edge behind it. This is one rule with a committed run. Both are honest about which they are; do not merge them. Returns as_of, stress (three conditions, each with value/reference/met, plus exit_permitted and degraded_inputs), and markets.SPY (close, trend_average, distance_to_average, realised_volatility, in_market, rule_weight, sizing, state_changes_at).

Get the committed 32-year run behind every published Risk State figure. SIMULATED RESULTS, NEVER A LIVE TRACK RECORD. The rule was designed with hindsight over this same history and has never been run forward. Say so whenever you quote a number from here; a reader who takes these for a live record has been misled even if every figure is accurate. QUOTE THE COSTS IN THE SAME BREATH AS THE RETURNS. Three fields exist to make that easy and must not be dropped: * `published.longest_lag_years` — how long the rule spent behind simply owning the index. It is the reason most people abandon a rule like this. * `crises` — all seven, INCLUDING episodes the rule handled worse than the index. Never filter this list to the flattering rows. * `controls.static_same_average_exposure` — the same average exposure held permanently and never traded. If a reader wonders whether the timing does anything a smaller constant position would not, this is the answer. `rebalance` records both sizing cadences, monthly and daily, because the choice is invisible in the rule's description and decides whether the strategy finishes ahead of the index or behind it. The published surface uses monthly. `gate_construction` shows the rule with no conditions, then each condition added in the order it was chosen. It is a record of how the rule was built, on this index's own history — not a test of the conditions, and not an ablation: no run removes a condition from the finished rule. Relay it as construction order, never as evidence that a condition earns its place. Everything is read from a file committed to the repository (`app/quantum_model/baselines/risk_state_baseline.json`), not recomputed on request: a figure that can be regenerated per call is a figure nobody can check against a diff.

Get the latest quantum swing signal for a single S&P 500 ticker. Returns TWO distinct facets — they answer different questions and are not interchangeable: * `verdict` (BUY | WAIT | EXIT, labelled BULLISH / NEUTRAL / BEARISH) — what the model thinks of the stock. This is the same word, over the same field, that the website shows a human. EXIT means "consider closing an existing long", never "short it". * `timing` (BUY | WAIT | AVOID | WATCH) — whether to put money in RIGHT NOW. A stock the model likes can still be a poor entry today. Alongside them: entry price, stop-loss, take-profit ladder (TP1/TP2/TP3), position-size suggestion, and risk-reward ratio generated by the Schrödinger + Feynman path-integral model. Data is refreshed on a scheduled basis (typically every few hours). A BUY verdict requires multi-signal convergence — a lone indicator never triggers one. Conviction score (0–10) reflects signal agreement depth. Call explain_signal to see the factor attribution — directional probability, expected upside, tail downside, band calibration — with the dominant driver and what argues against the call. Limits: S&P 500 universe only. Signal may be absent if the ticker was not included in the latest scan run. Timing: a BUY here is suppressed within 5 days of an earnings print — call get_earnings_calendar to see the event date and gap-risk note before entry. Args: ticker: Stock ticker symbol (e.g. "AAPL", "MSFT", "NVDA"). Case-insensitive. Returns a dict with signal, quantum forecast, generated_at, and disclaimer embedded in the payload.

Get historical signal events for a ticker. Events include: new_buy, tp_hit (the price actually reached a profit target we named), trail_stop_hit (the trailing stop closed the trade short of the target — may be a gain or a loss), stop_hit, position_closed. Useful for evaluating how past signals played out — the primary signal-quality verification tool. A trade WON only if payload.pnl_r > 0; the event type names the exit mechanism, never the result. Reviewing tp_hit / stop_hit ratios shows realised performance vs the stated R:R — a 2:1 R:R target is only meaningful if the stop_hit rate is low. Args: ticker: Stock ticker symbol (e.g. "AAPL"). Case-insensitive. limit: Number of events to return (1–100, default 10). Returns a dict with ticker, count, and events list.

List all available Quantustik MCP tools and resources. Use this as the entry point when a user asks what can you do with Quantustik, or to discover the full surface area of the server. Returns a structured description of every tool and resource.

Get the cross-ticker ENTANGLEMENT map — which S&P 500 names the quantum model expects to co-move. "Entanglement" here is the Pearson correlation of the quantum model's own FORECAST return paths (mode="forecast", the default) — a forward-looking, model-implied co-movement signal. It is NOT a claim about realised market correlation, and you must not present it as one. mode="realized" instead correlates trailing daily returns (the consensus baseline) for comparison. Two ways to read it: • Diversification / risk lens — high entanglement means two names are effectively one trade. Stacking five mutually-entangled longs is one position with 5x the size, not a diversified book. • Pairs / divergence lens — strongly NEGATIVE entanglement flags names the model expects to move oppositely (hedge or pairs candidates). Honesty: every number is computed from real persisted scan output. Tickers with no usable forecast curve are listed in `missing`, never imputed. The universe is the top_n names ranked by 3mo forecast growth. Args: ticker: Optional. When set, returns only that ticker's row (correlations + most_entangled + most_divergent), not the full matrix. Case-insensitive. top_n: Universe size — top-N tickers by 3mo forecast growth (2–100, default 25). Smaller = tighter LLM payload. horizon: Forecast horizon to correlate — "1mo", "3mo", "6mo", or "1y" (default "3mo"). mode: "forecast" (model-implied, default) or "realized" (trailing-returns baseline). basis: Forecast-mode correlation basis. "mean" (default) correlates the single mean forecast curve. "ensemble" correlates across the full forecast band envelope (q05/q25/mean/q75/q95) and averages the per-band correlations — this surfaces TAIL co-movement (two names whose stress/downside paths move together) that the mean curve understates, which is exactly when diversification matters most. Ignored in realized mode. The method label becomes "quantum_forecast_ensemble" so you never conflate the two. Returns the full-matrix shape (tickers / matrix / top_pairs / missing) by default, or the single-ticker shape when `ticker` is given. Carries method, basis, generated_at, scan_date, and disclaimer in the payload.

Get the earnings calendar (next + last report) for one S&P 500 ticker. Earnings are a scheduled volatility event. A swing entry held into a print carries gap risk that no stop can protect against — the price can jump the stop overnight. This tool surfaces the next-upcoming and last-reported earnings dates plus a derived `earnings_risk_note` so an agent can time entries around the event rather than blindly into it. Edge / risk discipline: when the next report is <= 5 days out, swing BUYs are suppressed server-side (see get_signal / get_trade_plan) — the note here says so loudly and flags any entry as elevated gap risk. Far from a print, the note is neutral. This is the timing companion to get_trade_plan. Graceful degradation: earnings data is a silently-degrading signal. When no data is available (cold cache + no live source), `available` is false and `next`/`last` are null — treat that as "unknown", not "no earnings". Args: ticker: Stock ticker symbol (e.g. "AAPL", "MSFT", "NVDA"). Case-insensitive. Returns a dict with available, next, last, days_until_next, earnings_risk_note, as_of and disclaimer embedded in the payload.

Explain WHY a ticker has its current verdict — the factor attribution behind it. get_signal gives the verdict; get_trade_plan gives the execution; explain_signal gives the *reasoning*. It decomposes the quantum signal into the individual factors that drove the call — directional probability, expected upside, tail downside, confidence-band width, band calibration, market-condition gating, and risk-reward — each with a direction, a 0..1 contribution weight, the raw value, and a plain-English sentence. Pure transform over the same data get_signal returns; no new model run. TWO-SIDED BY DESIGN (north-star honesty): the response always carries a `dominant_factor` (the single biggest mover) AND `dissenting_factors` (what argues against the verdict). A stand-aside verdict (WAIT/AVOID) flags any strong directional read it overrode — so an agent sees the bull case it is declining, not just the conclusion. An empty dissent list means nothing material pushed the other way, NOT that the call is certain. Use this when an agent (or its user) needs to defend, audit, or reject a signal — never pitch a one-sided trade from the verdict alone. Args: ticker: Stock ticker symbol (e.g. "AAPL", "MSFT", "NVDA"). Case-insensitive. Returns a dict with verdict, factors[], dominant_factor, dissenting_factors, generated_at and disclaimer embedded in the payload.

Get the latest Fear and Greed index value. Sourced from the CNN Fear and Greed model, cached and refreshed periodically. Values range 0 (Extreme Fear) to 100 (Extreme Greed). Read it alongside get_market_regime, which exposes both gauges: high greed with good buying conditions = momentum intact; high greed with a hot overheating gauge = crowded long, a contrarian warning. Fear (below 50) is the crowd NOT leaning in — on its own that argues against calling a market frothy, whatever the buying-conditions score says. Returns a dict with value (0-100), label (e.g. "fear"), and timestamp, plus `current` ({score, rating, updated_at}), `history`, and the per-component `sub_indicator_scores`.

Fetch the full Quantustik signal + forecast writeup for one ticker. Paired with search — call search(query) first to find the ticker's id, then fetch(id) here for the full readable content. Also accepts a bare ticker symbol typed directly (id need not come from a prior search call). Args: id: Ticker symbol as returned by search, e.g. "NVDA". Returns a dict with id, title, text (a plain-text signal/forecast summary suitable for quoting or summarizing), url, and metadata (verdict, conviction, generated_at).

Get the "Lazy Prices" 10-K/10-Q language diff for one ticker. Compares the two most recent 10-K (year-over-year, default) or 10-Q (quarter-over-quarter) filings' Risk Factors (Item 1A) and MD&A (Item 7 for 10-K, Item 2 for 10-Q) sections, pre-chewed so you don't have to parse raw filing HTML yourself: a real TF-IDF cosine similarity score between the two extracted section texts, plus the top added/removed sentences from a real sentence-level diff, plus a one-line AI summary grounded strictly in those diffed sentences (`summary_source: "llm"`), or a factual sentence built purely from the computed similarity/counts when no LLM is available (`summary_source: "computed"`) — never fabricated either way. Every result links to BOTH source filings via `filings[].accession_url` — verify anything before acting. Cites a known academic finding: Cohen, Malloy & Nguyen (2020), "Lazy Prices", Journal of Finance — YoY changes in 10-K Risk Factors/MD&A language are historically return-predictive. This is a third-party academic result cited for context, NOT a claim or backtest result of this app. An empty `sections` dict is a valid, honest answer when the ticker has fewer than 2 filings of the requested form on file, or a section couldn't be reliably extracted from both filings (known gap: this extractor targets the common modern EDGAR HTML filing format used by large-cap names; older/non-standard filing formats may not extract). Read-only surfacing: this is information, NOT a buy/sell recommendation, and it does NOT feed the quantum model's conviction/verdict logic — this is a candidate signal still pending backtest validation. Args: ticker: Stock ticker (e.g. "AAPL"). Case-insensitive. form: "10-K" (year-over-year, default) or "10-Q" (quarter-over-quarter). Returns: ticker, form, filings (the two compared filings with accession_url), sections (keyed by "risk_factors"/"mda", each with similarity, added_sentences, removed_sentences, summary, summary_source), generated_at, disclaimer.

Get SEC 8-K event digest — per-ticker detail or a site-wide recent feed. New EDGAR ingestion (unlike get_insider_pulse's Form 4 data, which was already ingested): polls 8-K filings and pre-chews each one so you don't have to parse raw filing HTML yourself. Event type comes from the filing's OWN structured SEC Item number(s) — GROUND TRUTH, never LLM-guessed (e.g. Item 5.02 = exec departure/appointment, Item 2.02 = earnings results, Item 2.01 = M&A completion, Item 4.02 = restatement). The `summary` field is a one-line AI narration grounded in the actual filed document text (`summary_source: "llm"`), or a factual sentence built purely from the Item label(s) when no document excerpt was available (`summary_source: "item_labels"`) — never fabricated content either way. Every filing links to its source SEC filing via `accession_url` — verify anything before acting. Two modes: - ticker set: per-ticker view — up to 15 most-recent 8-Ks over the trailing ~6 months. - ticker omitted: site-wide feed — up to 30 most-recent 8-Ks across the S&P 500 (top-100) universe in the trailing ~2 weeks. An empty `filings` list is a valid, honest answer on a quiet news day. Read-only surfacing: this is information, NOT a buy/sell recommendation, and it does NOT feed the quantum model's conviction/verdict logic. Args: ticker: Optional. Stock ticker for the per-ticker view (e.g. "AAPL"). Omit for the site-wide recent feed. Case-insensitive. Returns per-ticker: ticker, filings, generated_at, disclaimer. Feed: tickers_scanned, filings, generated_at, disclaimer.

Get quantum probability forecasts across multiple time horizons for a ticker. Delivers calibrated probability distributions from the Feynman path-integral model: prob_up, expected growth %, downside %, and 90% confidence interval (ci_low / ci_high). Backtest CI90 calibration is included where available. Each measured horizon (3mo / 6mo / 1y) carries a `calibration` block, and that block deliberately contains NO coverage figure for the ticker: `ci90_empirical_coverage` is always null. BE HONEST WITH USERS — do not fill that gap. Band calibration is measured across a twenty-name universe at a given forecast start date, so no cell of the published record is a property of one symbol, and `calibration_status` is a statement about what we publish (`varies-by-start-date`, `not-published`, `not-backtested`), never a grade for this ticker. The one number in the block, `universe_ci90_range_pct`, is the lowest and highest coverage observed ACROSS forecast start dates for the whole universe — quote it as the universe's range and say what it is, never as this ticker's accuracy, and never average it. Each row behind that range already averages twenty names, so per-ticker dispersion is wider still. 1mo is not measured and carries no block. Read the quantustik://calibration resource for the per-start-date table, its provenance and its worst individual windows. Horizons available: 1mo (always), 3mo, 6mo, 1y (availability may vary by entitlement tier; public API always returns at least 1mo). The model computes amplitude integrals over all simulated price paths to capture non-linear shifts in market conditions. Args: ticker: Stock ticker symbol (e.g. "AAPL"). Case-insensitive. horizon: Optional single horizon to return ("1mo", "3mo", "6mo", "1y"). If omitted, all available horizons are returned. Returns a dict with horizons keyed by label and disclaimer embedded in the payload.

Get SEC Form 4 insider-trading activity — per-ticker detail or S&P 500 screener. Surfaces already-ingested Form 4 filings (the same Form 4 feed behind the market model's `form4` stage) pre-chewed into analytical context so you don't have to parse raw XBRL yourself: buyer role (officer / director / 10% owner), transaction size vs that SAME insider's own historical buy pattern (`size_vs_own_median`, `is_unusually_large` when >=2x their own median), and cluster-buy detection (`is_cluster` — 3+ distinct insiders buying the same ticker within a 10-day window, historically the stronger signal vs a single insider's trade). Every transaction links to its source SEC filing via `accession_url` — verify anything before acting. Two modes: - ticker set: per-ticker view — up to 40 most-recent Form 4 transactions over the trailing year plus `cluster_buy_active`. - ticker omitted: S&P 500 (top-100) screener — tickers with a cluster buy or an unusually-large buy in the last 30 days. An empty `results` list is a valid, honest answer; most weeks most tickers show nothing notable. Read-only surfacing: this is information, NOT a buy/sell recommendation, and it does NOT feed the quantum model's conviction/verdict logic — insider clusters are a candidate signal still pending backtest validation. Args: ticker: Optional. Stock ticker for the per-ticker view (e.g. "AAPL"). Omit for the S&P 500 screener. Case-insensitive. Returns per-ticker: ticker, transactions, cluster_buy_active, generated_at, disclaimer. Screener: tickers_scanned, results, generated_at, disclaimer.

Get 13F whale summaries + SC 13D/G activist alerts for one ticker. Final slice of the SEC EDGAR AI-digest layer. Two surfaces in one payload: `whale_summary` — QoQ (quarter-over-quarter) change in institutional ownership across a curated ~50-filer 13F universe (activist funds, quant shops, mega index managers, tiger cubs, sovereign wealth, etc.): new positions opened, positions closed, and the largest increases/decreases by dollar value between the two most recent 13F quarters on file. Pure computed deltas — no LLM narration, just real numbers. Institutional filer names come from SEC's own submissions data (ground truth), and every filer row links to its source 13F accession via `accession_url`. When there's genuinely nothing to compute (ticker not held by any tracked filer, or fewer than 2 quarters on file), the `narration` field says so plainly instead of a fabricated result. A filer only ever appears in `closed_positions` when there is an actual filing from that filer covering the latest quarter that omits this ticker's cusip; a filer simply absent from the latest snapshot with no filing on file for that quarter at all lands in `no_recent_filing` instead — never treated as a sale. Absence of a filing is not evidence of a sale. `activist_alerts` — recent Schedule 13D (activist/control intent) and 13G (passive >5% stake) filings. 13D entries carry a one-line AI summary grounded STRICTLY in the filing's own Item 4 ("Purpose of Transaction") text when it can be confidently extracted (`summary_source: "llm"`) — never an invented intent; otherwise a factual fallback sentence (`summary_source: "item_label"`). 13G entries get a structured, non-AI note (`summary_source: "structured"`) since 13G is reserved for passive filers with nothing to narrate beyond the threshold crossing. Every alert links to its source filing via `accession_url`. Read-only surfacing: this is information, NOT a buy/sell recommendation, and it does NOT feed the quantum model's conviction/verdict logic — this is a candidate signal still pending backtest validation. Args: ticker: Stock ticker (e.g. "AAPL"). Case-insensitive. Returns: ticker, whale_summary (cusip, quarters, new_positions, closed_positions, no_recent_filing, increased, decreased, narration), activist_alerts (list of filings with form, reporting_person, summary, summary_source, accession_url), generated_at, disclaimer.

Scan the S&P 500 universe and return filtered signals. Pushes filters + pagination to the server (GET /signals): the REST API applies min_conviction/direction/sector and returns one page of size limit, so the LLM payload stays tight regardless of how broad the universe is. Use this to discover high-conviction opportunities across the market rather than analyzing tickers one by one. The scan covers all S&P 500 tickers simultaneously, surfacing cross-ticker convergence patterns that per-ticker analysis would miss. Freshness: scan runs on a scheduled cadence (typically several times per day). Results carry scan_generated_at, and a `data_freshness` sentence only when the scheduled run did not land. Pagination: results are deterministically ordered server-side. When more results remain, next_cursor is a non-null opaque token — pass it back as cursor= to fetch the next page (scan_universe(..., cursor=next_cursor)). next_cursor is null on the last page. Args: min_conviction: Minimum conviction score (0–10). Recommended: 6.0+ for actionable signals, 7.5+ for high-conviction only. direction: Filter by signal verdict — "BUY", "WAIT", "AVOID", or "WATCH". Case-insensitive. sector: Filter by sector name (partial match, case-insensitive). Examples: "Technology", "Health Care", "Financials". limit: Page size — max results per call (default 20, max 100). cursor: Opaque pagination cursor from a previous call's next_cursor. Omit for the first page. Returns a dict with count, scan_generated_at, results list, next_cursor (null when no further pages), and disclaimer embedded in the payload.

Search Quantustik for S&P 500 tickers by symbol or company name. Paired with fetch — this is the two-tool "search"/"fetch" convention ChatGPT connectors and deep-research clients expect from an MCP server: call search first to get lightweight hits, then fetch(id) on the one(s) worth reading in full. Args: query: Ticker symbol (e.g. "NVDA") or company-name substring (e.g. "nvidia", "apple"). Case-insensitive. Returns a dict with a `results` list of up to 10 {id, title, url} objects — id is the ticker symbol, ranked exact-symbol match first, then company-name/ticker prefix, then substring. Empty query or no scan data returns an empty list, never an error.

Get signals (or trade plans) for many S&P 500 tickers in ONE call. Built for portfolio / watchlist sweeps: a research agent analysing 10–30 names should fan out once here instead of N separate get_signal / get_trade_plan round-trips (N quota decrements, N disclaimer copies, N chances for partial failure). This is a pure transform over data already exposed by get_signal / get_trade_plan — no new model work. Per-ticker failure isolation: a not-found / timeout on one symbol records an entry in ``errors`` and the batch continues — one bad ticker never aborts the whole call. Input tickers are de-duplicated (first-seen order preserved) and capped at 25 per call; pass more and the extras are dropped with ``truncated: true``. Args: tickers: List of S&P 500 symbols (e.g. ["AAPL", "MSFT", "NVDA"]). Case-insensitive. Max 25 processed per call. plan: When False (default) each result is the get_signal payload (raw verdict + levels). When True each result is the full get_trade_plan payload (entry/exit ladder/sizing/risk; actionable=false unless a >=2:1 BUY/EXIT). Returns a dict: count (successful lookups), requested, truncated, results (keyed by ticker symbol), errors (keyed by ticker symbol), and disclaimer.

Onboard to the Quantustik API/MCP: anonymous access and quotas. No API key is needed — every tool is callable right now under an anonymous per-IP hourly cap. Returns the live keyless/free-key request quotas (pulled live from server config) plus the optional key-issuance URL and auth header format. Pure informational — no auth required to call it.

Get everything we compute about ONE stock, in plain English, with contributions. The per-ticker twin of `get_market_indicators`: the eight weighted components that make the conviction score (forecast direction, realistic downside, how well our past forecasts held up for this specific stock, trend, momentum, overbought/ oversold, position in the 52-week range, and path momentum — whether our forecast is in step with the stock's recent moves, a continuity check and NOT a forecast-accuracy score), the forecast band, the risk and sizing numbers, and every risk check that can veto a BUY. Rows are grouped by what they do to the verdict, under `groups`: - "down" — pushing the verdict down. Includes any risk check currently BLOCKING a BUY: those carry no points (they are vetoes, not subtractions) but they are the reason there is no signal. - "up" — pushing it up. - "silent" — measured and not moving the score: the neutral components, plus the context rows (price, band, volatility, beta, drawdown, position size) that are shown but never scored. - "unavailable" — no reading, or a risk check the cascade never reached because an earlier one had already blocked the signal. NOT a pass, and not the same as "silent" — do not report it as "fine". `aggregate.arithmetic` gives the sum that produces the score: a neutral stock starts at 5.0/10 and the scoring rows move it from there, so the column adds up to the headline and the verdict can be checked rather than asserted. This returns the SAME rows, with the SAME wording, that a human sees at /ticker/<TICKER>/indicators. Quote them as they are. Returns a dict with title, as_of, aggregate, groups, rows, and disclaimer.

Get a small, risk-vetted shortlist of asymmetric setups passing every gate right now. This is NOT a screener. Where scan_universe returns up to 100 sortable rows, top_opportunities answers the real question — "what are the 1-3 highest-conviction setups right now, and what's the catch on each?" — and deliberately returns FEW or ZERO names. A setup is included ONLY if it passes ALL of: • current market conditions permit new longs (not Caution / Strong Avoid), • conviction >= 7.5 (high-conviction floor — multi-signal convergence), and • risk-reward >= 2:1 with concrete entry + stop levels. AN EMPTY LIST IS A VALID, HONEST ANSWER. In a hostile or unclear market the right call is to wait — a missed trade is cheap, a bad trade is expensive. When nothing qualifies, `count` is 0, `results` is empty, and `message` explains why (e.g. the market is hostile, or no name cleared the bar). Every returned item carries its bear case in `key_risk` so you never present a one-sided pitch. Each also includes the full entry_plan / exit_plan / sizing from get_trade_plan. Args: max_results: How many setups to return (1–5, default 3). Capped at 5 — this surface is intentionally sparse. Returns a dict with count, regime (the market verdict — key name kept for existing integrations), message, results (each with ticker, verdict, conviction, entry_plan, exit_plan, sizing, rr_ratio, key_risk), and disclaimer embedded in the payload.

Get the realised track record: win-rate + R-multiple distribution. Aggregates actual closed outcomes (tp_hit, trail_stop_hit, stop_hit, position_closed) into an honest scorecard — win_rate, wins/losses, and the realised-R distribution (mean/median/min/max/total). Pass a ticker for its per-ticker record; omit it (or pass "") for the portfolio-wide record. HONESTY: small samples are flagged `illustrative: true` with an explanatory `note`, and `win_rate` is null when no closed P&L exists. Never present an illustrative record as a reliable hit-rate. Every number is grounded in stored outcome events — none are fabricated. This is the ground-truth check on signal quality: a high stated R:R only holds if the realised-R mean is positive and the stop-hit rate is low. Args: ticker: Stock ticker (e.g. "AAPL"), or "" for portfolio-wide. Returns a dict with scope, sample_size, win_rate, realised_r, and note.

Get an execution-ready trade plan for one S&P 500 ticker — entry, exit, size, risk. This is the decision tool: it turns the raw quantum signal into a concrete, risk-first plan you can act on. Unlike get_signal (which reports the raw verdict and levels), get_trade_plan wraps them in execution discipline: - entry_plan: the exact entry trigger, a "don't chase" rule, and the invalidation level that kills the thesis. - exit_plan: a take-profit ladder (TP1/TP2/TP3), scale-out guidance, a volatility-aware trailing-stop rule, and a 3-month time-stop. - sizing: position-size suggestion, worst-case max-drawdown %, and R:R. FALSE-NEGATIVE BIAS (by design — a missed trade is cheap, a bad trade is expensive): a plan is only `actionable=true` when the verdict is BUY/EXIT AND concrete entry+stop levels exist AND risk-reward is >= 2:1. In every other case — WAIT/AVOID, missing levels, or thin R:R — the tool returns `actionable=false`, emits NO entry trigger, and states the `no_trade_reason` loudly. Treat "no trade" as the correct, common answer, not a failure. Always check regime_gate: a BUY from a scan that had no live market snapshot is lower confidence. When `data_freshness` is present the payload is saying, in a sentence, that the last scheduled run did not land and the levels predate the current tape — relay that sentence; its absence means the data arrived on schedule and needs no mention. Always check get_earnings_calendar: an entry within 5 days of a print carries gap risk a stop can't protect, and swing BUYs are suppressed there. Args: ticker: Stock ticker symbol (e.g. "AAPL", "MSFT", "NVDA"). Case-insensitive. Returns a dict with actionable flag, verdict, entry_plan, exit_plan, sizing, regime_gate, calibration, and disclaimer embedded in the payload.