| 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
- 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.
- Group by filing_date. Two most recent 10-Ks (or the caller-
supplied dates) become current and prior.
- 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.
- 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).
- Take. Summarizes material shifts. When nothing shifted, says so.
Methodology detail in
references/methodology.md.
Foundations used
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.
