MetricDuck — Financial Analysis MCP Server

Retrieve 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). Reach for this for calendar questions: - "When does {ticker} next report / hold its earnings call?" → the UPCOMING list (scheduled events) - "What IR events did {ticker} have this year?" / "was {ticker} at any conferences?" - "What materials are attached to {ticker}'s last earnings event?" Each event has: occurred_at (issuer-local datetime) + time_precision, event_type (verbatim/open vocab), the verbatim source title, and material chips — each material's `material_id` is the get_ir_documents doc_id (read a deck's slide TEXT with get_ir_documents, not here). Coverage is honest: if a company hasn't been harvested yet, that is stated — an empty result does NOT mean the company has no IR events. `last_checked_at` stamps the calendar's as-of time (events announced since are not shown). When the calendar has no events, the company's results announcements filed with the SEC (8-K Item 2.02 — usually the quarterly earnings release; last 24 months) are listed instead — past filing dates that show its reporting cadence, not a scheduled date. What management SAID on earnings calls (guidance/tone by quarter) → compare_earnings_calls. Not point-in-time: upcoming vs past is relative to today; for as-of work use a tool that takes `vantage_date` (e.g. list_filings, get_earnings).

Use this when the user asks for a quick read on one company now: the latest price, valuation, margins, cash flow, balance sheet and segment mix in one call; get_financials gives the multi-period statements, and get_metric_history one metric over time. Includes: current price, valuation (P/E, P/B, EV multiples, PEG), profitability (revenue, margins, returns), cash flow (OCF, FCF, yields), balance sheet (debt, equity, ratios), capital allocation (buybacks, shares outstanding, shareholder yield), business segment + geographic revenue mix (latest 10-K, with YoY change), latest earnings insights, and company flags. Latest snapshot only — use get_xbrl_facts for multi-period segment history, get_filing_index for a signal map of the latest filing, compare_companies for peer benchmarking, get_stock_price for a historical/as-of-a-date close or a return between two dates (the price here is current only). Not point-in-time. For "as of <past date>" work use the tools that take `vantage_date` (get_financials, get_metric_history, get_filing_section, get_filing_index) and get_stock_price for a past close. Those bound which filings are visible, not restated values: a later restatement or recast is served under the as-of citation, and the LOOK-AHEAD flag (get_financials, get_metric_history, get_filing_index) covers only a later amendment of the period's own filing. For figures as known then, pin get_xbrl_facts to the accession_number of the latest filing reporting the period (list_filings takes vantage_date); period_history=true gives figures as originally filed.

Use this when the user asks how a company compares with its peers or named rivals: a side-by-side table of ~70 metrics (latest TTM, FY or Q), its rank on ROIC, operating margin and revenue growth, and whether it leads or trails on them; screen_companies finds companies by criteria, and get_metric_history covers one company's past. Returns a side-by-side table covering valuation (P/E, P/B, EV/EBITDA, EV/Sales, FCF yield), profitability (gross/operating/net/EBITDA margins, ROE, ROA, ROIC), leverage & liquidity (cash, debt/equity, net debt/EBITDA, interest coverage, current ratio), efficiency (asset/inventory turnover, DSO, cash conversion cycle), and capital returns (dividend yield, dividend payout ratio, buyback yield, shareholder yield). Sector-inapplicable metrics are omitted (e.g. gross margin / FCF leverage for banks). Pass 'metrics' to focus the table on specific metric_ids. Each company's row is dated: 'Data through' is its latest reported period, and valuation multiples are priced at the last close on/before that period end (period-end LOCF) — NOT today's price, and the dates can differ across peers by a quarter. For a multiple AS OF a specific date, or at the live price, or a CUSTOM definition (e.g. lease-adjusted EV), assemble it from get_stock_price (price leg) + get_metric_history primitives. peer_mode controls peer selection: - 'sector' (default): auto-selected from same sector + similar market cap - 'tags': auto-selected by business model similarity (tag Jaccard) — better for cross-sector comparisons Override with custom_peers for specific matchups. The number of custom_peers is capped (up to 10 peers); exceeding it returns the limit and the count you asked for, so retry with that many. Use Cases: - "Compare AAPL vs MSFT" -> compare_companies("AAPL", custom_peers="MSFT") - "How does NVDA stack up in its sector?" -> compare_companies("NVDA") - "Dividend payout ratio: KO vs KDP/PEP/KHC" -> compare_companies("KO", custom_peers="KDP,PEP,KHC", metrics="dividend_payout_ratio,dividend_yield")

How has management's posture shifted across recent earnings calls? Cross-quarter trajectory view of transcript signals for a single ticker. This is MetricDuck's EARNINGS-CALL TRANSCRIPT tool (agents also look for this as get_earnings_call_transcript / get_earnings_transcript / get_earnings_call / search_earnings_calls). It aligns calls by event date and surfaces CROSS-QUARTER patterns; for ONE call's verbatim prepared remarks or Q&A, drill with get_filing_section(section_id="transcript_prepared_remarks" | "transcript_qa_session"). Output (coverage-dependent): a coverage table per quarter — event date, fiscal period, accession, status, and transcript Source tier (SEC-filed vs Issuer-published vs Machine-transcribed), surfacing NO_TRANSCRIPT / WAITING gaps (transcripts are management commentary, not SEC-filed facts). Then an aggregate-trajectory table (Q&A Deflection / Concerns Retained / Forward Commits — one row per scalar, one column per quarter), guidance deltas grouped by metric, and the per-quarter qualitative arrays for whichever dimensions you request, side-by-side so drift reads across columns. Drill hints are pinned to accessions. Use Cases: - "Deflection trend?" -> compare_earnings_calls("RDDT", n_quarters=8, dimensions=["hedges", "qa"]) - "Guidance discipline shifting?" -> compare_earnings_calls("NVDA", dimensions=["guidance"]) - "Strategic priorities + KPIs drift" -> compare_earnings_calls("PG", dimensions=["priorities", "kpi"]) For signal changes across many companies between two windows, use `screen_filing_signals` with since_date/until_date.

Use this when the user asks what a company just reported in its earnings release: the 8-K's headline income statement (revenue, operating income, net income, diluted EPS) and as-released cash flow (OCF, capex, FCF, with growth), typically weeks before the 10-Q/10-K that get_financials reads; get_earnings_reports lists the documents, not the figures. Often the only MetricDuck source for the fresh quarter's capex/OCF/FCF (the 8-K carries no XBRL, so get_financials/get_metric_history still show the prior quarter until the 10-Q lands). Distinct from get_financials (10-K/10-Q XBRL — filed later, GAAP-consistent) and get_company_overview (its earnings section is prose, no figures). Each figure carries a deep-link + verbatim quote when the release has an attested receipt. Use Cases: - "What did NVDA report for its latest quarter's revenue?" -> get_earnings("NVDA") - "TSLA's last 8 quarters of earnings releases" -> get_earnings("TSLA", quarters=8) Release figures are management's own characterization and may be non-GAAP-adjacent — verify against the quote when precision matters. A figure without a receipt is still shown (often filled from a prior extraction pass or awaiting validation) but without a deep-link — absence of a receipt is not evidence the value is wrong. Point-in-time: `vantage_date` (YYYY-MM-DD) serves the releases known on/before that date, and `quarters` walks back from it. A revised release is a new accession, so there is no restatement look-ahead here. **Exactness:** the table ABBREVIATES (`$118.70B`) — quote exact figures from `<raw_data>` instead.

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. Reach for this to answer "what's available / where do I read it" per period: - "What documents does {ticker} have for its last earnings?" → the newest row's artifacts - "Give me {ticker}'s earnings transcripts / decks by quarter" → the per-period transcript + deck links - "Is there a webcast / presentation deck for {ticker}'s Q2?" → that row's webcast + deck cells A NAVIGATION index, not figures: release NUMBERS → get_earnings; filed XBRL statements → get_financials; the IR event CALENDAR → get_company_events; a deck's slide TEXT → get_ir_documents; what management SAID on calls → compare_earnings_calls. Coverage is honest per cell: a transcript reads present/pending/none; a deck join is exact (fiscal period, never a date); a webcast is a single-candidate ±1d match — and when the IR calendar isn't harvested that is stated (a missing webcast is NOT "no webcast held"). Not point-in-time: documents as known today; for as-of work use a tool that takes `vantage_date` (e.g. get_earnings, list_filings).

Use this when the user asks what matters in a company's latest 10-K or 10-Q — red flags, accounting quality, debt and liquidity stress, top risks, management tone and guidance, segments and customer concentration. Returns the facts MetricDuck extracted from that filing, each with evidence and a pointer to the section to read next with get_filing_section(). Facts are presented neutrally; those from LLM analysis are labeled. The optional `lens` narrows it to one view (listed on that parameter). Only the LATEST filing is indexed. For a PRIOR quarter's operating KPIs (same-store / comparable sales, ARPU, take-rate, bookings), guidance, or a beat/miss question (e.g. "FND same-store sales in Q4 2024", "did MU beat its Q3 gross-margin guidance"), don't page through the latest 10-Q/10-K — read that quarter's earnings-release 8-K: list_filings(ticker, form_subtype="8-K-earnings", years=N) labels each row with its implied fiscal period (8-Ks are not period-indexed, so don't pass fiscal_year/fiscal_period there); then get_filing_section(ticker, "earnings_press_release" | "earnings_income_statement" | "earnings_segment_data", accession_number=<that 8-K>). Highlights, guidance/outlook and CEO commentary are in "earnings_press_release" (query="outlook"); omit section_id for the release's outline. Use Cases: - "What should I look at in AAPL's 10-K?" -> get_filing_index("AAPL") - "Any accounting red flags for ENPH?" -> get_filing_index("ENPH", lens="earnings_quality") - "What are UNH's biggest risks right now?" -> get_filing_index("UNH", lens="risk_trajectory") For earnings-call trends across quarters, use `compare_earnings_calls`.

Use this when the user asks what a 10-K, 10-Q or 8-K says — risk factors, MD&A, the business description, an earnings release and its guidance / outlook, an 8-K event, a proxy (DEF 14A) — and for earnings call transcript Q&A or prepared remarks, where MetricDuck has the transcript. Returns the section's text, paginated, from the latest filing or a specific one. **Two modes:** 1. **Section mode (default)** — pass section_id for the section's text (up to 10 chunks per page). Valid ids are listed under `section_id`. 2. **Outline mode** — OMIT section_id, pass accession_number: returns the filing's section list with short previews, so you pick by content instead of guessing an id (multi-exhibit 8-K, DEF 14A, 6-K). Omitting accession_number reads the latest filing; `list_filings` finds a specific one. Use Cases: - "Apple risk factors" -> get_filing_section("AAPL", "risk_factors") - "Customer concentration in NVDA" -> get_filing_section("NVDA", "risk_factors", query="customer concentration") - "What did analysts ask on NVDA's last call?" -> get_filing_section("NVDA", "transcript_qa_session") - "Workforce / headcount by geography" -> get_filing_section("MSFT", "business_description", query="human capital") - "M&A terms" -> get_filing_section("CVX", "item_1_01_material_agreement", form_type="8-K") - "As of a past date / point-in-time" -> get_filing_section("MSFT", "business_description", vantage_date="2025-04-07") - "Multi-exhibit 8-K" -> get_filing_section(ticker, accession_number="...") (outline mode) → pick exhibit → drill by section_id Related: earnings-call trends across quarters → `compare_earnings_calls`; slide-deck guidance / KPIs (in neither the filing nor XBRL) → `get_ir_documents`; risk factors vs a prior year → read both years (`fiscal_year`); a figure missing from the section you expected → `search_sec_filings(company=<ticker/CIK>, query="exact phrase")` finds which section of which filing has it.

Use this when the user asks for one metric in a given period or over time (gross margin, ROE, P/E and 250+ more): its Q, FY or TTM series; get_financials returns whole statements, and compare_companies sets a company beside its peers. Returns newest-first rows labeled with the company's fiscal_year + fiscal_period — answer a period-specific question ("Q2 FY2025?") from those labels. The period_end calendar date is NOT the fiscal label, especially for non-December FYE companies (AAPL FY ends Sep; CRM FY ends Jan; ORCL FY ends May). Each row with an SEC accession is cited back to the source filing via the MetricDuck viewer (under vantage_date, the vantage-era filing). ⚠ CONSOLIDATED ONLY — there is no segment/geography/product breakdown here, and no parameter adds one: the metrics layer sums those axes away, so per-member values are never stored. For a BY-SEGMENT series use `get_xbrl_facts(ticker, search="<segment name> revenue", period_history=true)` (as-filed dimensional facts) or `get_filing_section(ticker, "table_segment_reporting")` (the schedule, 3 fiscal years per 10-K). Use Cases: - "What was AAPL's Q2 FY2025 gross margin?" -> get_metric_history("AAPL", "gross_margin") - "ROE last 5 years for MSFT" -> get_metric_history("MSFT", "roe", period_type="FY", window=5) - "As of a past date / point-in-time" -> get_metric_history("MSFT", "revenues", vantage_date="2024-04-30") Issuer operating KPIs (subscribers, backlog, NIM, occupancy…) are not served here: read them in the company's release, `get_filing_section(ticker, "earnings_press_release")`. Price-derived multiples here (pe_ratio, ev_ebitda, pb_ratio…) use the PERIOD-END close; for a price on a SPECIFIC date use get_stock_price. **Latest fiscal year during earnings season:** full-year results post in an earnings 8-K weeks before the 10-K that populates this FY series, so inside that gap the series ends a year early and this tool appends a pointer to the 8-K (get_filing_section "earnings_income_statement") — the year is not unavailable.

The DERIVATION of one COMPUTED metric — its human formula + immediate inputs (each value + source), one level at a time. The audit / verify affordance for derived figures (margins, ratios, ROIC, FCF, adj-EBITDA): call it ONLY when the query asks **how a metric is computed**, **which definition** MetricDuck used, or to **verify / audit** the derivation — NOT to get the value itself (use get_metric_history / get_company_overview for that). Drillable (lazy, one level per call): - a `derived` input points to its OWN derivation — call get_metric_lineage(ticker, that_symbol) to go deeper. - a `base` input is an as-filed XBRL fact — open its filing handle, or get_xbrl_facts(ticker, search="<symbol>") to land on the exact fact. Use Cases: - "How is AAPL's net_margin calculated?" -> get_metric_lineage("AAPL", "net_margin") - "Which ROIC definition does this use?" -> get_metric_lineage("AAPL", "roic") - "Audit / verify gross_margin for Q2 FY2025" -> get_metric_lineage("AAPL", "gross_margin", fiscal_year=2025, fiscal_period="Q2") Computed metrics only — a base as-filed figure has no derivation (the tool says so and points to get_xbrl_facts).

Screen US companies by financial metrics. Find stocks matching quantitative criteria. Metric IDs, period types (incl. growth: period_type="ttm.yoy") and sector codes are listed on the `filters` / `sectors` parameters. LATEST-snapshot values; full history via get_metric_history. Tag filtering (required_tags / excluded_tags) selects by business-model classification; unclassified companies are excluded from tag-filtered results. Use Cases: - "High ROIC tech stocks" -> filters=[{metric_id:"roic", operator:"gt", value:0.15}], sectors=["TECH"] - "Undervalued profitable industrials" -> filters=[{metric_id:"pe_ratio", operator:"lt", value:15}, {metric_id:"pe_ratio", operator:"gt", value:0}], sectors=["IND"] - "Revenue growing >10% YoY" -> filters=[{metric_id:"revenues", operator:"gt", value:0.10, period_type:"ttm.yoy"}] - "AI infrastructure companies not exposed to China supply chain" -> required_tags=["ai_ml_infrastructure"], excluded_tags=["china_supply_chain_heavy"] - "Profitable subscription businesses" -> filters=[{metric_id:"net_margin", operator:"gt", value:0.10}], required_tags=["subscription_recurring"] To screen by filing SIGNALS (tone, covenant risk, material weakness, etc.), use screen_filing_signals — a universe-correct cross-company signal screen — then intersect with a metric screen here.

Use this when the user asks which companies show a red flag or event across filings, earnings releases or earnings calls — "which companies lowered guidance?", "who has covenant risk or debt coming due?", "which tech companies sound cautious?", "who announced M&A or a partnership?" — or what has flagged for one company recently (`ticker`). Not metric screening (P/E, ROIC: use screen_companies). Most signals are LLM-classified, not computed facts. Signals come from 10-K/10-Q filings, 8-K/6-K earnings releases, earnings-call transcripts, 8-K M&A / partnership announcements and DEF 14A proxies. Ids and labels: see the `signals` parameter. Use Cases: - "Which tech companies have cautious management?" -> signals=["tone_cautious"], sectors=["TECH"] - "Who lowered guidance in an earnings release this month?" -> signals=["earnings_guidance_lowered_8k"], recency_days=30 - "Any filing red flags for NVDA lately?" -> ticker="NVDA", signals=["tone_cautious", "covenant_risk", "debt_maturity_near"], match_mode="any" - "Companies that gave specific guidance on calls?" -> signals=["transcript_has_guidance"] - "Which companies announced strategic partnerships or M&A deals?" -> signals=["ir_partnership"] M&A / partnership rows: an `ir_partnership` match on an 8-K Item 1.01 may carry `companion_accessions` — same-day 8-Ks (7.01 / 8.01, Ex 99 press release) holding the deal terms and CEO quotes. Read them with get_filing_section(ticker, section_id="item_1_01_material_agreement", accession_number=<the row's accession>, include_companions=true, companion_accessions=[...]). An empty list means none was found; the anchor alone still reads.

Use this when the user asks what MetricDuck has on a company or wants to start researching one: "what filings do you have for X?", "what's notable about X?", "where do I start on X?". One call returns the company's identity (ticker, name, CIK), its filings with extracted text by form type (10-K, 10-Q, 8-K, proxy), which filing signals fire (M&A, partnerships, guidance changes, accounting flags), the indexed date range, and suggested next calls. Accepts a ticker, a company name or a CIK. The filing counts cover filings whose section text MetricDuck extracted, not the company's full SEC history — `list_filings` lists every filing, including ones without extracted text. To pick between candidate companies for a name, use `search_companies` (it also returns the SEC EDGAR link, filer type, fiscal year-end and former names). To screen many companies: `screen_companies` (metrics) or `screen_filing_signals` (signals); for a theme across filings: `search_sec_filings`. Typical next calls: `get_filing_index(ticker)` for the latest filing's signal map; `get_xbrl_facts(ticker, search="...")` for segment / dimensional figures.

Use this when you have a company name or an ambiguous ticker and need the exact ticker (or CIK) before calling other tools. Fuzzy name/ticker match: handles partial names ("micro" -> MSFT), typos, and ticker variations. Returns ticker, full name, CIK, SIC, filer type (domestic / foreign private issuer / fund — i.e. which form family to expect), fiscal year-end, and the SEC EDGAR entity-page link (verify the match + see the full filing history) for each match. **Delisted / renamed / acquired companies** are resolvable by current OR former name if they filed with the SEC in roughly the last five years (e.g. "American Software" → Logility, "Chase Manhattan" → JPM); older ones may not be found. They are returned ranked below active matches, flagged `[delisted]`, with their CIK. They have no current ticker — pass the returned `cik` to downstream tools (company tools accept a CIK in place of a ticker, except `get_stock_price`, which needs a ticker). **Not for concept/theme/industry discovery** ("gold miners", "LNG exposure", "companies mentioning tariffs") — it matches company names only, not what companies do. Use `search_sec_filings` (full text of filings) or `screen_companies` (metric + sector filters). **Coverage boundary:** MetricDuck is **SEC-EDGAR only**, and this tool is its coverage check. A no-match on a **non-US local-exchange symbol** (e.g. `3087.T`, `LSE:HSBA`, `7203:JP`) is a coverage boundary, not a lookup miss — the tool says so explicitly and you should treat it as **terminal** (don't retry ticker variations). Foreign issuers that file a US 20-F/40-F ARE covered (see `query`).

Retrieve IR earnings-PRESENTATION-DECK text — forward guidance, operational KPIs, and segment outlook that are ONLY in the company's investor-relations slide deck and NOT in the SEC 8-K/10-Q release text or XBRL. Reach for this when get_metric_history / get_xbrl_facts have no series for a KPI or guidance figure, or the 8-K earnings release from get_filing_section lacks it (decks are a separate source): production or revenue guidance ranges, segment/division outlook, KPIs shown as slide charts (e.g., berth capacity %, Mboed production guidance, adjusted-EBITDA guidance). Use Cases: - "OXY Q3 2024 production guidance" -> get_ir_documents("OXY", fiscal_year=2024, fiscal_period="Q3", query="production guidance") - "NCLH berth capacity outlook" -> get_ir_documents("NCLH", fiscal_year=2021, fiscal_period="Q3", query="berth") - "KNTK adjusted EBITDA guidance range" -> get_ir_documents("KNTK", fiscal_year=2023, fiscal_period="Q3", query="EBITDA") Each deck returns its title, original IR url, a stable MetricDuck-hosted gcs_uri, and the matching slide text cited by page. Pass a `query` to land on the exact page; omit it for a bounded prefix of the latest deck. Resolve by ticker or cik; narrow with fiscal_year/fiscal_period.

Use this when the user asks which filings a company has made — its 10-K annual reports, 10-Q quarterly reports, 8-K current reports (earnings releases, events, call transcripts), proxy statements (DEF 14A), or 20-F / 40-F / 6-K for foreign issuers — or needs one specific past filing. Returns each filing's form type, dates and accession number, plus per-section sizes (words, chunks, tables) for 10-K / 10-Q / DEF 14A; 8-Ks return filing metadata only. Default: last 2 years; data from 2013. Use it to: - get the accession_number of a specific past filing (for `get_filing_section` or `get_xbrl_facts`) - pin one periodic filing (10-K / 10-Q, e.g. FY2020 Q3) with `fiscal_year` + `fiscal_period` — 8-K sub-types are not period-indexed, so pair `form_subtype` with `years` instead - see the section inventory with sizes, or confirm a filing exists For what matters in the latest filing use `get_filing_index`; for earnings-call trends, `compare_earnings_calls`. **Delisted / acquired companies**: pass `cik` (10-digit, zero-padded) instead of `ticker` and set `include_delisted=true`. SEC's ticker registry excludes delisted issuers, so `ticker`-only calls 404 even when MetricDuck holds the filings. Example: Spirit Airlines (`cik="0001498710"`). Responses capped at ~20K chars; narrow via `form_type`, `fiscal_year`, or fewer `years`.

Use this when the user asks for a company's income statement, balance sheet or cash flow over several quarters or years: all three statements in one call, up to 10 years, each period cited to its filing; get_metric_history follows one metric, and get_company_overview is the latest snapshot. Returns quantitative historical data with key metrics and trends. Default: all 3 statements, quarterly, 2 years. For qualitative analysis (risks, accounting quality, management tone), use get_filing_index (signal map) then get_filing_section to read the text. Use Cases: - "Show me AAPL's financials" -> all statements - "MSFT revenue trend 5 years" -> period="annual", years=5 - "Is Tesla's debt increasing?" -> statements=["balance"] - "As of a past date / point-in-time" -> get_financials("MSFT", vantage_date="2024-04-30") Periods cite the SEC filing that reported them (accession + filed date in a footnote; resolvable EDGAR index handles in the `<raw_data>` block); under vantage_date, a later recast can sit under the vantage-era citation. **Exactness:** the markdown table ABBREVIATES (`$68.14M`) — it quantises to $10K above $1M and $10M above $1B, so it is not a tie-out surface. The `<raw_data>` block carries the exact stored value (`68135000`). Quote figures from `<raw_data>`, not the table, whenever the precise number matters. Responses capped at ~20K chars. If too large, the OLDEST periods are trimmed first (the same count for every statement, with a note); a whole statement is dropped only if one period of each still does not fit. Nothing is sliced, and `<raw_data>` carries exactly the periods shown — request fewer statements for more periods each. Company-reported **Adjusted EBITDA** (issuer-specific add-backs) is NOT a computed metric here — read the issuer's own reconciliation via get_filing_section (earnings release / MD&A).

Did management deliver what they guided? Joins forward guidance from earnings-call transcripts to reported actuals from 10-K/10-Q + 8-K earnings for the same ticker + fiscal period. Returns both sides verbatim with quotes and locators. Use Cases: - "Did NVDA deliver on Q2 FY2026 guidance?" -> get_guidance_vs_actual("NVDA", fiscal_period="Q2 FY2026") - "How disciplined has MSFT been against its own guidance?" -> get_guidance_vs_actual("MSFT") then compare across periods - "Latest period's guidance-vs-actual" -> get_guidance_vs_actual("TSLA") (period defaults to most recent) Returns everything a beat/miss verdict needs — never the verdict: the comparison is basis-matched, as-reported arithmetic, and whether "above guidance" is good is the caller's judgment. Output: - Guidance: forward items targeting the period — from earnings-call transcripts AND 8-K earnings releases (metric, value/range, basis, period, verbatim quote, source). - Actuals: SEC 10-Q/K metric + narrative signals for that period, plus 8-K earnings signals when present. - Comparison: for each guidance item, when it can be recomputed from the receipts on its OWN basis (GAAP vs non-GAAP matched, units aligned, period settled) — a neutral `range_position` (above | within | below the guided band) + signed `delta`. Otherwise a typed `status` says why NOT (no_actual_on_basis / not_yet_settled / value_unparsed / period_unresolved / value_incongruent) — never a false or guessed verdict. A non-GAAP guide is never compared to a GAAP actual. - Notes: calls/filings covered + comparison statuses, so you know coverage depth before interpreting. Not point-in-time: the join uses everything stored today; for as-of work use a tool that takes `vantage_date` (e.g. get_earnings, get_financials).

Use this when the user asks what SEC filings came out recently — "any new 10-Ks, 10-Qs or 8-Ks this week?", "which of my portfolio companies filed since Monday?", "who reported earnings today?" — across all companies or a list of tickers, in one call. Also the building block for alerts and daily portfolio checks. **Returns:** a flat list of {ticker, accession, filed_at, form_type, form_subtype}, newest filing date first and **largest companies first within a date** — so `limit=15` during earnings week surfaces the banks and mega-caps that filed, not alphabetically-first micro-caps. `form_subtype` classifies 8-Ks (values under `form_subtypes`); null for other forms. **Portfolio filter:** `tickers` (an array); `ticker="TSM"` is accepted as an alias. Both given = union, cap 50. One call covers the portfolio — no per-ticker `list_filings` fan-out. Read a row's filing with `get_filing_section(ticker, accession_number=...)` — omit `section_id` for its section outline. For every filing of ONE company, use `list_filings`. Not point-in-time: the live feed as of today (one company as of a past date: `list_filings` with `vantage_date`).

Search the full text of SEC filings since 2001 to find companies related to any concept — a product, technology, regulation, event, or company. Returns filing-level results with aggregated statistics (company count, form type breakdown, industry distribution). For 10-K/10-Q filings processed by MetricDuck, also shows WHICH SECTIONS contain the term with drill-in pointers. **Searchable form types** — any SEC form (default window: last year); omit `form_type` for all: - Periodic reports: 10-K, 10-Q (section-level drill-down available), 20-F, 40-F, 6-K (foreign private issuers) - Events + proxies: 8-K, DEF 14A / DEFM14A / PRE 14A - Registration + offerings: S-1, F-1, S-3, S-4, 424B series - Ownership + other: SCHEDULE 13D/G (was SC 13D/G), SD (conflict minerals), N-CSR / N-CSRS (fund reports) **Section-level enrichment** (10-K/10-Q only): results name which sections contain the term, with chunk pointers for drill-in via get_filing_section. Other forms return filing metadata + accession numbers only. Use cases: - "Who supplies Apple?" → query="\"Apple Inc.\"", form_type="10-K,10-Q,8-K" → Company Exposure Map of the filers mentioning Apple. Constrain forms — mutual-fund NPORT-P filings otherwise crowd the results (see `date_from`). - "What did WM say at its investor day?" → query="\"investor day\"", company="WM" → that filer only - "Recent data breaches?" → query="cybersecurity incident", form_type="8-K" - "Tariff-exposed companies?" → query="tariff", form_type="10-K" → risk factor disclosures - "Activist campaigns?" → query="board representation", form_type="DEF 14A,SCHEDULE 13D" Other tools: one known company's filings → `get_filing_index` / `list_filings`; numeric filters → `screen_companies`; earnings-call trends → `compare_earnings_calls`. Key limitation: keyword matching only, not semantic. "No material weakness" matches "material weakness found." Verify hits with `get_filing_section` for context.

Call ONLY when the user asks to send feedback to MetricDuck. Pass the user's words in message; set source=user when the user wrote it, model when you summarised it. Sends the text to the MetricDuck team.

Use this when the user asks for a share price on a date or a return between two dates: daily end-of-day close, adj_close and volume for US-listed stocks, from a market-data feed, not SEC filings; get_company_overview shows only the latest price; get_metric_history has period-end multiples. Markets are open only on business days, so rows exist ONLY for trading days — the data IS the trading calendar: - Price ON OR AFTER a date (a single date, or an announcement landing on a weekend): pass start_date=<date> alone; the FIRST row of the short forward window is that date or the next open day. - Price ON OR BEFORE a date: pass end_date=<date>; the LAST row is that date or the prior open day. Use Cases: - "AAPL close on 2025-07-28" -> get_stock_price("AAPL", start_date="2025-07-28") - "DKNG return 2025-01-02 → 2026-02-27" -> get_stock_price("DKNG", start_date="2025-01-02") + get_stock_price("DKNG", end_date="2026-02-27"), first/last close (cheaper than one 14-month window) - "SUI +1/+14/+30 days after an 8-K" -> start_date=<announce>, end_date=<announce + ~32d>; pick rows on/after each - No dates -> the latest price When the window spans ≥2 trading days, the response also reports the first/last close and the period return on BOTH close (point-to-point) and adj_close (split-adjusted, and on some rows, mostly pre-Sept 2023, dividend-adjusted too; not a total return). Each response also includes the latest REPORTED period-end shares outstanding on/before your end date (period-end balance-sheet count; dei cover where absent) plus the implied market cap at the latest close — use these for market-cap / EV / P/B math instead of deriving share counts from NI/EPS (that yields weighted-average shares, a different basis). Coverage: ~8,400 US common-equity tickers, end-of-day only (no intraday/real-time, no options/FX). Recent history is dense; deep pre-2014 history may be sparse. For a CUSTOM multiple (e.g. lease-adjusted EV), get_metric_history's `metric_id` lists the primitives to price with this tool.

Use this when the user asks for a number the standard statements don't break out — revenue by segment, geography, product or customer, customer concentration, an industry metric (medical cost ratio, reserve replacement ratio) — or a figure exactly as filed in a 10-K / 10-Q. Searches the raw XBRL facts (~3,000 per filing, with dimensional breakdowns); for standard statements and the 250+ standard metrics, `get_financials` is faster. - Breakdowns exist only where the filer tags them (usually revenue + segment profit / Adjusted EBITDA). - **Revenue concentration / share** by customer, channel, distributor, geography or product: search `concentration` (as-filed `ConcentrationRiskPercentage`, present even when the prose is qualitative). - A past filing: the default is the latest filing as of TODAY; pin `accession_number` or `fiscal_year`/`fiscal_period`. - A standalone quarter from a cumulative YTD line: `period_history: true` (recipe on that parameter). **Sign — read before quoting a direction.** `<raw_data>.value` is the raw as-filed value: a positive magnitude for outflow / contra-asset concepts (`PaymentsTo…`, capex, accumulated depreciation) but **signed by construction** for the `IncreaseDecreaseIn…` working-capital family. Where a negative value carries the negated-label role, the table shows the filed face instead. `(filed −)` is a per-concept **hint, not a guarantee**: it fires wherever the filing presents that concept negatively *anywhere* (e.g. TXN's tax provision, whose face reads `709`). When direction is load-bearing, check the `edgar` fact link or use `get_financials` (a curated statement-sign map). **Share counts:** the **dei** `EntityCommonStockSharesOutstanding` ("cover-page / current", as of the filing date) is for market cap and equity value; the **us-gaap** `CommonStockSharesOutstanding` is the **balance-sheet period-end** count; `WeightedAverageNumberOf…SharesOutstanding` is the per-period EPS average. They can differ a few % — match the Period column to your task.