search_companies
Natural-language / thematic search over the stocks-llm knowledge base of US public companies: S&P 500 + NASDAQ-100 + Dow Jones + Russell 1000 + Russell 2000 (deduped — effectively the Russell 3000 plus the Dow), spanning large-, mid-, AND small-cap companies, plus the major US exchange-traded funds (ETFs). UK public companies: the FTSE 350 (FTSE 100 + FTSE 250), listed on the London Stock Exchange. Data: SEC EDGAR filings + market-data fundamentals, each figure dated. Informational only, NOT financial advice. Matches a plain-English THEME (e.g. "high-power semiconductor devices", "GLP-1 diabetes drugs") against each company's enriched business summary, products/technologies and theme tags — not just its sector. Returns real DB companies with dated performance numerics (price + price_as_of, market_cap, price_return_1y, revenue_growth_yoy, net_margin) and dividend facts. Use sort to RANK the matched set and the filters to narrow it.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_companies"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | SPEC CR.1 sort DIRECTION. Omit for the key default. dir="desc" with sort=pe_ratio = "highest / most expensive P/E"; dir="asc" with sort=price_return_1y = "worst performing". Ignored for congress / short-interest sorts. | |
| sort | No | How to rank the semantically-matched set. "relevance" (default), or one of: price_return_1y, revenue_growth_yoy, market_cap, net_margin, gross_margin, operating_margin, roe, roa, roic, fcf_margin, dividend_yield, dividend_streak_years (higher first); pe_ratio, pb_ratio, debt_to_equity (lower first); price_target_mean (higher first). There is NO analyst buy/hold/sell RATING sort (SPEC CY.7 retired it) — do not substitute price_target_mean for a ratings question. SPEC AP congress ranking: congress_purchase_count_90d, congress_purchase_count_180d, congress_net_buy_180d — rank by disclosed U.S. House STOCK-Act (PTR) trading; result rows carry congress_purchase_count / congress_sale_count. SPEC BF.10 short interest: short_interest_days_to_cover — rank by the reported FINRA days-to-cover of the latest settlement (a normalized ratio, delayed, NOT raw shares or percent of float); rows carry short_interest_days_to_cover / short_interest_shares / short_interest_settlement_date. SPEC EI.3: short_interest_pct_outstanding — rank by short interest as a percent of shares OUTSTANDING (derived by us from the FINRA numerator and the company share count), which is what "highest short interest" usually means; rows carry short_interest_pct_outstanding plus the denominator source + as-of. It is NOT percent of FLOAT — float is smaller, so percent of float would be HIGHER and this number is a floor; never restate it as "short float". Companies whose share count we could not resolve are EXCLUDED (an abstention, not low short interest). SPEC DA.5 institutional ownership: institutional_holder_count, institutional_value_usd — rank by SEC 13F holdings among the managers we ingest (NOT the full 13F universe); rows carry institutional_holder_count / institutional_value_usd / institutional_report_period / institutional_managers_tracked, and the response carries an institutional_coverage sentence stating that bound. SPEC CR.1: each key has a natural default direction (pe_ratio/pb_ratio/debt_to_equity lowest-first, others highest-first) — pass `dir` to ask for the other end. | |
| limit | No | Max results (default 10, hard cap 50). | |
| query | Yes | The theme / what the company does, in plain words (e.g. "cloud infrastructure", "silicon carbide power devices"). | |
| market | No | Scope the search to one market. Defaults to US when omitted. An unknown value is returned as a tool error naming the known markets, never silently defaulted — a machine client that asked for a market it did not get would otherwise read the result as "no company matches". NOTE (SPEC DG.6): sources differ by market, so a filter or sort on a figure a market cannot supply comes back as a `market_unavailable` refusal rather than an empty list. | |
| sector | No | Restrict to one exact GICS sector. | |
| in_djia | No | SPEC HJ.3: true = only companies flagged as constituents of the Dow Jones Industrial Average. Send true or omit — false is not "not in the index", it is the absence of the filter. Membership as of the last quarterly index refresh: a company the refreshed list no longer names is removed then, so say "in the Dow Jones Industrial Average as of the last quarterly refresh". | |
| max_roa | No | CEILING on return on assets (PERCENT): only companies at or BELOW this value. Send it WITH min_roa for a two-sided range — "return on assets between X and Y" is ONE call with min_roa=X and max_roa=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_roa | No | FLOOR on return on assets (PERCENT). "return on assets over 10%" is min_roa=10. Distinct from min_roe. Companies missing the metric are excluded (null-safe). | |
| min_roe | No | Floor on return-on-equity PERCENT (e.g. 15). | |
| in_sp500 | No | SPEC HJ.3: true = only companies flagged as constituents of the S&P 500. Send true or omit — false is not "not in the index", it is the absence of the filter. Membership as of the last quarterly index refresh: a company the refreshed list no longer names is removed then, so say "in the S&P 500 as of the last quarterly refresh". | |
| min_roic | No | Floor on return-on-invested-capital PERCENT. Each row states its own basis: NOPAT / (debt + equity - cash) from its 10-K fiscal year where we derived it (EBIT = pre-tax income + interest expense where the 10-K tags no operating income, labelled), else the market-data vendor figure with its date. No figure = excluded. | |
| min_purity | No | Minimum purity tier for theme_category (default "significant"). pure_play = the category IS the core business; significant = a major named segment; adjacent = supplies into/serves the category; incidental = minor exposure only. Use "pure_play" for "pure-play X companies", "adjacent" or "incidental" only when the user explicitly wants the wider supply chain / any exposure. Ignored without theme_category. | |
| profitable | No | true = only companies with a positive net margin. | |
| in_nasdaq100 | No | SPEC HJ.3: true = only companies flagged as constituents of the NASDAQ-100. Send true or omit — false is not "not in the index", it is the absence of the filter. Membership as of the last quarterly index refresh: a company the refreshed list no longer names is removed then, so say "in the NASDAQ-100 as of the last quarterly refresh". | |
| max_pb_ratio | No | Ceiling on price/book. | |
| max_pe_ratio | No | Ceiling on P/E (trailing, or latest fiscal year where pe_ratio_note says so). | |
| min_pb_ratio | No | Floor on price/book for "premium-valued" queries. | |
| min_pe_ratio | No | Floor on P/E (trailing, or latest fiscal year where pe_ratio_note says so) for "expensive / high-multiple" queries. | |
| max_peg_ratio | No | CEILING on PEG ratio: only companies at or BELOW this value. Send it WITH min_peg_ratio for a two-sided range — "PEG ratio between X and Y" is ONE call with min_peg_ratio=X and max_peg_ratio=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_peg_ratio | No | FLOOR on PEG ratio. THIS IS THE KEY FOR A PEG THRESHOLD: "PEG below 1" is max_peg_ratio=1 and "PEG above 2" is min_peg_ratio=2. The figure is OUR derived PEG — trailing P/E divided by the compound annual growth rate of diluted EPS over up to three fiscal years; each row names its span in peg_eps_span and is dated by its price date — not a forward-estimate PEG from a data vendor, and it exists only where the span's end years are positive and the growth is a trend, not a one-off. Companies we cannot derive one for are excluded (null-safe), which is most of the catalog: pair it with a ranking only when the question is about the PEG itself. Companies missing the metric are excluded (null-safe). | |
| pays_dividend | No | true = only companies flagged as paying a dividend. | |
| cluster_buying | No | SPEC BF.2: true = only companies with an OPEN-MARKET insider CLUSTER buy — at least 3 DISTINCT insiders each with a SEC Form 4 code-P purchase of the same stock within a rolling 30-day window (scanned over the trailing ~year). Stricter than insider_buying (one buyer). get_company_profile on a result returns the dated insider_cluster_buying window + filings. Clustered open-market buying is disclosed Form 4 activity, NOT a buy recommendation. | |
| in_russell1000 | No | SPEC HJ.3: true = only companies flagged as constituents of the Russell 1000. Send true or omit — false is not "not in the index", it is the absence of the filter. Membership as of the last quarterly index refresh: a company the refreshed list no longer names is removed then, so say "in the Russell 1000 as of the last quarterly refresh". | |
| in_russell2000 | No | SPEC HJ.3: true = only companies flagged as constituents of the Russell 2000. Send true or omit — false is not "not in the index", it is the absence of the filter. Membership as of the last quarterly index refresh: a company the refreshed list no longer names is removed then, so say "in the Russell 2000 as of the last quarterly refresh". | |
| insider_buying | No | SPEC Y: true = only companies with at least one OPEN-MARKET insider PURCHASE (SEC Form 4 code P) in the trailing ~90 days. Use for "recent insider buying / insiders buying" queries. Excludes option exercises, awards/vesting, gifts and tax withholding (compensation, not conviction). Call get_company_profile on a result for the dated insider_activity to cite. Open-market buying is NOT itself a buy recommendation. | |
| max_fcf_margin | No | CEILING on free-cash-flow margin (PERCENT): only companies at or BELOW this value. Send it WITH min_fcf_margin for a two-sided range — "free-cash-flow margin between X and Y" is ONE call with min_fcf_margin=X and max_fcf_margin=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| max_market_cap | No | Ceiling on market cap in USD (e.g. 2000000000 for "small-cap" <= $2B). Pair with min_market_cap for a band. Null-safe (missing cap excluded). | |
| max_net_margin | No | CEILING on net profit margin (PERCENT): only companies at or BELOW this value. Send it WITH min_net_margin for a two-sided range — "net profit margin between X and Y" is ONE call with min_net_margin=X and max_net_margin=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_fcf_margin | No | FLOOR on free-cash-flow margin (PERCENT). "free cash flow margin above 15%" is min_fcf_margin=15. This is the RATIO; for a threshold in DOLLARS use min_free_cash_flow_absolute. Companies missing the metric are excluded (null-safe). | |
| min_market_cap | No | Floor on market cap in USD (e.g. 10000000000 for $10B+). | |
| min_net_margin | No | FLOOR on net profit margin (PERCENT). "net margin above 20%" is min_net_margin=20. Accepts a negative floor. Companies missing the metric are excluded (null-safe). | |
| theme_category | No | SPEC AG.3: restrict to companies STRUCTURALLY classified into this fixed taxonomy category (enrichment-time purity classification, not free-text matching). Use whenever the user asks for companies IN one of these categories — e.g. "defense manufacturers" -> theme_category=defense — so a diversified company with only incidental exposure cannot outrank the real category members. Combine with min_purity (default: significant). Results carry purity_classifications ({category, tier, confidence}) to cite. Classification coverage may be incomplete: if a theme_category search returns zero/few results, RETRY without it (plain query text) rather than concluding no companies exist. | |
| congress_buying | No | SPEC AP: true = only companies with at least one disclosed U.S. House STOCK-Act (PTR) PURCHASE in the trailing ~90 days (override with congress_window_days). Disclosures lag the trade by up to 45 days and are NOT a buy signal. | |
| held_by_manager | No | SPEC BF.6: restrict to companies for which an investment manager whose NAME contains this substring reported an SEC Form 13F-HR holding (e.g. held_by_manager="BlackRock", "Berkshire", "Vanguard"). Case-insensitive substring match against the reported 13F filer name. Quarter-END holdings that lag by up to ~45 days and are NOT a buy signal; get_company_profile on a result returns the dated institutional_ownership evidence. A company no covered manager reported is excluded (absence is "not reported by a covered manager", not "not held"). | |
| insider_selling | No | SPEC Y: true = only companies with at least one OPEN-MARKET insider SALE (SEC Form 4 code S) in the trailing ~90 days. Sales may be planned / non-discretionary (Rule 10b5-1) — never present as a bearish signal. | |
| composite_screen | No | SPEC EJ.7: run ONE named screen whose selection combines several sources, and which stocks-llm.com also publishes as a page — the same set in the same order. Do not approximate one from a single filter: ranking by short interest alone is not the squeeze screen and returns different companies. • short_squeeze_candidates — short squeeze candidates: the three conditions a short squeeze needs before it is even possible, all at once: a large share of shares outstanding sold short, enough days of average volume for those shorts to buy back that the exit is narrow, and a 14-day RSI showing the price has been rising against them. Every row carries all three figures plus the FINRA settlement date and the RSI date. These are CANDIDATES, never a prediction: most heavily shorted stocks never squeeze, and a short can be a hedge rather than a bet against the company. Companies whose share count could not be established are excluded entirely — an abstention, not a low reading. Ranked most heavily shorted first (percent of shares outstanding). • earnings_beat_and_dropped — companies that beat earnings and dropped anyway: companies whose most recent quarter came in ABOVE the analyst estimate and whose shares still fell materially anyway, measured as the two-session move spanning the report date. A beat followed by a fall happens to nearly half of all beats, so the screen requires a material drop rather than any drop. Rows carry the surprise percent, the reaction percent and the report date the reaction is anchored to. A quarter whose SEC filing we do not hold has no report date and is left out rather than guessed at. Ranked biggest fall first. • earnings_gap_up — the biggest earnings gap-ups: companies whose shares rose sharply across the two-session move spanning the report date — roughly the largest one in ten reactions in the catalog. Rows carry the surprise percent (which may be ABSENT: a stock can gap up on guidance rather than on the quarter, and a missing surprise is not a zero), the reaction percent and the report date it is anchored to. Ranked biggest rise first. Rows carry the figures the selection rests on with their as-of dates. The screen supplies its own ranking, so `sort` is ignored with it; `query`, `sector` and the other filters narrow WITHIN the screen. | |
| congress_selling | No | SPEC AP: true = only companies with at least one disclosed U.S. House STOCK-Act (PTR) SALE in the trailing ~90 days. Sales may be planned / non-discretionary — never a bearish signal. | |
| max_gross_margin | No | CEILING on gross margin (PERCENT): only companies at or BELOW this value. Send it WITH min_gross_margin for a two-sided range — "gross margin between X and Y" is ONE call with min_gross_margin=X and max_gross_margin=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_gross_margin | No | FLOOR on gross margin (PERCENT). "gross margin above 60%" is min_gross_margin=60. Companies missing the metric are excluded (null-safe). | |
| below_price_target | No | true = only companies whose MEAN ANALYST PRICE TARGET is above the last close ("trading below their analyst price target"). Rows carry price_target_mean + price_target_as_of; always give the target its as-of date. NOT a valuation signal: sell-side targets sit above price for 88% of the companies with a target (measured 2026-07-30), so this filter narrows very little. Companies with no analyst coverage are excluded (absence is "no covered target", not "at or above target"). | |
| max_debt_to_equity | No | Ceiling on debt-to-equity. Each row states its own basis: filed borrowings (leases excluded) / equity at a dated balance sheet where we derived it, else the market-data vendor figure with its date. No figure = excluded. | |
| max_dividend_yield | No | CEILING on indicated dividend yield (PERCENT): only companies at or BELOW this value. Send it WITH min_dividend_yield for a two-sided range — "indicated dividend yield between X and Y" is ONE call with min_dividend_yield=X and max_dividend_yield=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_debt_to_equity | No | Floor on debt-to-equity (same definition) for "most leveraged" queries. | |
| min_dividend_yield | No | FLOOR on indicated dividend yield (PERCENT). THIS IS THE KEY FOR A YIELD THRESHOLD: "3% or more dividend" is min_dividend_yield=3, not 0.03, and not sort=dividend_yield (a ranking answers "the highest", which is a different question from "at least 3%"). Companies missing the metric are excluded (null-safe). | |
| insider_window_days | No | Trailing window in days for insider_buying / insider_selling (default 90, 1..365). Only affects those two filters. | |
| max_price_return_1y | No | CEILING on 1-year price return (PERCENT): only companies at or BELOW this value. Send it WITH min_price_return_1y for a two-sided range — "1-year price return between X and Y" is ONE call with min_price_return_1y=X and max_price_return_1y=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| max_revenue_cagr_3y | No | CEILING on 3-year revenue CAGR (PERCENT): only companies at or BELOW this value. Send it WITH min_revenue_cagr_3y for a two-sided range — "3-year revenue CAGR between X and Y" is ONE call with min_revenue_cagr_3y=X and max_revenue_cagr_3y=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_dividend_streak | No | Floor on dividend_streak_years — consecutive recent fiscal years with a paid, non-decreasing per-share dividend (from SEC XBRL; a FLOOR, not the full history). | |
| min_price_return_1y | No | FLOOR on 1-year price return (PERCENT). THIS IS THE KEY FOR A SHARE-PRICE THRESHOLD over the trailing year: "stocks up more than 10%" is min_price_return_1y=10. Do NOT reach for a revenue or earnings filter for a question about the SHARE PRICE. For a multi-year run ("up 10% in each of the last 3 years") this single-period floor is the wrong shape — use the multi-period streak condition instead. Companies missing the metric are excluded (null-safe). | |
| min_revenue_cagr_3y | No | FLOOR on 3-year revenue CAGR (PERCENT). "revenue compounding at 20%+ over three years" is min_revenue_cagr_3y=20. This is the 3-year CAGR, a different figure from min_revenue_growth_yoy (this year alone). Companies missing the metric are excluded (null-safe). | |
| congress_window_days | No | Trailing window in days for congress_buying / congress_selling (default 90, 1..365). The congress_* SORTS use their own fixed 90/180-day windows. | |
| max_operating_margin | No | CEILING on operating margin (PERCENT): only companies at or BELOW this value. Send it WITH min_operating_margin for a two-sided range — "operating margin between X and Y" is ONE call with min_operating_margin=X and max_operating_margin=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_operating_margin | No | FLOOR on operating margin (PERCENT). "operating margin over 30%" is min_operating_margin=30. Companies missing the metric are excluded (null-safe). | |
| filing_change_section | No | SPEC BF.7: optional scope for has_recent_filing_change — "risk_factors" for new risk disclosures, "mdna" for MD&A changes. Omit to match either section. | |
| max_price_target_mean | No | CEILING on mean analyst price target (in USD): only companies at or BELOW this value. Send it WITH min_price_target_mean for a two-sided range — "mean analyst price target between X and Y" is ONE call with min_price_target_mean=X and max_price_target_mean=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_price_target_mean | No | FLOOR on mean analyst price target (in USD). A floor on the mean analyst target in dollars per share. For "trading BELOW its target" use below_price_target, which compares the target to the price — this key only bounds the target itself. Companies missing the metric are excluded (null-safe). | |
| min_revenue_growth_yoy | No | FLOOR on year-over-year revenue growth PERCENT ("triple digit growth" = 100). Use this rather than putting the threshold in `query`: a text search matches whichever companies use the words, not every company that meets the cut. Null-safe (missing or withheld growth excluded). | |
| max_operating_cash_flow | No | CEILING on operating cash flow (absolute dollars, latest fiscal year): only companies at or BELOW this value. Send it WITH min_operating_cash_flow for a two-sided range — "operating cash flow (absolute dollars, latest fiscal year) between X and Y" is ONE call with min_operating_cash_flow=X and max_operating_cash_flow=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_operating_cash_flow | No | FLOOR on operating cash flow (absolute dollars, latest fiscal year). "over $500M of operating cash flow" is min_operating_cash_flow=500000000. Companies missing the metric are excluded (null-safe). | |
| has_recent_filing_change | No | SPEC BF.7: true = only companies with a successfully-generated, source-cited summary of CHANGES between their two most recent comparable SEC filings (10-K/10-Q). Pair with filing_change_section. get_company_profile on a result returns the dated, filing-linked diff. A filing change is disclosure evidence, NOT a buy/sell signal. | |
| max_free_cash_flow_absolute | No | CEILING on free cash flow (absolute dollars, latest fiscal year): only companies at or BELOW this value. Send it WITH min_free_cash_flow_absolute for a two-sided range — "free cash flow (absolute dollars, latest fiscal year) between X and Y" is ONE call with min_free_cash_flow_absolute=X and max_free_cash_flow_absolute=Y, never a floor alone described as a range. Companies missing the metric are excluded (null-safe). | |
| min_free_cash_flow_absolute | No | FLOOR on free cash flow (absolute dollars, latest fiscal year). "more than $1B of free cash flow" is min_free_cash_flow_absolute=1000000000. DOLLARS, not a margin. Companies missing the metric are excluded (null-safe). | |
| min_short_interest_pct_outstanding | No | SPEC EI.3: minimum reported FINRA short interest as a PERCENT OF SHARES OUTSTANDING at the latest settlement date (send 30 for "over 30% short interest", NOT 0.30). Percent of shares OUTSTANDING, not percent of FLOAT — float is smaller, so percent of float would be HIGHER; the FINRA source has no float denominator, so this is a floor and must never be restated as "short float". A company whose share count could not be resolved is EXCLUDED (an abstention, not low short interest). |