CSM Health Scoring

When to use

• A workflow needs a single Low/Medium/High grade per customer account (composite score 0-100).
• A workflow is about to invent its own weighting — stop, reference this skill so all surfaces agree.

Tools you'll touch

• company_install_time_series — adoption signal (the heavy weight).
• company_fai — sponsor coverage by functional area.
• company_intent — intent posture (engagement signal proxy).
• company_firmographic — basic context, never the score itself.
• company_technographic — corroborating signal for adoption claims.
• contact_search — title / seniority / location filter for the customer's buying-committee function (NOT name-based — that's contact_enrich).
• contact_enrich — verify a NAMED individual is still at the customer (firstName + lastName), for explicit {{prior_contacts}} baselines.

Out of scope: company_contracts. That tool returns ICT outsourced contracts (GSI-mediated), NOT the customer's own product contract or renewal date (the tool reference). Renewal-cycle weight is scored as unknown unless the workflow takes our_contract_renewal_date as a CRM-supplied parameter — see "Composite formula" below.

Composite formula

Component	Weight	Source signal	Scoring rule
Adoption strength	40%	company_install_time_series.current_intensity + intensity_momentum	40 pts if current_intensity ≥70 AND intensity_momentum ≥0; scale linearly down to 0 pts when current_intensity <30 OR intensity_momentum <-10
Sponsor coverage	20%	contact_enrich per-name match-rate against {{prior_contacts}} baseline (NOT contact_search — that doesn't filter by name)	20 pts if 100% of prior_contacts still match; 0 pts if 0%
Intent posture	20%	company_intent filtered to customer's category	20 pts if trend ≥+10% on our category; 10 pts if neutral; 0 pts if ≤-30%
Sentiment proxies	20%	company_firmographic strategic events + company_fai current departmentUsageShare / departmentSignalStrength in the relevant function	20 pts if no strategic-reset events in 90d + relevant FAI shows healthy current share; scale down on M&A / RIF / new-CIO signals OR low current share. Note: company_fai returns point-in-time only — no trend field.
Renewal-cycle weight	(optional)	our_contract_renewal_date (CRM-supplied parameter)	If absent: score as unknown and do NOT subtract from the composite. If supplied: apply consumer rule (e.g., -10 if ≤120 days) on top.

Grade mapping

Composite (0-100)	Grade
≥70	High
40-69	Medium
<40	Low

Per-component minimum evidence

A component contributes to the composite only if its source signal is fresh (per hg-recent-signals):

• Adoption: install_time_series last data point ≤90 days old.
• Sponsor coverage: contact_enrich / contact_search are real-time; always fresh.
• Intent: company_intent last_seen_at ≤90 days.
• Sentiment: strategic events ≤90 days, FAI ≤12 months.

If a component is stale, mark it "stale — not scored" and reduce the composite's max possible score. Never invent a missing component.

Why company_contracts is out of scope

The tool returns ICT outsourced contracts (Accenture/IBM/Cognizant-mediated), not the customer's product contract with you. Treating its daysUntilRenewal as "their renewal with us" produces confidently-wrong verdicts. Workflows that need renewal-cycle weight should:

1. Accept our_contract_renewal_date as a workflow parameter (CRM-supplied).
2. If absent, score the renewal-cycle weight as "unknown" (omit from the composite, document the gap).
3. Never compute renewal proximity from company_contracts.

Output convention

Grade + composite + top-2 evidence per component:

Health: Medium (composite 58/100)
- Adoption: 24/40 — current_intensity 62, intensity_momentum -3 [company_install_time_series]
- Sponsor coverage: 14/20 — 2 of 3 prior contacts still match (champion still in seat) [contact_enrich]
- Intent posture: 10/20 — trend neutral on the [our category] topics [company_intent]
- Sentiment: 10/20 — new CIO appointed 6 months ago, current Engineering `departmentUsageShare` low at 18% [company_firmographic, company_fai]
- Renewal-cycle: unknown (our_contract_renewal_date not supplied)

Common pitfalls

1. Treating company_contracts as the customer's product contract. It's GSI-outsourcing data. See "Why company_contracts is out of scope" above.
2. Inferring sponsor coverage without a prior_contacts baseline. Absence inference is unreliable.
3. Scoring stale components as if fresh. A 24-month-old FAI reading is not evidence of current sentiment.
4. Inventing a missing component. If sentiment can't be derived, mark it unscored and reduce the max possible composite.

Reference

• hg-insights-api-v2.md#install-time-series — adoption signal schema
• hg-insights-api.md#fai — FAI schema for sentiment proxy
• hg-insights-api-v2.md#intent-company-intent — /v2/intent/company schema
• hg-recent-signals — canonical recency thresholds
• csm-churn-signal-weighting — sibling skill for Watch/Yellow/Red verdict rubric