MetricDuck — Financial Analysis

{'type': 'object', 'required': ['query'], 'properties': {'query': {'type': 'string', 'minLength': 1, '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."}, 'include_delisted': {'type': 'boolean', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'ticker': {'type': 'string', 'description': "Primary company ticker symbol to compare (e.g., 'AAPL'). Must be exact."}, 'metrics': {'type': 'string', '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."}, 'peer_mode': {'enum': ['sector', 'tags'], 'type': 'string', '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."}, 'custom_peers': {'type': 'string', 'description': "Optional comma-separated peer tickers (e.g., 'MSFT,GOOG,AMZN'). Auto-selected if omitted."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'NVDA'). Must be exact."}, 'dimensions': {'type': 'array', 'items': {'enum': ['guidance', 'hedges', 'qa', 'priorities', 'macro', 'competitive', 'scale_claims', 'revdecomp', 'kpi', 'capital_allocation', 'scenarios', 'forward_commits', 'customer_cohort'], 'type': 'string'}, '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).'}, 'n_quarters': {'type': 'integer', 'default': 4, 'maximum': 8, 'minimum': 2, 'description': 'How many most-recent earnings calls to compare (default: 4, min: 2, max: 8).'}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Required."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'depth': {'enum': ['snapshot', 'core', 'full'], 'type': 'string', '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."}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL', 'MSFT'). Must be exact — search_companies resolves a name."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'NVDA'). Must be exact."}, 'quarters': {'type': 'integer', 'default': 4, 'maximum': 8, 'minimum': 1, 'description': 'Number of most recent quarters to return (1-8, default 4).'}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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. Measured 2026-08-25: 0.60% of release/signal pairs ever change value across extractions, all same-accession corrections, zero issuer revisions — a genuine issuer revision arrives as a NEW accession, which this bound catches.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'limit': {'type': 'integer', 'maximum': 40, 'minimum': 1, 'description': 'Most-recent fiscal periods to return (newest first). Default 12.'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'MRK'). Required."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'lens': {'enum': ['earnings_quality', 'debt_stress', 'risk_trajectory', 'competitive_position', 'management_outlook'], 'type': 'string', '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.'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Must be exact."}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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."}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'cik': {'type': 'string', 'pattern': '^\\d{10}$', '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."}, 'query': {'type': 'string', 'description': "Keyword to search within section chunks (e.g., 'customer concentration', 'export control'). Returns only matching chunks."}, 'offset': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Chunk offset for pagination (default 0)'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Required unless cik is provided."}, 'form_type': {'enum': ['10-K', '10-Q', '8-K', 'DEF 14A', '20-F', '40-F', '6-K'], 'type': 'string', '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).'}, 'max_chars': {'type': 'integer', 'default': 20000, 'maximum': 60000, 'minimum': 2000, '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.'}, 'max_chunks': {'type': 'integer', 'default': 10, 'maximum': 10, 'minimum': 1, 'description': 'Chunks per page (default 10, max 10)'}, 'section_id': {'type': 'string', '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.'}, 'char_offset': {'type': 'integer', 'default': 0, 'minimum': 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.'}, 'fiscal_year': {'type': 'integer', '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."}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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."}, 'fiscal_period': {'enum': ['Q1', 'Q2', 'Q3', 'Q4', 'FY'], 'type': 'string', '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."}, 'preview_chars': {'type': 'integer', 'default': 120, 'maximum': 200, 'minimum': 0, 'description': 'Outline-mode preview length per section (default 120 ≈ 25 words). Ignored when section_id is provided.'}, 'accession_number': {'type': 'string', 'description': 'Filing accession number from list_filings. Latest filing used if omitted.'}, 'include_delisted': {'type': 'boolean', 'description': 'Query a delisted/acquired company by its old ticker. Default false returns a structured delisted error pointing at the CIK.'}, 'include_companions': {'type': 'boolean', '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."}, 'companion_accessions': {'type': 'array', 'items': {'type': 'string'}, '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'years': {'type': 'integer', 'default': 2, 'maximum': 10, 'minimum': 1, 'description': 'Years of history (default 2, max 10)'}, 'period': {'enum': ['quarterly', 'annual'], 'type': 'string', 'default': 'quarterly', 'description': 'Time period granularity'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Must be exact."}, 'statements': {'type': 'array', 'items': {'enum': ['income', 'balance', 'cashflow'], 'type': 'string'}, 'default': ['income', 'balance', 'cashflow'], 'description': 'Which statements to include (default: all three)'}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'NVDA'). Must be exact."}, 'fiscal_period': {'type': 'string', 'description': 'Target fiscal period, e.g. "Q2 FY2026". If omitted, defaults to the most recent period with SEC filing actuals.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'cik': {'type': 'string', 'pattern': '^\\d{10}$', 'description': "10-digit SEC CIK as an alternative to ticker (e.g., '0000797468')."}, 'mode': {'enum': ['full', 'list'], 'type': 'string', '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).'}, 'query': {'type': 'string', '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.'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'OXY'). Required unless cik is provided."}, 'fiscal_year': {'type': 'integer', 'maximum': 2100, 'minimum': 2000, 'description': 'Fiscal year of the deck (e.g., 2024). Narrows to one period when combined with fiscal_period.'}, 'fiscal_period': {'type': 'string', 'description': "Fiscal period: 'Q3' (with fiscal_year) or combined '2024Q3'. Omit to return the latest deck(s)."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker', 'metric_id'], 'properties': {'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Must be exact."}, 'window': {'type': 'integer', 'default': 20, 'maximum': 40, 'minimum': 1, 'description': 'Max observations returned, newest first. Default 20, max 40.'}, 'metric_id': {'type': 'string', '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.'}, 'period_type': {'enum': ['Q', 'FY', 'TTM'], 'type': 'string', 'default': 'Q', 'description': 'Q = quarterly, FY = fiscal year, TTM = trailing 12 months.'}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker', 'metric'], 'properties': {'metric': {'type': 'string', 'description': "Metric id of a COMPUTED metric (e.g. 'net_margin', 'roic', 'fcf', 'ev_ebitda')."}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Must be exact."}, 'segment': {'type': 'string', 'description': 'Reporting segment id. Omit for the consolidated figure.'}, 'fiscal_year': {'type': 'integer', 'description': 'Pin the fiscal year (e.g. 2025). Omit for the latest period.'}, 'period_type': {'enum': ['Q', 'FY', 'TTM'], 'type': 'string', 'default': 'Q', 'description': 'Q = quarterly, FY = fiscal year, TTM = trailing 12 months.'}, 'fiscal_period': {'enum': ['Q1', 'Q2', 'Q3', 'Q4', 'FY'], 'type': 'string', 'description': 'Pin the fiscal period. Omit for the latest.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker'], 'properties': {'limit': {'type': 'integer', 'default': 30, 'maximum': 2000, 'minimum': 1, '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.'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). US exchange-listed (NYSE/Nasdaq/AMEX), 1–5 letters."}, 'end_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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.'}, 'start_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['ticker', 'search'], 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 200, 'minimum': 1, 'description': 'Maximum facts to return (default 50, max 200)'}, 'search': {'type': 'string', '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)."}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'UNH', 'AAPL'). Must be exact."}, 'form_type': {'enum': ['10-K', '10-Q', '20-F', '40-F', '6-K'], 'type': 'string', '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 (#558).'}, 'fiscal_year': {'type': 'integer', 'description': 'Fiscal year to look up (e.g., 2022). If omitted, uses the latest filing. Ignored if accession_number provided.'}, 'fiscal_period': {'enum': ['Q1', 'Q2', 'Q3', 'Q4', 'FY'], 'type': 'string', '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.)"}, 'period_history': {'type': 'boolean', '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."}, 'accession_number': {'type': 'string', '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).'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'cik': {'type': 'string', 'pattern': '^\\d{10}$', '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."}, 'years': {'type': 'integer', 'default': 2, 'maximum': 7, 'minimum': 1, 'description': 'Years of filing history (default 2, max 7). Ignored when fiscal_year is set.'}, 'ticker': {'type': 'string', 'description': "Company ticker symbol (e.g., 'AAPL'). Must be exact. Either ticker or cik required."}, 'form_type': {'enum': ['10-K', '10-Q', '8-K', 'DEF 14A', '20-F', '40-F', '6-K'], 'type': 'string', '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).'}, 'fiscal_year': {'type': 'integer', '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+."}, 'form_subtype': {'enum': ['8-K-earnings', '8-K-event', '8-K-transcript', '8-K-other'], 'type': 'string', '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."}, 'vantage_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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`.'}, 'fiscal_period': {'enum': ['Q1', 'Q2', 'Q3', 'Q4', 'FY'], 'type': 'string', '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.'}, 'include_delisted': {'type': 'boolean', '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['since'], 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 100, 'minimum': 1, '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.'}, 'since': {'type': 'string', '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."}, 'ticker': {'type': 'string', 'description': 'Single-ticker alias of `tickers`. Both may be given (union, cap 50).'}, 'tickers': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 50, 'description': 'Optional portfolio filter. Up to 50 tickers. Omit to scan the full universe.'}, 'form_types': {'type': 'array', 'items': {'type': 'string'}, 'description': "Filter by SEC form type. Examples: ['8-K'], ['8-K', '10-Q'], ['10-K']. Omit to include all form types."}, 'form_subtypes': {'type': 'array', 'items': {'enum': ['8-K-earnings', '8-K-transcript', '8-K-event', '8-K-other'], 'type': 'string'}, '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['filters'], 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 50, 'minimum': 1, 'description': 'Max results (default 20, max 50). Responses cap at ~20K chars: a lower limit or stricter filters keep them whole.'}, 'filters': {'type': 'array', 'items': {'type': 'object', 'required': ['metric_id', 'operator'], 'properties': {'value': {'type': 'number', 'description': 'Threshold value (for gt/gte/lt/lte/eq)'}, 'operator': {'enum': ['gt', 'gte', 'lt', 'lte', 'eq', 'between'], 'type': 'string', 'description': 'Comparison operator'}, 'max_value': {'type': 'number', 'description': "Max value (for 'between' only)"}, 'metric_id': {'type': 'string', '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).'}, 'min_value': {'type': 'number', 'description': "Min value (for 'between' only)"}, 'period_type': {'type': 'string', '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)."}}, 'additionalProperties': False}, 'description': 'Metric filters'}, 'sectors': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sector codes: TECH, FIN, HEALTH, CONS_STAPLES, CONS_DISC, IND, ENERGY, UTIL, RE, MAT, COMM.'}, 'sort_by': {'type': 'string', 'description': "Metric ID to sort by (default: 'market_cap')"}, 'excluded_tags': {'type': 'array', 'items': {'type': 'string'}, 'description': "Classification tags results must NOT have (e.g., ['china_supply_chain_heavy', 'regulated_industry'])."}, 'required_tags': {'type': 'array', 'items': {'type': 'string'}, '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['signals'], 'properties': {'limit': {'type': 'integer', 'default': 20, 'maximum': 50, 'minimum': 1, 'description': 'Max results (default: 20)'}, 'ticker': {'type': 'string', 'description': "Filter to a single ticker (e.g. 'NVDA'). Use for per-ticker cross-source signal inventory. Omit to screen across all companies."}, 'sectors': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Sector codes: TECH, HEALTH, FIN, RE, CONS_DISC, CONS_STAPLES, IND, MAT, ENERGY, UTIL, TRANSPORT, COMM, OTHER'}, 'signals': {'type': 'array', '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'}, '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"}, 'order_by': {'enum': ['recency', 'market_cap'], 'type': 'string', '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."}, 'match_mode': {'enum': ['all', 'any'], 'type': 'string', '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)."}, 'since_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', '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.'}, 'until_date': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'Upper bound (inclusive, YYYY-MM-DD). With since_date, overrides recency_days.'}, 'recency_days': {'type': 'integer', 'default': 90, 'maximum': 365, 'minimum': 1, 'description': 'Only filings from last N days (default: 90)'}, 'agreement_type_filter': {'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', '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."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['query'], 'properties': {'limit': {'type': 'integer', 'default': 5, 'maximum': 20, 'minimum': 1, 'description': 'Maximum results (default 5, max 20)'}, 'query': {'type': 'string', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 10, 'maximum': 100, 'minimum': 1, 'description': 'Max results (default 10, max 100). Results deduplicated by filing, sorted most recent first. Section-level enrichment applies to the first 5 results.'}, 'query': {'type': 'string', '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.'}, 'company': {'type': 'string', '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)."}, 'date_to': {'type': 'string', 'description': 'End date YYYY-MM-DD. Default: today.'}, 'rank_by': {'enum': ['date', 'relevance'], 'type': 'string', '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."}, 'sections': {'type': 'boolean', '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.'}, 'date_from': {'type': 'string', '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."}, 'form_type': {'type': 'string', '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)."}, 'ticker_lookup': {'type': 'string', 'description': 'RETIRED — returns a redirect. Scope with `company`; to find who MENTIONS a company, search its formal name with form_type.'}}, 'additionalProperties': False}