Server definition
- Hash
- sha256:03f326d9b9da61ed515f4cec6571612040bacedfdb402034dc33de4e83318989
- What it is
- What a remote MCP server returned when asked what it offers: 22 tools
The blob, as servednamed by its sha256
{
"instructions": "MetricDuck answers questions about public companies from SEC filings. Use it when the user asks about company financials (revenue, margins, cash flow), 10-K, 10-Q or 8-K filings, risk factors, MD&A, earnings calls, guidance, or stock prices. Trust rule: quote figures as MetricDuck's tools return them; if a tool returns no data, an error, or 'no coverage', say the figure could not be retrieved from MetricDuck — never substitute a number from memory or another source without flagging it as unverified. MetricDuck's SEC filing data — financials, XBRL facts, and filing text — is an audit-grade primary source. Earnings-call and IR content is management's own words, labeled by credibility tier (SEC-filed vs Issuer-published vs Machine-transcribed) — treat it as commentary to verify against the quote, not as an SEC-audited figure. Coverage: 5,500+ US public companies (10-K/10-Q/8-K/DEF 14A) and foreign private issuers filing with the SEC (20-F, 40-F, 6-K), updated daily from SEC EDGAR, with 250+ pre-computed metrics. Periods: fiscal labels like \"Q2 FY2025\" follow the company's own fiscal year, which may not match the calendar (Apple's ends in September); period_end is the calendar date a period ended — match a calendar-dated question on period_end, not on the label. Limitations: end-of-day prices only (no intraday/real-time), no options data, no analyst estimates/consensus, no insider-transaction or institutional-holdings feeds (Form 3/4/5, 13F — these ARE filed with the SEC, MetricDuck just does not ingest them). Signals derive from filings, earnings-call transcripts and IR disclosures; end-of-day prices come from a market-data feed and power the valuation multiples.",
"tools": [
{
"description": "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.\n\nThe 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.\n\nTo 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`.\n\nTypical next calls: `get_filing_index(ticker)` for the latest filing's signal map; `get_xbrl_facts(ticker, search=\"...\")` for segment / dimensional figures.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"include_delisted": {
"default": false,
"description": "Include delisted companies among FUZZY candidates (ticker-prefix / name matches). Default false. A delisted company always resolves by its exact ticker, former ticker, or CIK regardless of this flag — prefer the CIK for delisted companies.",
"type": "boolean"
},
"query": {
"description": "Company name, ticker, or 10-digit zero-padded CIK. Accepts free-text fuzzy match like 'US Steel' or 'AAPL'. For delisted companies, prefer the CIK.",
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "browse_company",
"outputSchema": null
},
{
"description": "Compare a company against peers across ~70 curated fundamental metrics (TTM), with percentile rankings and relative strengths/weaknesses.\n\nReturns 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),\nleverage & liquidity (debt/equity, net debt/EBITDA, interest coverage, current ratio), efficiency (asset/inventory turnover, DSO, cash conversion cycle),\nand capital returns (dividend yield, dividend payout ratio, buyback yield, shareholder yield). Sector-inapplicable metrics are omitted (e.g. gross margin / FCF leverage for banks).\n\nPass 'metrics' to focus the table on specific metric_ids. This is a TTM cross-sectional snapshot — for a single company's value in a specific fiscal year/quarter use get_metric_history. 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.\n\npeer_mode controls peer selection:\n- 'sector' (default): auto-selected from same sector + similar market cap\n- 'tags': auto-selected by business model similarity (tag Jaccard) — better for cross-sector comparisons\n\nOverride with custom_peers for specific matchups. The number of custom_peers is capped by plan (Free: 3, Pro: 10); exceeding it returns the limit and the count you asked for, so retry with that many.\n\nUse Cases:\n- \"Compare AAPL vs MSFT\" -> compare_companies(\"AAPL\", custom_peers=\"MSFT\")\n- \"How does NVDA stack up in its sector?\" -> compare_companies(\"NVDA\")\n- \"Dividend payout ratio: KO vs KDP/PEP/KHC\" -> compare_companies(\"KO\", custom_peers=\"KDP,PEP,KHC\", metrics=\"dividend_payout_ratio,dividend_yield\")",
"inputSchema": {
"additionalProperties": false,
"properties": {
"custom_peers": {
"description": "Optional comma-separated peer tickers (e.g., 'MSFT,GOOG,AMZN'). Auto-selected if omitted.",
"type": "string"
},
"metrics": {
"description": "Optional comma-separated metric_ids to show instead of the default curated table (e.g. 'dividend_payout_ratio,dividend_yield,ev_ebitda,roa,interest_coverage'). Drawn from the ~70 curated fundamentals. A near-miss such as 'operating_margin' is read as 'oper_margin' and said so; any other unknown id is named in the response with its closest ids. Responses cap at ~20K chars — a subset here (or fewer custom_peers) keeps a large comparison whole.",
"type": "string"
},
"peer_mode": {
"default": "sector",
"description": "Peer selection method: 'sector' (same sector + similar market cap, default) or 'tags' (business model similarity — finds companies with overlapping classification tags). Use 'tags' for cross-sector business model comparisons, e.g. NVDA vs AMD/Broadcom instead of NVDA vs MSFT/GOOG.",
"enum": [
"sector",
"tags"
],
"type": "string"
},
"ticker": {
"description": "Primary company ticker symbol to compare (e.g., 'AAPL'). Must be exact.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "compare_companies",
"outputSchema": null
},
{
"description": "How has management's posture shifted across recent earnings calls? Cross-quarter trajectory view of transcript signals for a single ticker.\n\nThis 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\").\n\nOutput (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.\n\nUse Cases:\n- \"Deflection trend?\" -> compare_earnings_calls(\"RDDT\", n_quarters=8, dimensions=[\"hedges\", \"qa\"])\n- \"Guidance discipline shifting?\" -> compare_earnings_calls(\"NVDA\", dimensions=[\"guidance\"])\n- \"Strategic priorities + KPIs drift\" -> compare_earnings_calls(\"PG\", dimensions=[\"priorities\", \"kpi\"])\n\nFor signal changes across many companies between two windows, use `screen_filing_signals` with since_date/until_date.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"dimensions": {
"description": "Filter to specific trajectory axes; every axis is a per-quarter series. Omit for all. guidance: forward guidance items with delta_vs_prior. hedges: Q&A deflection rate. qa: Q&A Exchange Analyzer aggregates (analyst questions, concerns, concerns retained, forward commits). priorities: ranked strategic priorities. macro: macro factor responses (factor + stance + drift tag). competitive: competitive mentions (competitor + context_type + drift tag). scale_claims: quantified scale claims (metric_name + value + direction). revdecomp: segment revenue decompositions (segment + period_type + total_growth). kpi: issuer-disclosed operating KPIs (kpi_name + value). capital_allocation: forward capital-allocation postures (buyback cadence, leverage targets, funding rationale, capex, M&A). scenarios: conditional scenario sensitivities (trigger event + impacts on revenue / EBITDA / margin / EPS). forward_commits: calendar-anchored forward commitments (speaker + analyst + verbatim excerpt). customer_cohort: customer-cohort disclosures (deals above an ACV/NACV threshold, threshold-crossing flow, top-N attach, new-logo growth).",
"items": {
"enum": [
"guidance",
"hedges",
"qa",
"priorities",
"macro",
"competitive",
"scale_claims",
"revdecomp",
"kpi",
"capital_allocation",
"scenarios",
"forward_commits",
"customer_cohort"
],
"type": "string"
},
"type": "array"
},
"n_quarters": {
"default": 4,
"description": "How many most-recent earnings calls to compare (default: 4, min: 2, max: 8).",
"maximum": 8,
"minimum": 2,
"type": "integer"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'NVDA'). Must be exact.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): compare only calls reported ON OR BEFORE this date, window anchored there rather than today — don't assume the latest calls reflect a past vantage. Omit for the most recent.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "compare_earnings_calls",
"outputSchema": null
},
{
"description": "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).\n\nReach for this for calendar questions:\n- \"When does {ticker} next report / hold its earnings call?\" → the UPCOMING list (scheduled events)\n- \"What IR events did {ticker} have this year?\" / \"was {ticker} at any conferences?\"\n- \"What materials are attached to {ticker}'s last earnings event?\"\n\nEach 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).\n\nCoverage 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.\n\nWhat management SAID on earnings calls (guidance/tone by quarter) → compare_earnings_calls.\n\nNot 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).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Required.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_company_events",
"outputSchema": null
},
{
"description": "Get comprehensive financial overview for a company in a single call.\n\nIncludes: current price, valuation (P/E, P/B, EV multiples, PEG), profitability (revenue, margins, returns),\ncash flow (OCF, FCF, yields), balance sheet (debt, equity, ratios), capital allocation (buybacks, shares outstanding, shareholder yield),\nbusiness segment + geographic revenue mix (latest 10-K, with YoY change), latest earnings insights, filing intelligence highlights, and company flags.\n\nLatest snapshot only — use get_financials for multi-year trends, 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).\n\nNot 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 (get_financials and get_metric_history flag a LOOK-AHEAD); get_xbrl_facts with period_history=true gives figures as originally filed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"depth": {
"default": "core",
"description": "Response shape preset. 'snapshot' = headline facts only (~2K chars: key signals, filing-signal summary, flags, latest filing pointers) — best for multi-ticker sequencing or quick checks. 'core' (default) = standard overview (~5-9K). 'full' = core + all tags and earnings highlights/concerns (no truncation) + a 5Y historical distribution (median/p25/p75/p90) of P/E, EV/EBITDA, EV/FCF.",
"enum": [
"snapshot",
"core",
"full"
],
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL', 'MSFT'). Must be exact — search_companies resolves a name.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_company_overview",
"outputSchema": null
},
{
"description": "8-K earnings-RELEASE financials — headline income statement (revenue, net income, operating income, diluted EPS) PLUS the as-released cash-flow statement (operating cash flow, capex, free cash flow, +growth), typically WEEKS before the audited 10-Q/10-K. Often the ONLY structured 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).\n\nDistinct from get_financials (audited XBRL 10-K/10-Q — 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.\n\nUse Cases:\n- \"What did NVDA report for its latest quarter's revenue?\" -> get_earnings(\"NVDA\")\n- \"TSLA's last 8 quarters of earnings releases\" -> get_earnings(\"TSLA\", quarters=8)\n\nRelease 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.\n\nPoint-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.\n\n**Exactness:** the table ABBREVIATES (`$118.70B`) — quote exact figures from `<raw_data>` instead.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"quarters": {
"default": 4,
"description": "Number of most recent quarters to return (1-8, default 4).",
"maximum": 8,
"minimum": 1,
"type": "integer"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'NVDA'). Must be exact.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): serve releases KNOWN on/before this date — the quarters walk back from the vantage instead of today. For backtests / point-in-time questions. Omit for the latest. Scope: this bounds which RELEASES are visible, not which EXTRACTION of them — a figure MetricDuck later re-extracted is served at its current (corrected) reading. That is deliberate: the corrected reading is the better answer to what the filing said at that date. Such corrections are rare — 0.60% of release/signal pairs ever changed value across extractions, all within the same accession — and a genuine issuer revision arrives as a NEW accession, which this bound catches.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_earnings",
"outputSchema": null
},
{
"description": "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.\n\nReach for this to answer \"what's available / where do I read it\" per period:\n- \"What documents does {ticker} have for its last earnings?\" → the newest row's artifacts\n- \"Give me {ticker}'s earnings transcripts / decks by quarter\" → the per-period transcript + deck links\n- \"Is there a webcast / presentation deck for {ticker}'s Q2?\" → that row's webcast + deck cells\n\nA NAVIGATION index, not figures: release NUMBERS → get_earnings; audited 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.\n\nCoverage 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\").\n\nNot point-in-time: documents as known today; for as-of work use a tool that takes `vantage_date` (e.g. get_earnings, list_filings).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"limit": {
"description": "Most-recent fiscal periods to return (newest first). Default 12.",
"maximum": 40,
"minimum": 1,
"type": "integer"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'MRK'). Required.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_earnings_reports",
"outputSchema": null
},
{
"description": "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).\n\nOnly 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:\nlist_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.\n\nUse Cases:\n- \"What should I look at in AAPL's 10-K?\" -> get_filing_index(\"AAPL\")\n- \"Any accounting red flags for ENPH?\" -> get_filing_index(\"ENPH\", lens=\"earnings_quality\")\n- \"What are UNH's biggest risks right now?\" -> get_filing_index(\"UNH\", lens=\"risk_trajectory\")\n\nFor earnings-call trends across quarters, use `compare_earnings_calls`.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"lens": {
"description": "Filter to a specific analytical view. earnings_quality: SBC dilution, accounting flags, material weaknesses, earnings quality assessments. debt_stress: Debt profile, covenant compliance, near-term maturities, critical liability findings. risk_trajectory: Risk factors, new/escalated risks, key uncertainties, concern evolution. competitive_position: Business segments, customer / channel / geographic concentration. management_outlook: Management tone, tone change, forward guidance, guidance accuracy. Omit for the full signal index.",
"enum": [
"earnings_quality",
"debt_stress",
"risk_trajectory",
"competitive_position",
"management_outlook"
],
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Must be exact.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): index the signal map for the latest filing filed ON OR BEFORE this date — for point-in-time / 'as of <date>' analysis (backtest, 'what was known at the announcement'). Omit for the latest filing.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_filing_index",
"outputSchema": null
},
{
"description": "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.\n\n**Two modes:**\n1. **Section mode (default)** — pass section_id for the section's text (up to 10 chunks per page). Valid ids are listed under `section_id`.\n2. **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).\n\nOmitting accession_number reads the latest filing; `list_filings` finds a specific one.\n\nUse Cases:\n- \"Apple risk factors\" -> get_filing_section(\"AAPL\", \"risk_factors\")\n- \"Customer concentration in NVDA\" -> get_filing_section(\"NVDA\", \"risk_factors\", query=\"customer concentration\")\n- \"What did analysts ask on NVDA's last call?\" -> get_filing_section(\"NVDA\", \"transcript_qa_session\")\n- \"Workforce / headcount by geography\" -> get_filing_section(\"MSFT\", \"business_description\", query=\"human capital\")\n- \"M&A terms\" -> get_filing_section(\"CVX\", \"item_1_01_material_agreement\", form_type=\"8-K\")\n- \"As of a past date / point-in-time\" -> get_filing_section(\"MSFT\", \"business_description\", vantage_date=\"2025-04-07\")\n- \"Multi-exhibit 8-K\" -> get_filing_section(ticker, accession_number=\"...\") (outline mode) → pick exhibit → drill by section_id\n\nRelated: 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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"accession_number": {
"description": "Filing accession number from list_filings. Latest filing used if omitted.",
"type": "string"
},
"char_offset": {
"default": 0,
"description": "Within-chunk character offset (default 0). A chunk exceeding max_chars serves a char-window and emits a `char_offset` cursor — pass it back with the same `offset` to read deeper. Ignored on normal chunks.",
"minimum": 0,
"type": "integer"
},
"cik": {
"description": "10-digit SEC CIK as an alternative to ticker — use for delisted/acquired companies (e.g. Activision cik='0000718877') whose ticker no longer resolves.",
"pattern": "^\\d{10}$",
"type": "string"
},
"companion_accessions": {
"description": "Explicit companion accessions (from a `screen_filing_signals` row's `value.companion_accessions`). With `include_companions=true`, skips the discovery hop — halves the round-trips if you already screened.",
"items": {
"type": "string"
},
"type": "array"
},
"fiscal_period": {
"description": "Fiscal period: 'Q1'/'Q2'/'Q3' for a quarter's 10-Q, or 'FY' for the annual 10-K (the default when omitted). Resolved via the XBRL DEI period index (correct for non-calendar fiscal years). The fourth quarter is reported in the annual 10-K — 'Q4' is treated as 'FY'. Use with fiscal_year. Ignored if accession_number provided.",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"FY"
],
"type": "string"
},
"fiscal_year": {
"description": "Fiscal year to look up (e.g., 2023). Resolves to that fiscal year's filing via the XBRL period index — correct for non-calendar fiscal years (e.g. a 10-K filed Feb 2024 covers FY2023, not FY2024). Combine with fiscal_period for a specific quarter; omit fiscal_period to get the annual 10-K. Ignored if accession_number provided. DEF 14A / non-XBRL forms are not period-indexed — for those use accession_number (via list_filings), or vantage_date for as-of-date retrieval.",
"type": "integer"
},
"form_type": {
"description": "Form type filter (picks the latest of that type when accession_number is omitted). 20-F/40-F/6-K cover foreign private issuers. Other forms (424B2, FWP, 13F-HR, 4): search_sec_filings(query, company, form_type, sections=false) links the filing on EDGAR (company: the 10-digit CIK; date_from for older filings).",
"enum": [
"10-K",
"10-Q",
"8-K",
"DEF 14A",
"20-F",
"40-F",
"6-K"
],
"type": "string"
},
"include_companions": {
"default": false,
"description": "With section_id='item_1_01_material_agreement' on an 8-K anchor: also return text from same-day same-issuer companion 8-Ks (7.01 Reg FD + Ex 99 / 8.01). Default false = anchor only.",
"type": "boolean"
},
"include_delisted": {
"description": "Query a delisted/acquired company by its old ticker. Default false returns a structured delisted error pointing at the CIK.",
"type": "boolean"
},
"max_chars": {
"default": 20000,
"description": "Soft response-size cap (default 20,000 chars). The anchor is always served in full; companions are appended in priority order and truncated with a follow-up-call marker. Raise only when you need wider context.",
"maximum": 60000,
"minimum": 2000,
"type": "integer"
},
"max_chunks": {
"default": 10,
"description": "Chunks per page (default 10, max 10)",
"maximum": 10,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Chunk offset for pagination (default 0)",
"minimum": 0,
"type": "integer"
},
"preview_chars": {
"default": 120,
"description": "Outline-mode preview length per section (default 120 ≈ 25 words). Ignored when section_id is provided.",
"maximum": 200,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Keyword to search within section chunks (e.g., 'customer concentration', 'export control'). Returns only matching chunks.",
"type": "string"
},
"section_id": {
"description": "Section ID — omit it (with `accession_number` set) for outline mode. Common IDs by category:\n\n**10-K / 10-Q core:** `risk_factors`, `business_description`, `mda_full`, `mda_results_operations`, `mda_liquidity`, `mda_outlook`, `mda_critical_accounting`, `legal_proceedings`, `market_risk`, `controls_procedures`, `cybersecurity`, `properties`, `signature_officers`\n ↳ Human Capital / headcount lives in `business_description` (Item 1) — there is no `human_capital` id; use `query=\"human capital\"`.\n\n**Footnotes:** `footnote_revenue`, `footnote_segment`, `footnote_debt`, `footnote_accounting_policies`, `footnote_commitments`, `footnote_stock_comp`, `footnote_income_tax`, `footnote_leases`, `footnote_goodwill`, `footnote_business_combinations`, `footnote_fair_value`, `footnote_related_party`\n\n**Data tables:** `table_revenue_disaggregation`, `table_segment_reporting`, `table_eps`, `table_deferred_taxes`, `table_ppe`, `table_fair_value`, `table_goodwill`, `table_lease_costs`, `table_contract_assets`, `table_debt_maturities`\n ↳ These carve the numeric tables OUT of the parent footnote, so the matching `footnote_*` may be PROSE-ONLY — query the `table_*` id for a disaggregated figure. A 10-K's segment schedule carries THREE fiscal years, so one filing is not the whole series.\n ↳ ⚠ Consolidated income-statement cost lines (`earnings_income_statement`, the 10-Q statements) are COMPANY-WIDE, not per-segment.\n\n**8-K earnings release:** `earnings_document_map`, `earnings_press_release`, `earnings_guidance`, `earnings_guidance_prose`, `earnings_income_statement`, `earnings_balance_sheet`, `earnings_cash_flow`, `earnings_segment_data`, `earnings_gaap_reconciliation`, `earnings_supplemental_tables`, `earnings_full_text`\n ↳ `earnings_guidance` = the outlook TABLE, `earnings_guidance_prose` its prose sibling — check both. `earnings_full_text` = the whole release in one searchable section — the residual fallback when a guided figure was mis-classified into another id.\n\n**8-K events:** `item_1_01_material_agreement`, `item_2_01_acquisition`, `item_2_01_exhibit_2_1`, `item_2_01_exhibit_99_1`, `item_2_03_financial_obligation`, `item_3_03_material_modification`, `item_5_02_executive_changes`, `item_5_03_articles_amendment`, `item_5_07_shareholder_votes`, `item_8_01_other_events`\n ↳ Exhibits are `item_<event>_exhibit_<major>_<minor>` (non-padded minor). Every non-earnings 8-K carries an **`exhibit_manifest`** listing every exhibit with its section_id, or an EDGAR link when link-only — read it before guessing.\n\n**Earnings call transcript:** `transcript_prepared_remarks`, `transcript_qa_session`, `transcript_guidance`\n\n**DEF 14A proxy:** `proxy_cd_and_a`, `proxy_compensation_table`, `proxy_peer_group`, `proxy_ceo_pay_ratio`, `proxy_pay_vs_performance`, `proxy_board_composition`, `proxy_shareholder_proposals`, `proxy_say_on_pay`\n\n**Risk vs risk management:** `risk_factors` lists what risks exist; for risk MANAGEMENT / mitigation read `mda_full` with `query` (e.g. 'risk management'). `mda_full` is the complete MD&A — use it when a subsection (`mda_results_operations`, `mda_liquidity`) comes back empty or thin.\n**20-F / foreign filer:** `mda_operating_results`, `mda_trend_information`, `mda_research_development`, `business_overview`, `business_organizational_structure`, `major_shareholders`, `directors_management`\n\n**FPI 6-K interim metrics:** `interim_monthly_revenue` (TSM monthly revenue release — primary doc text + inline NT$ table)\n\n**Accounting standard:** chunks carry `accounting_standard` (`US-GAAP` / `IFRS`), populated for FPI extractions, NULL for domestic 10-K/Q (implicitly US-GAAP) — read it before comparing ratios across filer types.",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Required unless cik is provided.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): serve the latest filing filed ON OR BEFORE this date — don't assume the newest filing reflects a past vantage. Omit for the latest. Ignored if accession_number is provided.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
},
"type": "object"
},
"name": "get_filing_section",
"outputSchema": null
},
{
"description": "Get multi-period financial statements: income statement, balance sheet, and cash flow in one call.\n\nReturns quantitative historical data with key metrics and trends. Default: all 3 statements, quarterly, 2 years.\nFor qualitative analysis (risks, accounting quality, management tone), use get_filing_index (signal map) then get_filing_section to read the text.\n\nUse Cases:\n- \"Show me AAPL's financials\" -> all statements\n- \"MSFT revenue trend 5 years\" -> period=\"annual\", years=5\n- \"Is Tesla's debt increasing?\" -> statements=[\"balance\"]\n- \"As of a past date / point-in-time\" -> get_financials(\"MSFT\", vantage_date=\"2024-04-30\")\n\nEach period cites its original disclosing SEC filing (accession + filed date in a footnote; resolvable EDGAR index handles in the `<raw_data>` block), so every figure is traceable to its source filing.\n\n**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.\n\nResponses capped at ~20K chars. If truncated, whole statements are dropped (not sliced) with a note — request fewer statements or reduce years. Note the cap also trims `<raw_data>` periods, so a truncated response can lose the exact channel for the dropped periods.\n\nCompany-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).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"period": {
"default": "quarterly",
"description": "Time period granularity",
"enum": [
"quarterly",
"annual"
],
"type": "string"
},
"statements": {
"default": [
"income",
"balance",
"cashflow"
],
"description": "Which statements to include (default: all three)",
"items": {
"enum": [
"income",
"balance",
"cashflow"
],
"type": "string"
},
"type": "array"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Must be exact.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): restrict to filings PUBLISHED on or before this date, and cite the filing that was current then. Omit for the latest. IMPORTANT — this bounds which FILINGS are visible and which SOURCE is cited; it does NOT reconstruct the value as it stood on that date. If a later filing restated a period, THE RESTATED VALUE IS WHAT IS SERVED under a pre-vantage citation — and the response carries an explicit LOOK-AHEAD warning naming the affected periods, so the exposure is disclosed rather than silent. For a true as-originally-filed series use get_xbrl_facts with period_history=true.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"years": {
"default": 2,
"description": "Years of history (default 2, max 10)",
"maximum": 10,
"minimum": 1,
"type": "integer"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_financials",
"outputSchema": null
},
{
"description": "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.\n\nReturns both sides verbatim with quotes and locators.\n\nUse Cases:\n- \"Did NVDA deliver on Q2 FY2026 guidance?\" -> get_guidance_vs_actual(\"NVDA\", fiscal_period=\"Q2 FY2026\")\n- \"How disciplined has MSFT been against its own guidance?\" -> get_guidance_vs_actual(\"MSFT\") then compare across periods\n- \"Latest period's guidance-vs-actual\" -> get_guidance_vs_actual(\"TSLA\") (period defaults to most recent)\n\nReturns 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.\n\nOutput:\n- Guidance: forward items targeting the period — from earnings-call transcripts AND 8-K earnings releases (metric, value/range, basis, period, verbatim quote, source).\n- Actuals: SEC 10-Q/K metric + narrative signals for that period, plus 8-K earnings signals when present.\n- 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.\n- Notes: calls/filings covered + comparison statuses, so you know coverage depth before interpreting.\n\nNot 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).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fiscal_period": {
"description": "Target fiscal period, e.g. \"Q2 FY2026\". If omitted, defaults to the most recent period with SEC filing actuals, or to a newer quarter whose 8-K earnings release is out when guidance targets it.",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'NVDA'). Must be exact.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_guidance_vs_actual",
"outputSchema": null
},
{
"description": "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.\n\nReach 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).\n\nUse Cases:\n- \"OXY Q3 2024 production guidance\" -> get_ir_documents(\"OXY\", fiscal_year=2024, fiscal_period=\"Q3\", query=\"production guidance\")\n- \"NCLH berth capacity outlook\" -> get_ir_documents(\"NCLH\", fiscal_year=2021, fiscal_period=\"Q3\", query=\"berth\")\n- \"KNTK adjusted EBITDA guidance range\" -> get_ir_documents(\"KNTK\", fiscal_year=2023, fiscal_period=\"Q3\", query=\"EBITDA\")\n\nEach 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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cik": {
"description": "10-digit SEC CIK as an alternative to ticker (e.g., '0000797468').",
"pattern": "^\\d{10}$",
"type": "string"
},
"fiscal_period": {
"description": "Fiscal period: 'Q3' (with fiscal_year) or combined '2024Q3'. Omit to return the latest deck(s).",
"type": "string"
},
"fiscal_year": {
"description": "Fiscal year of the deck (e.g., 2024). Narrows to one period when combined with fiscal_period.",
"maximum": 2100,
"minimum": 2000,
"type": "integer"
},
"mode": {
"description": "Response mode. 'full' (default): slide TEXT for the matched deck(s) — combine with query/period to pull a figure. 'list': a cheap one-row-per-item INVENTORY of the company's served IR documents (doc_kind, period, date, links; NO slide text) — use to answer \"what IR materials does X have?\". In list mode `query` is ignored (it filters slide text).",
"enum": [
"full",
"list"
],
"type": "string"
},
"query": {
"description": "Keyword filter over slide text — returns ONLY the deck pages whose text matches every word (whole-word AND, case-insensitive). Use this to pull a specific figure (e.g., query=\"production guidance\", \"berth capacity\", \"adjusted EBITDA guidance\") so the response cites the exact page instead of dumping the deck.",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'OXY'). Required unless cik is provided.",
"type": "string"
}
},
"type": "object"
},
"name": "get_ir_documents",
"outputSchema": null
},
{
"description": "Time series for one metric across fiscal periods. 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).\n\nEach row with an SEC accession is cited back to the source filing via the MetricDuck viewer.\n\n⚠ 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).\n\nUse Cases:\n- \"What was AAPL's Q2 FY2025 gross margin?\" -> get_metric_history(\"AAPL\", \"gross_margin\")\n- \"ROE last 5 years for MSFT\" -> get_metric_history(\"MSFT\", \"roe\", period_type=\"FY\", window=5)\n- \"As of a past date / point-in-time\" -> get_metric_history(\"MSFT\", \"revenues\", vantage_date=\"2024-04-30\")\n\nAlso serves NON-XBRL operating KPIs (LLM-extracted from earnings releases), almost all QUARTERLY — coverage varies by KPI. Besides the ids on `metric_id`: gross_booking_value, take_rate (marketplaces), revpar, occupancy_rate (lodging/REIT), passenger_load_factor, prasm, casm (airlines), oil_production, and more.\n\nPrice-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.\n\n**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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"metric_id": {
"description": "Exact metric id (lowercase + underscores). Common XBRL financials: gross_margin, oper_margin, net_margin, ebitda_margin, roe, roa, roic, pe_ratio, ev_ebitda, ev_sales, fcf_yield, pb_ratio, current_ratio, debt_to_equity, interest_coverage, revenues, net_income, ebitda, fcf, net_cf_ops, capex, dividends_per_share, dividends_paid, dividend_yield, dividend_payout_ratio, fcf_payout_ratio, dividend_coverage. Operating KPIs (non-XBRL, mostly quarterly), most-covered first: net_interest_margin, return_on_average_assets, return_on_average_equity, nonperforming_assets_to_total_assets, nonperforming_loans_to_total_loans, allowance_for_credit_losses_to_total_loans, loan_to_deposit_ratio, net_charge_offs_to_average_loans, common_equity_tier_1_capital_ratio, tier_1_leverage_ratio, tier_1_capital_ratio, total_capital_ratio, return_on_average_tangible_common_equity, net_leverage_ratio, nonperforming_loan_ratio, liquidity_coverage_ratio, net_stable_funding_ratio, combined_ratio, loss_ratio, expense_ratio, policies_in_force, arr, recurring_revenue, remaining_performance_obligations, organic_revenue_growth, cancellation_rate, subscribers, arpu, store_count, same_store_sales. Both lists are non-exhaustive — try a canonical name even if unlisted; a miss returns the full served catalog and steers. Banks/insurers often NULL on COGS-based metrics (gross_margin, gross_profit) — use sector alternatives. A CUSTOM multiple (e.g. lease-adjusted EV) = get_stock_price (price leg) + the primitives oper_lease_liabs, ttl_debt, cash_st_invs, ttl_equity, shares_basic.",
"type": "string"
},
"period_type": {
"default": "Q",
"description": "Q = quarterly, FY = fiscal year, TTM = trailing 12 months.",
"enum": [
"Q",
"FY",
"TTM"
],
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Must be exact.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): restrict the series to periods whose ORIGINAL filing was published on or before this date, and cite the filing that was current then. Omit for the latest. IMPORTANT — this bounds period EXISTENCE and the CITATION; it does NOT reconstruct the value as it stood on that date. If a later filing restated a period, the restated value is what is served, and the response carries an explicit LOOK-AHEAD warning naming the affected periods. For a true as-originally-filed series use get_xbrl_facts with period_history=true.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"window": {
"default": 20,
"description": "Max observations returned, newest first. Default 20, max 40.",
"maximum": 40,
"minimum": 1,
"type": "integer"
}
},
"required": [
"ticker",
"metric_id"
],
"type": "object"
},
"name": "get_metric_history",
"outputSchema": null
},
{
"description": "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).\n\nDrillable (lazy, one level per call):\n- a `derived` input points to its OWN derivation — call get_metric_lineage(ticker, that_symbol) to go deeper.\n- 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.\n\nUse Cases:\n- \"How is AAPL's net_margin calculated?\" -> get_metric_lineage(\"AAPL\", \"net_margin\")\n- \"Which ROIC definition does this use?\" -> get_metric_lineage(\"AAPL\", \"roic\")\n- \"Audit / verify gross_margin for Q2 FY2025\" -> get_metric_lineage(\"AAPL\", \"gross_margin\", fiscal_year=2025, fiscal_period=\"Q2\")\n\nComputed metrics only — a base as-filed figure has no derivation (the tool says so and points to get_xbrl_facts).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fiscal_period": {
"description": "Pin the fiscal period. Omit for the latest.",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"FY"
],
"type": "string"
},
"fiscal_year": {
"description": "Pin the fiscal year (e.g. 2025). Omit for the latest period.",
"type": "integer"
},
"metric": {
"description": "Metric id of a COMPUTED metric (e.g. 'net_margin', 'roic', 'fcf', 'ev_ebitda').",
"type": "string"
},
"period_type": {
"default": "Q",
"description": "Q = quarterly, FY = fiscal year, TTM = trailing 12 months.",
"enum": [
"Q",
"FY",
"TTM"
],
"type": "string"
},
"segment": {
"description": "Reporting segment id. Omit for the consolidated figure.",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Must be exact.",
"type": "string"
}
},
"required": [
"ticker",
"metric"
],
"type": "object"
},
"name": "get_metric_lineage",
"outputSchema": null
},
{
"description": "Daily end-of-day stock prices (open/high/low, close, split- & dividend-adjusted adj_close, volume) for US exchange-listed companies. Sourced from a market-data feed, not SEC filings.\n\nMarkets are open only on business days, so rows exist ONLY for trading days — the data IS the trading calendar:\n- 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.\n- Price ON OR BEFORE a date: pass end_date=<date>; the LAST row is that date or the prior open day.\n\nUse Cases:\n- \"AAPL close on 2025-07-28\" -> get_stock_price(\"AAPL\", start_date=\"2025-07-28\")\n- \"DKNG total 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)\n- \"SUI +1/+14/+30 days after an 8-K\" -> start_date=<announce>, end_date=<announce + ~32d>; pick rows on/after each\n- No dates -> the latest price\n\nWhen 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/dividend-adjusted: the economic return).\n\nEach 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).\n\nCoverage: ~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. Period-end multiples (P/E, EV/EBITDA, P/B): get_metric_history, whose `metric_id` lists the primitives for a CUSTOM multiple (e.g. lease-adjusted EV) priced with this tool.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"end_date": {
"description": "Window end (YYYY-MM-DD). The LAST returned row on/before this date is the price ON OR BEFORE it. Omit start_date to fetch just the price on/before this date.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"limit": {
"default": 30,
"description": "Max rows (newest first if the window exceeds it). Default 30. For a point-to-point return over a long span, make TWO narrow-window calls (one per date) rather than one wide window — cheaper, and avoids the cap dropping your start date.",
"maximum": 2000,
"minimum": 1,
"type": "integer"
},
"start_date": {
"description": "Window start (YYYY-MM-DD). Markets trade only on business days — if this date is a weekend/holiday the FIRST returned row is the next OPEN day (the price ON OR AFTER this date). Omit end_date to fetch just the price on/after this date.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). US exchange-listed (NYSE/Nasdaq/AMEX), 1–5 letters.",
"type": "string"
}
},
"required": [
"ticker"
],
"type": "object"
},
"name": "get_stock_price",
"outputSchema": null
},
{
"description": "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.\n\n- Breakdowns exist only where the filer tags them (usually revenue + segment profit / Adjusted EBITDA).\n- **Revenue concentration / share** by customer, channel, distributor, geography or product: search `concentration` (as-filed `ConcentrationRiskPercentage`, present even when the prose is qualitative).\n- A past filing: the default is the latest filing as of TODAY; pin `accession_number` or `fiscal_year`/`fiscal_period`.\n- A standalone quarter from a cumulative YTD line: `period_history: true` (recipe on that parameter).\n\n**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).\n\n**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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"accession_number": {
"description": "Specific filing accession number (from list_filings — which takes vantage_date, so it gives the filing current as of a past date). If omitted, resolves automatically from form_type + fiscal_year (latest filing as of today).",
"type": "string"
},
"fiscal_period": {
"description": "Pin the exact period when resolving by fiscal_year (Q1/Q2/Q3/Q4/FY). WITHOUT it, fiscal_year resolves to the LATEST filing of that year — wrong for 'as of <quarter>' questions (use this to get the right quarter's balance/figure). Ignored if accession_number or period_history is set. (For a concept's value across ALL periods at once, use period_history instead.)",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"FY"
],
"type": "string"
},
"fiscal_year": {
"description": "Fiscal year to look up (e.g., 2022). If omitted, uses the latest filing. Ignored if accession_number provided.",
"type": "integer"
},
"form_type": {
"default": "10-K",
"description": "Filing type when auto-resolving (ignored if accession_number provided). Default: 10-K (annual). FPI filers: 20-F/40-F (annual) or 6-K (interim) — the backend auto-resolves the right form family, so the default also serves FPIs.",
"enum": [
"10-K",
"10-Q",
"20-F",
"40-F",
"6-K"
],
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum facts to return (default 50, max 200)",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"period_history": {
"default": false,
"description": "Return the searched concept's full as-filed series ACROSS filings (every period: quarter, 6-month YTD, 9-month YTD, FY) instead of one filing's facts. Use this to de-cumulate a cumulative cash-flow / income line into a standalone quarter — e.g. Q2 cash paid for acquisitions = the 6-month YTD minus the Q1 3-month (both shown, sharing the same start date). Requires search; ignores accession_number / fiscal_year.",
"type": "boolean"
},
"search": {
"description": "Search XBRL concepts by label or name. SPACES INSIDE A TERM ARE 'AND' — every word must appear somewhere in the fact's concept name, label, OR its dimension axis/member labels AS THE FILER WROTE THEM. Commas are OR ('goodwill,impairment'). So adding a category word to narrow a search can silently DROP the series you want: the filer may name the axis something else entirely (AutoNation tags reporting-unit goodwill on 'Goodwill Reporting Units', so 'goodwill segment' eliminates it while 'goodwill' finds it). PREFER ONE WORD and filter the results yourself; widen if a multi-word search returns suspiciously few facts. Examples: 'goodwill', 'medical cost ratio', 'goodwill,impairment', 'concentration' (revenue share by customer / channel / distributor / geography / product).",
"type": "string"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'UNH', 'AAPL'). Must be exact.",
"type": "string"
}
},
"required": [
"ticker",
"search"
],
"type": "object"
},
"name": "get_xbrl_facts",
"outputSchema": null
},
{
"description": "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.\n\nUse it to:\n- get the accession_number of a specific past filing (for `get_filing_section` or `get_xbrl_facts`)\n- 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\n- see the section inventory with sizes, or confirm a filing exists\nFor what matters in the latest filing use `get_filing_index`; for earnings-call trends, `compare_earnings_calls`.\n\n**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\"`).\n\nResponses capped at ~20K chars; narrow via `form_type`, `fiscal_year`, or fewer `years`.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"cik": {
"description": "10-digit SEC CIK as alternative to ticker. Use for delisted/acquired companies (e.g., Z=Zillow ticker may not resolve; pass cik='0001617640' instead). Either ticker or cik required.",
"pattern": "^\\d{10}$",
"type": "string"
},
"fiscal_period": {
"description": "Pick a specific fiscal period. FY = annual (10-K / 20-F / 40-F); Q1/Q2/Q3 = quarterly (10-Q). The 4th quarter is reported in the annual 10-K, so Q4 is treated as FY. Combine with fiscal_year to pin a single filing.",
"enum": [
"Q1",
"Q2",
"Q3",
"Q4",
"FY"
],
"type": "string"
},
"fiscal_year": {
"description": "Pick a specific fiscal year (e.g., 2020). Resolved via the XBRL period index — correct for non-calendar fiscal years (a 10-K filed Feb 2024 is FY2023). Alone, lists all of that fiscal year's filings (10-K + its 10-Qs); combine with fiscal_period to pin one. Overrides years. DEF 14A / non-XBRL forms are not period-indexed. Data horizon: 2013+.",
"type": "integer"
},
"form_subtype": {
"description": "Filter 8-K filings by sub-type (derived from section inventory): earnings releases; event = M&A / exec changes / debt; transcript = earnings calls; other = misc. Implicitly narrows to form_type='8-K'. CANNOT be combined with fiscal_year/fiscal_period — 8-Ks carry no XBRL fiscal-period focus to pin against; use `years` and read the implied period off each row.",
"enum": [
"8-K-earnings",
"8-K-event",
"8-K-transcript",
"8-K-other"
],
"type": "string"
},
"form_type": {
"description": "Filter by form type: 10-K annual, 10-Q quarterly, 8-K current reports, DEF 14A proxy; 20-F/40-F annual and 6-K interim for foreign private issuers. Other forms (424B2, FWP, 13F-HR, 4): search_sec_filings(query, company, form_type, sections=false) links the filing on EDGAR (company: the 10-digit CIK; date_from for older filings).",
"enum": [
"10-K",
"10-Q",
"8-K",
"DEF 14A",
"20-F",
"40-F",
"6-K"
],
"type": "string"
},
"include_delisted": {
"default": false,
"description": "Opt in to historical data for a delisted company. Default false returns a structured 'delisted' error (HTTP 410) naming the delisting date. Querying by cik bypasses this gate. Applies to 10-K/10-Q/DEF 14A only.",
"type": "boolean"
},
"ticker": {
"description": "Company ticker symbol (e.g., 'AAPL'). Must be exact. Either ticker or cik required.",
"type": "string"
},
"vantage_date": {
"description": "As-of vantage (YYYY-MM-DD): only list filings filed ON OR BEFORE this date (point-in-time). Omit to list the most recent filings. For vantages older than the `years` window, pass a larger `years`.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"years": {
"default": 2,
"description": "Years of filing history (default 2, max 7). Ignored when fiscal_year is set.",
"maximum": 7,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"name": "list_filings",
"outputSchema": null
},
{
"description": "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.\n\n**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.\n\n**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.\n\nRead 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`.\n\nNot point-in-time: the live feed as of today (one company as of a past date: `list_filings` with `vantage_date`).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"form_subtypes": {
"description": "Filter by 8-K sub-type derived from section inventory. '8-K-earnings' = earnings release; '8-K-transcript' = earnings call transcript; '8-K-event' = M&A / executive changes / debt; '8-K-other' = misc. Implies 8-K filings only. Omit to include all subtypes.",
"items": {
"enum": [
"8-K-earnings",
"8-K-transcript",
"8-K-event",
"8-K-other"
],
"type": "string"
},
"type": "array"
},
"form_types": {
"description": "Filter by SEC form type. Examples: ['8-K'], ['8-K', '10-Q'], ['10-K']. Omit to include all form types.",
"items": {
"type": "string"
},
"type": "array"
},
"limit": {
"default": 50,
"description": "Max results (default 50, max 100). Sorted newest filing date first, then by company size, so a small limit still surfaces the largest issuers that filed.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"since": {
"description": "Filing date floor (inclusive): the SEC filing date, not the date MetricDuck extracted it. YYYY-MM-DD. Required. A small share of filings (mostly 8-K and 6-K exhibits) are extracted days or weeks after their filing date, so a poll from your last poll's date misses them: look back up to a month and dedupe by accession.",
"type": "string"
},
"ticker": {
"description": "Single-ticker alias of `tickers`. Both may be given (union, cap 50).",
"type": "string"
},
"tickers": {
"description": "Optional portfolio filter. Up to 50 tickers. Omit to scan the full universe.",
"items": {
"type": "string"
},
"maxItems": 50,
"type": "array"
}
},
"required": [
"since"
],
"type": "object"
},
"name": "list_recent_filings",
"outputSchema": null
},
{
"description": "Screen 5,500+ US companies by financial metrics. Find stocks matching quantitative criteria.\n\nMetric 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.\n\nTag filtering (required_tags / excluded_tags) selects by business-model classification; unclassified companies are excluded from tag-filtered results.\n\nUse Cases:\n- \"High ROIC tech stocks\" -> filters=[{metric_id:\"roic\", operator:\"gt\", value:0.15}], sectors=[\"TECH\"]\n- \"Undervalued profitable industrials\" -> filters=[{metric_id:\"pe_ratio\", operator:\"lt\", value:15}, {metric_id:\"pe_ratio\", operator:\"gt\", value:0}], sectors=[\"IND\"]\n- \"Revenue growing >10% YoY\" -> filters=[{metric_id:\"revenues\", operator:\"gt\", value:0.10, period_type:\"ttm.yoy\"}]\n- \"AI infrastructure companies not exposed to China supply chain\" -> required_tags=[\"ai_ml_infrastructure\"], excluded_tags=[\"china_supply_chain_heavy\"]\n- \"Profitable subscription businesses\" -> filters=[{metric_id:\"net_margin\", operator:\"gt\", value:0.10}], required_tags=[\"subscription_recurring\"]\n\nTo 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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"excluded_tags": {
"description": "Classification tags results must NOT have (e.g., ['china_supply_chain_heavy', 'regulated_industry']).",
"items": {
"type": "string"
},
"type": "array"
},
"filters": {
"description": "Metric filters",
"items": {
"additionalProperties": false,
"properties": {
"max_value": {
"description": "Max value (for 'between' only)",
"type": "number"
},
"metric_id": {
"description": "Metric identifier. Valuation: pe_ratio, pb_ratio, ev_ebitda, fcf_yield, market_cap, ev. Profitability: gross_margin, oper_margin, net_margin, ebitda_margin, roe, roa, roic. Cash flow: fcf, net_cf_ops, cash_conversion. Balance sheet: debt_to_equity, current_ratio, ttl_debt, ttl_equity, cash_st_invs. Size: revenues, net_income, ebitda, gross_profit. Margins, returns and ROIC are decimals (0.15 = 15%); a negative P/E means losses (add a gt 0 filter to exclude loss-makers).",
"type": "string"
},
"min_value": {
"description": "Min value (for 'between' only)",
"type": "number"
},
"operator": {
"description": "Comparison operator",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq",
"between"
],
"type": "string"
},
"period_type": {
"description": "Period: 'ttm' (default), 'ss' (balance-sheet snapshot), growth pairs revenues/net_income/eps_basic/eps_diluted/fcf/roic @ 'ttm.yoy', revenues/fcf @ 'ttm.cagr3', ttl_assets @ 'ss.yoy', and 'q.med8'/'q.trend8'/'q.stdv8' valuation-quality series (pe_ratio, ev_ebitda, ev_fcf, roic). LATEST-snapshot values only; an unsupported metric+period returns a 422 naming the supported set (full history: get_metric_history).",
"type": "string"
},
"value": {
"description": "Threshold value (for gt/gte/lt/lte/eq)",
"type": "number"
}
},
"required": [
"metric_id",
"operator"
],
"type": "object"
},
"type": "array"
},
"limit": {
"default": 20,
"description": "Max results (default 20, max 50). Responses cap at ~20K chars: a lower limit or stricter filters keep them whole.",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"required_tags": {
"description": "Classification tags all results must have (e.g., ['ai_ml_infrastructure', 'subscription_recurring']). Tags: cloud_infrastructure, saas_enterprise, saas_smb, marketplace_platform, semiconductor_design, semiconductor_foundry, financial_services_traditional, insurance_carrier, investment_management, pharmaceutical_discovery, medical_devices, retail_physical, ecommerce_direct, media_streaming, subscription_recurring, usage_based, hardware_sale, transaction_fee, advertising_based, government_contract, services_project, ai_ml_core_product, ai_ml_infrastructure, semiconductor_advanced_node, data_center_hyperscale, cybersecurity, autonomous_vehicles, electric_vehicle, renewable_energy, biotech_genomics, mrna_platform, robotics_automation, enterprise_b2b_large, smb_focused, consumer_direct, developer_platform, china_revenue_heavy, china_supply_chain_heavy, us_domestic_only, global_diversified, regulated_industry, export_controlled, dual_use_technology, foreign_private_issuer, holding_company_structure.",
"items": {
"type": "string"
},
"type": "array"
},
"sectors": {
"description": "Sector codes: TECH, FIN, HEALTH, CONS_STAPLES, CONS_DISC, IND, ENERGY, UTIL, RE, MAT, COMM.",
"items": {
"type": "string"
},
"type": "array"
},
"sort_by": {
"description": "Metric ID to sort by (default: 'market_cap')",
"type": "string"
}
},
"required": [
"filters"
],
"type": "object"
},
"name": "screen_companies",
"outputSchema": null
},
{
"description": "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.\n\nSignals 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.\n\nUse Cases:\n- \"Which tech companies have cautious management?\" -> signals=[\"tone_cautious\"], sectors=[\"TECH\"]\n- \"Who lowered guidance in an earnings release this month?\" -> signals=[\"earnings_guidance_lowered_8k\"], recency_days=30\n- \"Any filing red flags for NVDA lately?\" -> ticker=\"NVDA\", signals=[\"tone_cautious\", \"covenant_risk\", \"debt_maturity_near\"], match_mode=\"any\"\n- \"Companies that gave specific guidance on calls?\" -> signals=[\"transcript_has_guidance\"]\n- \"Which companies announced strategic partnerships or M&A deals?\" -> signals=[\"ir_partnership\"]\n\nM&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.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"agreement_type_filter": {
"description": "Discriminator for `ir_partnership` signals — e.g. 'm_and_a_announcement' for fresh M&A deals, 'partnership_strategic' for alliances. Ignored for non-IR signals.",
"enum": [
"partnership_strategic",
"partnership_supply",
"partnership_jv",
"partnership_amendment",
"warrant_issuance",
"m_and_a_announcement",
"m_and_a_amendment",
"m_and_a_termination",
"m_and_a_close",
"other"
],
"type": "string"
},
"limit": {
"default": 20,
"description": "Max results (default: 20)",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"match_mode": {
"default": "all",
"description": "Match semantics within a source type. 'all' (default) = every requested signal fires on the SAME row (targeted screening); 'any' = at least one fires (broadcast discovery / digest pools).",
"enum": [
"all",
"any"
],
"type": "string"
},
"order_by": {
"default": "recency",
"description": "Result ordering. 'recency' (default) = event_date/filing_date DESC; 'market_cap' = market-cap DESC NULLS LAST with a recency tiebreak — use it so high-impact filings aren't pushed past the limit by fresher small-cap noise.",
"enum": [
"recency",
"market_cap"
],
"type": "string"
},
"recency_days": {
"default": 90,
"description": "Only filings from last N days (default: 90)",
"maximum": 365,
"minimum": 1,
"type": "integer"
},
"sectors": {
"description": "Sector codes: TECH, HEALTH, FIN, RE, CONS_DISC, CONS_STAPLES, IND, MAT, ENERGY, UTIL, TRANSPORT, COMM, OTHER",
"items": {
"type": "string"
},
"type": "array"
},
"signals": {
"description": "Signal filters to match. Pass one or more ids EXACTLY as listed below (only these are screenable).\nOmit `ticker` to screen the whole universe for a signal (the common case); pass `ticker` only to check ONE company — don't loop company-by-company.\n\n**Filing signals (10-K/10-Q):**\n- `tone_cautious` — Management tone is cautious/defensive\n- `customer_concentration_high` — Customer concentration > 20% or elevated risk\n- `covenant_risk` — Covenant tight, waiver obtained, or violation\n- `debt_maturity_near` — Significant debt maturing within 12 months\n- `dividend_coverage_weak` — Dividend coverage below operating cash flow\n- `sbc_unhedged` — Stock comp exceeds buybacks (net dilution)\n- `has_fuel_sensitivity` — Fuel cost sensitivity quantified in MD&A\n- `mda_has_scale_claims` — ≥3 quantified operational scale claims extracted from MD&A narrative (e.g. renewal rates, member counts, comp sales)\n\n**Earnings releases (8-K Item 2.02 + 6-K Ex 99.1):**\n- `earnings_revenue_grew` — Revenue grew year-over-year\n- `earnings_revenue_declined` — Revenue declined year-over-year\n- `earnings_margin_expanded` — Operating or gross margin expanded vs prior year\n- `earnings_margin_contracted` — Operating or gross margin contracted vs prior year\n- `earnings_guidance_raised_8k` — Forward guidance raised in earnings release\n- `earnings_guidance_lowered_8k` — Forward guidance lowered in earnings release\n- `earnings_has_special_items` — Non-recurring charges or special items disclosed\n- `earnings_accrual_concerning` — Accrual quality weak or concerning (cash vs earnings divergence)\n- `earnings_has_capital_return` — Shareholder capital returned (buybacks and/or dividends)\n\n**Earnings call transcript:**\n- `transcript_has_guidance` — Specific guidance given on earnings call\n- `transcript_has_prepared_remarks` — Prepared remarks available (true for all transcript sources)\n- `transcript_has_analyst_questions` — Analyst Q&A captured with topics + firms\n- `transcript_guidance_raised` — ≥1 guidance item raised vs prior quarter (from transcript)\n- `transcript_guidance_lowered` — ≥1 guidance item lowered vs prior quarter (from transcript)\n- `transcript_has_revenue_decompositions` — Segment-level revenue decomposed into quantified drivers (volume / price / mix / FX / M&A) on call\n- `transcript_qa_concerns_retained` — ≥2 analysts left with concerns retained after Q&A\n- `transcript_qa_forward_committed` — ≥2 executive responses with forward-looking commitments on call (count-based; transcript_has_forward_commits exposes the underlying instances)\n\n**IR events:**\n- `ir_partnership` — Strategic partnerships announced\n\n**DEF 14A proxy:**\n- `def14a_peer_group` — Compensation peer group disclosed (with company names)\n- `def14a_ceo_pay_ratio` — CEO pay ratio disclosed",
"items": {
"enum": [
"tone_cautious",
"customer_concentration_high",
"covenant_risk",
"debt_maturity_near",
"dividend_coverage_weak",
"sbc_unhedged",
"has_fuel_sensitivity",
"earnings_revenue_grew",
"earnings_revenue_declined",
"earnings_margin_expanded",
"earnings_margin_contracted",
"earnings_guidance_raised_8k",
"earnings_guidance_lowered_8k",
"earnings_has_special_items",
"earnings_accrual_concerning",
"earnings_has_capital_return",
"transcript_has_guidance",
"transcript_has_prepared_remarks",
"transcript_has_analyst_questions",
"transcript_guidance_raised",
"transcript_guidance_lowered",
"transcript_has_revenue_decompositions",
"transcript_qa_concerns_retained",
"transcript_qa_forward_committed",
"mda_has_scale_claims",
"ir_partnership",
"def14a_peer_group",
"def14a_ceo_pay_ratio"
],
"type": "string"
},
"type": "array"
},
"since_date": {
"description": "Lower bound (inclusive, YYYY-MM-DD) on event_date / filing_date. With until_date, defines an explicit range that OVERRIDES recency_days — use for historical windows, backfilling past digests, or comparing two windows to detect cross-period signal change.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"ticker": {
"description": "Filter to a single ticker (e.g. 'NVDA'). Use for per-ticker cross-source signal inventory. Omit to screen across all companies.",
"type": "string"
},
"until_date": {
"description": "Upper bound (inclusive, YYYY-MM-DD). With since_date, overrides recency_days.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
},
"required": [
"signals"
],
"type": "object"
},
"name": "screen_filing_signals",
"outputSchema": null
},
{
"description": "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.\n\n**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).\n\n**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).\n\n**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`).",
"inputSchema": {
"additionalProperties": false,
"properties": {
"limit": {
"default": 5,
"description": "Maximum results (default 5, max 20)",
"maximum": 20,
"minimum": 1,
"type": "integer"
},
"query": {
"description": "Company name or ticker (supports partial matches and typos). 2-5 uppercase letters are read as a ticker: pass an all-caps NAME that is not a ticker (\"AMCOR\") in normal casing (\"Amcor\"). A miss returns near-matches when possible. Foreign issuers filing a US 20-F/40-F (HSBC, Toyota, Novo Nordisk): use the company name, not a local symbol.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "search_companies",
"outputSchema": null
},
{
"description": "Search the full text of SEC filings since 2001 to find companies related to any concept — a product, technology, regulation, event, or company.\n\nReturns 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.\n\n**Searchable form types** — any SEC form (default window: last year); omit `form_type` for all:\n- Periodic reports: 10-K, 10-Q (section-level drill-down available), 20-F, 40-F, 6-K (foreign private issuers)\n- Events + proxies: 8-K, DEF 14A / DEFM14A / PRE 14A\n- Registration + offerings: S-1, F-1, S-3, S-4, 424B series\n- Ownership + other: SCHEDULE 13D/G (was SC 13D/G), SD (conflict minerals), N-CSR / N-CSRS (fund reports)\n\n**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.\n\nUse cases:\n- \"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`).\n- \"What did WM say at its investor day?\" → query=\"\\\"investor day\\\"\", company=\"WM\" → that filer only\n- \"Recent data breaches?\" → query=\"cybersecurity incident\", form_type=\"8-K\"\n- \"Tariff-exposed companies?\" → query=\"tariff\", form_type=\"10-K\" → risk factor disclosures\n- \"Activist campaigns?\" → query=\"board representation\", form_type=\"DEF 14A,SCHEDULE 13D\"\n\nOther tools: one known company's filings → `get_filing_index` / `list_filings`; numeric filters → `screen_companies`; earnings-call trends → `compare_earnings_calls`.\n\nKey limitation: keyword matching only, not semantic. \"No material weakness\" matches \"material weakness found.\" Verify hits with `get_filing_section` for context.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"company": {
"description": "Restrict to one company. Accepts a ticker (e.g. 'WSC'), a CIK (exact match, preferred — get from search_companies; shorter numeric CIKs are auto-zero-padded to 10 digits), or a company name (partial match — may include unrelated companies).",
"type": "string"
},
"date_from": {
"description": "Start date YYYY-MM-DD. Default: 1 year ago. For a HISTORICAL event (M&A announcement, lawsuit, restructuring, leadership change) set it before the event, with form_type='8-K' and rank_by='relevance': the default window and date order bury the anchor 8-K under mutual-fund NPORT-P holdings.",
"type": "string"
},
"date_to": {
"description": "End date YYYY-MM-DD. Default: today.",
"type": "string"
},
"form_type": {
"description": "SEC form type filter. 10-K (annual report), 10-Q (quarterly), 8-K (material events), DEF 14A (proxy/compensation), S-1 (IPO registration). Comma-separated for multiple: '10-K,10-Q'. Omit to search all types. 13D/13G are filed as 'SCHEDULE 13D' / 'SCHEDULE 13G' since December 2024 and as 'SC 13D' / 'SC 13G' before: pass both ('SC 13D,SCHEDULE 13D') for a window that spans it. Forms 3/4/5: a ticker in company finds almost none of a company's filings; use the 10-digit CIK (exact), not a name (partial match).",
"type": "string"
},
"limit": {
"default": 10,
"description": "Max results (default 10, max 100). Results deduplicated by filing, sorted most recent first. Section-level enrichment applies to the first 5 results.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"query": {
"description": "Search terms. All terms required by default (implicit AND). Syntax: exact phrase \"revenue recognition\", OR: \"goodwill impairment\" OR \"asset writedown\", NOT: restructuring NOT \"restructuring charges\", NEAR: goodwill NEAR(5) impairment (within N words), wildcard: restructur* (trailing only, not in phrases). Use formal terms as written in SEC filings, not abbreviations. Required.",
"type": "string"
},
"rank_by": {
"default": "date",
"description": "Sort order for the returned filing list. 'date' (default) = most recent filings first — best for time-sensitive queries (breaches, guidance changes, recent events). 'relevance' = EFTS native relevance score — best for thematic discovery where the most concentrated mentions matter more than recency (e.g., 'liquefied natural gas', 'H100 supply chain'). The Company Exposure Map is always frequency-ranked from EFTS aggregation regardless of rank_by.",
"enum": [
"date",
"relevance"
],
"type": "string"
},
"sections": {
"default": true,
"description": "Include section-level matches showing WHERE in each filing the term appears. Provides exact section + chunk pointers for immediate drill-in with get_filing_section. Set false for faster filing-level-only results.",
"type": "boolean"
},
"ticker_lookup": {
"description": "RETIRED — returns a redirect. Scope with `company`; to find who MENTIONS a company, search its formal name with form_type.",
"type": "string"
}
},
"type": "object"
},
"name": "search_sec_filings",
"outputSchema": null
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:03f326d9b9da61ed515f4cec6571612040bacedfdb402034dc33de4e83318989 | sha256sum