Screen Filing Signals
screen_filing_signalsUse this when the user asks which companies show a red flag or event across filings, earnings releases or earnings calls — "which companies lowered guidance?", "who has covenant risk or debt coming due?", "which tech companies sound cautious?", "who announced M&A or a partnership?" — or what has flagged for one company recently (ticker). Not metric screening (P/E, ROIC: use screen_companies). Most signals are LLM-classified, not computed facts.
Signals come from 10-K/10-Q filings, 8-K/6-K earnings releases, earnings-call transcripts, 8-K M&A / partnership announcements and DEF 14A proxies. Ids and labels: see the signals parameter.
Use Cases:
"Which tech companies have cautious management?" -> signals=["tone_cautious"], sectors=["TECH"]
"Who lowered guidance in an earnings release this month?" -> signals=["earnings_guidance_lowered_8k"], recency_days=30
"Any filing red flags for NVDA lately?" -> ticker="NVDA", signals=["tone_cautious", "covenant_risk", "debt_maturity_near"], match_mode="any"
"Companies that gave specific guidance on calls?" -> signals=["transcript_has_guidance"]
"Which companies announced strategic partnerships or M&A deals?" -> signals=["ir_partnership"]
M&A / partnership rows: an ir_partnership match on an 8-K Item 1.01 may carry companion_accessions — same-day 8-Ks (7.01 / 8.01, Ex 99 press release) holding the deal terms and CEO quotes. Read them with get_filing_section(ticker, section_id="item_1_01_material_agreement", accession_number=<the row's accession>, include_companions=true, companion_accessions=[...]). An empty list means none was found; the anchor alone still reads.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: 20) | |
| ticker | No | Filter to a single ticker (e.g. 'NVDA'). Use for per-ticker cross-source signal inventory. Omit to screen across all companies. | |
| sectors | No | Sector codes: TECH, HEALTH, FIN, RE, CONS_DISC, CONS_STAPLES, IND, MAT, ENERGY, UTIL, TRANSPORT, COMM, OTHER | |
| signals | Yes | Signal filters to match. Pass one or more ids EXACTLY as listed below (only these are screenable). Omit `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. **Filing signals (10-K/10-Q):** - `tone_cautious` — Management tone is cautious/defensive - `customer_concentration_high` — Customer concentration > 20% or elevated risk - `covenant_risk` — Covenant tight, waiver obtained, or violation - `debt_maturity_near` — Significant debt maturing within 12 months - `dividend_coverage_weak` — Dividend coverage below operating cash flow - `sbc_unhedged` — Stock comp exceeds buybacks (net dilution) - `has_fuel_sensitivity` — Fuel cost sensitivity quantified in MD&A - `mda_has_scale_claims` — ≥3 quantified operational scale claims extracted from MD&A narrative (e.g. renewal rates, member counts, comp sales) **Earnings releases (8-K Item 2.02 + 6-K Ex 99.1):** - `earnings_revenue_grew` — Revenue grew year-over-year - `earnings_revenue_declined` — Revenue declined year-over-year - `earnings_margin_expanded` — Operating or gross margin expanded vs prior year - `earnings_margin_contracted` — Operating or gross margin contracted vs prior year - `earnings_guidance_raised_8k` — Forward guidance raised in earnings release - `earnings_guidance_lowered_8k` — Forward guidance lowered in earnings release - `earnings_has_special_items` — Non-recurring charges or special items disclosed - `earnings_accrual_concerning` — Accrual quality weak or concerning (cash vs earnings divergence) - `earnings_has_capital_return` — Shareholder capital returned (buybacks and/or dividends) **Earnings call transcript:** - `transcript_has_guidance` — Specific guidance given on earnings call - `transcript_has_prepared_remarks` — Prepared remarks available (true for all transcript sources) - `transcript_has_analyst_questions` — Analyst Q&A captured with topics + firms - `transcript_guidance_raised` — ≥1 guidance item raised vs prior quarter (from transcript) - `transcript_guidance_lowered` — ≥1 guidance item lowered vs prior quarter (from transcript) - `transcript_has_revenue_decompositions` — Segment-level revenue decomposed into quantified drivers (volume / price / mix / FX / M&A) on call - `transcript_qa_concerns_retained` — ≥2 analysts left with concerns retained after Q&A - `transcript_qa_forward_committed` — ≥2 executive responses with forward-looking commitments on call (count-based; transcript_has_forward_commits exposes the underlying instances) **IR events:** - `ir_partnership` — Strategic partnerships announced **DEF 14A proxy:** - `def14a_peer_group` — Compensation peer group disclosed (with company names) - `def14a_ceo_pay_ratio` — CEO pay ratio disclosed | |
| order_by | No | 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. | recency |
| match_mode | No | 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). | all |
| since_date | No | 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 | No | Upper bound (inclusive, YYYY-MM-DD). With since_date, overrides recency_days. | |
| recency_days | No | Only filings from last N days (default: 90) | |
| agreement_type_filter | No | 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. |