certified_measure

What it answers

1. 1Run a GOVERNED KPI by name from the certified measures registry.
2. 2A 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.
3. 3Call with NO name to list every measure with its status and definition.
4. 4Call 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.
5. 5Use this for any governed KPI FIRST; if no measure covers the question, fall back to query_substrate and label the result uncertified.

Inputs (2)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
certified_measure()

curl -X POST https://api.vladahealth.com/v1/tools/certified_measure \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/certified_measure/schema

A real answer

{
 "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
…

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "CertifiedMeasureResponse",
 "type": "object"
}

Sources

Known limits (2)

1. 1Runs 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.
2. 2A measure with status 'draft' has not yet been certified by the owner; treat its number as provisional until status is 'certified'.