EdgarParser MCP

Cite a registry-backed concept by returning the canonical concept value and the filing prose around that value from MD&A, notes, risk factors, and optional cached extraction spans. Use `cite_concept` for metric-anchored narrative joins (concept value first → find the prose around it). For question-shaped narrative retrieval (no anchoring concept), use `get_filing_evidence` instead. The two tools are sharply distinguished: `cite_concept` ALWAYS resolves a canonical concept value and returns the narrative around it; `get_filing_evidence` runs a source-pack planner and surfaces evidence for an arbitrary query. Discovery: choose concept_name from the v1 concept registry (data/concept_registry_v1.json) or from get_statement output, then pass the canonical name exactly. Each citation includes corpus_coverage. Use Edgar mint fields only when corpus_coverage="gap". Treat corpus_coverage="unknown" exactly like "covered": attempt the corpus excerpt service, then fall back to unverified if the corpus cannot resolve it. For gap citations, corpus_content_hash is sha256 over the ENTIRE content stream named by locator.content/locator.content_norm (whole cached filing markdown or whole flattened document text), not over the cited span; recompute that full stream and use locator to select the span within it.

Compare one registry-backed concept across a caller-provided list of filers. This is cross-filer comparison, not search: caller ticker order is preserved, and partial coverage is returned per row with available=false. Discovery: choose concept_name from the v1 concept registry (data/concept_registry_v1.json) or from a prior get_statement/get_concept call, then reuse that exact canonical name for every ticker.

Compare structured filing tables across caller-provided tickers in one response. Preserves ticker order and returns per-ticker availability, matching table metadata, and optionally hydrated table rows.

Return a cache-only time series for a registry-backed concept over a period range. v1 uses the latest filing's reported series and has no restatement awareness: it does not return restated or original_value fields. Discovery: choose concept_name from the v1 concept registry (data/concept_registry_v1.json), get_statement output, or a successful get_concept call before requesting the trend.

Show cached data availability for one filing across XBRL, sections, tables, extraction schemas, and markdown. Read-only; does not populate caches.

Resolve a short-lived artifact handle issued by get_filing_sections and run scratch extraction for the requested schema via /api/documents/scratch-extract, without creating a canonical filing identity. Discovery: choose schema_name from list_extraction_schemas and pass the artifact_handle returned by get_filing_sections(output="file"). Local file paths and unregistered bytes are never accepted.

Get a registry-backed financial concept value from cached XBRL financials. v1 resolves tag-backed concepts only and returns available=false for derivation or unsupported concepts. It never warms caches; call get_financials first when cache_status is cold. Discovery: choose concept_name from the v1 concept registry (data/concept_registry_v1.json) or from statement rows returned by get_statement. Pass the canonical concept name exactly.

Discover SEC event filings by ticker/CIK, filing-date range, and form type. Use this for deal, financing, proxy, filed-communication, and status-update materials that are not tied to a fiscal quarter's 10-K/10-Q. Do not pass 10-K or 10-Q here; use get_filings for periodic filing discovery, or get_filing_document/get_filing_sections when periodic filing content is needed. Event-form examples include 8-K, 425, proxy forms, S-3/S-3ASR, S-4, FWP, 424B*, 8-A12B, CERT, and SC 13D. Returns accession, issuer CIK, form, filing date, primary document URL, and deterministic event_type labels; it does not perform broad corpus search.

Periodized counts (and optional hits) for langextract spans across a YYYY-Qn/YYYY-FY period range. ISO dates are not accepted. Cache read only. For raw cross-filing hits, use search_extractions.

Get exact cover-page DEI facts from a 10-K/10-Q, including citation-ready source metadata. Use this for outstanding-share questions instead of balance-sheet common-stock rows or weighted-average share metrics. Related tools: get_filing_document for markdown, get_filing_evidence for qualitative evidence, and get_filing_extractions for cached structured spans.

Get a SEC filing as readable markdown. Returns sectioned markdown with ## SECTION: headers. Supports section filtering and pagination via char range or max_chars cap. Pass accession plus cik/form_type/primary_document from get_event_filings to read an exact event filing without falling back to the latest filing for a fiscal quarter. Period-keyed reads are cache backed; exact-accession reads are fetched live. sections accepts canonical keys such as item_1a, item_7, item_7a, item_8, part1_item1, part1_item2, earnings_release, and proxy_statement; Item notation such as "Item 7" is also accepted. Common aliases include MD&A, Risk Factors, Financial Statements, Notes, Debt, Leases, Non-GAAP reconciliation / non_gaap_reconciliation, Director Compensation, Voting Rights, Election of Directors, and Proposal 1. For narrow topical phrases inside a filing section, call search_filing_text first and then read the returned section key or char range with get_filing_document. Related tools: get_filing_evidence plans evidence retrieval, get_filing_cover_facts reads exact DEI facts, and get_filing_extractions returns cached structured spans. char_start/char_end are always full-document offsets; offset_frame="document" or offset_frame="auto" is accepted for compatibility and ignored. Do not use offset_frame="scoped" here; use corpus filings_read for section-scoped offsets. The top-level response includes corpus_coverage; document_id, corpus_content_hash, and locator are emitted only for parser-owned gaps. Treat corpus_coverage="unknown" exactly like "covered": attempt the corpus excerpt service, then fall back to unverified if unresolved. For gap responses, corpus_content_hash is sha256 over the ENTIRE content stream named by locator.content/locator.content_norm, not over the returned slice; recompute that full stream and use locator to select the slice within it.

Plan and retrieve filing evidence in one call for a qualitative SEC filing question. The source planner is internal; inspect its output by setting include_planner_trace=true, or by reading the X-Edgar-Planner-Trace response header when using the HTTP route directly. For metric-anchored joins from a concept value to supporting prose, use cite_concept instead once that Phase 6 tool is shipped. Supported task_intent values include regulatory_risk, concentration_risk, acquisition_strategy, revenue_disaggregation, debt_terms, deal_status, security_offering_terms, and guidance_actuals; deal_terms is accepted as a deal_status alias for merger/acquisition-status questions. For event backed intents, pass filing_date_from/to and form_types when known. Related tools: get_filing_document for source markdown, get_filing_cover_facts for exact cover facts, and get_filing_extractions for cached structured spans. Evidence rows include corpus_coverage. Use document_id, corpus_content_hash, and locator only on rows where corpus_coverage="gap". Treat corpus_coverage="unknown" exactly like "covered": attempt the corpus excerpt service, then fall back to unverified if unresolved. For gap rows, corpus_content_hash is sha256 over the ENTIRE content stream named by locator.content/locator.content_norm (whole cached filing markdown or whole flattened document text), not over the cited span; recompute that full stream and use locator to select the span within it. For table-kind rows, top-level char_start/char_end are a legacy table-ordinal anchor retained for compatibility, not character offsets; the locator object is authoritative for table rows.

Return cached langextract spans for one filing, or fetch the filing and run extraction on cache miss. Use this for ticker/year/quarter-keyed filings. Related tools: get_filing_document reads markdown, get_filing_evidence plans qualitative evidence, and get_filing_cover_facts returns DEI facts.

Parse qualitative sections from one filing resolved by ticker/year/quarter. Required call shape: `get_filing_sections(ticker="MSCI", year=2025, quarter=4, sections=["item_1", "item_7"])`. This tool does not accept accession-only calls. If you only have an accession, call get_filing_document for readable markdown, or recover the ticker/year/quarter with get_filings/get_event_filings before requesting sections. Do not pass `form_types`, `forms`, `limit`, `years`, or `period`. Section filters accept canonical keys like "item_1" and "part1_item2", or filing headings like "Item 1. Business". Use source='8k' for 8-K earnings release sections or source='proxy' for DEF 14A proxy statements. Use source='20f' or source='6k' for foreign private issuer filings exposed as whole-document sections. get_filings does not list proxy filings; use this routed access path directly. Do not use as the first step for broad qualitative questions; prefer corpus search (research-corpus-mcp.filings_search) when available, or search_filing_text once it lands. Pass explicit sections only after evidence discovery has identified them. Related tools: get_filing_document for readable markdown, get_filing_evidence for question-shaped evidence, and get_filing_cover_facts for exact DEI cover-page facts.

Fetch structured filing tables. Listing modes return metadata only; supplying table_id returns a single table with full row data. Pass accession to require the returned table cache to match a specific resolved filing identity. Omit source or use source='auto' for ordinary 10-K/10-Q tables. Use source='proxy' for DEF 14A proxy tables; use source='20f' or source='6k' with accession to target a specific foreign issuer filing from get_filings. Related tools: get_filing_document reads markdown, get_filing_evidence finds prose evidence, and get_filing_cover_facts returns exact cover-page DEI facts.

Fetch SEC filing metadata for one fiscal period. Required call shape: `get_filings(ticker="MSCI", year=2025, quarter=4)`. This is not a recent-filings/list/search endpoint. Do not pass `form_types`, `forms`, `limit`, `years`, or `period`. For annual 10-K discovery use quarter=4. For quarterly 10-Q discovery use the target fiscal quarter. Defaults to 10-Q, 10-K, and 8-K earnings release filings. Use source='20f' or source='6k' to list foreign issuer filings and discover accessions for targeted table retrieval. Do not use source='proxy' here: get_filings does not list DEF 14A proxy filings. For proxy discovery, call get_event_filings with form_types=['DEF 14A'] and a filing-date range. For proxy content, call get_filing_document, get_filing_sections, or get_filing_tables with source='proxy' and quarter=4 because DEF 14A is annual.

Extract all financial facts from one fiscal filing. Required call shape: `get_financials(ticker="MSCI", year=2024, quarter=4, full_year_mode=True)`. This is not a multi-year/list endpoint. Do not pass `years`, `period`, `limit`, `statement`, `forms`, or `form_types`. For a five-year history, call this tool once per target fiscal period, or use get_statement range mode when a bulk template-backed statement is acceptable. Returns structured JSON with income statement, balance sheet, and cash flow data. If returned, `scope_warnings` flag mixed-scope cash-flow facts. `scope_bridges` are returned only when distinct, period-aligned continuing- or discontinued-operations CFO facts support a same-scope candidate; otherwise the warning reports `bridge_status="unavailable"` and the raw filing facts remain authoritative.

Fetch an issuer's SEC submissions header by CIK. Returns the issuer name, tickers, exchanges, and fiscal year end directly from the public SEC submissions JSON. This tool does not require EDGAR_API_KEY. CIK must contain at most 10 digits; shorter values are zero-padded to the SEC's 10-digit format.

Get a specific financial metric by common name or XBRL tag and return current/prior values with YoY comparison. For guessed or user-facing names, call search_metrics or list_metrics first and pass an exact discovered metric_name into this tool; do not retry near-miss names blindly. Optional role filters accept friendly statement roles such as ["cash_flow"] or ["balance_sheet"]. If the response says the cache is cold, call warm_metric_cache with warm_hint.body.items, poll warm_metric_cache_status, then retry get_metric. Cash-flow metrics may include `scope_warnings` and `scope_bridges`; treat bridges as adjustment candidates for same-scope analysis, not replacements for reported facts. Filing-native operational KPI misses include a remediation hint for get_operational_kpi_drivers when the name looks like a non-XBRL operating metric. Scope bridges require direct, period-aligned CFO-scope facts; component-level wind-down or working-capital facts remain evidence and do not create calculated continuing-operations CFO. Discovery: call list_metrics or search_metrics for the same ticker, year, quarter, source, and date_type before choosing metric_name. Use get_metric for one period and get_metric_series when the same metric is needed across periods.

Fetch one metric across multiple periods in a single call, using cache-first execution and per-period status reporting. Optional role filters are applied per period before the best match is selected. Pass `axis_key` exactly as returned by search_metrics/list_metrics when the user needs a dimensional fact such as product revenue. For FCF, FCF margin, cash conversion, or trend questions, inspect per-period `scope_warnings` and `scope_bridges`. Bridges require direct, period-aligned CFO-scope facts; when a warning instead reports `bridge_status="unavailable"`, present the raw trend and underlying evidence without manufacturing a same-scope value. `metric_name` must be an exact discovered metric name, not a natural-language description. If the metric label came from the user, a filing heading, or your own shorthand, call `search_metrics` or `list_metrics` for the ticker/period first and pass the returned `metric_name`/`metric_id` exactly. Do not guess nearby names such as `Revenues`, `capital expenditures`, `cash flow from operations`, or `GrossBookingValue`; use discovered values such as `Revenue`, `NetCashProvidedByUsedInOperatingActivities`, or `PaymentsToAcquirePropertyPlantAndEquipment` when those are the returned matches. Required parameters are `metric_name`, `end_year`, and `end_quarter`; do not use `metric`, `years`, or `period`. If the result says "Metric series has no values," treat it as a metric-name miss and retry after discovery unless the message explicitly says uncached. If the message says uncached, call `warm_metric_cache` with `warm_hint.body.items`, poll `warm_metric_cache_status`, then retry this tool. Discovery: call list_metrics or search_metrics for the same ticker, period, source, and date_type to choose metric_name. Use get_metric for a single period and get_metric_series for multi-period retrieval.

Return the strict producer-owned operational-KPI driver row DTO from `/api/operational-kpis/drivers`. Use these versioned, calculation-ready rows for programmatic consumers and cross-transport interoperability. `topic` optionally scores rows against a requested metric. Set `filter_to_topic=true` to exclude rows with no positive topic match. `include_non_numeric` preserves explicitly non-numeric observations when the producer has them. The MCP transport returns the HTTP data payload unchanged and does not infer missing semantic fields. For exploratory filing research that needs narrative change amounts, constant-currency driver commentary, or filing-local label discovery, use `get_operational_kpi_drivers`; that distinct research tool is not a mirror of this DTO.

Return structured operational KPI values and driver growth rates from a filing's MD&A/earnings discussion. Use this for non-XBRL operating metrics such as Gross Bookings, MAPCs, Trips, customer counts, revenue driver bridges, take-rate inputs, segment growth rates, constant-currency growth, and volume-vs-price decomposition. It discovers candidate labels from the filing document and returns citation-ready rows with snippets; it does not run the slower generic KPI catalog extractor. For the strict producer-owned operational-KPI row DTO mirrored from HTTP, use get_operational_kpi_driver_rows instead.

Return a bulk structured statement (income statement, balance sheet, or cash flow statement) from a deterministic v1 statement template and the v1 concept registry. Supports single-period mode with year+quarter and range mode with period_from+period_to; the two modes are mutually exclusive. v1 templates contain tag-kind concepts only, so computed or derivation rows such as margins and ratios belong in separate concept_trend calls. Note for model_build / AI-excel-addin populator consumers: this tool is NOT pre-approved as a model_build input. Production model_build flows must continue to use `/api/financials` + `/api/metric/series` until model_build explicitly accepts this tool's contract, provenance shape, error semantics, and `concept_registry_version` pinning. `get_statement` is additive and opt-in for ad-hoc use, FinanceBench harness, and standalone Edgar product.

List the document extraction schemas available through the EDGAR API.

List available metric tags for a filing period so an agent can choose an exact metric_name before calling get_metric. Cash-flow candidates may carry `scope_warning` and `scope_bridge_ids`; validate those before using CFO in margin or trend formulas. Debt candidates may carry `debt_component_kind` values such as `instrument_principal`, `coupon_rate`, `finance_lease`, `other_notes`, or `total_debt_rollup`; consumers own any source-basis sum.

Search cached langextract spans across filings using structured filters. Periods must use YYYY-Qn or YYYY-FY, not ISO dates. Read-only; cache misses are reported and never trigger LLM extraction.

Cross-filing search over an Edgar table index for a ticker. Matches on table description, table_type, and section. Returns metadata only; use get_filing_tables with the table_id to fetch full table contents. Use search_filing_text for same-filing prose search.

Search cached markdown within one SEC filing keyed by ticker, year, quarter, and source. Read-only: cold caches return cache_status='cold' and are not warmed. CC5 prefix exception: although search_* usually denotes cross-filing search, search_filing_text is intentionally same-filing only and requires the per-filing ticker/year/quarter inputs. Use search_filing_tables for cross-filing table metadata search. Hits include corpus_coverage. Mint fields appear only when Edgar is the authoritative parser-side source for the cited span. Treat corpus_coverage="unknown" exactly like "covered": attempt the corpus excerpt service, then fall back to unverified if unresolved. For gap hits, corpus_content_hash is sha256 over the ENTIRE content stream named by locator.content/locator.content_norm (whole cached filing markdown), not over the hit span; recompute that full stream and use locator to select the span within it.

Search available filing metrics by natural-language query and return ranked candidates. Optional role filters accept friendly statement roles such as ["cash_flow"], ["balance_sheet"], or ["income_statement"]. Cash-flow matches may carry mixed-scope warnings and bridge IDs; inspect the returned top-level `scope_bridges` before using CFO in FCF-style formulas. Debt refinance/tranche queries surface structured XBRL components with `debt_component_kind`; this tool does not pre-sum refinanceable debt.

Enqueue async cache warming for metric periods. Paid/internal API tiers only. Each item requires ticker, year, quarter, and optional full_year_mode. Returns a job_id for warm_metric_cache_status polling.

Poll an async metric cache warming job by job_id. Discovery: job_id is returned by warm_metric_cache; do not invent one.