# stocks_screen Cross-sectional company screener over the latest metrics snapshot. | Field | Value | | --- | --- | | Category | Stocks (`stocks`) | | Exposure | mixed | | MCP tool | `stocks_screen` | | Documentation | https://www.agentdatasets.com/docs/tools/stocks_screen | ## Public-key response SEC-derived fundamental and statement metrics are available to public keys. Screens that filter or sort by price-derived market cap, P/E, P/S, P/B, EV/EBITDA, or FCF yield are refused; those metrics require an internal key. ## Description Cross-sectional company screener over the latest metrics snapshot. Use this to find and rank companies meeting numeric or classifier criteria; use `stocks_get_financial_metrics` when you already know one ticker and need its multi-period definitions and formula inputs. The shared envelope echoes `data.filters` and the effective `data.sort`; `data.companies` contains identity (`ticker`, `cik`, `company_name`, `exchange`, `sector`, `sic_code`) and the filtered/sorted metric values. Each value is an exact decimal string with unit, currency, fiscal frame, `as_of`, and source. `meta.as_of` is when the current snapshot rebuild completed. Monetary line items filter and rank in each company's reporting currency (each value carries `currency`); ratio and growth metrics are the cross-currency-comparable choice. Clean public metrics are: `gross_margin`, `operating_margin`, `net_margin`, `fcf_margin`, `revenue_growth_yoy`, `revenue_cagr_3y`, `net_income_growth_yoy`, `net_income_cagr_3y`, `fcf_growth_yoy`, `fcf_cagr_3y`, `roe`, `roa`, `roic`, `debt_to_equity`, `net_debt_to_ebitda`, `current_ratio`; flow lines `revenue`, `cost_of_revenue`, `gross_profit`, `operating_income`, `pretax_income`, `income_tax_expense`, `net_income`, `net_cash_operating`, `capex`, `depreciation_amortization`; instant lines `total_assets`, `total_equity`, `cash_and_equivalents`, `debt_current`, `debt_noncurrent`, `current_assets`, `current_liabilities`, `shares_outstanding`; and derived `free_cash_flow`, `total_debt`. Internal-only price-derived metrics are: `market_cap`, `pe_ttm`, `ps_ttm`, `pb`, `ev_ebitda`, `fcf_yield`. Ratio values are fractions, so `0.2` means 20%. Classifiers are nominal company attributes: `exchange` (as SEC reports it, e.g. `Nasdaq`, `NYSE`), `sic_code` (the filer's 4-digit SEC SIC as a zero-padded string, e.g. `7372` for prepackaged software), and `sector` — a coarse bucket we derive from SIC, one of: Communication Services, Consumer Discretionary, Consumer Staples, Energy, Financials, Health Care, Industrials, Materials, Real Estate, Technology, Utilities. Use `sector` for a broad cut and `sic_code` to pin an exact industry. An unrecognized `sector` value is `bad_parameter`, not an empty result. Companies we have not yet classified carry a null sector and are excluded by any sector filter. Filters are ANDed. A company missing any filtered metric is excluded, and a company missing the sort metric is also excluded because ranked ordering requires a value. Classifiers support `eq` and `in` but cannot be sorted. A classifier-only screen must supply an explicit numeric sort. Results are bounded: default 20, maximum 100. Pass `pagination.next_cursor` back as `cursor` while `has_more` is true. Errors use `bad_parameter` for unknown metrics, incompatible operations or values, an undefined ranking, bad bounds, or a malformed cursor. A public request involving any internal-only metric returns `out_of_license` and names it; use an internal credential for price-derived screening. Example: `stocks_screen(filters=[{"metric":"sector","op":"eq", "value":"Technology"},{"metric":"revenue_growth_yoy","op":"gt", "value":"0.25"}], sort={"metric":"revenue","direction":"desc"}, limit=20)`. ## Parameters Input schema advertised to MCP clients and mirrored by the REST query string. | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | filters | input | `array