get_filing_section

{
  "type": "object",
  "properties": {
    "ticker": {
      "type": "string",
      "description": "Company ticker symbol (e.g., 'AAPL'). Required unless cik is provided."
    },
    "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."
    },
    "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."
    },
    "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_income_statement`, `earnings_balance_sheet`, `earnings_cash_flow`, `earnings_segment_data`, `earnings_gaap_reconciliation`, `earnings_supplemental_tables`, `earnings_full_text`\n  ↳ `earnings_guidance` = the forward guidance/outlook table (next-period ranges). `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**20-F / foreign filer:** `mda_operating_results`, `mda_trend_information`, `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."
    },
    "accession_number": {
      "type": "string",
      "description": "Filing accession number from list_filings. Latest filing used if omitted."
    },
    "form_type": {
      "type": "string",
      "enum": [
        "10-K",
        "10-Q",
        "8-K",
        "DEF 14A",
        "20-F",
        "40-F",
        "6-K"
      ],
      "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."
    },
    "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."
    },
    "fiscal_period": {
      "type": "string",
      "enum": [
        "Q1",
        "Q2",
        "Q3",
        "Q4",
        "FY"
      ],
      "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."
    },
    "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."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "default": 0,
      "description": "Chunk offset for pagination (default 0)"
    },
    "char_offset": {
      "type": "integer",
      "minimum": 0,
      "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."
    },
    "max_chunks": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 10,
      "description": "Chunks per page (default 10, max 10)"
    },
    "query": {
      "type": "string",
      "description": "Keyword to search within section chunks (e.g., 'customer concentration', 'export control'). Returns only matching chunks."
    },
    "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."
    },
    "max_chars": {
      "type": "integer",
      "minimum": 2000,
      "maximum": 60000,
      "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."
    },
    "preview_chars": {
      "type": "integer",
      "minimum": 0,
      "maximum": 200,
      "default": 120,
      "description": "Outline-mode preview length per section (default 120 ≈ 25 words). Ignored when section_id is provided."
    }
  },
  "additionalProperties": false
}