Verify Fact Lineage
verify_fact_lineageUse this tool when the user asks BOTH what a financial figure is AND which filing reported it — e.g. "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." 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 identifiers and returns no financial data. Use this INSTEAD OF get_company_fundamentals when the user explicitly wants the filing/form type or the accession ID — get_company_fundamentals returns metrics across periods but omits filing provenance.
Two lookup modes: (1) by fact_id (deterministic SHA-256 identity) or (2) by concept name plus a ticker (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 (no look-ahead); check _meta.pit_safe.
DURATION: a single 10-K tags BOTH a 12-month figure and a 3-month Q4 stub at the same period_end; on a tie this returns the longer (headline) window, and every result carries period_type and period_span_days so a 3-month stub is never mistaken for the annual figure.
Provide either fact_id or concept (required). Returns DATA_NOT_AVAILABLE_FOR_PERIOD if no matching fact exists (NO_FACTS_BEFORE_AS_OF_DATE when a concept was only filed after as_of_date). Available on all plans.
Third mode: derived_id (a drv1: id a tool gave you for a COMPUTED figure) re-reads the input facts, re-runs the registered formula and returns the recomputed lineage.display with a derived block listing the inputs; verified:false plus an error code says why it could not be proven. ticker is required by the schema but the id carries its own filer.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'. | |
| concept | No | Standard concept to look up the most recently known fact for (see the enum for the full fundamentals + capital-allocation set). Use this when you don't have a fact_id. Provide either concept OR fact_id. | |
| fact_id | No | 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). | |
| as_of_date | No | Point-in-time cutoff (YYYY-MM-DD) used with `concept` — returns the latest fact whose 10-K/10-Q was accepted by SEC on or before this date (true PIT, no lookahead; any calendar date works). Canonical name across the suite; supersedes the legacy `period_end`. | |
| derived_id | No | Citation id of a computed figure (`drv1:...`), exactly as a tool result gave it to you. Re-derived from its input facts; `as_of_date` applies the point-in-time cut to every input. | |
| period_end | No | [DEPRECATED — pass `as_of_date` instead.] Filing-acceptance cutoff (YYYY-MM-DD) used with `concept`; despite the name it filters on filing accepted_at, not the returned fact's period_end. Kept one release for back-compat. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _meta | Yes | Provenance envelope — data lineage for every MCP response | |
| error | No | Derived mode only, with verified:false: why the figure could not be proven. Permanent: INVALID_ARGUMENT, UNKNOWN_FORMULA, INPUT_NOT_FOUND, INPUT_UNAVAILABLE, UNDEFINED_RESULT, ENTITLEMENT_DENIED. Transient (retry): UPSTREAM_UNAVAILABLE, STALE_SNAPSHOT, RATE_LIMITED, INTERNAL_ERROR. | |
| derived | No | Derived mode only: the formula and input facts behind the recomputed `lineage`. | |
| lineage | No | Full provenance for one fact. Identity: fact_id, entity_id, ticker, company_name, concept, standard_concept, accession_id. Value: numeric_value (raw), `display` (the SAME number already rendered — "$391.04B" — QUOTE THIS rather than re-rounding numeric_value yourself), unit, plus derived_quarterly_value/derived_quarterly_display (a Q2/Q3 10-Q states year-to-date, so the quarter and the filing are different numbers). Filing: source_url, inline_viewer_url, document_url, filing_date, form_type, accepted_at. Duration: period_start, period_end, period_span_days, and period_type (instant | quarterly | half_year | nine_month | annual | duration) so a 3-month stub is never mistaken for the 12-month figure — a 10-K tags BOTH at the same period_end. ⚠️ There is no `value` key and no `cik` key; the fields are named exactly as emitted. | |
| verified | Yes | True when the fact was located and its provenance resolved | |
| lookup_by | Yes | How the fact was located: 'fact_id' or 'concept' |