StockMarketScan

Minimal sanity check. Returns { status, version, timestamp, cache_size }. No auth needed. Use this to verify the MCP server is reachable and responsive.

Takes no parameters.

Return metadata for all 24 stock screeners on the platform: slug, name, description, category, tier, whether the caller can read it, and its row fields with their JSON value types. Use this to discover which screeners are available before calling get_screener_data. Call this once per session; the list changes very rarely. Returns { data: [{ slug, name, description, category, tier, accessible, columns: [{ key, label, type, value_type }] }], meta: { caller_tier, total, accessible } }.

Takes no parameters.

Return the rows of a single stock screener for its latest snapshot. Use this when the user asks about a specific screener like 'hot prospects' or 'golden cross'. Common slugs: hot-prospects, golden-cross, death-cross, rsi-oversold, rsi-overbought, defensive-stocks, dividend-prospects, j-pattern, nearing-6-month-highs, week-52-high-top-picks, top-penny-pops, strong-volume-gains, top-tech-stocks, fundamentally-fine, income-and-growth, best-reits. If you don't know the slug, call list_screeners first. Numbers are JSON numbers (percent_change 1.25 means +1.25%), dates are YYYY-MM-DD. Returns { data: [rows], meta: { as_of, screener, pagination: { next_cursor, total } } }. For the next page pass meta.pagination.next_cursor as cursor.

Find stocks that appear in multiple screeners simultaneously. Useful for finding overlap across screeners. Use when the user asks 'which stocks are in both X and Y' or 'find stocks in 3+ bullish screeners'. Returns { screeners_queried, mode, count, symbols: [{symbol, screeners, match_count}] }. Intersection mode returns only stocks in ALL listed screeners; union returns stocks in ANY.

Return all chart patterns currently detected for a single stock symbol. Detectable pattern ids: double_top, double_bottom, triple_top, triple_bottom, head_shoulders, inv_head_shoulders, round_bottom, cup_handle, asc_triangle, desc_triangle, sym_triangle, channel_up, channel_down, rectangle, flag, wedge_rising, wedge_falling, abcd, gartley, bat, butterfly, crab, impulse_wave, corrective_wave. Use when the user asks 'what patterns does X have' or 'is X forming a head and shoulders'. Requires a Pro or Enterprise API key. Returns { data: { symbol, interval, computed_at, candle_count, patterns: [{ id, name, type, category, confidence, points, lines, target_price, last_structural_point }] } } where type is the pattern direction (bullish, bearish, neutral). Empty patterns array if none detected.

Find all stocks across one or more screeners that currently exhibit specific chart patterns. Much faster than calling get_chart_patterns in a loop. Use when the user asks 'which stocks have a cup and handle' or 'find me hot prospects with bullish reversal patterns'. Requires a Pro or Enterprise API key; unknown slugs or pattern ids and screeners above the plan are errors. Results are capped per screener group via `limit` (default 100); capped groups carry truncated: true. Returns { data: [{ screener_slug, screener_name, count, truncated, stocks: [{ symbol, symbol_name, last_price, volume, data_date, matched_patterns }] }], meta: { total_unique_stocks } }.

Return the daily options flow table for one trading day: aggregated call/put volume, premium, implied volatility, and consecutive-day streaks for every notable symbol. Use when the user asks 'what's the options flow today' or 'show me the largest premium'. Each row includes call_put_volume_ratio (> 1.0 means more call than put volume), consecutive_days (streak length), total_premium (dollar size), call_avg_iv/put_avg_iv. Returns { data: [...], meta: { as_of, market_stats, available_dates, pagination: { next_cursor } } }. Tier: Pro or Enterprise.

Return the historical options flow for a single stock: most recent days first. Use when the user asks 'show me X's options flow history' or 'how long has X been bullish'. Returns { data: [daily rows, newest first], meta: { as_of, pagination: { next_cursor } } }. Tier: Pro only.

Return ranked options flow records for a date range: the records that stand out by long consecutive-day streaks, large premium, and screener confluence. Each record includes data-only performance tracking measured from a realistic entry reference: entry_price = open of the trading day AFTER signal_date (the close of signal_date is not an available fill price). max_gain_pct/max_drawdown_pct/price_change_pct are computed against entry_price; if that day's US open hasn't happened yet, these fields and entry_price are null ('pending'). This is descriptive market data for your own research, not a recommendation. If date_from/date_to omitted, returns last 60 days. Returns { data: [...], meta: { as_of, pagination: { next_cursor }, parameters: { date_from, date_to } } }. Dates are YYYY-MM-DD and numbers are JSON numbers. Tier: Pro only.

Return daily options market sentiment: one row per trading day. Combines NYSE/NASDAQ market breadth (advance/decline + new highs/lows) with the market-wide call/put ratio. Each row includes market_breadth_score (0-100), market_call_put_ratio, the daily filter context (bullish_only/bearish_only/mixed), bullish_count/bearish_count of flow records that day, plus a derived sentiment_score (0-100) and sentiment_label (bullish/neutral/bearish). Use when the user asks 'what's market sentiment today', 'how bullish is the market', 'show me sentiment over the last week'. If date_from/date_to omitted, returns last 60 days. Returns { data: [...], meta: { as_of, pagination } }. Tier: Pro only.

Return individual options contracts flagged as unusual activity (Vol/OI > 1.5). Each row is one contract, not one stock. Use when the user wants contract-level detail. Filter by symbol, side (call/put/both), minimum vol/oi, minimum premium, or max days to expiration. For aggregated stock-level flow use get_options_flow_overview instead. Returns { date, count, contracts: [...], next_cursor }.

Return basic metadata for a stock: full company name, exchange, industry, last price, and daily percent change. Use this when you first encounter a symbol and need to identify it. Lighter than get_stock_report (composite) or get_candles (full history). Returns { data: { symbol, symbol_name, last_price, percent_change, exchange, industry }, meta: { as_of } }; percent_change 1.27 means +1.27%. Returns NOT_FOUND for unknown tickers.

Return OHLCV price candles for a single stock, oldest first. Use when you need price history to compute indicators or answer 'how much is X up this month'. date is the trading day (YYYY-MM-DD; weekly candles use the Monday). Default range is 6mo. Use larger ranges like '1y' or '2y' only when the user explicitly asks for long history; max range is 20 years. Returns { data: [{ date, open, high, low, close, volume }], meta: { as_of, pagination: { total } } }.

Search for stocks by ticker prefix or company name. THE tool to use when the ticker is unknown ('what's the symbol for Palantir?') or ambiguous: resolve the name to a symbol here, then use get_stock_info / get_stock_report with the symbol. No API key required. Returns { data: [{ symbol, name }], meta } ordered by best match.

Return a comprehensive report on a single stock in one call: metadata, screener appearances, chart patterns, options flow, signal status, price summary, and upcoming earnings. THIS IS THE PREFERRED FIRST TOOL when a user asks about a single stock. It replaces 5-7 separate tool calls (get_stock_info + get_chart_patterns + get_options_flow_timeline + get_options_flow_ranked + screener lookups + get_candles). Do NOT also call the primitives after calling this: the composite already has everything. Parallel fetch under the hood, graceful partial failures (if one source errors, that section returns null with a note). Returns { symbol, as_of, info, screeners, patterns, options_flow, signal, candle_summary, overall_bias }. overall_bias is a heuristic hint, not financial advice.

List today's options flow records for one side (bullish or bearish), ranked by a descriptive composite score (strength score + consecutive-day streak + premium size). Use when the user asks which symbols had the most notable options flow today. This is descriptive market data, not a recommendation. Summarize the first few rows rather than dumping the raw JSON. Use get_stock_report to look at a single symbol in more detail. Returns { side, date, count, setups: [{ symbol, score, signal: { type, strength, consecutive_days, call_put_ratio, total_premium } }] }.

Return NYSE and NASDAQ market breadth: advancing/declining/unchanged issues, their percentages, and new highs/lows. Use when the user asks 'how's the market today' or 'is breadth strong'. Default (no params): last 7 trading days. Send either date or date_from/date_to (either end may be omitted). Returns { data: [{ data_date, exchange, advancing_issues, declining_issues, unchanged_issues, percent_advancing_issues, percent_declining_issues, percent_unchanged_issues, new_highs, new_lows }], meta: { as_of } }; all counts and percents are numbers (63 means 63%). Two rows per date (NYSE + NASDAQ). Tier: Pro or Enterprise.

Return AI-detected trending topics in tech & science, patents, or funding events. Use when the user asks 'what's trending in tech' or 'show me patent trends'. Use one of latest, date, or days. Returns { data: [{ date, topic, weight }], meta: { as_of } } where weight is 0-1. Tier: Pro only.

Return AI-computed connections between trending topics across categories (tech → patents, tech → funding, etc). Useful for spotting meta-trends. Use when the user asks 'what trends are connected' or 'show me cross-category signals'. Use one of latest, date, or days. Returns { data: [{ date, source_category, source_topic, target_category, target_topic, strength, rationale }], meta: { as_of } }. Tier: Pro only.

Return a plain-language explanation of a platform-specific term, metric, or screener. Use ONLY for terms that are specific to StockMarketScan (e.g. 'strength_score' which is our internal scoring, or 'hot_prospects' which is our curated screener). Do NOT use for generic finance terms the model already knows: answer those directly. Returns { term, title, explanation, interpretation, related_terms }.