screen_filing_signals

{
  "type": "object",
  "properties": {
    "signals": {
      "type": "array",
      "items": {
        "type": "string",
        "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"
        ]
      },
      "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"
    },
    "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"
    },
    "recency_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "default": 90,
      "description": "Only filings from last N days (default: 90)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20,
      "description": "Max results (default: 20)"
    },
    "match_mode": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "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)."
    },
    "order_by": {
      "type": "string",
      "enum": [
        "recency",
        "market_cap"
      ],
      "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."
    },
    "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 or backfilling past digests."
    },
    "until_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Upper bound (inclusive, YYYY-MM-DD). With since_date, overrides recency_days."
    },
    "agreement_type_filter": {
      "type": "string",
      "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"
      ],
      "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."
    }
  },
  "required": [
    "signals"
  ],
  "additionalProperties": false
}