filing-sentiment

name

filing-sentiment

description

Score 10-K narrative sections (Business, Risk Factors) for a ticker using the Loughran-McDonald finance sentiment dictionary and report year-over-year tone shifts by category (negative, uncertain, litigious, modal-weak, modal-strong, constraining). Answers "did management's language get more defensive this year?" Uses Massive's pre-parsed 10-K sections endpoint. Requires Stocks Basic. Runs on the free tier.

filing-sentiment

You hand over a ticker. The skill pulls the last two 10-K narrative sections (Business, Risk Factors), tokenizes each, applies the Loughran-McDonald finance sentiment dictionary (curated 900-word negative set, 550-word litigious set, etc), and reports the tone shift per category per section year-over-year.

The output tells you whether management's language got more defensive, more uncertain, more litigious, or held steady. Not clause-level meaning — a bag-of-words score with the tone shifts flagged so a reader knows where to focus when reading the actual section text.

When to invoke

• A fundamental analyst asks "did AAPL's 10-K get more defensive this year?"
• Screening a watchlist for issuers whose litigious language jumped (a proxy for undisclosed legal exposure)
• Cross-reference with risk-factor-delta: this scores the tone, that identifies category-level structural changes
• The user says "10-K tone", "filing sentiment", "language shift", "management is getting defensive"

Not for: clause-level or sentence-level meaning. Not for sell-side sentiment (that's news + analyst commentary). Not for 10-Q amendments.

What you need

• A ticker (--ticker, required)
• MASSIVE_API_KEY exported
• Stocks Basic plan minimum. The /stocks/filings/10-K/vX/sections endpoint is included on every Stocks plan.

Optional:

• --current-filing-date (YYYY-MM-DD): pin the "current" filing. Default: most recent 10-K on record.
• --prior-filing-date (YYYY-MM-DD): pin the "prior" filing. Default: second most recent.

What you get back

Two output layers from one run.

Layer 1: canonical JSON matching output-schema.json. sections.current and sections.prior each carry per-section n_tokens, counts per LM category, and rates_per_10k (words per 10,000-word normalization). yoy_deltas reports per-section per-category prior_rate, current_rate, delta, delta_pct, and a shift label (flat / noticeable / material / dramatic).

Layer 2: rendered note. Per-section header with token counts + length delta, six-row table of category scores prior vs current with labels. One-line Take highlighting material shifts. See references/rendering.md.

How it works

1. Pull 10-K sections via GET /stocks/filings/10-K/vX/sections?ticker={T}&limit=100&sort=filing_date.desc. Massive returns pre-parsed plain-text extracts for Business, Risk Factors, and other Item 1/1A/7 sections.
2. Group by filing_date. Two most recent 10-Ks (or the caller- supplied dates) become current and prior.
3. Score each section per filing with the LM dictionary. Tokenize with [A-Za-z][A-Za-z\-']+, lowercase, count occurrences in each of six category sets: negative, uncertain, litigious, modal-strong, modal-weak, constraining. Normalize to words per 10,000 tokens so sections of different lengths are comparable.
4. Compute YoY deltas. Per category: absolute delta in rate, delta as % of prior rate, and a shift label based on the |delta|/current_rate ratio:
   • flat: |ratio| < 10%
   • noticeable: 10-25%
   • material: 25-50%
   • dramatic: >= 50% Any category whose current rate is under 10 per 10k gets n/a (sample too small to trust).
5. Take. Summarizes material shifts. When nothing shifted, says so.

Methodology detail in references/methodology.md.

Foundations used

• massive-api-patterns for REST auth, retry, pagination.

Output mode: note

Narrative note with a per-section score table. A 10-K sentiment diff is a small number of numbers (2 sections × 6 categories × 2 filings = 24 cells). Table renders cleanly.

Endpoints used

• GET /stocks/filings/10-K/vX/sections?ticker={T} — pre-parsed narrative sections for the ticker. One paginated call.

Doesn't handle (yet)

• MD&A section. Endpoint may return MD&A (Item 7); the current skill focuses on Business + Risk Factors. Adding MD&A is a drop-in change (already in the sections union).
• Sentence-level pinpointing. Bag-of-words. A future extension could highlight the top 5 sentences responsible for each category shift.
• Cross-ticker peer comparison. No "is AAPL's uncertain language above peer median?" Requires a peer set and a normalized score. Queued.
• Trend across N filings. Only diffs two. A three-year or five-year tone trajectory is a clean composite.

These are clean PR extensions. Output schema is forward-compatible.