# certified_measure Certified Measure · v1.0.0 · curated Run a GOVERNED KPI by name from the certified measures registry. A measure is a registry entry (definition + vintage bindings + official citation + canonical SQL); this tool runs ONLY that registry SQL, so a governed statistic (like the enrollment-weighted share of MA-PD enrollees in 4-plus star contracts) is computed by a compiled methodology, never an improvised join. Call with NO name to list every measure with its status and definition. Call with a name (and optionally rating_year, an int) to execute that measure and get the rows plus the vintage columns, the official citation, the certification status (draft / certified), and the definitional notes. Use this for any governed KPI FIRST; if no measure covers the question, fall back to query_substrate and label the result uncertified. **Inputs.** - `name`: - `rating_year`: **Known limits.** - Runs ONLY the registry's canonical SQL; a governed question with no matching certified measure is NOT answered here, and there is currently NO sanctioned raw-SQL fallback (query_substrate is quarantined pending its truncation-honesty re-grade). An unanswered governed question stays unanswered rather than improvised. - A measure with status 'draft' has not yet been certified by the owner; treat its number as provisional until status is 'certified'. **A real answer** (customer seat, 0.1 s, args `{}`): ```json { "value": { "mode": "list", "measure_count": 4, "index": [ "- pct_enrollment_4plus_stars [certified]: Share of MA-PD enrollment in 4-plus star contracts, weighted by payment-year December enrollment (house convention) Use when: the user asks what percent of Medicare Advantage members are in 4-star-or-better plans.", "- pct_enrollment_4plus_stars_by_canonical_parent [certified]: Share of MA-PD enrollment in 4-plus star contracts BY CANONICAL PARENT (one series through renames and acquisitions), weighted by payment-year December enrollment (house convention) Use when: the user wants a carrier's Star share AS A SERIES across years, or compares carriers across a rename or acquisition (Aetna and CVS Health as one series; Anthem and Elevance; Cigna's Medicare book moving to HCSC in 2025); for a single year's ranking on CMS's name of record use pct_enrollment_4plus_stars_by_parent.", "- pct_enrollment_4plus_stars_by_parent [certified]: Share of MA-PD enrollment in 4-plus star contracts BY PARENT CARRIER, weighted by payment-year December enrollment (house convention) Use when: the user asks about a specific carrier's Star ratings (Humana, UnitedHealth, CVS/Aetna, Elevance, etc.) or wants carriers ranked/compared by their 4-plus-star enrollment share.", "- pct_enrollment_4plus_stars_cms [certified]: CMS-convention enrollment-weighted share of MA-PD enrollees in 4-plus star contracts (reconciles to CMS published figures) Use when: the user wants the CMS-published star share, or to reconcile our number to a CMS fact sheet (CMS weights by November of the release year per 42 CFR 422.166)." ], "measures": [ { "name": "pct_enrollment_4plus_stars", "title": "Share of MA-PD enrollment in 4-plus star contracts, weighted by payment-year December enrollment (house convention)", "status": "certified", "governed": true, "definition": "The HOUSE convention, certified by the owner: for rating year Y, the percent of enrollment in RATED MA-PD contracts (those carrying an Overall Star rating) whose Overall Star is 4.0 or higher, weighted by enrollment in DECEMBER of the PAYMENT year (Y+1) -- the final enrollment number of the year those stars pay out (rating year Y drives quality bonus payments in Y+1). When that December is not yet published, the most recent available month is used and the row says so in weight_basis. Contracts with no Overall rating are excluded from the denominator. The Star measurement window is approximately Y-2 and is reported as metadata only, never joined. This deliberately differs from CMS's published convention (November of the release year); use pct_enrollment_4plus_stars_cms to reconcile to CMS fact sheets.", "params": { "rating_year": { "type": "int", "required": false, "description": "a single Star rating year (e.g. 2025); omit for all available years" } } }, { "name": "pct_enrollment_4plus_stars_by_canonical_parent", "title": "Share of MA-PD enrollment in 4-plus star contracts BY CANONICAL PARENT (one series through renames and acquisitions), weighted by payment-year December enrollment (house convention)", "status": "certified", "governed": true, "params": { "rating_year": { "type": "int", "required": false, "description": "a single Star rating year (e.g. 2025); omit for all available years" } } }, { "name": "pct_enrollment_4plus_stars_by_parent", "title": "Share of MA-PD enrollment in 4-plus star contracts BY PARENT CARRIER, weighted by payment-year December enrollment (house convention)", "status": "certified", "governed": true, "definition": "The HOUSE convention, certified by the owner, rolled up to the PARENT CARRIER: for each parent organization and rating year Y, the percent of that carrier's enrollment in RATED MA-PD contracts (those carrying an Overall Star) whose Overall Star is 4.0 or higher, plus the enrollment-weighted average Overall Star. Weighting is enrollment in DECEMBER of the PAYMENT year (Y+1) -- the final enrollment the stars pay out on -- falling back to the latest available month when that December is not yet published (weight_basis says which). THE CARRIER ROLLUP IS THE POINT: contracts are rolled to the carrier on parent_org_raw (the certified join key), NEVER by name-matching organization_name, which badly undercounts (Humana via a name LIKE catches 37 contracts; via parent_org_raw='Humana Inc.' catches 48). This measure exists so a carrier Star question is never improvised with a wrong rollup. Contracts with no Overall rating are excluded from the denominator. Covers carriers with at least 5,000 rated members; pass a rating_year to get every carrier for one year (a clean ranking), or omit it for all years (rows are ordered largest-carrier-first within each year, so the majors always survive the result-size cap; a mid-size carrier's full multi-year trend is best pulled one rating_year at a time if the all-years result truncates).", "params": { "rating_year": { "type": "int", "required": false, "description": "a single Star rating year (e.g. 2025); omit for all available years" } } }, { "name": "pct_enrollment_4plus_stars_cms", "title": "CMS-convention enrollment-weighted share of MA-PD enrollees in 4-plus star contracts (reconciles to CMS published figures)", "status": "certified", "governed": true, "definition": "The enrollment-weighted Star statistic per 42 CFR 422.166. For each rating year Y, the percent of enrollment in RATED MA-PD contracts (those carrying an Overall Star rating) whose Overall Star is 4.0 or higher. Weight is the CMS Monthly Enrollment by Contract for NOVEMBER of the release year: rating year Y is published in October of Y-1, so Y pairs with November of Y-1 (rating year 2026 pairs with November 2025). Contracts with no Overall rating are excluded from the denominator. The Star measurement window is approxima ... (truncated) ``` REST: `POST https://api.vladahealth.com/v1/tools/certified_measure` with the inputs as the JSON body. MCP: the tool by name.