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.
Connector