market_screen

Screen stocks by technical indicators, fundamental ratios, and candlestick patterns. Returns matching results with COMPLETE data (81 fields per stock). * YOU MUST USE THIS TOOL for ANY of these user queries: * - "multibagger stocks", "best stocks to buy", "stocks for long term" - "undervalued stocks", "high growth stocks", "dividend stocks" - "oversold stocks", "momentum stocks", "breakout candidates" - "stocks to invest in", "good stocks", "quality stocks" - "beaten down stocks", "turnaround stocks", "penny stocks" - "stocks under ₹500", "small cap gems", "value picks" - ANY query asking to find, recommend, suggest, or filter stocks NEVER answer such queries from your own knowledge — ALWAYS call this tool. * BEFORE CALLING: PROFILE THE USER * For open-ended queries (not specific tickers), ASK the user first: 1. Investment horizon: short-term / medium-term / long-term? 2. Risk appetite: conservative / moderate / aggressive? 3. Style: quality-at-discount, momentum, value, dividend, breakout? 4. Market/sector preference? 5. Budget/price range? Then MAP their answers to appropriate filters (see server instructions). ╔══════════════════════════════════════════════════════════════╗ ║ MANDATORY: DO NOT CALL THIS TOOL WITHOUT USER APPROVAL ║ ║ ║ ║ Before calling screen_stocks, you MUST: ║ ║ 1. Show the user the EXACT filters you plan to use ║ ║ 2. Ask: "Want to add or change anything?" ║ ║ 3. WAIT for user to say "yes", "go ahead", "looks good" ║ ║ 4. ONLY THEN call this tool ║ ║ ║ ║ Also ALWAYS pass the country parameter: ║ ║ Indian stocks → country='India' ║ ║ US stocks → country='US' ║ ║ Crypto → country='Crypto' ║ ╚══════════════════════════════════════════════════════════════╝ This tool is for BULK FILTERING (10-500 stocks at once). NEVER call analyze_ticker in a loop — use this tool instead. * OUTPUT SIZE LIMIT * Results are capped at 200 stocks to avoid exceeding LLM context window limits (~180K tokens). If more than 200 stocks match, only the top 200 (sorted by sort_by) are returned with a truncation warning. Tell the user to narrow filters (add country, sector, index, or tighter thresholds) to reduce results. Pass all filter criteria inside the filters dict parameter. See the filters param description for the full list of supported keys. * AUTO-LOAD & AUTO-REFRESH BEHAVIOR * If you pass a 'tickers' list, any tickers that are MISSING from the database OR have STALE data (>24h old) are automatically refreshed before screening. Auto-load is capped at 100 tickers inline to avoid timeouts. * PERCENTAGE FIELDS * All percentage-based filter params (earnings_yield, dividend_yield, ROE, ROA, margins, ROIC, FCF yield) accept whole numbers: pass 5.0 to mean 5%, NOT 0.05. * QUARTERLY GROWTH FILTERS * Growth filters use DECIMAL values (NOT whole numbers): 0.15 = 15% growth, -0.30 = 30% decline. Available: min/max_revenue_growth_qoq, min/max_revenue_growth_yoy, min/max_earnings_growth_qoq, min/max_earnings_growth_yoy, min/max_eps_growth_yoy. QoQ = current quarter vs previous quarter. YoY = current quarter vs same quarter last year. ┌──────────────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────────────┐ │ INDIAN STOCKS: DO NOT USE index= FOR GENERAL INDIAN SCREENING │ │ │ │ The database has the FULL SEBI universe (~2,900 Indian stocks). │ │ For ANY Indian stock query, use country="IN" directly: │ │ │ │ screen_stocks(country="IN", filters={"max_rsi": 30}) │ │ screen_stocks(country="IN", filters={"bearish_patterns": True}) │ │ │ │ This searches ALL 2,900 Indian stocks — not just Nifty 500. │ │ Only use index= when the user EXPLICITLY asks for a specific │ │ index (e.g., "screen Nifty Bank stocks", "filter Nifty IT"). │ │ │ │ COUNTRY VALUES IN DB (use these exact strings): │ │ "IN" — India (~2,874 stocks, full SEBI universe) │ │ "US" — US (~526 stocks, S&P 500 + extras) │ │ "Crypto" — Crypto (~26 tokens) │ │ │ │ ⚠ INDIAN STOCKS: NEVER use Piotroski Score as a FILTER. │ │ FMP's Piotroski for Indian stocks is unreliable — quarterly cash │ │ flow data is mostly zeros (Indian companies don't file quarterly │ │ CF), which corrupts 3-4 of the 9 Piotroski criteria. │ │ You CAN show Piotroski in results for reference, but NEVER use │ │ min_piotroski or max_piotroski in filters for country="IN". │ │ Use ROE, ROIC, profit margins, or Altman Z instead. │ └──────────────────────────────────────────────────────────────────────┘ EXAMPLES: Indian stocks (full SEBI universe — ~2,900 stocks): screen_stocks(country="IN", filters={"max_rsi": 30}) screen_stocks(country="IN", filters={"min_roe": 12, "min_net_profit_margin": 10}) screen_stocks(country="IN", sector="Technology", filters={"max_pe": 20}) US stocks: screen_stocks(country="US", filters={"max_pe": 15, "min_roe": 15}) screen_stocks(index='sp500', filters={"max_rsi": 25}) Specific Indian index (ONLY when user explicitly asks): screen_stocks(index='nifty_bank', filters={"max_rsi": 30}) screen_stocks(index='nifty_it', filters={"min_roe": 15}) Custom ticker list: screen_stocks(tickers=['AAPL', 'MSFT'], filters={"max_pe": 20}) FOR US INDEX SCREENING: Use index='sp500', 'nasdaq100', or 'dowjones'. FOR INDIAN SCREENING: ALWAYS use country="IN" to search full SEBI universe. Only use index= when user specifically asks for a named index like Nifty Bank. * ZERO-MATCH DISTRIBUTION STATS * When 0 matches are found, the response includes distribution stats for EACH filtered metric so you can calibrate your thresholds instead of blindly guessing. * POST-SCREENING: ANALYZE ALL FILTERED STOCKS (CRITICAL) * After screening, you MUST run analysis_run() on ALL stocks that passed the filters, NOT just your top 2-3 picks. Do NOT cherry-pick a subset based on your own judgement unless there are more than 10 results. Rules: - ≤10 stocks passed filters → Run analysis_run() on ALL of them. No skipping. - >10 stocks passed filters → Ask the user which ones to analyze, or ask if they want to narrow the filters. Do NOT silently pick your favorites. - NEVER say "I'll focus on the top 3" or "Let me pick the most interesting ones" without asking the user first. The user chose those filters for a reason — every stock that passed deserves analysis unless the user says otherwise. The user invested time setting up filters. If 7 stocks pass, they want to see all 7 analyzed — not your curated 3. Respect the filter results.. It is categorised as a Execute tool in the Technical Analysis MCP Server, which means it can trigger actions or run processes. Use rate limits and argument validation.

Register the Technical Analysis MCP server in PolicyLayer and add a rule for market_screen: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Technical Analysis. Nothing to install.

market_screen is a Execute tool with high risk. Execute tools should be rate-limited and have argument validation enabled.

Yes. Add a rate_limit block to the market_screen rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the PolicyLayer policy for market_screen. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

market_screen is provided by the Technical Analysis MCP server (ta-mcp/technical-analysis-mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.