Server definition
- Hash
- sha256:73f692527ecb28e936b8d1cf12d216309411d1eeda75be5fdeebca568bde79d4
- What it is
- What a remote MCP server returned when asked what it offers: 3 tools
The blob, as servednamed by its sha256
{
"instructions": "stocks-llm: natural-language discovery over 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. Call search_companies with a theme, get_company_profile for one ticker, or compare_companies for two. Every result is real, dated and cited; this is informational only, NOT financial advice.",
"tools": [
{
"description": "Head-to-head comparison of TWO companies (mirrors the /compare/{a}-vs-{b} page): the same real, dated side-by-side metrics — price, market cap, P/E, PEG, margins, ROE/ROA, debt/equity, revenue growth, dividend yield + streak, beta, 1-year return — plus each company's one-line pitch. A metric absent for either company is returned as null (never fabricated). Both tickers must be in the covered universe: 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.",
"inputSchema": {
"properties": {
"ticker_a": {
"description": "First ticker, e.g. AAPL.",
"type": "string"
},
"ticker_b": {
"description": "Second ticker, e.g. MSFT.",
"type": "string"
}
},
"required": [
"ticker_a",
"ticker_b"
],
"type": "object"
},
"name": "compare_companies",
"outputSchema": null
},
{
"description": "Full enriched profile for ONE company (mirrors the /company/{ticker} page): name, ticker, sector, the LLM business summary + one-line pitch, key fundamentals (price + as-of date, market cap, margins, ROE/ROA, valuation), dividend facts, competitors, plus its latest SEC filings — the DATED evidence you cite. May also include `insider_cluster_buying`: a dated open-market cluster-buy DISCLOSURE fact (≥3 distinct insiders each buying, SEC code P, within a 30-day window; disclosed Form 4 activity, not a prediction or buy signal; only when one qualifies). May also include `sector_percentiles`: where the company's metrics (P/E, margins, ROE, growth, yield, absolute FCF) sit relative to covered peers in the same sector, each with a summary + peer count + as-of date (a relative position, not a valuation/quality judgment; only when rankable). May also include `long_term_picture`: business quality, price vs fundamentals, long-run trend and cash returned as x/10 from the published Top 10 pillars, with a summary sentence (a published formula, not advice). May also include `valuation_context`: today's P/E, P/S, P/FCF against the company's own fiscal-year range and a reverse DCF's implied free-cash-flow growth (a simple model, not a price target). May also include `dividend_safety`: a single-fiscal-year dividend-coverage assessment from SEC XBRL (earnings + free-cash-flow payout ratios; outcome supported/stretched/not_assessable/stale_dividend_data; past coverage, not a forecast; only when the company paid a dividend). `stale_dividend_data` means the latest fiscal year with a reported dividend payment is OLDER than the latest year of reported accounts (`latest_financials_fiscal_year`), so no ratio is given — do not infer from it that the dividend was cut, nor that the data is missing. May also include `filing_changes`: an AI-assisted, source-bounded comparison of the two most-recent same-form SEC filings (Risk Factors / MD&A additions, removals, wording changes) with each side's filed date + SEC url — a source comparison, not a materiality/legal/investment conclusion; only when a cached diff exists. May also include `institutional_ownership`: dated SEC Form 13F-HR holdings — the count of distinct investment managers reporting this security at the latest quarter-end plus a derived between-quarters position-change count (quarter-end snapshots filed within 45 days, not real-time; a reported holdings change, never a same-day trade; only when 13F data exists). May also include `short_interest`: reported FINRA equity short interest (shares) as of the latest settlement date, with the source-reported change + days-to-cover (delayed, bi-monthly; not real-time, not a percent of float, not a squeeze signal; only when short-interest data exists). May also include `signal_agreement`: how many standard chart readings are currently in a bullish vs bearish state for this company — `bullish.count` / `bearish.count` with the member signals as { key, note }, `neutral`, and `computable`, the number of signals we could actually compute for it. ALWAYS cite the count against `computable` (\"6 of 9\"): a company with a short price history has no 200-day average and is scored out of fewer signals, so a bare count is not comparable across companies. Describes past price behaviour only — never a buy/sell signal (only when computable signals exist). May also include `next_earnings_date` — which never travels alone: `next_earnings_is_estimate` says what KIND of date it is (1 = the data source's own ESTIMATE, 0 = a confirmed/announced date, null = unknown), and `next_earnings_as_of` says when it was last refreshed. State the kind whenever you cite the date — an estimated date is \"expected around\", never \"reports on\". Dates are refreshed in rotation, so a date at or before its `next_earnings_as_of` stamp may have moved since we read it; treat it as the date we hold rather than as settled. `next_earnings_date` is always today or later: a date that has already passed is withheld. `next_earnings_status` says which case you are in — \"upcoming\" means we hold a forward date; \"passed\" means our calendar's last expected date has gone by, and that date is carried in `last_expected_earnings_date` for context only. Never present `last_expected_earnings_date` as upcoming, and never read it as confirmation that the company reported — only `last_earnings` below is a filed fact. May also include `last_earnings` — the OPPOSITE KIND of date: the day the company filed its earnings announcement with the SEC (Form 8-K, Item 2.02). It is BACKWARD-looking and is a FILED FACT, never an estimate, so never present it as upcoming and never mix it with `next_earnings_date` without saying which is which. When its `stale` flag is true the announcement is over two quarters old — call it the most recent one IN OUR DATA rather than implying the company reported recently. When `date` is null, `reason` says why and the difference matters: `foreign_private_issuer` means the company reports on Form 6-K, which carries no earnings item code, so we hold no confirmed date — a coverage boundary, NOT a claim that it has not reported. Never substitute another filing or date for a missing one. Identify by ticker (preferred) or name. Returns an error object if the company is NOT in the covered universe. Universe: 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.",
"inputSchema": {
"properties": {
"name": {
"description": "Company name (used if ticker is unknown).",
"type": "string"
},
"ticker": {
"description": "Ticker, e.g. NVDA (preferred).",
"type": "string"
}
},
"type": "object"
},
"name": "get_company_profile",
"outputSchema": null
},
{
"description": "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.",
"inputSchema": {
"properties": {
"below_price_target": {
"description": "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\").",
"type": "boolean"
},
"cluster_buying": {
"description": "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.",
"type": "boolean"
},
"composite_screen": {
"description": "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.\n• 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).\n• 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.\n• 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.\nRows 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.",
"enum": [
"short_squeeze_candidates",
"earnings_beat_and_dropped",
"earnings_gap_up"
],
"type": "string"
},
"congress_buying": {
"description": "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.",
"type": "boolean"
},
"congress_selling": {
"description": "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.",
"type": "boolean"
},
"congress_window_days": {
"description": "Trailing window in days for congress_buying / congress_selling (default 90, 1..365). The congress_* SORTS use their own fixed 90/180-day windows.",
"type": "integer"
},
"dir": {
"description": "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.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"filing_change_section": {
"description": "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.",
"enum": [
"risk_factors",
"mdna"
],
"type": "string"
},
"has_recent_filing_change": {
"description": "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.",
"type": "boolean"
},
"held_by_manager": {
"description": "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\").",
"type": "string"
},
"in_djia": {
"description": "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\".",
"type": "boolean"
},
"in_nasdaq100": {
"description": "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\".",
"type": "boolean"
},
"in_russell1000": {
"description": "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\".",
"type": "boolean"
},
"in_russell2000": {
"description": "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\".",
"type": "boolean"
},
"in_sp500": {
"description": "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\".",
"type": "boolean"
},
"insider_buying": {
"description": "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.",
"type": "boolean"
},
"insider_selling": {
"description": "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.",
"type": "boolean"
},
"insider_window_days": {
"description": "Trailing window in days for insider_buying / insider_selling (default 90, 1..365). Only affects those two filters.",
"type": "integer"
},
"limit": {
"description": "Max results (default 10, hard cap 50).",
"type": "integer"
},
"market": {
"description": "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.",
"enum": [
"US",
"UK"
],
"type": "string"
},
"max_debt_to_equity": {
"description": "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.",
"type": "number"
},
"max_dividend_yield": {
"description": "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).",
"type": "number"
},
"max_fcf_margin": {
"description": "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).",
"type": "number"
},
"max_free_cash_flow_absolute": {
"description": "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).",
"type": "number"
},
"max_gross_margin": {
"description": "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).",
"type": "number"
},
"max_market_cap": {
"description": "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).",
"type": "number"
},
"max_net_margin": {
"description": "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).",
"type": "number"
},
"max_operating_cash_flow": {
"description": "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).",
"type": "number"
},
"max_operating_margin": {
"description": "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).",
"type": "number"
},
"max_pb_ratio": {
"description": "Ceiling on price/book.",
"type": "number"
},
"max_pe_ratio": {
"description": "Ceiling on P/E (trailing, or latest fiscal year where pe_ratio_note says so).",
"type": "number"
},
"max_peg_ratio": {
"description": "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).",
"type": "number"
},
"max_price_return_1y": {
"description": "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).",
"type": "number"
},
"max_price_target_mean": {
"description": "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).",
"type": "number"
},
"max_revenue_cagr_3y": {
"description": "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).",
"type": "number"
},
"max_roa": {
"description": "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).",
"type": "number"
},
"min_debt_to_equity": {
"description": "Floor on debt-to-equity (same definition) for \"most leveraged\" queries.",
"type": "number"
},
"min_dividend_streak": {
"description": "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).",
"type": "number"
},
"min_dividend_yield": {
"description": "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).",
"type": "number"
},
"min_fcf_margin": {
"description": "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).",
"type": "number"
},
"min_free_cash_flow_absolute": {
"description": "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).",
"type": "number"
},
"min_gross_margin": {
"description": "FLOOR on gross margin (PERCENT). \"gross margin above 60%\" is min_gross_margin=60. Companies missing the metric are excluded (null-safe).",
"type": "number"
},
"min_market_cap": {
"description": "Floor on market cap in USD (e.g. 10000000000 for $10B+).",
"type": "number"
},
"min_net_margin": {
"description": "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).",
"type": "number"
},
"min_operating_cash_flow": {
"description": "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).",
"type": "number"
},
"min_operating_margin": {
"description": "FLOOR on operating margin (PERCENT). \"operating margin over 30%\" is min_operating_margin=30. Companies missing the metric are excluded (null-safe).",
"type": "number"
},
"min_pb_ratio": {
"description": "Floor on price/book for \"premium-valued\" queries.",
"type": "number"
},
"min_pe_ratio": {
"description": "Floor on P/E (trailing, or latest fiscal year where pe_ratio_note says so) for \"expensive / high-multiple\" queries.",
"type": "number"
},
"min_peg_ratio": {
"description": "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).",
"type": "number"
},
"min_price_return_1y": {
"description": "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).",
"type": "number"
},
"min_price_target_mean": {
"description": "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).",
"type": "number"
},
"min_purity": {
"description": "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.",
"enum": [
"pure_play",
"significant",
"adjacent",
"incidental"
],
"type": "string"
},
"min_revenue_cagr_3y": {
"description": "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).",
"type": "number"
},
"min_revenue_growth_yoy": {
"description": "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).",
"type": "number"
},
"min_roa": {
"description": "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).",
"type": "number"
},
"min_roe": {
"description": "Floor on return-on-equity PERCENT (e.g. 15).",
"type": "number"
},
"min_roic": {
"description": "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.",
"type": "number"
},
"min_short_interest_pct_outstanding": {
"description": "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).",
"type": "number"
},
"pays_dividend": {
"description": "true = only companies flagged as paying a dividend.",
"type": "boolean"
},
"profitable": {
"description": "true = only companies with a positive net margin.",
"type": "boolean"
},
"query": {
"description": "The theme / what the company does, in plain words (e.g. \"cloud infrastructure\", \"silicon carbide power devices\").",
"type": "string"
},
"sector": {
"description": "Restrict to one exact GICS sector.",
"type": "string"
},
"sort": {
"description": "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.",
"type": "string"
},
"theme_category": {
"description": "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.",
"enum": [
"defense",
"ai_infrastructure",
"cybersecurity",
"quantum_computing",
"renewable_energy",
"domestic_manufacturing"
],
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "search_companies",
"outputSchema": null
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:73f692527ecb28e936b8d1cf12d216309411d1eeda75be5fdeebca568bde79d4 | sha256sum