CSM Health Scoring

When to use

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

Tools you'll touch

• get_vendor_information, product_search_and_enrich (action search), list_intent_topics, list_fai_departments: resolve product, topic and department ids. Cost: free.
• company_install_time_series: adoption, the heavy weight. Cost: 3 per product row returned. Always pass product_ids.
• company_technographic: product_last_verified_date for your product, used to trim the series. Cost: 2 per company.
• contact_enrich: sponsor match rate against prior_contacts. Cost: 0.2 per matched contact with revealPhone:false; always pass it.
• company_intent: intent posture on your category. Cost: 0.1 per call.
• sec_filing_section (8-K) and web_search: strategic events. Cost: 1 per SEC call; 0.05 per basic search. Neither is cached.
• company_fai: current department share for your product. Cost: 2 per call.

Out of scope: company_contracts. It covers GSI / ICT outsourcing contracts and federal awards only, with no renewal fields. Renewal-cycle weight comes from CRM only (see below).

Composite formula

Component	Max Points	Source	Scoring Rule
Adoption strength	40	company_install_time_series detection days + intensity_momentum	Adoption matrix below
Sponsor coverage	20	contact_enrich match rate against prior_contacts	20 × (contacts still at the customer ÷ prior contacts)
Intent posture	20	company_intent topic trend on resolved topic_ids	≥ +1 → 20; between -2 and +1 → 10; ≤ -2 → 0
Sentiment proxies	20	Strategic events (10) + FAI department share (10)	Rules below
Renewal-cycle weight	optional	our_contract_renewal_date from CRM	Absent: unknown, no deduction. Supplied: consumer rule on top

Adoption strength (40)

1. Call company_install_time_series with your resolved product_ids and time_range:"last_6_months" or "last_12_months".
2. Clean the series: drop the trailing null (current month); drop the month containing product_last_verified_date unless that date is at month end, and any later month (it is partly loaded). A null inside the series means no detection that month; count it as 0.
3. Average detection days (data_points[].intensity, 1 to 31) over the last 3 complete, loaded months. 20 or more = heavy; 5 to 19 = regular; under 5 = sparse.
4. Classify intensity_momentum: ≤ -20 declining; -10 to -20 early decline; otherwise stable or growing.

Detection Band	Stable or Growing	Early Decline	Declining
Heavy (≥ 20 days)	40	30	20
Regular (5 to 19 days)	25	18	10
Sparse (< 5 days)	10	5	0

Several products: score each and take the mean. Never score current_intensity (all-time aggregate, another scale).

Sponsor coverage (20)

Bulk-enrich prior_contacts (up to 25 per call) with firstName, lastName, company_domain and revealPhone:false. A contact counts as still at the customer when the returned organization.domain is the customer. Unmatched people are omitted from the result: match by name or id, never by position, and report "no match" separately from "moved". Contact data comes from a third-party provider, not HG. No baseline: mark the component unscored.

Intent posture (20)

Resolve your category's topics with list_intent_topics (one lowercase keyword), then:

{ "company_domain": "acme.com", "fields": ["topics"], "granularity": "global", "topic_ids": ["<ids>"] }

Take the median trend across your topics that come back. Thresholds are provisional (unit unconfirmed; observed values run about -3 to +7): ≥ +1 → 20 points; above -2 and below +1 → 10; ≤ -2 → 0. data_available:false, or none of your topics returned, means no coverage: unscored, not 10.

Sentiment proxies (20)

Strategic events (10). company_firmographic returns no events. Use:

• sec_filing_section with companyTicker, filingType:"8-K", dateFrom 90 days back, and section "5.02" (officer changes), "2.01" (M&A) or "2.05" (exit or restructuring costs). US issuers only; it returns the most recent matching filing.
• web_search for private companies or press coverage. Cite result URLs, not the answer summary.

No strategic-reset event (new CIO or CTO, M&A, layoffs or restructuring) in 90 days → 10; one event → 5; two or more → 0.

FAI department share (10). Call company_fai with product_ids for your product and sort_field:"department_usage_share". Rows repeat per role and location, so dedupe by department. department_usage_share is the product's usage mix across departments in %, summing to 100. The department that should own your product is among the top 3 by share → 10; present but lower → 5; absent → 0. FAI is a point-in-time reading with no trend field.

Renewal-cycle weight

From CRM only. If our_contract_renewal_date is absent, report "unknown" and don't deduct. If supplied, the consumer may apply its own rule (for example -10 at 120 days or less). Never derive it from company_contracts.

Grade mapping

Composite	Grade
70 or more	High
40 to 69	Medium
Under 40	Low

When components are unscored, rescale: composite = points earned ÷ max points available × 100, and say which components are missing.

Minimum to grade. Give a grade only when adoption is scored and at least 60 of the 100 points are scorable. Otherwise report "Not enough evidence to grade" with the components that were scored.

Product not detected. If company_technographic and the time series return no rows for your product, adoption is "not detected": not 0, and not silently unscored. Say it first. Either the customer isn't live, or HG can't see the deployment; ask the user to confirm with CRM usage data. No grade follows (see the minimum above).

Per-component minimum evidence

A component counts only if its evidence is fresh (see hg-recent-signals):

• Adoption: product_last_verified_date within 90 days (is_active:true). Otherwise stale.
• Sponsor coverage: contact_enrich is a live lookup; fresh.
• Intent: topic last_seen_at within 90 days.
• Sentiment: events within 90 days; FAI last_verified_at within 12 months.

Stale: mark it "stale, not scored" and reduce the maximum. Never invent a missing component.

Required content

Layout is up to the formatting skills. Whatever the layout, the answer contains:

• The grade (Low, Medium or High) and the composite out of 100, or "Not enough evidence to grade".
• For each component: points earned out of its maximum, the evidence value, its date, and the source tool in brackets. Example: "Adoption 25/40: 14 detection days a month over Jun to Aug 2026, intensity_momentum -3 [company_install_time_series]".
• Components not scored, and why (no baseline, no coverage, stale, product not detected); when rescaled, the points available.
• For adoption: the 3-month detection-day average with the months named, and intensity_momentum.
• Renewal-cycle weight: the CRM date, or "unknown".

Common pitfalls

1. Treating company_contracts as the customer's contract with you. It has no renewal data.
2. Scoring adoption on current_intensity, or keeping the partly loaded last month.
3. Sourcing strategic events from company_firmographic. It returns none.
4. Reading FAI rows without deduping by department.
5. Sponsor coverage without a baseline, or with the default phone reveal.
6. Scoring "no intent coverage" as neutral, or inventing any missing component. Mark it unscored and rescale.

Reference

• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-install-time-series
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-intent
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/company-fai
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/contact-enrich
• V2 tool docs: https://phoenix.hginsights.com/docs/mcp-tools/v2/sec-filing-section
• Full docs for LLMs: https://phoenix.hginsights.com/docs/llms-full.txt
• Related skills: hg-mcp-calling-rules, csm-churn-signal-weighting, hg-recent-signals, hg-fai, hg-sec-research, hg-fallback-to-web-search