MetricDuck

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.

get_ir_documents

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

get_company_events

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

list_filings

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.

get_metric_history

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

get_metric_lineage

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.

get_xbrl_facts

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.

get_filing_section

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`).

list_recent_filings

Screen 5,500+ 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.

screen_companies

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.

screen_filing_signals

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`).

search_companies

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.

send_feedback

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.

get_stock_price