Complete reference for all 22 Metric Duck MCP tools available via the remote server at mcp.metricduck.com
Contract version 0.9.0 — auto-derived from mcp-worker/tool-contract.json
Entity-axis orientation map for one company. Returns identity, filing inventory by form type, signal availability inline, indexed range, and ranked drill-down pointers — all in one call, so you can see which axis (signal, source, metric) to descend. Accepts a ticker, name, or CIK, so it resolves the entity too; search_companies is the resolver for picking between candidates.
Accepts ticker, company name, or 10-digit CIK. For delisted companies, prefer the CIK.
query[string]requiredCompany name, ticker, or 10-digit zero-padded CIK. Free-text fuzzy match.
include_delisted[boolean]optionaldefault: falseInclude delisted companies in the fuzzy match.
GET /api/v1/companies/search + /data-availability + /signal-summary"What signals fire for US Steel?" or "Tell me about NVDA"Find companies matching a name, ticker, or keyword.
query[string]requiredSearch query (company name, ticker, or keyword).
limit[integer]optionaldefault: 5range: 1–20Max results to return.
GET /api/v1/companies/search"Find semiconductor companies" or "Search for NVDA"Everything about a company in one call: profile, profitability (ROE, ROIC, margins), balance-sheet strength, cash-flow quality, valuation multiples, capital allocation, 8-quarter trends, and latest filing-intelligence highlights.
ticker[string]requiredCompany ticker symbol (e.g., AAPL).
depth[string]optionaldefault: coreHow much detail to include. snapshot = thinnest, core = default, full = every section.
GET /api/v1/companies/{ticker}/overview-page"Tell me about Apple" or "Give me a full overview of COST"Daily end-of-day stock prices (open/high/low, close, split- & dividend-adjusted adj_close, volume) for ~8,400 US exchange-listed companies. Rows exist only for trading days — the data is the trading calendar. When the window spans 2+ days it also reports the first/last close and the period return on both close and adj_close. Sourced from a market-data feed, not SEC filings.
Markets trade only on business days: start_date returns the price on/after that date; end_date returns the price on/before it; omit both for the latest price.
ticker[string]requiredCompany ticker symbol (e.g., AAPL). US exchange-listed, 1–5 letters.
start_date[string]optionalWindow start (YYYY-MM-DD). First row is this date or the next open day (price on/after). Omit end_date for just the on/after price.
end_date[string]optionalWindow end (YYYY-MM-DD). Last row is this date or the prior open day (price on/before).
limit[integer]optionaldefault: 30range: 1–2000Max rows to return.
GET /api/v1/market/daily/{ticker}"AAPL close on 2025-07-28" or "DKNG total return Jan 2025 → Feb 2026"Multi-period financial statement data: income statement, balance sheet, cash flow. Quarterly or annual, up to 10 years.
ticker[string]requiredCompany ticker symbol (e.g., MSFT).
period[string]optionaldefault: quarterlyReporting period.
years[integer]optionaldefault: 2range: 1–10Number of years of history.
statements[array]optionaldefault: [income, balance, cashflow]Which statements to include. Pass any subset.
vantage_date[string]optionalGET /api/v1/companies/{ticker}/income-statementGET /api/v1/companies/{ticker}/balance-sheetGET /api/v1/companies/{ticker}/cash-flow"Show me MSFT revenue trend last 5 years" or "AAPL quarterly cash flow"Benchmark a company against its sector peers across 70+ metrics with sector percentile rankings, 8-quarter trends, and relative strengths/weaknesses.
ticker[string]requiredCompany ticker symbol to benchmark.
custom_peers[string]optionalComma-separated tickers to use instead of sector defaults.
peer_mode[string]optionaldefault: sectorHow peers are selected. sector = SIC peers, tags = thematic-tag peers.
metrics[string]optionalGET /api/v1/peers/{ticker}"How does MSFT compare to its peers?" or "Compare Google to its sector"Filter companies by financial metrics. Define metric thresholds with operators (gt/lt/between/...) and rank results by any metric.
filters[array]requiredArray of metric filters. Each filter: { metric_id, operator, value | min_value | max_value, period_type? }.
each: { metric_id, operator, value, min_value, max_value, period_type }
sort_by[string]optionalMetric to sort results by.
sectors[array]optionalOptional sector codes to restrict the universe.
required_tags[array]optionalOnly include companies with these thematic tags.
excluded_tags[array]optionalExclude companies with these thematic tags.
limit[integer]optionaldefault: 20range: 1–50Max results.
POST /api/v1/screener/screen"Find high-ROIC tech stocks" or "Screen for companies with FCF yield > 8%"Browse SEC filings for a company with section-level inventory — available sections, word counts, chunk counts, and table counts per filing. Use this to discover what's available before reading specific sections.
ticker[string]optionalCompany ticker symbol.
cik[string]optionalform_type[string]optionalSEC form type filter.
form_subtype[string]optional8-K subtype derived from section inventory (earnings, event, transcript, other).
years[integer]optionaldefault: 2range: 1–7Years of history.
fiscal_year[integer]optionalFilter to a specific fiscal year.
fiscal_period[string]optionalFilter to a specific fiscal period (Q1–Q4 or FY).
vantage_date[string]optionalinclude_delisted[boolean]optionaldefault: falseInclude filings from delisted companies.
GET /api/v1/filings/sections/summary"What filings does Apple have?" or "Show me Tesla's 10-K filings"Read specific sections from SEC filings with pagination. Supports 70 section types for 10-K/10-Q (risk_factors, mda_results_operations, footnote_debt, …) and earnings sections for 8-K filings.
Provide either ticker or cik (CIK is required for delisted companies).
ticker[string]optionalCompany ticker symbol.
cik[string]optional10-digit SEC CIK (zero-padded). Use instead of ticker for delisted companies.
include_delisted[boolean]optionalAllow lookups against delisted companies.
section_id[string]optionalSection identifier (e.g., risk_factors, mda_results_operations).
accession_number[string]optionalSpecific filing accession number (default: latest).
form_type[string]optionalSEC form type filter.
fiscal_year[integer]optionalFilter to a specific fiscal year.
fiscal_period[string]optionalFilter to a specific fiscal period (Q1–Q4 or FY).
vantage_date[string]optionaloffset[integer]optionaldefault: 0≥ 0Chunk pagination start.
char_offset[integer]optionaldefault: 0≥ 0max_chunks[integer]optionaldefault: 10range: 1–10Chunks per page.
query[string]optionalOptional keyword to bias chunk selection.
include_companions[boolean]optionaldefault: falseFor Pattern 4 cross-filing 8-Ks (anchor + same-day companion). Expands companion section text inline.
companion_accessions[array]optionalCompanion accession list to expand. If omitted with include_companions=true, falls back to same-day discovery.
max_chars[integer]optionaldefault: 20000range: 2000–60000Response character cap. Larger = more content, more tokens.
preview_chars[integer]optionaldefault: 120range: 0–200GET /api/v1/filings/text"Show me Apple's risk factors" or "Read Tesla's MD&A section"Search raw XBRL facts by human-readable label, with dimensional breakdowns (segment, geography, product). Machine-readable SEC data that complements get_financials with granular detail.
ticker[string]requiredCompany ticker symbol.
search[string]requiredSearch by human-readable label. Comma-separated for OR (e.g., "revenue,product").
accession_number[string]optionalSpecific filing accession number (default: latest).
form_type[string]optionaldefault: 10-KFiling form type.
fiscal_year[integer]optionalFilter to a specific fiscal year.
fiscal_period[string]optionallimit[integer]optionaldefault: 50range: 1–200Max facts to return.
period_history[boolean]optionaldefault: falseGET /api/v1/companies/{ticker}/raw-facts"AAPL revenue by segment" or "UNH medical cost ratio"Compact signal map of a single filing — what's interesting and where, in ~30% of the tokens of get_filing_intelligence. Use this first to triage, then drill in with get_filing_section for narrative content.
ticker[string]requiredCompany ticker symbol.
lens[string]optionalOptional lens to bias the signal map (earnings_quality, debt_stress, risk_trajectory, competitive_position, management_outlook).
vantage_date[string]optionalGET /api/v1/companies/{ticker}/filing-intelligence"What's in Apple's latest 10-K?" or "Risk-trajectory lens for Tesla's 10-Q"Cross-company screening by qualitative signals — tone shifts, earnings beats/misses, guidance moves, new risks, IR events — across SEC filings, 8-K earnings releases, transcripts, and IR press releases. Verifiable signals (not LLM scores).
signals[array]requiredSignal IDs to screen for. See enum below.
ticker[string]optionalOptional single-ticker filter for per-company inventory.
sectors[array]optionalSector codes (TECH, HEALTH, FIN, RE, CONS_DISC, CONS_STAPLES, IND, MAT, ENERGY, UTIL, TRANSPORT, COMM, OTHER).
recency_days[integer]optionaldefault: 90range: 1–365Only include filings from the last N days.
limit[integer]optionaldefault: 20range: 1–50Max results.
match_mode[string]optionaldefault: allall = every signal must fire on the same row; any = any signal qualifies.
order_by[string]optionaldefault: recencyrecency = newest first; market_cap = largest companies first (recency tiebreaker).
since_date[string]optionalInclusive lower bound on filing/event date (YYYY-MM-DD).
until_date[string]optionalInclusive upper bound on filing/event date (YYYY-MM-DD).
agreement_type_filter[string]optionalPOST /api/v1/filing-intelligence/screen"Which tech companies have cautious management?" or "Who beat earnings this quarter?"Full-text search across all SEC EDGAR filings (not just MetricDuck-tracked tickers). Returns aggregated company / form-type / industry stats plus per-result section enrichment for 10-K and 10-Q hits.
query[string]optionalEDGAR full-text query.
ticker_lookup[string]optionalFilter to a specific ticker (uses CIK lookup).
form_type[string]optionalSEC form type filter.
company[string]optionalFilter by company name.
date_from[string]optionalStart date (YYYY-MM-DD).
date_to[string]optionalEnd date (YYYY-MM-DD).
limit[integer]optionaldefault: 10range: 1–100Max results.
sections[boolean]optionaldefault: trueWhether to enrich first 10 hits with section context.
rank_by[string]optionaldefault: dateSort order: date (newest) or relevance.
GET https://efts.sec.gov/LATEST/search-index"Which companies discuss AI agents in 10-Ks?" or "Find proxy fights in 2025"8-K earnings-RELEASE headline financials (revenue, net income, operating income, diluted EPS) — the figures management reports on release day, typically weeks before the audited 10-Q/10-K. Each figure carries a per-figure deep-link + verbatim quote into the source exhibit when the API has an attested receipt.
Distinct from get_financials (audited XBRL, filed later) — this is the earliest-available, as-reported release figure. A figure without a receipt is still shown; absence of a receipt is not evidence the value is wrong.
ticker[string]requiredCompany ticker symbol (e.g., NVDA). Must be exact.
quarters[integer]optionaldefault: 4range: 1–8Number of most recent quarters to return (1-8, default 4).
vantage_date[string]optionalGET /api/v1/earnings/{ticker}/history"What did NVDA report for its latest quarter's revenue?" or "TSLA's last 8 quarters of earnings releases"Cross-feed temporal join: stitches together transcript guidance items, the SEC filing for the period, and the actual results 8-K for the same fiscal_period. Answers 'did they hit guidance?' for a single ticker and quarter.
ticker[string]requiredCompany ticker symbol.
fiscal_period[string]optionalOptional period filter (e.g., Q2-2025). Omit for latest.
GET /api/v1/companies/{ticker}/guidance-vs-actual"Did NVDA hit Q1 guidance?" or "Show DOW guide vs actual for FY24"Cross-quarter trajectory view of earnings-call signals for one ticker — guidance deltas, strategic priorities, Q&A aggregates (deflection rate, concerns retained, forward commitments), macro and competitive stance, capital-allocation posture, scenario sensitivities. Aligns calls by event date for multi-quarter pattern detection.
ticker[string]requiredCompany ticker symbol.
n_quarters[integer]optionaldefault: 4range: 2–8How many recent earnings calls to compare.
dimensions[array]optionalFilter to specific trajectory axes. Omit for all.
vantage_date[string]optionalGET /api/v1/companies/{ticker}/transcript-trajectory"How has NVDA's guidance discipline trended?" or "AT&T tone over last 4 calls"Time series for a single metric across recent fiscal periods. Each row carries fiscal_year + fiscal_period for authoritative 'Q2 FY2025' lookups, plus filing accession for citation.
ticker[string]requiredCompany ticker symbol.
metric_id[string]requiredMetric identifier (e.g., gross_margin, fcf, roic).
period_type[string]optionaldefault: QPeriod granularity: Q (quarterly), FY (annual), TTM (trailing).
window[integer]optionaldefault: 20range: 1–40How many periods to return.
vantage_date[string]optionalGET /api/v1/companies/{ticker}/metrics/history"AAPL gross margin trend" or "MSFT FCF history annual"The derivation of one COMPUTED metric — its human-readable formula plus immediate inputs (each value + source), one level at a time. The audit / verify affordance for derived figures (margins, ratios, ROIC, FCF): use it to show HOW a metric is computed or WHICH definition was used, not to fetch the value.
Drillable: a derived input points to its own lineage (call again with that symbol); a base input is an as-filed XBRL fact.
ticker[string]requiredCompany ticker symbol. Must be exact.
metric[string]requiredMetric id of a COMPUTED metric (e.g., net_margin, roic, fcf, ev_ebitda).
period_type[string]optionaldefault: QPeriod granularity: Q (quarterly), FY (annual), TTM (trailing).
fiscal_year[integer]optionalPin the fiscal year (e.g., 2025). Omit for the latest period.
fiscal_period[string]optionalPin the fiscal period (Q1–Q4, FY). Omit for the latest.
segment[string]optionalReporting segment id. Omit for the consolidated figure.
GET /api/v1/companies/{ticker}/metrics/lineage"How is AAPL's net_margin calculated?" or "Audit MSFT ROIC for FY2024"IR earnings-PRESENTATION-DECK text — forward guidance, operational KPIs, and segment outlook that live ONLY in a company's investor-relations slide deck, not in the SEC 8-K/10-Q release text or XBRL. The channel to reach for when get_metric_history / get_filing_section / get_xbrl_facts come up empty on a guidance or KPI question.
Pass a query to land on the exact slide page; omit it for a bounded prefix of the latest deck. Resolve by ticker or cik.
ticker[string]optionalCompany ticker symbol (e.g., OXY). Required unless cik is provided.
cik[string]optional10-digit SEC CIK as an alternative to ticker.
fiscal_year[integer]optionalrange: 2000–2100Fiscal year of the deck (e.g., 2024).
fiscal_period[string]optionalFiscal period: 'Q3' (with fiscal_year) or combined '2024Q3'. Omit for the latest deck(s).
query[string]optionalKeyword filter over slide text — returns only pages matching every word; cites the exact page.
mode[string]optionalGET /api/v1/ir-documents"OXY Q3 2024 production guidance" or "NCLH berth-capacity outlook"A company's IR event CALENDAR — upcoming and past investor-relations events (earnings calls, annual/shareholder meetings, broker conferences, investor days) with the materials attached to each (deck, webcast, press release, transcript). The when/what-is-attached surface — distinct from get_ir_documents (a document's content) and compare_earnings_calls (what management said).
Returns upcoming (soonest-first) + past events with material chips; a chip's material_id is the get_ir_documents doc_id. Coverage is honest — a not-yet-harvested company says so.
ticker[string]requiredCompany ticker symbol (e.g., AAPL). Required.
GET /api/v1/companies/{ticker}/events"When does AAPL next report?" or "What IR events did NVDA have this year?"Per-fiscal-period earnings DOCUMENT INDEX — one row per quarter/year gathering the documents for that reporting period: the 8-K press release, the earnings-call transcript (with prepared-remarks / Q&A deep-links), the 10-Q/10-K, the IR presentation deck(s), and the webcast event. Each artifact is present or honestly absent — the “what can I pull for this quarter, and how do I reach it” map.
A NAVIGATION index, not figures — for the release NUMBERS use get_earnings, for audited statements get_financials, for the IR event CALENDAR get_company_events, for a deck's slide TEXT get_ir_documents, for what management SAID on the call compare_earnings_calls.
ticker[string]requiredCompany ticker symbol (e.g., MRK). Required.
limit[integer]optionalrange: 1–40Most-recent fiscal periods to return, newest first (1-40, default 12).
GET /api/v1/companies/{ticker}/earnings-reports"What documents does MRK have for its last earnings?" or "Give me AMD's earnings decks and transcripts by quarter"Universe-wide watermark feed: every filing that landed since a date floor. Pass your last-poll watermark to get only new filings. Single call regardless of portfolio size — the right primitive for event-driven workflows and daily portfolio checks.
since[string]requiredFiling date floor (inclusive). YYYY-MM-DD.
form_types[array]optionalOptional SEC form type filter (e.g., ['8-K', '10-Q']).
form_subtypes[array]optional8-K subtype filter computed from section inventory. Implies 8-K only.
tickers[array]optionalOptional portfolio filter (up to 50 tickers).
limit[integer]optionaldefault: 50range: 1–100Max results, sorted by filing date DESC.
GET /api/v1/filings/recent"What 8-Ks landed today?" or "New filings for my watchlist since Monday"get_company_overview for a comprehensive snapshot before drilling into specificsget_filing_index first to triage what's interesting in a filing — then get_filing_section to read the narrativeget_financials for raw numbers in DCFs; get_metric_history for a single metric across periodsscreen_companies with compare_companies for a complete screening workflowscreen_filing_signals for cross-company qualitative screening (tone, beats, guidance, IR events)list_recent_filings as the watermark feed for event-driven workflows and daily portfolio checksget_xbrl_facts for industry-specific metrics or dimensional breakdowns (segment, geography)