Skip to main content
Glama

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

NameRequiredDescriptionDefault
dirNoSPEC 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.
sortNoHow 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.
limitNoMax results (default 10, hard cap 50).
queryYesThe theme / what the company does, in plain words (e.g. "cloud infrastructure", "silicon carbide power devices").
marketNoScope 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.
sectorNoRestrict to one exact GICS sector.
in_djiaNoSPEC 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_roaNoCEILING 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_roaNoFLOOR 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_roeNoFloor on return-on-equity PERCENT (e.g. 15).
in_sp500NoSPEC 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_roicNoFloor 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_purityNoMinimum 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.
profitableNotrue = only companies with a positive net margin.
in_nasdaq100NoSPEC 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_ratioNoCeiling on price/book.
max_pe_ratioNoCeiling on P/E (trailing, or latest fiscal year where pe_ratio_note says so).
min_pb_ratioNoFloor on price/book for "premium-valued" queries.
min_pe_ratioNoFloor on P/E (trailing, or latest fiscal year where pe_ratio_note says so) for "expensive / high-multiple" queries.
max_peg_ratioNoCEILING 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_ratioNoFLOOR 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_dividendNotrue = only companies flagged as paying a dividend.
cluster_buyingNoSPEC 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_russell1000NoSPEC 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_russell2000NoSPEC 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_buyingNoSPEC 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_marginNoCEILING 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_capNoCeiling 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_marginNoCEILING 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_marginNoFLOOR 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_capNoFloor on market cap in USD (e.g. 10000000000 for $10B+).
min_net_marginNoFLOOR 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_categoryNoSPEC 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_buyingNoSPEC 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_managerNoSPEC 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_sellingNoSPEC 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_screenNoSPEC 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_sellingNoSPEC 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_marginNoCEILING 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_marginNoFLOOR on gross margin (PERCENT). "gross margin above 60%" is min_gross_margin=60. Companies missing the metric are excluded (null-safe).
below_price_targetNotrue = 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_equityNoCeiling 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_yieldNoCEILING 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_equityNoFloor on debt-to-equity (same definition) for "most leveraged" queries.
min_dividend_yieldNoFLOOR 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_daysNoTrailing window in days for insider_buying / insider_selling (default 90, 1..365). Only affects those two filters.
max_price_return_1yNoCEILING 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_3yNoCEILING 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_streakNoFloor 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_1yNoFLOOR 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_3yNoFLOOR 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_daysNoTrailing 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_marginNoCEILING 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_marginNoFLOOR on operating margin (PERCENT). "operating margin over 30%" is min_operating_margin=30. Companies missing the metric are excluded (null-safe).
filing_change_sectionNoSPEC 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_meanNoCEILING 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_meanNoFLOOR 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_yoyNoFLOOR 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_flowNoCEILING 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_flowNoFLOOR 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_changeNoSPEC 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_absoluteNoCEILING 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_absoluteNoFLOOR 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_outstandingNoSPEC 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).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does well: it discloses the company universe, data sources, dated figures, theme-matching mechanism, and an informational-only disclaimer. It does not cover operational traits such as authentication, rate limits, pagination, or empty-result behavior, but those are less central for this read-oriented search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then adds coverage, data provenance, return fields, and usage guidance in a logical single paragraph. The long enumeration of index memberships is dense, but it is relevant to scope and not gratuitous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 64-parameter tool with no output schema, the description gives substantial context: coverage, data sources, thematic matching, return metrics, sorting/filtering guidance, and a disclaimer. It is complete enough to support selection and invocation, though it leaves sibling differentiation and some output details to the schema and surrounding context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage across all 64 parameters, so the schema already supplies detailed semantics. The description only briefly says to use `sort` for ranking and filters for narrowing, adding little parameter-specific meaning beyond the schema, which matches the baseline of 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: natural-language/thematic search over a knowledge base of US and UK public companies. It clearly describes the scope and matching approach, but it does not name or differentiate from sibling tools like compare_companies or get_company_profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives some usage guidance by explaining that `sort` ranks the matched set and filters narrow it, and it provides thematic query examples. However, it does not explicitly say when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources