get_stars

Get Stars

What it answers

Returns a Medicare Advantage contract's CMS Star Ratings: the Overall, Part C, and Part D summary stars for a rating year, each with the year-over-year change vs the prior year. Set include_measures=true to also get the full per-measure breakdown (measure name, part, domain, weight, the raw value and its star, and the star's YoY change) so you can see exactly which measures moved the rating. Filter by contract_id (required) + optional year (the rating_year, defaults to the latest) + optional limit (max measure rows returned). Rating years 2012-2026. The answer is a detail payload: the headline stars sit in value.summary, the part rows in value.summary_parts, the measure rows in value.measures.

Stars drive the quality-bonus payment and rebate, so this sits directly upstream of get_plan_payment / get_mlr (the economics) and is reported at the CONTRACT level (no plan_id).

SOURCE: CMS Star Ratings (summary + measure-level + measure dimension).

Inputs

contract_id

string · required

include_measures

boolean · optional

default: false

limit

integer · optional

year

integer · optional

Call it

From an agent: connect the Vlada MCP once (one click for Claude, ChatGPT, Cursor, VS Code) and ask in plain English; the agent selects get_stars when the question fits. From code: the same tool over REST with an API key. The schema endpoint needs no key.

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

curl https://api.vladahealth.com/v1/tools/get_stars/schema      # the JSON schema, no auth
# MCP endpoint (Streamable HTTP): https://mcp.vladahealth.com/mcp

What comes back

Typed rows plus provenance on every answer: the public source file, its vintage, the methodology, and a response_hash you can replay. Prove and replay tools turn any number into a re-runnable receipt. A number the data cannot support comes back as “not in the data”, never as zero.

Sources behind it

medicare_silver.stars_ratings_summary
medicare_silver.stars_ratings_measure
medicare_silver.dim_stars_measures

tables: medicare_silver.stars_ratings_summary · medicare_silver.stars_ratings_measure · medicare_silver.dim_stars_measures

Known limits

Stars are contract-level (no plan_id).
Measure set + weights are methodology-versioned per rating_year; a measure retired or added between years has no YoY counterpart (null change).

As of the 2026-09-19 build of the served surface · machine-readable catalog · the live server may run a different version; the schema endpoint above is authoritative for what is deployed.