Unified Screener (Universe × Fundamental × Technical)
screen_unifiedRead-only
EXECUTE a unified screen = universe ∩ fundamental ∩ technical ∩ options (any leg optional; each grammar resolved
server-side — key or plain English). Returns {universe, count, sort, executed_criteria (the resolved request that ran — save/re-run it verbatim), results:[{head_listing_id, ticker, name, score,
matched_legs, matched:{ta, fundamental:{:{value, basis, window?, series?, periods?}}}, context}], notes}.
Evidence keys == the leg name you sent (TA→matched.ta, fundamentals→matched.fundamental, NOT technical/financial);
matched_legs lists which leg(s) a row passed. A thin intersection adds partial:true + per-leg near-misses — never
present a partial/one-leg row as a full match; read notes (names the tighter leg + how to broaden).
Time windows are PER-LEG: TA 'within last N bars' = top-level window_bars; a fundamental trend's span = that
condition's N. Options leg is US-optionable only (~557 → US-capped); sort='options' ranks by it; an
options-vs-price divergence = just send the phrase in options. FAILS LOUD: an unsupported pattern/operand/concept
returns a 400, so count:0 with NO error = a VALID query that matched zero now (loosen / widen window_bars, don't say
'can't do X'); notes may say 'insufficient history' (not a no-match) or which basis was screened. Over-fetches a
~4× buffer (cap 100) so 'show me more' is served from these rows — don't re-call.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "screen_unified"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ta | No | The TECHNICAL leg — a THEN chain of steps (usually ONE). Each signal = `pattern` (SHAPE) + operands `a`/`b` (LINES), key or plain English, server-resolved. e.g. golden cross + volume spike → [{anchor:[{pattern:'crossover_up',a:'ema50',b:'ema200'}],quals:[{any:[{pattern:'volume_spike'}]}]}]. 'within the last N bars' = each signal's own `window_bars` (else the screen-level default); mix timeframes by setting a qualifier's own `timeframe` (1/2/3). Omit for a fundamentals-only screen. | |
| gics | No | OPTIONAL universe SCOPE — industry/theme concept(s), CSV of ATOMIC concepts (decompose 'banks and insurance' → 'banks,insurance'). Each = English ('banks','semiconductors','AI') or a GICS code prefix ('45'=IT sector, '352010'=biotech industry; shorter=broader); the server picks the axis (industry→GICS, megatrend→THEME). Omit = all sectors. | |
| mode | No | What to do with the formula. 'run' (default) = screen and return the stocks. 'check' = NO scan, no market data: resolve every field exactly as a run does and validate the formula (rules only, fast) → {ok, executed_criteria, snaps/notes}, or the same needs_rewrite answer (code, path, error, _guide, nearest) when it cannot run — use it to try a formula or a choice BEFORE you offer it. 'count' = 'check' + how many stocks match (exact up to 500, `capped` above) — use it when only how many is needed. No rows in check/count; count_total is for 'run' only. | |
| size | No | OPTIONAL market-cap size tier(s), OR'd — 'large'|'mid'|'small'|'micro'. RELATIVE per-market MSCI tiers ('small' = small FOR ITS market, not in USD; no separate 'mega'). For an ABSOLUTE USD size / 'under $X' use min/max_market_cap_usd instead. Omit = all sizes. | |
| sort | No | Rank key: 'ta' (default, TA chain score) · 'options' (use when `options` present) · 'mcap' · a TA-context oscillator ('rsi'/'adx' — 'most overbought'→'rsi') · or any fundamental metric key in the results (pe/roe/…). | |
| limit | No | How many stocks to SHOW (default 10). Over-fetches a ~4× buffer (capped 100) so 'show me a few more' is served from THIS result — don't re-screen; re-screen only to exceed the buffer. | |
| theme | No | ADVANCED raw-passthrough — megatrend THEME node_id(s), OR'd (core member of ANY). Normally OMIT: name the theme in `gics` ('AI') and the server routes it. Use only with a known node_id. | |
| country | No | OPTIONAL operating-country scope — one or MORE ISO-2 codes, OR'd (a stock matches if in ANY of them). e.g. ['US'] · ['CN','US'] for China+US · ['TH','SG','MY']. Omit = all countries. | |
| options | No | The OPTIONS leg — an options-behaviour term, key or plain English ('fear_building','iv_cheap','the crowd getting brave'), server-resolved. Intersects the ~557 US-optionable names showing it; an options-vs-price DIVERGENCE also goes here (the server expands it). US-optionable only. Omit for a non-options screen. | |
| criteria | No | A WHOLE formula in the saved shape — the `executed_criteria` a screen_unified call returned, or the user's saved formula ({universe:{include:[{country,gics,size,theme,asset_type,mcap_min,mcap_max}], exclude:[…]}, ta, fundamental:[{concept,pattern,params}], options:{pattern,horizon}, timeframe, window_bars, dividend}). To change a formula you got back, send it here WITH YOUR CHANGE APPLIED — resolved keys stay as they are, plain-English fields inside are resolved as usual. Works with every `mode`. Do not also send the separate formula fields (fundamental, ta, options, gics, country, …) — one or the other; sort / limit / count_total / mode may go with it. | |
| timeframe | No | Chart for the TA leg: 1=daily (default) · 2=weekly · 3=monthly. TA operand periods & for_bars are counted in BARS of this timeframe. | |
| asset_type | No | OPTIONAL asset type(s), OR'd: 'Common Stock','ETF','Crypto','Currency','Commodity','Bond','Index','Fund','ADR','REIT'. Crypto≠Currency (forex); gold/silver=Commodity. Omit = all (a company screen usually wants 'Common Stock'). | |
| count_total | No | Set true ONLY when the user asks HOW MANY match ('how many stocks…', 'is it more than 500?'): returns the exact `total` up to 500, else `total_over: 500`. Slower (runs every leg in full) — omit for a normal screen. | |
| fundamental | No | The FUNDAMENTAL leg — AND-ed conditions (each = a METRIC `concept` + a SHAPE `pattern` + its value; key or plain English, server-resolved). e.g. roe>20% & 3y revenue growth → [{concept:'roe',pattern:'above',threshold:0.20},{concept:'revenue',pattern:'consecutive_growth',N:3}]. 🔴 A fundamental trend's TIME SPAN goes in that condition's `N` (periods of its `basis`, annual by default; set basis only for quarterly/TTM) — SEPARATE from the TA leg's window_bars. Omit for a TA-only screen. | |
| window_bars | No | TA-leg LOOKBACK in bars of `timeframe` — how far back a signal may have fired / the span a THEN-chain completes within ('…within the last N days'; 'divergence within 50 days' → 50). Whole `ta` leg; omit → default 30 × number of ta steps. SEPARATE from a fundamental trend's `N`. | |
| exclude_gics | No | OPTIONAL — EXCLUDE industry/theme CONCEPT(s), CSV, codes or plain English ('banks','AI'); server-resolved & routed same as `gics`. Applies to EVERY leg ('high-yield but NOT banks' = fundamental dividend_yield + exclude_gics='banks'). `gics` INCLUDES; this EXCLUDES. | |
| exclude_theme | No | ADVANCED raw-passthrough — EXCLUDE megatrend THEME node_id(s). Normally just name the theme to exclude in `exclude_gics` ('not AI'); the server routes it. Universe-level negation across every leg. | |
| exclude_country | No | OPTIONAL — EXCLUDE operating-country(ies), ISO-2. 'global ex-US' = exclude_country=['US']. Universe-level, applies to every leg. | |
| options_horizon | No | Options horizon: 'long' (default, positioning/conviction) or 'short' (gamma/near-term). Only meaningful with `options`. | |
| dividend_min_cagr | No | OPTIONAL dividend gate — 5-year dividend CAGR ≥ this % (5 = ≥5%/yr). Needs a fundamental/ta/options base leg too. | |
| max_market_cap_usd | No | OPTIONAL ABSOLUTE max market cap USD (2000000000 = under $2bn). Pair with min for a band. | |
| min_market_cap_usd | No | OPTIONAL ABSOLUTE min market cap USD (50000000000 = $50bn). Use this (not `size`) for a USD floor / 'under $X' band. | |
| dividend_min_streak_years | No | OPTIONAL dividend gate — keep stocks with a no-cut dividend streak ≥ N years (reliability streak in a 10-year window, capped at 10; NOT the full age). A membership gate — combine with a fundamental/ta/options base leg (pure dividend screen → screen_dividends). |