Search for US public companies by name, ticker symbol, CIK (SEC identifier), or SIC industry code. Returns ticker, company name, sector, industry, exchange, and current S&P 500 membership status. Use this tool to resolve a company name to ticker/CIK before calling `get_company_fundamentals`, `get_valuation_metrics`, or other tools that require a ticker — they do not fuzzy-match company names.
**Use this tool — NOT `get_pit_universe` — when the user asks about CURRENT S&P 500 members.** To list current S&P 500 members, call `search_companies({ is_sp500: true })` (the `is_sp500` filter is itself a valid search parameter, so no other input is required). This returns the live snapshot as of query time. Example: "List 5 current S&P 500 members" → call `search_companies({ is_sp500: true, limit: 5 })`.
**Use `get_pit_universe` ONLY when the user explicitly needs a survivorship-free historical universe as of a specific past date** (e.g. "S&P 500 members as of March 2018"). If the user says "current," "today," "now," or gives no date, use `search_companies` instead.
**Data details:** `sic_code` is the 4-digit SIC; `industry` is the human-readable label. `sector` is SIC-derived with GICS-style labels — NOT licensed GICS, so industrial conglomerates may map differently from official GICS (e.g. 3M → 'Health Care' by SIC vs Industrials by GICS). S&P 500 membership is sourced from index_membership.parquet (current SP500 = `index_name='SP500' AND removal_date IS NULL`). Available on all plans.
Parameters (6)
querystring
Free-text search over company name and ticker. Case-insensitive. E.g. 'Apple', 'AAPL', 'Microsoft', 'semiconductor'.
cikstring
SEC CIK identifier (exact match). E.g. '0000320193' for Apple.
sic_codestring
4-digit SIC industry code. E.g. '7372' for Prepackaged Software.
is_activeboolean
Filter to active (currently trading) companies only.
is_sp500boolean
Filter to current S&P 500 members only.
limitinteger
Maximum number of results to return (1–50). Defaults to 25.
get_company_fundamentals
Retrieve standardized SEC EDGAR fundamental financial metrics for a US public company. Returns revenue, gross profit, operating income, net income, EPS (diluted), total assets, total liabilities, stockholders' equity, cash & equivalents, total debt, operating cash flow, and capital expenditures for one or more fiscal periods. Data sourced from 10-K (annual) and 10-Q (quarterly) filings. Point-in-time: no look-ahead bias — pass `as_of_date` (YYYY-MM-DD) to reconstruct exactly the information set known on that date. This returns the raw as-reported line items; for pipeline-computed ratios (margins, ROE, ROIC, leverage, per-share) use `get_financial_ratios`, and for margins combined with DCF/DDM model inputs use `get_valuation_metrics` — both derive from the figures this tool returns.
Parameters (8)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT, BRK.B
fiscal_yearinteger
Fiscal year (YYYY). Omit to return the most recent available years.
periodstring
Filing period granularity. Annual uses 10-K; quarterly uses 10-Q.
as_of_datestring
Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias for backtesting. Omit for the full dataset.
limitinteger
Maximum number of periods to return (1–40). Defaults to 5.
strictboolean
When true, fail with PLAN_LIMIT_EXCEEDED if the plan cannot satisfy the requested limit. Default false: return what's available and explain the gap in _meta.truncation.
Output shape. 'flat' (default) returns the legacy `metrics` object plus the additive `metrics_availability`/`metrics_provenance` sidecars. 'envelope' additionally attaches `metric_envelopes` — one canonical {metric,value,unit,scale,period,availability,provenance} object per metric.
get_valuation_metrics
Get comprehensive valuation and profitability metrics for a US public company. Returns per-period data combining computed ratios (gross_margin, operating_margin, net_margin, ROE, ROA, ROIC, debt_to_equity, FCF, FCF margin) with optional pre-computed DCF model inputs (WACC, fcf_base_per_share, stage1_growth_rate, terminal_growth_rate, dcf_value_per_share, ddm_value_per_share). Profitability + cash flow + leverage fields are sourced from fact.parquet (PIT-safe via accepted_at). DCF/DDM fields are sourced from valuation.parquet (pipeline-computed; recomputed each pipeline run, so NOT strictly PIT-safe). DCF/DDM fields are commonly null — for newer tickers, transition periods, or before the valuation pipeline has run. Each null carries a `null_reasons[field]` entry with one of: VALUATION_NOT_COMPUTED, INPUT_MISSING, INPUT_NEGATIVE, PIPELINE_PENDING. ALWAYS check `null_reasons` before assuming a field is zero — null != 0. For agents needing strict PIT DCF reasoning, use the SDK or compute DCF inputs from `get_company_fundamentals` directly. Use this *instead of* `get_financial_ratios` when DCF/intrinsic value matters; use `get_financial_ratios` when you only need the ratio table without DCF wiring. Available on all plans.
Parameters (5)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT
fiscal_yearinteger
Fiscal year (YYYY). Omit to return most recent periods.
periodstring
Filing period granularity. Annual uses 10-K; quarterly uses 10-Q.
as_of_datestring
Point-in-time date (YYYY-MM-DD). Only returns data with accepted_at on or before this date. Eliminates look-ahead bias for backtesting.
limitinteger
Maximum number of periods to return (1–40). Defaults to 5.
get_financial_ratios
Get pipeline-computed financial ratios from ratio.parquet. Served categories: profitability (margins, ROE, ROA, ROIC), liquidity (current ratio, quick ratio), leverage (D/E, interest coverage, net debt/EBITDA), efficiency (asset turnover, inventory days), per_share (EPS, BVPS, FCF/share), owner_earnings (Buffett FCF, owner yield), and the pipeline-emitted forensic, growth, and rank (cross-sectional *_sector_pctile) categories. NOT every category exists for every ticker — the exact set is data-driven; omit `categories` to get whatever this ticker has, or read the `available_categories` list returned in the CATEGORY_NOT_AVAILABLE envelope. valuation (EV/EBITDA, P/E, P/FCF) is DECLARED BUT NOT YET POPULATED for any ticker (price feed pending) — requesting it returns a CATEGORY_NOT_AVAILABLE envelope, never data. Includes TTM (trailing twelve months) rows alongside annual periods. Each row carries `is_calendar_aligned` (boolean) — TRUE when period_end is actually on the entity's fiscal year boundary (±7 days), FALSE when the pipeline emitted a calendar-quarter row tagged fiscal_period='FY' for a non-December fiscal-year filer. Filter to `is_calendar_aligned=TRUE` if you're joining ratios with fact-table fundamentals on (entity, fiscal_year). Ratios are pipeline-derived — they're recomputed on each pipeline run with ON CONFLICT DO UPDATE. For historical cuts use `as_of_date` (the canonical cross-tool name; alias `period_end_before`). PIT semantics are data-driven: when the ratio data carries an SEC `accepted_at` timestamp, `as_of_date` filters point-in-time by accepted_at (zero look-ahead, latest-knowable per period) and `_meta.pit_safe=true`; when it does not (today's data), the cut is by ratio.period_end and `_meta.pit_safe=false`. For guaranteed accepted_at PIT regardless, use `get_company_fundamentals` (which carries fact.accepted_at). Use this *instead of* `get_valuation_metrics` when you only need ratios (no DCF wiring); use `get_valuation_metrics` when you also need DCF/DDM. Each ratio is a `{value, unit, category, reason}` entry; a response-level `lineage` (DerivedLineage) envelope marks the values pipeline-derived and points to `get_company_fundamentals` / `verify_fact_lineage` for filing-level provenance. Use the returned `value` exactly — do not recompute it; a null value carries a `reason` (e.g. INPUT_MISSING, DENOMINATOR_NEGATIVE) so missing is never confused with a real zero. Available on all plans.
Parameters (6)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT
categoriesarray
Ratio categories to include. Omit to return all categories this ticker has. Served: profitability, liquidity, leverage, efficiency, per_share, owner_earnings, forensic, growth, rank. valuation is accepted but NOT yet populated for any ticker (price feed pending) — it returns a CATEGORY_NOT_AVAILABLE envelope, not data. Availability is per-ticker; the envelope lists this ticker's available_categories.
fiscal_periodstring
Filter to a specific fiscal period type. Use 'TTM' for trailing twelve months. Omit to return both annual (FY) and TTM rows.
as_of_datestring
Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics). When the ratio data carries an SEC accepted_at timestamp, this filters point-in-time by accepted_at (returns the latest value knowable on or before the date, zero look-ahead, _meta.pit_safe=true). When it does not (current data), it filters by ratio.period_end and is not strict point-in-time (_meta.pit_safe=false). For guaranteed accepted_at-based PIT, use get_company_fundamentals.
period_end_beforestring
Alias of as_of_date — either works; as_of_date is preferred (it is the canonical name used across every time-series tool). Returns only ratios with period_end on or before this date.
limitinteger
Number of distinct period_end dates to return (1–20). Defaults to 5. Within each period, all matching ratio_names are included.
get_sec_filing_links
Get direct links to original SEC EDGAR filings for any US public company. Returns four per-filing deep links: `sec_url` (the EDGAR filing-index page listing every document), `viewer_url` (the cgi-bin Financial-Report viewer for the specific accession), `inline_viewer_url` (the SEC Inline-XBRL viewer opened on the rendered primary document — the strongest provenance link, `null` when the filing is not Inline-XBRL), and `document_url` (a direct link to the rendered primary document itself — opens the actual filing, never the index page, `null` only when primary_document is unknown). Prefer `inline_viewer_url ?? document_url ?? viewer_url ?? sec_url`. Supported form_types (enum): 10-K, 10-Q, 8-K, 20-F, 40-F, 10-K/A, 10-Q/A, 20-F/A, 40-F/A. Other forms (6-K, DEF 14A, Form 4, 13F) are NOT yet exposed by this tool — use `describe_schema` to confirm the parquet has them, then read raw via the SDK. 8-K item codes are filterable via `event_types` (e.g. ['2.02'] for earnings, ['1.01'] for material agreements, ['5.02'] for officer changes). PIT-safe — filings are filtered by accepted_at, never by report_date alone. Use this *instead of* `verify_fact_lineage` when you want a list of filings; use `verify_fact_lineage` when you want one specific fact-to-filing trace. Available on all plans.
Parameters (6)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT
form_typesarray
Filing form types to include. Defaults to 10-K and 10-Q.
start_datestring
Inclusive lower bound on filing_date (YYYY-MM-DD). E.g. '2023-01-01'.
end_datestring
Inclusive upper bound on filing_date (YYYY-MM-DD). E.g. '2023-12-31'.
event_typesarray
8-K item codes to filter by. E.g. ['1.01'] for material agreements, ['2.01'] for asset acquisitions, ['5.02'] for director/officer changes. Only relevant when form_types includes '8-K'.
limitinteger
Maximum number of filings to return (1–50). Defaults to 10.
get_capital_allocation_profile
Get a multi-year capital allocation breakdown for a US public company. Shows how management deploys cash across all six categories — capex, R&D, M&A, dividends, buybacks, and debt — plus pre-computed deployment ratios (% of operating cash flow) and over-distribution flags. Use this tool when the user asks: how does a company allocate capital, what's the buyback-vs-dividend mix, is the company over-distributing, is growth funded by R&D or M&A, what's the cash return ratio trend, or any 'where does the money go' question. Also use for owner-earnings analysis (Buffett-style) and reinvestment-rate analysis (Damodaran-style). Data sourced from annual 10-K filings (SEC EDGAR) — income statement (R&D), investing section (capex, M&A), financing section (dividends, buybacks, debt). All figures are point-in-time safe via the as_of_date parameter — no look-ahead bias. R&D semantics: R&D is included as a deployment category despite being an income-statement expense, because for knowledge-economy businesses (tech, pharma, industrials with heavy engineering) it represents the primary growth reinvestment vehicle and often dwarfs capex. R&D is already deducted before reaching operating cash flow, so `rd_pct_ocf` is INFORMATIONAL — it does not reduce OCF a second time. The `total_deployment_pct_ocf` field excludes R&D from its sum to preserve the cash-flow identity (OCF = capex + M&A + dividends + buybacks + debt repayment + change in cash). Flags object: pre-computed booleans for common analytical questions. Use `buybacks_exceed_fcf` to identify years a company returned more to shareholders via repurchases than it generated in free cash flow. Use `total_returns_exceed_fcf` for the stricter test (buybacks + dividends > FCF). Use `debt_funded_distribution` to distinguish over-distribution funded by leverage (typical industrials) from over-distribution funded by cash hoard (Apple 2018-2019 post-tax-reform repatriation). NOT yet included (separate roadmap items): `buyback_yield_implied` requires a price × shares market-cap series; equity-method investments and intangibles are excluded from `acquisitions_net` to keep M&A semantics tight (request `other_investing_outflows` if needed). Available on all plans.
Parameters (3)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT
lookback_yearsinteger
Number of fiscal years to look back from the most recent filing (1–20). Defaults to 5 years for a full capital allocation cycle.
as_of_datestring
Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias.
get_peer_comparables
Get ratio-based peer comparison for a company and its closest competitors. Peers are selected by matching 2-digit SIC industry code. Returns pipeline-computed ratios from up to 10 peers alongside the subject company for direct benchmarking. Ratio categories: profitability, liquidity, leverage, efficiency, per_share, owner_earnings, valuation. TTM (trailing twelve months) ratios are used when available for the most current view. Use as_of_date to compare peers at a specific historical date. PIT semantics for the figure leg are data-driven: when the ratio data carries an SEC accepted_at timestamp, as_of_date filters point-in-time by accepted_at (zero look-ahead, _meta.pit_safe=true); when it does not (today's data), the cut is by ratio.period_end (_meta.pit_safe=false). NOTE: peer SELECTION still uses CURRENT S&P 500 membership as a size/relevance ranking proxy regardless of as_of_date (W3-G2). Available on every plan — sample returns the subset covered by the sample bucket.
Parameters (5)
tickerstringrequired
Subject company ticker, e.g. AAPL. Peers are auto-selected by SIC code.
categoriesarray
Ratio categories to include in the comparison. Defaults to profitability, valuation, and leverage.
as_of_datestring
Historical cutoff (canonical cross-tool date param — same name as get_company_fundamentals / get_valuation_metrics) for the figure leg. When the ratio data carries an SEC accepted_at timestamp, this filters the figures point-in-time by accepted_at (latest-knowable per ratio, zero look-ahead, _meta.pit_safe=true). When it does not (current data), it filters by ratio.period_end (_meta.pit_safe=false). Peer SELECTION still uses current S&P 500 membership as a ranking proxy regardless of as_of_date (W3-G2).
period_end_beforestring
Alias of as_of_date — either works; as_of_date is preferred (canonical name used across every time-series tool). Only include ratios with period_end on or before this date.
limitinteger
Maximum number of peers to return alongside the subject company (1–10). Defaults to 5.
get_pit_universe
Use this tool to answer questions about historical index membership — e.g. "Was Company X in the S&P 500 on date Y?" or "Which companies were in the Russell 2000 on 2010-01-01?" Use this INSTEAD OF `search_companies` when the question involves a specific historical date or asks whether a company was an index member at a point in the past. `search_companies` only returns current membership snapshots and cannot answer historical membership questions.
Returns a survivorship-free universe of companies valid on a specific as_of_date: only companies that existed and were index members on that exact date — no hindsight contamination. Supports SP500, RUSSELL1000, RUSSELL2000, RUSSELL3000 via index_membership.parquet (accurate join/leave dates with [) interval semantics). To check a single company's membership, pass its ticker and the target date; if the company appears in the response it was a member, if absent it was not.
Returns per company: CIK, ticker, name, sector, industry, SIC code, plus per-row membership confidence (high/medium/low). Check `_meta.pit_safe`: true only when every matched row is high-confidence; medium/low rows downgrade it to false — treat low-confidence rows with caution for backtest use.
NOTE: `sector` is SIC-derived (GICS-aligned labels via sic_to_sector.csv), not licensed GICS — industrial conglomerates may map differently. Treat as a screening bucket, not an authoritative GICS label.
Use as the first step of a quantitative backtest before calling `get_compute_ready_stream` to pull Parquet data for the universe. Returns empty array (with error detail) if the date is out of range or the index_membership data has no coverage for that date. Available on every plan — sample tier returns the subset covered by the sample bucket.
Parameters (7)
indexstring
Index filter. 'sp500' (~500 large caps), 'russell1000' (~1000 large/mid), 'russell2000' (~2000 small caps), 'russell3000' (~3000 broad market). Omit for no index filter (sector-only or full universe queries).
sectorstring
Sector filter (case-insensitive substring match) over the SIC-derived, GICS-aligned sector label. E.g. 'Technology', 'Health Care', 'Energy'. Not licensed GICS — see tool description for caveat.
as_of_datestring
Historical date (YYYY-MM-DD) for survivorship-free universe construction. For an index: uses index_membership join/leave dates — companies that entered after this date are excluded; companies later removed are kept. For sector: uses security valid_from/valid_to. Omit for the current universe.
is_activeboolean
Filter to active (currently trading) companies only. Omit to include all. WARNING: setting this to true on a HISTORICAL query reintroduces survivorship bias — companies that were active on as_of_date but later went bankrupt or got acquired will be filtered out. Leave unset for true PIT backtests.
include_share_classesboolean
When false (default), the universe is collapsed to one row per CIK — matches how index providers count constituents (BRK is one S&P 500 member, not two for BRK-A + BRK-B). When true, every share-class row is returned (GOOG and GOOGL emit separate rows, etc.). Use only for security-level (not company-level) analysis.
as_of_basisstring
Which date column to filter on for historical universe construction. 'effective' (default) — match against effective_date / removal_date (first trading day as a member; passive index replication). 'announcement' — match against announcement_date / removal_announcement_date (the day S&P publicly announced the change; use for inclusion-arb backtests). 'announcement' rows with NULL announcement_date are silently skipped — pre-2015 changes generally lack press-release coverage.
limitinteger
Maximum number of companies to return (1–3500). Defaults to 100. Sized to fit Russell 3000 (~3000 members) plus headroom for delisted/historical members. Universe is deduped to one row per CIK by default, so set near the index size (SP500 ~505, Russell 1000 ~1010, Russell 3000 ~3050) — no need for share-class headroom.
get_compute_ready_stream
STATUS: pending — direct R2 Parquet access is in private beta (ETA 2026-Q3). Calls return 501 FEATURE_NOT_AVAILABLE today. When live: returns a pre-signed Cloudflare R2 URL for bulk Parquet access that can be piped into Python/DuckDB/Polars for high-throughput computation that exceeds the MCP context window. Datasets: fact (per-entity partition — requires ticker), ratio (all computed ratios), valuation (DCF inputs), filing (SEC filing metadata), references (company universe), index_membership (historical index composition). URL would expire in 15 minutes. TODAY use the Python SDK (`pip install valuein-sdk`) for the same data via DuckDB.
Parameters (2)
dataset_typestringrequired
Dataset to access. 'fact' requires ticker (per-entity partition). All others are full-universe tables.
tickerstring
Required when dataset_type is 'fact'. Resolves to the per-entity fact/{CIK}.parquet partition for that company.
describe_schema
Returns the Parquet schema for all tables in the Valuein SEC data warehouse. Includes table descriptions, column names, types, primary keys, and foreign-key references. Use this tool to understand the data model before querying with other tools. No data reads required — schema is embedded in the manifest. Available on all plans.
Parameters (1)
tablestring
Filter to a single table name (e.g. 'fact', 'entity', 'references'). Omit to return the full schema for all tables.
verify_fact_lineage
Use this tool when the user asks BOTH what a financial figure is AND which filing reported it — for example "What was Apple's most recently reported revenue, and which 10-Q filed it?" or "Show me the accession ID for Tesla's latest net income" or "Which filing form reported Amazon's Q3 operating cash flow?" This tool returns a single fact plus its complete filing provenance: entity, concept, period, value, accession ID, filing URL, and form type (10-K, 10-Q, etc.).
Use this INSTEAD OF `search_companies` when the user already names a company and wants a financial figure with its source filing — `search_companies` only resolves company identifiers and returns no financial data. Use this INSTEAD OF `get_company_fundamentals` when the user explicitly wants to know which filing or form type reported a number, or needs the accession ID — `get_company_fundamentals` returns metrics across multiple periods but omits filing provenance.
Two lookup modes: (1) by fact_id (SHA-256 hash of entity_id|accession_id|concept|period_end|unit) for deterministic identity; or (2) by concept name (e.g., TotalRevenue, NetIncome, EPSDiluted, TotalAssets, OperatingCashFlow) plus a ticker to retrieve the most recently reported fact. Optionally pin a point-in-time cutoff via as_of_date (YYYY-MM-DD) — returns the latest filing accepted by SEC on or before that date, eliminating look-ahead bias. Check `_meta.pit_safe` in the response to confirm PIT correctness.
DURATION: income-statement flow concepts (NetIncome, TotalRevenue, etc.) are reported over a window, and a single 10-K tags BOTH a 12-month figure and a 3-month Q4 stub at the same fiscal-year-end period_end. On a tie this tool returns the longer (headline) window, and every result carries `period_type` (instant | quarterly | half_year | nine_month | annual | duration) and `period_span_days` so you always know whether a number is a quarter or a full year — never present a 3-month stub as the annual figure.
Provide either fact_id or concept (required). Returns empty result with error_code FACT_NOT_FOUND if no matching fact exists for the given concept and ticker. Available on all plans.
Parameters (5)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT, BRK.B
fact_idstring
Deterministic fact identity hash: SHA-256(entity_id|accession_id|concept|period_end|unit). 64-char lowercase hex. Use this when you already have the hash from a previous query. Provide either fact_id OR concept (not both required, but at least one must be set).
conceptstring
Standard concept name to look up the most recently known fact for. Use this when you don't have a fact_id. Covers the full fundamentals + capital-allocation set: income statement (TotalRevenue, CostOfRevenue, GrossProfit, OperatingIncome, OperatingExpenses, ResearchAndDevelopment, NetIncome, EPSDiluted), balance sheet (TotalAssets, TotalLiabilities, StockholdersEquity, StockholdersEquityIncludingNCI, CashAndEquivalents, TotalDebt), and cash flow (OperatingCashFlow, CAPEX, Dividends, ShareBuyback, DebtIssuance, DebtRepayment, Acquisitions, Divestitures). Provide either concept OR fact_id.
period_endstring
[DEPRECATED — pass `as_of_date` instead.] Filing-acceptance cutoff (YYYY-MM-DD) used with `concept`. The name is misleading — it actually filters on filing accepted_at, not on the period_end of the returned fact (the returned fact's period_end is whatever the SEC filed, e.g. a Q3 cumulative figure). Kept for one release for backwards compat; new callers MUST use `as_of_date`.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD) used with `concept`. Returns the most recently known fact whose 10-K / 10-Q filing was accepted by SEC on or before this date — true PIT, no lookahead bias. Any calendar date works (not limited to fiscal-period closes); the latest preceding filing is returned. This is the canonical name shared by every other PIT tool in the suite; supersedes the legacy `period_end` parameter on this tool.
compare_periods
Compare a company's core financial metrics across two fiscal periods side-by-side. Shows absolute and percentage changes with significance classification (minor < 5%, notable 5–15%, significant > 15%). The response includes a `material_changes` count: this is the number of metrics whose `significance` ∈ {notable, significant} (i.e. absolute percentage change > 5%). Use it as a quick scalar to triage filings — anything > ~3 typically signals a material event worth deeper review. Use period format: 'FY2024' for annual, 'Q1-2024' for quarterly. Pass `period_a` as the EARLIER period and `period_b` as the LATER one — if you invert them the server auto-swaps and sets `swapped: true` in the response so deltas always carry the correct sign (rather than silently flipping). Point-in-time safe via as_of_date. Available on all plans.
Parameters (4)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT, BRK.B
period_astringrequired
Earlier fiscal period. Format: 'FY2023' for annual or 'Q1-2023' for quarterly.
period_bstringrequired
Later fiscal period. Format: 'FY2024' for annual or 'Q1-2024' for quarterly.
as_of_datestring
Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias for backtesting.
screen_universe
Rank companies by cross-sectional factor scores from factor_scores.parquet. Returns the underlying factors (roe, gross_margin, operating_margin, net_profit_margin, revenue_growth_yoy, fcf_to_assets, debt_to_equity, asset_turnover, current_ratio, piotroski_f_score) plus their percentile ranks (1.0 = best in universe; 0.0 = worst). `composite_rank` is a composite percentile rank across the factor set — a one-number screening shortcut. For single-factor sorts, use the specific rank column (e.g. `sort_by=roe_rank`); for a balanced multi-factor view, use `sort_by=composite_rank` (default). Two modes: full-universe (omit ticker) or single-entity (ticker set — useful for spot-checking ONE company's factor profile without scrolling the whole leaderboard). Sector filter is SIC-derived (GICS-aligned labels, not licensed GICS — see `get_pit_universe` description for the caveat). Use this *instead of* `get_financial_ratios` when you want CROSS-SECTIONAL comparison (rank vs peers); use `get_financial_ratios` when you want one company's ratios over time. Supports survivorship-free POINT-IN-TIME screening: pass `as_of_date` (YYYY-MM-DD) to reconstruct the cross-section as it was knowable on that date — factor_scores carries the SEC `accepted_at` of each period, so the screen filters to scores whose underlying filing had been accepted by the as-of date (zero look-ahead) and ranks each entity at its latest-KNOWABLE period. Omit `as_of_date` for the latest available snapshot. When supplied, the response carries `as_of_date` and `pit_safe=true`. Full-universe screens omit rows that don't join to a company (null symbol, unusable for ranking); pass `exclude_outliers=true` to additionally drop shell-company rows with implausible factor values. Available on every plan — sample returns the subset covered by the sample bucket.
Parameters (6)
tickerstring
If provided, show only this ticker's factor scores (single-entity mode). Omit to screen the full universe.
sectorstring
Filter to a specific sector (case-insensitive partial match). E.g. 'Technology', 'Healthcare'.
sort_bystring
Which factor rank to sort by. Options: roe_rank, gross_margin_rank, operating_margin_rank, net_profit_margin_rank, revenue_growth_yoy_rank, fcf_to_assets_rank, debt_to_equity_rank, asset_turnover_rank, current_ratio_rank, piotroski_f_score_rank, composite_rank. Defaults to composite_rank. An unrecognized column is rejected with INVALID_ARGUMENT (no silent fallback).
limitinteger
Number of results to return (1-100). Defaults to 25.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD). When supplied, the screen is reconstructed as of this date: factor scores are filtered to those whose underlying SEC filing had been accepted on or before the date (via factor_scores.accepted_at), and each entity is ranked at its latest-knowable period — zero look-ahead, survivorship-free. Omit for the latest available snapshot.
exclude_outliersboolean
Optional data-quality guard (default false). When true, additionally drops rows with implausible raw factor values (non-finite, or e.g. asset_turnover > 50x, |FCF/assets| > 10) from shell companies with near-zero denominators. Rows that do not join to a company (null symbol) are ALWAYS omitted in full-universe mode, regardless of this flag.
get_earnings_signals
Reported earnings results and a model-derived earnings-trend signal for a company, by fiscal period: actual reported EPS, a trailing-trend EPS estimate (`eps_trend_est`), the deviation of actual vs that trend (`eps_surprise_pct`), reported revenue, and year-over-year revenue growth. IMPORTANT: `eps_trend_est` is NOT Wall Street analyst consensus — Valuein is sourced purely from SEC EDGAR and carries no consensus feed. It is a deterministic estimate computed from the company's own prior reported EPS, so `eps_surprise_pct` measures how far the print landed from its own trailing trend, not whether it 'beat the Street'. Use it to track earnings/revenue trajectory and momentum, not to claim a consensus beat or miss. Point-in-time safe — pass as_of_date to filter by SEC acceptance (accepted_at) for look-ahead-free backtests. Available on all plans.
Parameters (3)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT
as_of_datestring
Point-in-time filter: only return signals with accepted_at on or before this date. Use for backtesting to avoid look-ahead bias.
limitinteger
Maximum number of periods to return (1–40), most recent first. Defaults to 8 — covers 2 years of quarterly signals plus their TTM equivalents. earnings_signals.parquet currently emits one row per (entity, period_end); older rows surface here as more historical periods are published.
submit_feedback
File product feedback to the Valuein team — a bug, feature request, experience note, or data-quality issue — directly from the agent surface. Available on EVERY tier including guest/sample (no token required), so an agent can report a rough edge in-band without the human leaving the conversation. Provide a `category` and a `message`; optionally a `subject` title, a `severity` (low/medium/high), the `surface` it concerns (mcp/workspace/sdk/dashboard/api), and a free-form `context` object (e.g. the tool that failed, the ticker, the request_id). Authenticated callers (those with a token) can pass an `idempotency_key` to make a retried submission safe — the same key from the same account files exactly once; guest/sample callers are never deduplicated. Returns a friendly acknowledgment you can relay to the user. Do NOT use this to query data; it is a one-way report channel.
Parameters (7)
categorystringrequired
What kind of feedback this is: 'bug' (something broke), 'feature_request' (something missing), 'experience' (UX / clarity / docs), 'data_quality' (a wrong/missing/stale figure), or 'other'.
messagestringrequired
The feedback body (1–4000 chars). Be specific: what you expected, what happened, and any reproduction steps. May contain the user's own words — it is stored for triage and never used for arithmetic.
subjectstring
Optional short title (≤140 chars) summarizing the feedback.
severitystring
Optional impact classification: 'low', 'medium', or 'high'.
surfacestring
Optional product surface the feedback concerns: 'mcp', 'workspace', 'sdk', 'dashboard', or 'api'.
contextobject
Optional free-form context object (stored as JSON), e.g. { tool: 'get_company_fundamentals', ticker: 'AAPL', request_id: 'abc123' }. Avoid secrets.
idempotency_keystring
Optional client-supplied key (1–64 chars). For authenticated callers, reusing the same key files the feedback exactly once — safe to retry on a network error. Ignored for guest/sample callers (no account to scope dedup to).
get_insider_transactions
Form 3 / 4 / 5 / 144 line items for a US public company. Returns each transaction (or initial holding / proposed sale) with the insider's name, role, transaction code, share count, price, and notional. Filters by lookback window, transaction code (P=purchase, S=sale, A=grant, M=option exercise, F=tax withholding, etc.), insider role, and minimum share threshold. Institutional tier only — sample / sp500 / pro return ENTITLEMENT_DENIED with an upgrade link.
Parameters (8)
tickerstringrequired
Stock ticker symbol, e.g. AAPL, MSFT, BRK.B
lookback_daysinteger
How many days back from today to scan transactions for. Ignored when as_of_date is set.
transaction_codesarray
SEC transaction codes to keep (uppercase, single-letter): P=purchase, S=sale, A=grant, M=option exercise, F=tax withholding, G=gift, J=other. Unknown codes are rejected. Omit to include all codes.
roles_inarray
Insider roles to keep. Omit to include any role.
min_sharesnumber
Minimum |shares| per transaction. Omit for no floor.
as_of_datestring
Point-in-time date (YYYY-MM-DD). Only returns transactions with accepted_at <= this date — eliminates look-ahead bias. When set, lookback_days is ignored.
Returns top-N institutional holders of a US public company at a specific period_end (latest by default), with aggregate institutional shares, total market value, holder count, and HHI concentration (sum of squared share-of-total percentages). Sourced from Form 13F-HR via the by-issuer partition. Institutional tier only. 13F filings carry a ~45-day reporting lag — staleness_warning fires when latest data is older than 90 days.
Parameters (5)
tickerstringrequired
Stock ticker symbol of the issuer.
period_endstring
Quarter-end of the 13F reporting period (YYYY-MM-DD). Omit to use the latest period available. This is a REPORTING period, NOT a point-in-time cutoff — use as_of_date for that.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD): only 13F filings ACCEPTED by SEC on or before this date are considered, applied BEFORE the latest period is resolved. A 13F/A amendment or late filing accepted after this date is excluded (zero look-ahead) — use this for survivorship-free backtests. Omit for the latest knowable book.
top_ninteger
Maximum holders to return, ranked by market_value_usd. Default 25, max 200.
lineage_detailstring
Per-row provenance envelope. compact / full / off.
get_manager_portfolio
Returns a 13F filer's full portfolio at a specific period_end (latest by default), with QoQ deltas vs the prior quarter (new / increased / decreased / exited / unchanged). Specify the filer either by filer_cik (preferred) or filer_name (fuzzy match against entity.name; multiple matches raise an ambiguity error so you can disambiguate by CIK). Institutional tier only.
Parameters (6)
filer_cikstring
CIK of the 13F filer (1-10 digits; will be zero-padded to 10). Preferred over filer_name when known.
filer_namestring
Filer name to fuzzy-match against entity.name. Case-insensitive substring match. Multiple matches raise INVALID_ARGUMENT — use filer_cik in that case.
period_endstring
Quarter-end (YYYY-MM-DD). Omit to use latest available. This is a REPORTING period, NOT a point-in-time cutoff — use as_of_date for that.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD): only 13F filings ACCEPTED by SEC on or before this date are considered, applied BEFORE the latest + prior periods (and the QoQ basis) are resolved. A 13F/A amendment or late filing accepted after this date is excluded (zero look-ahead). Omit for the latest knowable portfolio.
top_ninteger
Maximum positions to return, ranked by market_value_usd. Default 25.
lineage_detailstring
Per-row provenance envelope.
get_blockholders
Returns SC 13D / SC 13G blockholder disclosures (5%+ stakes) for a US public company. Each row carries percent_owned, sole/shared voting + dispositive split, schedule_type, and the first-class ``going_active`` flag — TRUE when the same filer flipped 13G → 13D within the lookback window (the single most actionable activist signal in this dataset). Use latest_only=true (default) to dedupe to the most recent filing per filer. Use collapse_groups=true to fold multi-person filings into one row. Institutional tier only.
Parameters (7)
tickerstringrequired
Stock ticker symbol of the issuer.
schedule_filterstring
Which schedule(s) to return. '13D' = activist (intent to influence). '13G' = passive. 'both' = no filter.
as_of_datestring
PIT filter on accepted_at — only filings on or before this date.
latest_onlyboolean
When true (default), keep only the most recent filing per (filer, schedule prefix) — typically what analysts want. Set false to see the full filing history.
collapse_groupsboolean
When true, fold multi-reporting-person filings into a single row, with secondary persons in the ``persons[]`` field. Default false: each person stays as its own row.
lookback_daysinteger
Window for the going_active (13G → 13D) detection. Default 365 days.
lineage_detailstring
Per-row provenance envelope.
get_insider_sentiment
Role-weighted insider sentiment score on a fixed [-100, +100] scale for a single issuer over a lookback window. Role weights: CEO/CFO = 3.0 (via officer_title pattern), other NEO Officer = 2.0, 10%-Owner = 1.5, Director = 1.0. P = +1, S = -1; option exercises, grants, and tax withholdings are neutralised. Cluster flag = TRUE when ≥3 distinct insiders transacted within any 30-day window inside the lookback. Institutional tier only.
Parameters (3)
tickerstringrequired
Issuer ticker symbol.
lookback_daysinteger
Days back from today to scan transactions for. Default 180.
cluster_window_daysinteger
Sliding window for the cluster_flag detection. Default 30 days.
get_top_holders
Classification-aware UNION across insider transactions (latest post_transaction_shares per insider), 13F institutional holdings, and SC 13D / 13G blockholder filings for one issuer. Each row carries holder_class ∈ {insider, institutional, blockholder_13D, blockholder_13G}. Dedupes overlapping filers by precedence (13D > 13G > institutional > insider). One call, classified cap table — Bloomberg charges separately for INSIDER<GO>, OWNER<GO>, and HDS<GO>; this consolidates them.
Parameters (4)
tickerstringrequired
Issuer ticker symbol.
top_ninteger
Maximum holders to return, ranked by shares. Default 25.
period_endstring
13F REPORTING period_end. Omit for latest. NOT a point-in-time cutoff — use as_of_date.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD): only filings ACCEPTED by SEC on or before this date are considered across all three sources (institutional via accepted_at, insider via accepted_at, blockholders via accepted_at). Excludes amendments/late filings accepted after this date (zero look-ahead). Omit for the latest knowable cap table.
get_smart_money_flow
Composite flow score on [-100, +100] aggregating insider transactions, 13F institutional Δ-shares vs the prior quarter, and SC 13D/13G blockholder changes over a lookback window. Each component normalised independently, then combined with configurable weights (default: institutional 0.4, blockholder 0.4, insider 0.2). Returns per-component attribution so an agent can see WHY the score is what it is — not just the headline number. NOTE: the institutional component is a QoQ share-change signal computed over the top-5 13F filers on a MATCHED current-vs-prior basis (a filer only counts when its prior-quarter book is observable), NOT the issuer's complete institutional book — treat the score as a directional signal, not an exact flow. `coverage.coverage_confidence` (0–1) reports how much of that basis had a real prior quarter; when it is 0 the institutional component is forced to 0 so a 13F ingestion gap can never surface as a false max-conviction buy. See the `coverage` block for holder coverage + staleness. The score is a unitless composite, not a dollar figure. Institutional tier only.
Parameters (6)
tickerstringrequired
Issuer ticker symbol.
lookback_daysinteger
Lookback window for insider + blockholder components. Default 90.
weight_institutionalnumber
Weight applied to the institutional component (0–1).
weight_blockholdernumber
Weight applied to the blockholder component (0–1).
weight_insidernumber
Weight applied to the insider component (0–1).
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD) applied to all three legs (institutional, insider, blockholder) via SEC accepted_at — filings accepted after this date are excluded so the composite is computed with zero look-ahead. Omit for the latest knowable signal.
save_thesis
Persist a directional investment thesis (bull / bear / neutral) on a ticker. The thesis becomes part of the caller's private research diary; pair with `list_theses` + `score_thesis_outcome` to track conviction-vs-outcome over time. Pass `idempotency_key` for at-most-once semantics from a retrying agent.
**Use this AFTER** the agent has finished its analysis, not before — the thesis records the conclusion, not the question. Pair with `source_report_id` to link the thesis back to a published report so the buyer's thesis-tracking carries provenance.
Tier: all paid + free tiers (sample tier rejected — sample is guest access with no customerId binding). Per-tier cap on # of stored theses: sp500=100, pro=500, full=10,000.
Parameters (9)
tickerstringrequired
US-listed ticker. Case-insensitive — normalised to upper. E.g. 'AAPL'.
Investment horizon in days. 1 day–5 years (1825d). The grader uses this to pick the as-of period.
notesstring
Free-form rationale, ≤4000 chars. Stored verbatim; trim before submitting.
thesis_at_price_centsinteger
Optional snapshot of the ticker's market price (integer cents) at thesis creation. Used by future versions of the grader that mix in price returns; null for now is fine.
source_report_idstring
Optional id of a report (from `create_report` / `publish_report`) that contains the supporting analysis.
idempotency_keystring
Optional client-supplied key. If a previous `save_thesis` from the same user used this key, the existing thesis is returned instead of creating a duplicate.
visibilitystring
Phase 3: 'private' (default) is owner-only; 'unlisted' is visible at a known direct URL; 'public' surfaces on the author's /[handle] profile and contributes to their reputation score.
list_theses
Return the caller's saved theses, newest-first. Filters: ticker (exact), view, status. Cursor-based pagination — pass `next_cursor` from the previous response to fetch the next page. Sample tier rejected (no per-user state).
Parameters (5)
tickerstring
Filter to theses on this ticker (case-insensitive).
viewstring
Filter to a single view.
statusstring
'active' (default) hides archived theses; pass 'all' to include them.
limitinteger
Page size, 1–100. Defaults to 20.
cursorstring
Pagination cursor returned by the previous `list_theses` call's `next_cursor`.
get_thesis
Fetch a single saved thesis by its id. Returns the full record including outcome (if scored). Returns NOT_FOUND if the id is unknown or belongs to another user. For the claims composing a thesis use list_claims_for_thesis; for an individual claim use get_claim. Tier: paid + free (sample rejected).
Parameters (1)
thesis_idstringrequired
Id returned by `save_thesis` or `list_theses`.
delete_thesis
Soft-delete a saved thesis: status flips to `archived` (the row stays for audit / re-scoring). Idempotent — archiving an already-archived thesis succeeds. Hard-delete is not supported by design; future versions may expire archived theses after N years. This does not delete the claims linked to the thesis — use delete_claim for those. Tier: paid + free (sample rejected).
Parameters (1)
thesis_idstringrequired
Id returned by `save_thesis` or `list_theses`.
score_thesis_outcome
Grade a saved thesis against fundamental momentum since its creation. Pulls revenue / operating-margin / EPS / OCF deltas and aggregates into a score in [-1, +1]. Bull theses are graded by directional alignment, bear by inverse, neutral by closeness-to-flat. The grade is persisted back to the thesis row; re-call to refresh once new fundamentals land.
**Note (PR 2)**: scoring is fundamental-only — does NOT yet include market-price returns. Phase 2 will mix in price data via a partner feed; the response shape is stable.
Parameters (2)
thesis_idstringrequired
Id returned by `save_thesis` or `list_theses`.
as_ofstring
Snapshot date for the 'current' fundamentals window. Defaults to today UTC. The scorer picks the fiscal period closest to this date.
score_due_theses
Find every thesis past its horizon with no outcome yet, and grade each via `score_thesis_outcome`. Operates on the caller's own theses by default; can target any user when called with `customer_id` from a `full`-tier (admin) token. Returns a summary + per-thesis results. Idempotent — a re-call only re-grades anything not already graded.
Parameters (3)
customer_idstring
Stripe customer_id of the target user. Defaults to the caller's own; required to be the caller's own unless the caller's plan is `full` (admin / internal cron).
maxinteger
Soft cap on theses scored per call. Defaults to 100. The frontend cron walks users serially so a low cap per user keeps each MCP request bounded.
as_ofstring
Snapshot date for the 'current' fundamentals window. Defaults to today UTC.
run_workflow
Resolve a saved workflow by id and return a structured execution plan for a single ticker. Each plan entry names a real MCP tool or SOP plus its ticker-substituted arguments; the calling agent invokes them in order, applying any `skip_if` predicate against the previous step's output.
**This tool does NOT execute the steps server-side.** It plans; the agent runs. Iterate through `plan[]` in order, call the named tool/SOP with `args`, accumulate outputs, and apply each step's `skip_if` (skip the step when the previous output's `path` equals `equals`).
Workflows are private state owned by the calling user. Sample-tier callers are rejected. Pair with `list_workflows` (frontend) to discover available workflow_ids.
Parameters (3)
workflow_idstringrequired
Workflow id returned by the frontend workflow builder.
tickerstring
US-listed ticker the workflow should run against, e.g. 'AAPL'. Pass either `ticker` (single) or `tickers` (batch up to 50). Exactly one is required.
tickersarray
Batch mode — array of US-listed tickers, up to 50. When provided, the response has `plans[]` (one plan per ticker) instead of `plan`. Parity with the frontend batch-runner so agents can request 'plan over my watchlist' in a single call.
list_public_theses_by_user
Return the PUBLIC theses + reputation aggregate for a user identified by Stripe customer_id. Used by the /[handle] profile page to render an analyst's track record. Only entries with visibility='public' are surfaced — private theses never leak. Reputation is correct/(correct+wrong) over graded theses; null when n < 5 (sample too small). Sample tier rejected; sp500+ only.
Parameters (2)
customer_idstringrequired
Target user's Stripe customer_id (resolved by the frontend from the handle).
limitinteger
Max public theses to return. Defaults to 20.
publish_thesis
Make a saved thesis discoverable by flipping its visibility: `public` (default) surfaces it on the author's /[handle] profile and counts toward their reputation aggregate; `unlisted` makes it reachable at a known direct link but keeps it off the profile. Use AFTER save_thesis to promote an existing thesis (save_thesis sets visibility only at creation). Idempotent. Pair with unpublish_thesis to revert to private. Tier: sp500+ (sample rejected).
Parameters (2)
thesis_idstringrequired
Id returned by `save_thesis` or `list_theses`.
visibilitystring
`public` (default) → profile + reputation; `unlisted` → direct-link-only, off the profile. To revert to private, use unpublish_thesis.
unpublish_thesis
Revert a published thesis (public or unlisted) back to `private` — removes it from the author's /[handle] profile and excludes it from the public reputation aggregate. The inverse of publish_thesis. Owner-only, idempotent. Tier: sp500+ (sample rejected).
Parameters (1)
thesis_idstringrequired
Id returned by `save_thesis` or `list_theses`.
save_claim
Persist a single falsifiable, evidence-backed CLAIM — the atomic unit of the research graph. Use this for each discrete assertion an analysis produces (e.g. 'NVDA gross margin stays above 70% through FY2026'), then compose claims into a thesis with `link_claim_to_thesis`. Claims are scored independently of theses, so claim accuracy is tracked as its own track record.
Pick `claim_type` by HOW it's judged, not what it's about: `assertion` = true now, checked against data; `prediction` = resolves at `horizon_days` via `verifiable_condition`; `judgment` = qualitative, not auto-scored. Use `tags` for the topic (financial, valuation, macro, …). Set `eval_mode: 'auto'` + a `verifiable_condition` for deterministic grading, else `'agent'`/`'manual'`.
Tier: all paid + free tiers (sample rejected — guest has no customerId). Verifiable claims must cite evidence.
Parameters (14)
statementstringrequired
The atomic, falsifiable statement. One claim, not a paragraph.
tickersarrayrequired
Entities referenced (uppercased). 1 for most claims; 2+ for a comparison claim.
claim_typestringrequired
Epistemic type — drives scoring. assertion=true now (verified vs data); prediction=future (resolves at horizon via verifiable_condition); judgment=qualitative (not auto-scored).
Author confidence in [0,1]. Used as the Brier/log-loss weight when scored.
eval_modestring
How the outcome is resolved: auto (deterministic grade vs data via verifiable_condition), agent (an LLM judges at resolution), manual (a human marks it).
verifiable_conditionany
Machine-evaluable condition for eval_mode='auto'. Null otherwise.
antecedentany
Scenario precondition — the claim only resolves when this holds. Null = unconditional.
horizon_daysany
Resolution horizon in days (predictions). Null for assertions/judgments.
evidenceobject
Evidence grounding the claim.
source_report_idstring
Optional id of a report that contains the supporting analysis.
visibilitystring
'private' (default) owner-only; 'unlisted' visible at a direct URL; 'public' surfaces on the author's profile and contributes to the claim-accuracy reputation.
idempotency_keystring
Optional client key for at-most-once semantics from a retrying agent.
list_claims
List the caller's saved claims, most-recent-first, with AND-composed filters and cursor pagination. Filter by ticker, claim_type (assertion/prediction/judgment), tag, or lifecycle status (open/confirmed/refuted/expired/stale/needs_review). Archived claims are excluded unless include_archived is set.
Tier: all paid + free tiers (sample rejected).
Parameters (7)
tickerstring
Filter to claims referencing this ticker.
claim_typestring
Filter by epistemic type.
tagstring
Filter to claims carrying this topical tag.
statusstring
Filter by lifecycle status, or 'all'.
include_archivedboolean
Include soft-deleted claims.
limitinteger
Page size (max 100).
cursorstring
Pagination cursor from a previous page's next_cursor.
get_claim
Fetch a single claim by id, plus the ids of theses it supports/refutes and its full append-only score history. Use this to inspect a claim's evidence, current status, and how its outcome has evolved.
Tier: all paid + free tiers (sample rejected).
Parameters (1)
claim_idstringrequired
Id returned by save_claim or list_claims.
delete_claim
Soft-delete a claim by id. The row and its score history are preserved for audit (archived, not erased); the claim drops out of default list_claims results. Idempotent — deleting an already-archived claim succeeds.
Tier: all paid + free tiers (sample rejected).
Parameters (1)
claim_idstringrequired
Id of the claim to archive.
link_claim_to_thesis
Attach a claim to a thesis with a role: 'supports' (the claim, if true, strengthens the thesis), 'refutes' (if true, weakens it — track disconfirming evidence first-class), or 'context' (relevant but not directional). Idempotent — re-linking updates the role. A claim can support one thesis and refute another.
This composes theses from claims; it does NOT make the thesis score a function of claim scores (they're scored independently). Tier: paid + free (sample rejected).
Parameters (3)
thesis_idstringrequired
Id of the thesis (from save_thesis/list_theses).
claim_idstringrequired
Id of the claim (from save_claim/list_claims).
rolestringrequired
Relational role of the claim toward the thesis.
unlink_claim_from_thesis
Remove the link between a claim and a thesis. Idempotent — succeeds whether or not the link existed. The claim and thesis themselves are untouched. Tier: paid + free (sample rejected).
Parameters (2)
thesis_idstringrequired
Identifier of the thesis to unlink the claim from, as returned by save_thesis or list_theses.
claim_idstringrequired
Identifier of the claim to unlink, as returned by save_claim or list_claims.
list_claims_for_thesis
List the claims composing a thesis, each with its role (supports/refutes/context). This is how you read a thesis as the structured argument it is — its supporting and disconfirming claims with their current statuses. Archived claims are omitted. Tier: paid + free (sample rejected).
Parameters (1)
thesis_idstringrequired
Id of the thesis whose claims to list.
score_claim
Resolve a claim's outcome. By default auto-grades an `auto` claim by evaluating its verifiable_condition against SEC fundamentals (confirmed/refuted), or marks it `needs_review` when it can't be resolved deterministically (judgment, antecedent, or missing data). To record a human/agent judgment instead, pass `manual_status` (+ optional score/reason). Idempotent — re-scoring the same resolution is a no-op.
Tier: sp500+ (sample rejected).
Parameters (5)
claim_idstringrequired
Id of the claim to resolve.
as_ofstring
Snapshot date for the fundamentals window (auto mode). Defaults to today UTC.
manual_statusstring
Provide to record a human/agent outcome instead of auto-grading.
manual_scoreany
Outcome score in [-1,1] for a manual resolution. Null for non-scored statuses.
manual_reasonstring
Explanation for a manual resolution.
score_due_claims
Find every auto-gradable claim that is due (assertions in open/needs_review/stale; predictions whose horizon has passed) and resolve each against fundamentals. Operates on the caller's own claims by default; can target any user when called with `customer_id` from a `full`-tier (admin) token. Returns a summary + per-claim results. Idempotent — re-calling only re-resolves what changed.
Parameters (3)
customer_idstring
Target user's Stripe customer_id. Defaults to caller; requires `full` tier to target others.
maxinteger
Soft cap on claims scored per call (default 100).
as_ofstring
Snapshot date for the fundamentals window. Defaults to today UTC.
list_public_claims_by_user
Return the PUBLIC claims + claim-accuracy reputation for a user identified by Stripe customer_id. Used by the /[handle] profile to render an analyst's claim-level track record — a separate signal from thesis-outcome accuracy. Only visibility='public' claims surface; private state never leaks. Accuracy is confirmed/(confirmed+refuted) over resolved claims; null when n < 5. Sample tier rejected; sp500+ only.
Parameters (2)
customer_idstringrequired
Target user's Stripe customer_id (resolved by the frontend from the handle).
limitinteger
Max public claims to return. Defaults to 20.
publish_claim
Make a saved claim discoverable by flipping its visibility: `public` (default) surfaces it on the author's /[handle] profile and counts toward their claim-accuracy reputation; `unlisted` makes it reachable at a known direct link but keeps it off the profile. Use AFTER save_claim to promote an existing claim. Idempotent. Pair with unpublish_claim to revert to private. Tier: sp500+ (sample rejected).
Parameters (2)
claim_idstringrequired
Id returned by `save_claim` or `list_claims`.
visibilitystring
`public` (default) → profile + reputation; `unlisted` → direct-link-only, off the profile. To revert to private, use unpublish_claim.
unpublish_claim
Revert a published claim (public or unlisted) back to `private` — removes it from the author's /[handle] profile and excludes it from the public claim-accuracy aggregate. The inverse of publish_claim. Owner-only, idempotent. Tier: sp500+ (sample rejected).
Parameters (1)
claim_idstringrequired
Id returned by `save_claim` or `list_claims`.
save_citation_override
Persist a correction of a citation value. The correction is keyed on the canonical `fact_id` (a stable hash of CIK + accession + concept + period) so it applies to every report that references that same fact — including agent-regenerated reports. Re-saving the same fact_id replaces the prior correction in place (no duplicate row).
The `fact_id` is VERIFIED against live SEC data (scoped to `ticker`) before the correction is stored — a fact_id that doesn't resolve to a real fact is rejected with FACT_NOT_FOUND and nothing is persisted. You therefore must supply the `ticker` the fact belongs to.
Use this when the user notices an inaccuracy in an AI-generated report and wants the fix to persist. Provide `notes` for the rationale (≤500 chars) and `source_report_id` for provenance. Tier caps: sp500=500, pro=5000, full=50000.
Parameters (5)
fact_idstringrequired
Canonical fact identifier — usually returned in a citation's `fact_ids` array by get_report or any compute tool. Stable across report regenerations. Verified against live SEC data (scoped to `ticker`) before persistence — a fabricated or unresolvable fact_id is rejected.
corrected_valuestringrequired
User-corrected value, stringified. The frontend interprets it based on the fact's known datatype (number, string, ISO date).
tickerstringrequired
Ticker the fact belongs to (REQUIRED) — scopes fact_id resolution against live SEC data and denormalises the row for fast filtering (the workspace UI's 'my corrections on AAPL' view).
source_report_idstring
Optional report id the user was viewing when they applied the correction (provenance).
notesstring
Optional free-form rationale, ≤500 chars.
list_citation_overrides
Author-only newest-first listing of the caller's citation corrections. Filterable by ticker (e.g. all AAPL corrections) or by a single fact_id (returns 0 or 1 row). Pair with `save_citation_override` and `delete_citation_override`. Sample tier rejected.
Agent use: call with `ticker` to introspect what corrections the user has previously applied on that ticker — useful for system prompts that respect prior corrections during regeneration.
Optional fact_id filter — returns at most one row.
limitinteger
Maximum number of citation overrides to return (1–100). Defaults to 20.
cursorinteger
Cursor from the previous response's `next_cursor` — the updated_at of the last row on that page. Omit for first page.
delete_citation_override
Remove a user-authored citation correction by fact_id. Idempotent — deleting a missing override returns deleted=false without error. Once deleted, reports that previously rendered the corrected value revert to the canonical fact value on next regeneration. Tier: paid + free (sample rejected).
Parameters (1)
fact_idstringrequired
Fact identifier whose citation override should be removed, as returned by save_citation_override or list_citation_overrides.
save_watchlist
Upsert a named watchlist with a list of tickers. Replace semantics — the full ticker list is the source of truth for that name. Use this for both creation AND modification (delete + recreate is not required for edits). 500-ticker cap per list. Names are case-insensitive uniqueness.
Paginated newest-first listing of the caller's watchlists (id, name, tickers, status, counts). Filter by `status` (active/archived/all). Returns metadata only — use get_watchlist for one list's full ticker set, or watchlist_diff for new filings across a list. Tier: sp500+ (sample rejected).
Parameters (3)
statusstring
Filter by state; defaults to `active`. Use `all` to include archived watchlists.
limitinteger
Maximum number of watchlists to return (1–100). Defaults to 20.
cursorstring
Opaque pagination cursor from a previous response; omit for the first page.
get_watchlist
Fetch a single watchlist (full ticker set + criteria) by its name, not an id (case-insensitive). NOT_FOUND if the name is unknown to this user. Tier: sp500+ (sample rejected).
Parameters (1)
namestringrequired
Watchlist name to fetch (case-insensitive, 1–80 chars).
delete_watchlist
Soft-delete a watchlist by its name (not id): status flips to `archived` (still readable via list_watchlists status=all/archived). The name is freed for reuse by a new save_watchlist. Idempotent. Tier: sp500+ (sample rejected).
Parameters (1)
namestringrequired
Watchlist name to soft-delete (case-insensitive, 1–80 chars); frees the name for reuse.
watchlist_diff
Return new SEC filings across the caller's watchlist tickers since a given date. Reads filing.parquet — does not call insider/ratio surfaces (use those tools separately if you need them). Concurrency-bounded; max 50 tickers per call.
Parameters (3)
namestringrequired
Watchlist name.
sincestringrequired
Cutoff date (YYYY-MM-DD); the diff returns SEC filings accepted on or after this date across the watchlist's tickers.
form_typesarray
Filing forms to include. Defaults to 10-K + 10-Q + 8-K.
create_alert
Persist an alert and register it with the firing pipeline. Three condition shapes:
* `filing_event` — fire when a ticker files a chosen form type (8-K, 10-K, etc.).
* `ratio_threshold` — fire when a ticker's financial ratio crosses a threshold (e.g. interest_coverage < 1.5).
* `watchlist_change` — fire on any filing on any ticker in a named watchlist.
Delivery channels: `email` (transactional via Resend) or `webhook` (HMAC-SHA256-signed POST). The cron evaluator runs every 5 minutes. Use `test_alert` to verify your channel is wired correctly before relying on the cron.
Parameters (3)
namestringrequired
Human-readable label.
conditionanyrequired
Condition evaluated each cron tick — a discriminated union of `filing_event` (a watched ticker files a new form), `ratio_threshold` (a financial ratio crosses a comparator/threshold), or `watchlist_change` (a named watchlist's membership changes).
channelanyrequired
Delivery channel for a match — `email` (Resend transactional email), `webhook` (HMAC-SHA256-signed POST to your URL), `slack` (POST to a hooks.slack.com incoming-webhook URL), or `dashboard` (in-app inbox, readable via list_alert_inbox).
list_alerts
Paginated newest-first listing of the caller's alerts (id, condition, channel, status, trigger_count, evaluator health). Filter by `status` (active/paused/deleted/all). Use the returned alert id with delete_alert or test_alert. Tier: sp500+ (sample rejected).
Parameters (3)
statusstring
Filter by lifecycle state; defaults to `active`. Use `all` to include paused and soft-deleted alerts.
limitinteger
Maximum number of alerts to return (1–100). Defaults to 20.
cursorstring
Opaque pagination cursor from a previous response; omit for the first page.
delete_alert
Soft-delete an alert by its id (from create_alert/list_alerts): status flips to `deleted` and it is removed from the cron evaluator index so it stops firing. Alerts are immutable — to change one, delete then create_alert. Idempotent. Tier: sp500+ (sample rejected).
Parameters (1)
alert_idstringrequired
Identifier of the alert to soft-delete, as returned by create_alert or list_alerts.
test_alert
Fire a synthetic notification through the alert's configured channel. Use this immediately after `create_alert` to verify the channel (email address valid / webhook URL reachable + HMAC verification on the receiver). The synthetic fire is logged as `attempt=1 channel='test'` so it doesn't affect the real fire counter — the next genuine match still fires normally.
Parameters (1)
alert_idstringrequired
Identifier of the alert to fire a synthetic test notification through, as returned by create_alert or list_alerts.
list_alert_inbox
Newest-first listing of the caller's in-app alert inbox. Each item is a single FIRE of an alert with a `dashboard` channel — written by the cron evaluator (or `test_alert`); use list_alerts instead for the alert definitions themselves. By default dismissed items are hidden and read items are included. Cursor-paginated by `fired_at`. Sample tier rejected — alerts are a paid-tier feature (sp500+).
Parameters (4)
unread_onlyboolean
When true, return only items where read_at IS NULL.
include_dismissedboolean
When true, also return items the caller previously dismissed.
limitinteger
Maximum number of inbox items to return (1–100). Defaults to 20.
cursorinteger
Pagination cursor — the `fired_at` of the last item on the previous page.
mark_inbox_read
Set `read_at` on a single inbox item by its id (from list_alert_inbox or the alerts feed resource) — not an alert id. Idempotent — re-marking does NOT reset the first-read timestamp; there is no unmark. Returns the new unread_count so the agent/UI can update its badge without a follow-up call. Tier: sp500+ (sample rejected).
Parameters (1)
inbox_idstringrequired
Identifier of the inbox item to mark read, as returned by list_alert_inbox or the alerts feed resource.
dismiss_inbox_item
Soft-delete a single inbox item by its id (from list_alert_inbox) — not an alert id; sets `dismissed_at`. The row stays queryable via `list_alert_inbox(include_dismissed=true)` for audit. Idempotent. Tier: sp500+ (sample rejected).
Parameters (1)
inbox_idstringrequired
Identifier of the inbox item to dismiss (soft-delete), as returned by list_alert_inbox.
create_report
Synchronously generate a research report and persist it under the caller's authorship. Two subtypes:
• `reverse_dcf` — solves the stage-1 free-cash-flow growth rate the market price implies, with a 5×5 sensitivity grid across WACC × terminal-growth assumptions. Returns full markdown + structured JSON + every numerical claim's citation chain to the originating SEC accession.
• `thesis` — snapshot a saved thesis (via `save_thesis`) as a frozen narrative report with at-a-glance table, author notes, anchor fundamentals (latest annual), and lineage to the source filing. Later edits to the thesis do NOT propagate — generate a new report to capture new state.
Tier: sample tier rejected — reports are per-author state.
US-listed ticker — required for report_type=reverse_dcf. Case-insensitive.
paramsobject
Reverse-DCF parameters — required for report_type=reverse_dcf.
thesis_idstring
Id of a saved thesis owned by the caller — required for report_type=thesis.
titlestring
Optional human-supplied title; auto-generated when omitted.
idempotency_keystring
Optional key for at-most-once semantics. Same key from the same user always yields the same report id.
get_report
Fetch the current HEAD of a report by id. `format=markdown` returns the rendered body, `format=json` returns the full structured payload (sections + citations + report-type-specific data), `format=preview` returns abstract-only. Authors see any of their own reports; non-authors only get `preview` of listed reports and need the report's required tier for full bodies. Sample-tier non-authors are downgraded to preview regardless of input. For an archived prior version use `get_report_version`, not this tool.
Parameters (2)
report_idstringrequired
Id from `create_report` or `list_my_reports`.
formatstring
Response shape. Defaults to markdown.
list_my_reports
Cursor-paginated newest-first listing of the caller's own reports (owner-scoped). Filters compose with AND; `status` defaults to 'ready' so pass status='draft' or 'all' to see drafts. Use `cursor` from the previous response's `next_cursor` to fetch the next page (limit max 100). Sample tier rejected (no per-author state).
Parameters (5)
statusstring
Filter by status. Default 'ready' (excludes drafts + delisted).
report_typestring
Filter by report type.
tickerstring
Filter to a single ticker (case-insensitive).
limitinteger
Page size.
cursorstring
Cursor from previous `next_cursor`.
delete_report
Soft-delete a report owned by the caller: status flips to `delisted`, visibility to `private` — not a hard delete, the row and R2 artifact are preserved (90-day audit window). Idempotent (deleting an already-delisted report succeeds). Sample tier rejected.
Parameters (1)
report_idstringrequired
Id from `create_report` or `list_my_reports`.
publish_report
Publish a report for FREE at `listed` or `unlisted` visibility to build your public author profile. `listed` makes it discoverable via `search_reports` (keyword catalog search); `unlisted` keeps it out of the catalog but accessible by direct id (shareable link). Author can set a `tier_required` no higher than their own plan. All listings are free today (omit `price_cents` or set it to 0); paid listings are a future capability.
Parameters (4)
report_idstringrequired
visibilitystring
price_centsinteger
Currently must be omitted or 0 — all listings are free. A non-zero value is rejected until paid listings ship.
tier_requiredstring
Minimum subscriber tier to read the full body. Defaults to the author's plan.
unpublish_report
Revert a published report (listed or unlisted) back to `private` visibility, removing it from the public catalog. Author-only. Idempotent.
Parameters (1)
report_idstringrequired
search_reports
Search the catalog of published research reports. All listings are free to read. Filters: free-text (matches title + abstract), ticker, report_type. Sort: `newest` (default) or `oldest`. Tier-gated: callers only see reports their plan tier can read.
Parameters (7)
querystring
Free-text query over title + abstract (case-insensitive).
tickerstring
Filter to a single subject ticker.
report_typestring
Filter by report type.
price_max_centsinteger
Reserved for future paid listings; currently ignored (all reports are free).
sortstring
limitinteger
cursorstring
compute_dcf
Forward discounted-cash-flow valuation (two-stage Gordon-growth model): caller provides growth + WACC + terminal assumptions, returns per-share intrinsic value (`value_per_share_cents`, cents USD) + 5×5 sensitivity grid. Pulls FCF base + net debt + shares from R2; caller can override any field. Definitions (consistent with `get_financial_ratios` / `get_capital_allocation_profile`): FCF base = operating_cash_flow − capex (absolute USD); net_debt = total_debt − (cash + short-term investments). Shares resolve via a fallback chain (valuation row → fact CommonSharesOutstanding → net_income/eps_diluted), reported as `result.shares_source`. The pulled inputs are echoed in `result.inputs_echo` with their source lineage so the valuation is reproducible and traceable. A null `value_per_share_cents` means the model is degenerate (e.g. WACC ≤ terminal growth, or FCF base ≤ 0) or a required input was unavailable — it is NOT a zero valuation; the `reason` field explains. Use the returned figures exactly. Use this when you want to drive the assumptions yourself; for the pipeline's pre-computed DCF/DDM value and inputs (no assumptions needed) use `get_valuation_metrics` instead. Does NOT persist a report — use `create_report` (report_type:'reverse_dcf') for that. Tier: sp500+.
Parameters (8)
tickerstringrequired
Stock ticker symbol of the company to value, e.g. AAPL, MSFT, BRK.B.
stage1_growth_ratenumberrequired
Stage-1 FCF growth rate (e.g. 0.12 = 12%/yr).
waccnumber
Discount rate. Default 0.09.
terminal_growth_ratenumber
Long-run growth. Default 0.025.
stage1_yearsinteger
Number of explicit high-growth projection years before the terminal stage (3–15). Defaults to 5.
fcf_base_overridenumber
Override the auto-pulled FCF base (USD). Leave unset to use R2-derived.
shares_overridenumber
Override shares outstanding. Leave unset to use R2-derived.
as_of_datestring
Point-in-time cutoff (YYYY-MM-DD) for the auto-pulled inputs. Fundamentals are filtered by SEC accepted_at (strict PIT); valuation.parquet inputs are best-effort PIT (filtered by created_at, its accepted_at proxy — no SEC acceptance timestamp exists for pipeline-computed valuations). Omit to use the latest knowable inputs.
forensic_audit
Deterministic forensic-accounting scores for a single ticker: partial Beneish M-Score, Sloan accruals, and a solvency snapshot. Returns a red-flag narrative ranked by severity, with citations to source filings. Used by the `forensic_earnings_brief` SOP.
Note: full Beneish needs AR / current assets / PPE / SGA / current liabilities, which aren't in our fundamentals model. We compute the recoverable subset (SGI + TATA + LVGI) and flag `partial=true`. Tier: sp500+.
Parameters (1)
tickerstringrequired
Stock ticker symbol of the company to audit, e.g. AAPL, MSFT, BRK.B.
update_report
Replace one or more sections of an existing report owned by the caller. Useful for authoring workflows where the agent's first draft (`create_report`) is refined by additional analysis before publishing. Bumps `version`. Does NOT change price / tier / visibility — use publish_report for those.
Parameters (5)
report_idstringrequired
Identifier of the report to update, as returned by create_report or list_my_reports.
titlestring
Optional new title.
abstractstring
Optional new abstract.
sectionsarrayrequired
Sections to replace. Sections not listed are preserved. Section ids must match the existing payload.
expected_versioninteger
Optimistic concurrency check. If supplied and the current HEAD version is different, the call returns a `version_conflict` error WITHOUT writing. Pass the version you loaded so a concurrent agent edit produces a 'conflict — review' UX instead of silently overwriting (eng review A3A).
list_report_versions
Author-only newest-first listing of a report's archived version history. Each entry summarises what changed (sections edited, etc.) so the workspace UI can render a clickable history without loading every artifact. Pair with `get_report_version` to fetch a specific version's content for diffing against HEAD.
Parameters (3)
report_idstringrequired
Identifier of the report whose version history to list, as returned by create_report or list_my_reports.
limitinteger
Maximum number of archived versions to return (1–100). Defaults to 20.
cursorinteger
Cursor from the previous response's `next_cursor` — the smallest version number on the previous page. Omit for the first page.
get_report_version
Author-only fetch of a specific archived version of one of your reports, by positive-integer `version`. Returns metadata + the full payload (sections, citations, structured, markdown) — enough to render a diff against the current HEAD in the workspace editor. Use after `list_report_versions` identifies the version number you want; for the current HEAD use `get_report` instead.
Parameters (2)
report_idstringrequired
Identifier of the report whose archived version to fetch, as returned by create_report or list_my_reports.
versionintegerrequired
Version number to fetch (from list_report_versions).
render_report
Return a 15-minute presigned download URL for a report in the requested binary format.
`format=md` presigns the cached markdown — instant, no compute. `format=docx` returns a branded Word document with a cover page (logo, title, ticker, tier badge), the report body (abstract, sections, citations table with clickable SEC EDGAR links), and a back page (methodology, sources, disclaimer). The DOCX is cached in R2 alongside the markdown after first build so repeat downloads are instant; pass `force_regenerate: true` to bust the cache (e.g. right after `update_report`).
Tier gate mirrors `get_report`: authors always see their own reports; non-authors below the report's required tier get an upgrade prompt.
Parameters (3)
report_idstringrequired
Id from create_report or list_my_reports.
formatstringrequired
md = raw markdown (the same body the editor renders). docx = branded Word document with cover + back page.
force_regenerateboolean
If true, ignore the cached DOCX and re-render. No effect on md (markdown is canonical).
save_freeform_report
Save free-form markdown (e.g. a chat synthesis) as a DRAFT report you can refine in the editor and export to Word/PDF. Unlike `create_report` (which computes a structured reverse_dcf or thesis report), this accepts raw markdown and splits it into sections. No compute, so no citations/lineage — add citations later via `update_report`. Tier: sample rejected (reports are per-author state). Idempotency-key → stable report id.
Parameters (5)
titlestringrequired
Report title.
markdownstringrequired
Free-form markdown body (≤100k chars). Headings become sections.
tickerstring
Optional ticker for context/catalog. Case-insensitive.
abstractstring
Optional 1–2 sentence summary.
idempotency_keystring
Optional key for at-most-once semantics. Same key from the same user always yields the same report id.
generate_dcf_xlsx
Render a forward DCF result into a professional Excel workbook (Summary + 5×5 Sensitivity heatmap + Inputs sheet). Native conditional formatting — no chart images needed. Returns a 15-minute presigned R2 download URL.
SERVER-TRUST: the DCF is re-derived in-Worker from the supplied `inputs_echo` (the math is pure + deterministic) and the workbook renders Valuein's recomputed figures — never the caller's claimed values. If the claimed figures disagree, the workbook is still produced but stamped with a visible correction banner and the response `verification.status` is 'corrected'. A fabricated per-share value can never appear as Valuein-authoritative.
Pair with `compute_dcf` for a typical analyst flow: agent calls `compute_dcf({ticker, ...})`, then passes the structured result straight to `generate_dcf_xlsx({ticker, dcf_result, ...})` to materialise a shareable file.
Tier: pro+.
Parameters (3)
tickerstringrequired
Stock ticker symbol of the company the DCF workbook is built for, e.g. AAPL.
company_namestring
Optional — surfaces on the cover row. Falls back to ticker only.
dcf_resultobjectrequired
Structured DCF result — typically the `result` field returned by `compute_dcf`.
generate_research_brief_docx
Render a structured research brief into a professionally-styled Word document — cover, abstract, optional snapshot table, body sections, and a citations table with clickable SEC EDGAR links. No embedded charts in v1; pair with `generate_dcf_xlsx` / `generate_comps_xlsx` for visuals the analyst pastes in.
SERVER-TRUST: prose, snapshot rows, and citations are rendered as-supplied and are NOT verified by Valuein, so the brief carries a visible 'figures supplied by caller, not verified by Valuein' watermark (response `verification.status` = 'unverified'). Resolve each citation via `verify_fact_lineage` before publishing.
Consumes the same `sections` + `citations` shape `create_report` emits, so the typical flow is two tool calls: `create_report` → `generate_research_brief_docx`.
Tier: pro+.
Parameters (7)
tickerstringrequired
Stock ticker symbol the brief covers, e.g. AAPL, MSFT, BRK.B.
company_namestring
Optional display name shown on the cover page; falls back to the ticker if omitted.
titlestringrequired
Document title rendered on the cover page (1–200 chars).
abstractstring
Optional executive-summary paragraph (≤2000 chars) shown after the cover page.
snapshotarray
Optional at-a-glance metric rows (≤20) rendered as the snapshot table.
sectionsarrayrequired
Ordered body sections of the brief (1–20); each has a heading and body text.
citationsarray
Optional source citations (≤60) rendered as a table with clickable SEC EDGAR hyperlinks.
generate_comps_xlsx
Render a peer comparables table into an Excel workbook. The Comps sheet is formatted as a named Excel Table (`ValueinPeerComps`) so the user gets one-click Insert Chart on any column — the cleanest workaround for not embedding chart objects server-side. Subject-row highlight makes side-by-side comparison instant. A Summary sheet adds subject vs peer-median deltas.
SERVER-TRUST: the ratios you pass are rendered as-supplied and are NOT re-derived by Valuein, so the workbook carries a visible 'figures supplied by caller, not verified by Valuein' watermark (response `verification.status` = 'unverified'). For authoritative numbers, source them from `get_peer_comparables` / `get_financial_ratios` first.
Pair with `get_peer_comparables` for a typical flow.
Tier: pro+.
Parameters (4)
subject_tickerstringrequired
Stock ticker symbol of the subject company the comps sheet is built around, e.g. AAPL.
subject_company_namestring
Optional display name for the subject company; falls back to the ticker if omitted.
peersarrayrequired
Peer companies to tabulate against the subject (1–50 rows); each row carries the peer's ticker, name, and comparable ratio values.
notesstring
Optional free-text note (≤500 chars) rendered on the Summary sheet.
Valuein — SEC EDGAR fundamentals for analysts, quants, and AI agents
Survivorship-bias-free, point-in-time US fundamentals — streamed as Parquet, queried with DuckDB or natural language.
This repository is the public home and discovery hub for the Valuein data platform. It hosts the documentation, examples, notebooks, and the MCP registry manifest used by AI agents to find us. Source code for the SDK, MCP server, and data pipeline lives in dedicated repositories — this is the front door.
bash
pip install valuein-sdk # data for code# or add this URL to any MCP-capable AI client:# https://mcp.valuein.biz/mcp # data for agents
Survivorship-bias-free, point-in-time US fundamentals sourced directly from SEC EDGAR.
12M+ filings — 10-K, 10-Q, 8-K, 20-F, 40-F, and amendments since 1993
111M+ standardized facts across 19,000+ active and delisted US public-company entities
11,966 raw XBRL tags normalized to ~286 canonical standard_concept values (95%+ coverage)
Cloud Parquet on Cloudflare R2 — stream with DuckDB; no database setup, no local downloads
PIT-correct — every fact carries filing_date and millisecond-precision accepted_at
Semantic core — every 10-K / 10-Q / 20-F's narrative sections (Risk Factors, MD&A, Business, Legal, Controls) chunked and indexed for natural-language search via the MCP server
Delisted, bankrupt, and acquired companies remain in every snapshot — your backtest sees the universe the market saw.
📊 Standardized concepts
Both the raw XBRL tag (fact.concept) and the canonical name (fact.standard_concept) are on every row. No hidden mapping table.
🔍 CPA-verified catalog
Every standard_concept carries a review_confidence — 1.0 once an accountant has signed off on its name, statement and rule (then it's locked; the pipeline only ever adds new concepts, never mutates a verified one), 0.7 while provisional. Filter review_confidence >= 1.0 for the labels analysts, quants and AI models can agree on and train against.
🚀 DuckDB-native
Millisecond analytics over remote Parquet via httpfs. Zero database provisioning.
🔁 Append-only restatements
A 10-K/A adds a new row — the original stays. Reconstruct the as-reported view of any historical date.
🔐 One token, every channel
The same Bearer token authenticates the SDK, MCP server, and bulk-data API.
Distribution channels
The same dataset, delivered four ways so it lands where you already work.
A single Stripe-issued token unlocks every channel at your tier — no per-channel billing.
Plans & access
Pricing and feature scope are mirrored from valuein.biz/pricing — the website is the source of truth and our checkout flow routes to the correct Stripe product.
Each tier removes a different buyer objection — Pro removes the universe + history limits on the fundamentals dataset; Institutional adds the smart-money dataset (insider transactions + institutional ownership), unlimited history back to 1993, filing-event webhooks, and a commercial redistribution license under a business-hours SLA; Enterprise adds dedicated infrastructure and bespoke contracts.
Pay-per-call (MPP)
Autonomous AI agents that hit a rate or tier limit can pay per request using Stripe card tokens — no human checkout loop. Payment uses the Machine Payment Protocol. The agent quotes a price, charges a card Shared Payment Token, then retries the MCP call with the confirmed token.
Payment is card-only today. Fetch https://api.valuein.biz/api/mpp/well-known to see which networks are live before paying.
PAYG is priced at 5× the subscription-equivalent rate — steady-state agent usage is almost always cheaper with a Pro or Institutional subscription. Daily spend caps exist per token as abuse protection; caps are raisable on request. See AGENTS.md for the full three-step MPP flow.
Rate limits per tier (canonical at https://data.valuein.biz/v1/plans):
Plan
Per minute
Per hour
Sample (anonymous)
15
150
Free
60
1,000
Pro
100
3,000
Institutional / Enterprise
300
10,000
Quickstart (30 seconds, no token)
Pick whichever Python workflow you already use — both work in any virtual environment, and both run the same code below:
bash
# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install valuein-sdk
bash
# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install valuein-sdk
Zero-friction by design. No VALUEIN_API_KEY? No problem. The SDK detects the missing token and falls back to the SAMPLE dataset (S&P 500, last 5 years); the edge gateway does the same — GET /v1/{sp500,pro,full}/:table with no Authorization header automatically 302-redirects to /v1/sample/:table. The snippet below runs as-is.
python
from valuein_sdk import ValueinClient
with ValueinClient() as client:
print(client.me()) # {plan, status, email, createdAt}print(client.manifest()) # snapshot id, last_updated, tablesprint(client.tables()) # currently loaded tables
df = client.run_query("""
SELECT r.symbol, r.name, r.sector
FROM "references" r
JOIN index_membership im ON im.cik = r.cik
WHERE im.index_name = 'SP500'
AND im.removal_date IS NULL
AND r.is_active = TRUE
ORDER BY r.name
LIMIT 10
""")
print(df)
That's a real query against the live S&P 500 sample. Add a token only when you need full universe or full history:
bash
# optional — sample tier works without a keyecho'VALUEIN_API_KEY="your_token_here"' >> .env
The same code now reads from your tier — no other changes.
Production pattern — context manager, typed errors, pre-built templates
python
from valuein_sdk import (
ValueinClient,
ValueinAuthError,
ValueinPlanError,
ValueinRateLimitError,
ValueinAPIError,
ValueinError,
)
# Two-level try/except is intentional:# outer = init errors raised by ValueinClient.__enter__ (auth, manifest, 503)# inner = per-query errors raised by run_query / run_template (rate-limit,# plan denial, bad SQL). Each level dispatches by exception type so# you can act on the right cause — exit on auth, sleep on rate-limit,# upsell on plan, log + skip on a single bad row.try:
with ValueinClient() as client:
try:
# 1) Build & run a raw SQL query → pandas DataFrame
sql = "SELECT COUNT(cik) FROM entity"
result = client.run_query(sql)
print(result)
# 2) Run a named SQL template with kwargs (the SDK quotes safely)
df = client.run_template(
"fundamentals_by_ticker",
ticker="AAPL",
start_date="2020-01-01",
end_date="2024-12-31",
form_types=["10-K", "10-Q"],
metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
)
print(df.head())
except ValueinPlanError:
print("This query needs a higher plan — see valuein.biz/pricing.")
except ValueinRateLimitError as e:
print(f"Rate limited; retry in {e.retry_after}s.")
except ValueinError as ve:
# Catch-all for any other per-query failure (validation, bad SQL, etc.)print(f"Query failed: {ve}")
except ValueinAuthError:
raise SystemExit("Token missing or expired — set VALUEIN_API_KEY.")
except ValueinAPIError as e:
print(f"Gateway error during init (HTTP {e.status_code}).")
except Exception as e:
print(f"Initialization failed: {e}")
The SDK ships 54 named SQL templates for the most common screens, ratios, and PIT backtests. List them:
python
from valuein_sdk import ValueinClient
with ValueinClient() as c:
print(c.list_templates())
Every link below points to a runnable script in examples/python/ (mirror notebook in examples/notebooks/). The Sample tier runs every example — no token, no signup.
Start here. Flat join of entity + security. One row per security with cik, is_active, sector, exchange, FIGI. For membership, JOIN index_membership on cik = cik.
One scan for cross-company metadata; index membership stays in its own table so historical entry/exit is preserved.
entity
Company metadata — CIK, name, sector, SIC, status, fiscal year end
The legal entity dimension.
security
Ticker history (SCD Type 2 with valid_from / valid_to)
Source of the Vectorize index that powers semantic search via MCP.
Date columns — which to use when
Column
Table
Use for
report_date / period_end
filing / fact
Aligning to the fiscal calendar
filing_date
filing
PIT backtest filter — when the SEC received it
accepted_at
fact, valuation, filing_text
Millisecond-precision PIT for intraday research
For any cross-company backtest, always filter by filing_date <= trade_date. Filtering by report_date introduces look-ahead bias.
Three patterns that pay off in DuckDB
1. Start from references (one join for cross-company filters; membership is in index_membership):
sql
SELECT r.symbol, r.name, r.sector
FROM "references" r
JOIN index_membership im ON im.cik = r.cik
WHERE im.index_name ='SP500'AND im.removal_date ISNULL-- current memberAND r.is_active =TRUEAND r.sector ILIKE '%technology%'
2. LATERAL for the latest filing per company:
sql
JOINLATERAL (
SELECT accession_id, filing_date FROM filing
WHERE entity_id = r.cik AND form_type ='10-K'ORDERBY filing_date DESC LIMIT 1
) f ONTRUE
3. Pivot multiple concepts in one fact scan:
sql
SELECTMAX(CASEWHEN standard_concept ='TotalRevenue'THEN numeric_value END) AS revenue,
MAX(CASEWHEN standard_concept ='StockholdersEquity'THEN numeric_value END) AS equity
FROM fact
WHERE standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUPBY accession_id
Quarterly cash flows: use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD; this column isolates the single quarter. CAPEX sign varies by filer — always ABS(capex).
The full cookbook — 20 recipes, 8 anti-patterns, end-to-end factor screen — lives in docs/QUERY_COOKBOOK.md.
Canonical concept names
Query fact.standard_concept with canonical names like 'TotalRevenue', 'NetIncome', 'OperatingCashFlow', 'CAPEX', 'StockholdersEquity' — not raw XBRL tags ('Revenues', 'NetIncomeLoss', 'Assets'). The full list lives in docs/data_catalog.md and the machine-readable form is in docs/data_catalog.json.
MCP for AI agents
Valuein ships a remote Model Context Protocol server so any MCP-capable agent (Claude Desktop, Cursor, Codex, custom) can answer fundamentals questions without writing code.
Reference:docs/MCP_TOOLS.md — every tool, every parameter, every tier gate
Tools
<!-- GEN:mcp-summary -->
The server exposes 95 live tools, plus 28 agentic SOP prompts (two flagship cross-persona briefs — equity_research_brief and screen_and_shortlist — plus specialised chains for analyst, PM, quant, ratio, smart-money, and workflow personas) and 3 data resources (schema://{table}, reference://sp500, pricing://current). Tier gating happens at the data layer — Sample / Free tokens see Sample / S&P 500 data; Pro sees the full 19,000+-entity universe with a 15-year point-in-time window (2011 → present); Institutional unlocks the smart-money tools (insider transactions on Forms 3 / 4 / 5 / 144 + institutional ownership on Forms 13F / 13D / 13G), unlimited history back to 1993, filing-event webhooks, and the commercial redistribution license.
<!-- /GEN:mcp-summary -->
Discovery & schema
Tool
What it does
search_companies
Look up tickers, names, CIKs; filter by sector, S&P 500, active status
describe_schema
Return columns, types, and descriptions for any table
get_pit_universe
The live constituent list (S&P 500 or all) for any historical as_of_date
Fundamentals & ratios
Tool
What it does
get_company_fundamentals
Income statement, balance sheet, cash flow per ticker per period
Direct EDGAR URLs for 10-K / 10-Q / 8-K / 20-F / 40-F
verify_fact_lineage
Trace any number back to the exact filing + accession ID it came from
Comparison & analytics
Tool
What it does
compare_periods
Side-by-side comparison across periods with material-change flags
get_peer_comparables
Peer set + comparable metrics by sector
screen_universe
Multi-factor screen across the universe
Bulk data
Tool
What it does
get_compute_ready_stream
Issue presigned R2 URLs for direct Parquet streaming (skip the gateway)
Smart money — Institutional tier and above
The smart-money bundle replaces Bloomberg's INSIDER<GO> / OWNER<GO> / HDS<GO> screens with a single Valuein token. Each tool reads a per-CIK Parquet partition and returns structured rows with the lineage envelope for one-click SEC verification.
Tool
What it does
get_insider_transactions
Form 3 / 4 / 5 / 144 line items per issuer — joined to insider_party for name + role
get_institutional_holdings
Form 13F top holders for one issuer with HHI concentration + 13F-lag staleness flag
get_manager_portfolio
Form 13F filer's full portfolio with QoQ deltas (new / increased / decreased / exited)
get_blockholders
SC 13D / 13G with the first-class going_active flag (13G→13D = control-change signal)
Public publishing — free reputation building (all tiers)
Publish your saved research to a public @handle profile — free to build a public track record and reputation. Reports become a shareable /r/[slug] page discoverable via keyword catalog search (no semantic search yet); theses and claims get the same free publish / unpublish visibility toggle. This is publishing, not selling; the paid report-marketplace tools (purchase_report, list_my_purchases, connect_stripe_account) remain unreleased.
Tool
What it does
publish_report
Publish a saved report to your public profile (@handle) as a shareable /r/[slug] page
unpublish_report
Take a previously published report private again
search_reports
Search the public report catalog by ticker, author, or keyword (keyword catalog search)
publish_thesis / unpublish_thesis
Toggle a saved thesis public / private on your profile — parity with publish_report
publish_claim / unpublish_claim
Toggle a saved claim public / private on your profile — parity with publish_report
Accuracy proof — measured source of truth is docs/accuracy/baseline.json (current snapshot: see baseline.json for the latest figure on modern-era ≥2010 S&P 500 FY filings), citable to FactSet PIT / FASB ASC / Penman, reproducible via duckdb -c ".read scripts/accuracy/accuracy_check.sql"
For private or contractual matters (DPAs, procurement, DDQs, enterprise SLAs): support@valuein.biz.
Contributions — examples, notebook improvements, documentation fixes, query recipes — are very welcome. See CONTRIBUTING.md for the workflow and CODE_OF_CONDUCT.md for community standards.
This repository is provided for research and educational purposes. It is not investment advice. No warranty of fitness for any particular trading, investment, or regulatory purpose is implied.
