Vlada Health

Given an HCPCS code or short-description search, returns Medicare Part B ASP quarterly payment-limit rows from drug_silver.fact_drug_asp_quarterly_v2 (is_current) with trend aggregates. Use for Part B reimbursement checks and CY 2026 IRA/MFP methodology caveats.

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.

Compares what a billing code costs ACROSS hospitals (cheapest real price first) with a p10/median/p90 benchmark AND a per-(payer x line-of-business) breakdown. The product query for 'where is care cheapest' and 'what does each payer actually pay'. Reads the canonical serving view vlada_curated.vw_fact_hospital_chargemaster_canonical, which resolves each raw payer string to its REAL parent entity (the canonical payer graph) and classifies each plan to a regulatory line-of-business (commercial / medicare_advantage / medicaid / marketplace / ...). Inputs: billing_code (required), state (optional 2-letter), code_system (optional), billing_class (default 'institutional' = facility/UB-04; or 'professional'/'both'; classes are never mixed -- since 1.6.0 'institutional'/'professional' each WIDEN to include billing_class_resolved='both' rows, a charge posted on both the facility and professional side of a bill per the HPT schema; pass 'institutional_only'/'professional_only' for the strict single-class stratum), limit (default 25), payer (optional brand OR parent, e.g. 'Aetna' or 'CVS Health'), line_of_business (optional, e.g. 'medicare_advantage'). Each returned rate carries the view's canonical payer columns (payer_canonical_id, payer_parent_name, payer_entity_class, payer_match_method) plus line_of_business so a comparison is apples-to-apples (Aetna-MA != Aetna-Commercial). value.by_payer_lob is the 'rates across all the payers' table. CROSS-SUBSTRATE: every rate also carries x_medicare (the multiple of the Medicare allowed amount: PFS national non-facility for professional, OPPS APC for outpatient institutional, IPPS MS-DRG national base for inpatient DRG codes); value.medicare holds the allowed amount + schedule + year, so the answer is 'this payer pays 1.6x Medicare at this hospital'. VALIDATION (load-bearing): billing_class is normalized + inferred from code_system/rate_type where the source omits it; only the requested class is compared; class-implausible rates (e.g. $0.007 for a CT) and code-relative outliers are filtered. CHEAPEST HEADLINE (1.2.0): value.cheapest is ranked over rows PLAUSIBLE for the code's Medicare basis -- when the allowed amount is a real procedure (>= $500) a row under 0.3x Medicare (the comparability cascade's own lower sane bound) is set aside into value.implausible_tail (full rows + floor + reason, never deleted; benchmark still includes it), and the rest rank hospital-stated methodology (fee_schedule/case_rate/per_diem) before methodology-unknown, rate ascending within each tier -- read plausibility + rank_tier on each row. Under the $500 gate (imaging / visits / labs) no floor applies, so a $44 head CT still headlines. CASE-RATE HEADLINE (1.7.0): on a DRG/case-rate seat the floor is 0.5x (not 0.3x -- an inpatient rate below half of IPPS is not credible as the full case price), and cheapest headlines hospital-STATED case_rate rows ONLY when at least one survives the floor; methodology-unknown rows are demoted into value.implausible_tail (tail_reason='methodology_unknown_demoted') even when they themselves clear the floor. cheapest headlines an unknown row only when NO stated row survives, and a headline_methodology_unknown warning caveat says so. ENCOUNTER-BASIS FLOOR (1.15.0): the floor also reads the Medicare basis -- when the allowed amount is a facility-encounter payment (OPPS APC, IPPS MS-DRG, ASC; e.g. the comprehensive APC behind a CPT 27447 knee) the floor is 0.5x on every seat except per_diem, stated as floor_rule='encounter_basis' on every floor block and on value.implausible_tail. ONE CODE SYSTEM PER WINDOW (1.3.0): cheapest holds rows of the seated code system only (value.code_system_resolved, the dominant system or the caller's code_system), each row stamped code_system; when the floor empties a full window the tool re-asks once for rows at or above the floor rate (value.cheapest_window.second_pass), and if cheapest still ends empty a no_plausible_rows_in_window caveat says why. ONE METHODOLOGY FAMILY PER WINDOW (1.4.0): within the seated code system, cheapest and the re-seated value.benchmark / comparable_benchmark are further restricted to ONE methodology family -- fee_schedule (a line, the natural family for CPT/HCPCS/APC/RC), case_rate (an admission, the natural family for a DRG/MS-DRG seat), or per_diem (a day) -- because a case rate, a per diem and a fee schedule price different economic objects and must never share a median or a ranked list. methodology_family (optional: fee_schedule|case_rate|per_diem) overrides the natural seat. Rows the hospital stated in a DIFFERENT family are set aside into value.other_family, in full, never blended in; value.by_methodology_family reports n/n_hospitals/p10/median/p90 for every family present, and a methodology_families_mixed caveat fires when more than 10% of the population sits outside the seated family. BY_METHODOLOGY RECONCILES (1.6.1): value.by_methodology (percent_of_charge/fee_schedule/case_rate/per_diem/other/unknown, with median_rate_over_gross_charge) is narrowed to the SAME population value.benchmark.n reports -- sum(by_methodology[].n) == benchmark.n, ALWAYS, by construction; the unstratified, every-family view (within the seated code system) is value.by_methodology_all_families, which is what value.percent_of_charge_share and the methodology_mix caveat read (percent_of_charge rows are always 'unknown' family and would otherwise be invisible once a family is seated). SOURCE: CMS Hospital Price Transparency MRFs (45 CFR 180.50) + CMS Medicare PFS/OPPS fee schedules. KNOWN GAPS: not geo-aware beyond state; payer resolution covers ~80.9% of volume and line-of-business ~85.7% (measured on the 70553 probe, 2026-08-13; call state_expert for live per-state counts), unmatched rates fall to '(unresolved)'/'unspecified'; bare Blue-family labels (e.g. 'Bcbs') are bucketed '(blue family: label too generic to attribute)' with payer_resolution='generic_label' and never attributed to a specific Blue parent; IPPS DRG x_medicare is the national base (excludes wage index/IME/DSH/outliers); x_medicare null for revenue/non-HCPCS CDM codes; ghost-rate filter is heuristic. DRG GROUPER PRECISION (1.5.0): MS-DRG, APR-DRG and AP-DRG are different maintainers with different numbering (MS-DRG 470 = joint replacement, APR-DRG 470 = chronic kidney disease) and only MS-DRG prices against the IPPS base; the served mart still collapses all of them into one bare 'DRG' code system, so value.medicare.precision reads 'drg_grouper_unknown' (with a warning caveat) on that seat until the code_system_resolved bucket split rebuild lands, and 'exact' otherwise. BOTH-CLASS DEFAULT STRATUM (1.6.0): billing_class 'institutional'/'professional' each widen to include billing_class_resolved='both' rows (a charge the HPT schema posts for both sides of a bill); every row still carries its own resolved billing_class, and a both_class_rows_included caveat states the measured count whenever the answer includes at least one such row. Measured on CT (2026-08-18): 9.63% of REAL_NEGOTIATED rows are 'both', 100% with no institutional sibling row -- previously invisible at the old strict-institutional default. Pass 'institutional_only'/'professional_only' for the pre-1.6.0 strict single-class stratum.

Return the catalog record for one substrate data source. Compact by default (grain, queryable, claim ceiling, freshness SLA, top caveats, recommended next action, columns); pass verbosity='full' for the previous full record: description, row count, provenance chain reference, context doc path, known gaps, and the full source_product_card. IDENTIFIERS: accepts the PUBLIC source_code that find_data_sources returns (e.g. cms_ma_plan_payment) as well as a table FQN (e.g. vlada_curated.fact_rate) or a catalog source_id -- all three resolve to the same card. Also accepts a data-point ID, returning its exact bound table plus the selected point's units, grain, nulls and execution route. When the card includes a coverage-check recipe, run its stated query to inspect retained editions; it is not measured coverage. Do not infer all-history coverage from current-only rows. Avoid extra schema calls when this card already supplies the needed columns. A RETIRED source answers with a redirect (status retired + superseded_by + the successor's fqn), never a card. COLUMNS (1.1.0): the card's columns field lists each column's name and type (and a one-line note where the source publishes one), read from a committed snapshot -- never a live Glue call -- so a caller no longer has to SELECT * LIMIT n on query_substrate just to learn a table's shape. A source not yet in the snapshot reads columns_unavailable: run snapshot rather than silently omitting the field; run ops/scripts/snapshot_catalog_columns.py to populate it. WHAT TO QUERY (2026-09-18): every card carries a block saying what to type. It states the literal fully-qualified table name the raw SQL door accepts -- neither the public source code nor the catalog source id is a table -- plus the predicates a correct read carries (a currentness filter, a year pin, a partition column), and one bounded example SELECT that has been run through the door's own SQL guard before it was printed. A source served by a typed tool instead names that tool and its call; a seat not entitled to the table is told which pack grants it. Column lists are split: the data columns first, the row-lineage columns every row carries in their own named group.

Return the semantic layer: marts, columns, invariants, canonical payers, and the tools YOU can call (the same list tools/list returns for you, never a wider catalog). Compact by default (a manifest: marts + a name + one-line summary per tool, under ~8K chars). Fetch one section with describe_schema(section='') / section='tools' / section='invariants'. Pass verbosity='full' for the previous full payload. Agents call this first to learn the surface, then fetch the section or tool they need.

Given an NPI (10-digit), returns OIG LEIE exclusion status and — if excluded — any Open Payments received OR Part D prescribing activity recorded AFTER the exclusion date (and before any reinstatement). The textbook qui-tam / False Claims Act screening query. Bridges three substrate sources: dim_oig_leie (LEIE), fact_drug_payment_to_prescriber (Open Payments), fact_part_d_prescriber (Part D Prescriber-by-Drug).

Returns: total post-exclusion payment dollars + Part D drug-cost exposure, broken down by year + top 5 manufacturers. Every answer carries an explicit exclusion_status (not_in_leie, excluded, or excluded_then_reinstated) beside the dollars, so a $0 result is never ambiguous: a not-in-LEIE NPI returns zero ANCHORED to the LEIE snapshot date it was checked against (leie_asserted_at), which is a different thing from an excluded prescriber who drew no post-exclusion payments.

KNOWN GAPS: open_payments_publication_lag_one_year (current PY publishes June+1); part_d_puf_annual_grain_only (Part D PUF is annual not monthly — finer-grain timing requires claims data). LEIE refreshes monthly per the M-6 schedule (cycle 2).

Fetch the result of an async job once it is done. Returns the wrapped tool's full response when status is done; a not_ready caveat while it is still queued/running; or the error when it failed.

Search the Vlada substrate catalog by keyword. Returns the matching data sources (commercial TiC, hospital HPT, Medicare, drug pricing, provider identity, curated marts, provenance registries) ranked by relevance. Compact by default (identity + queryable + claim ceiling + the exact describe_data_source call per hit); pass verbosity='full' for the previous full source_product_card per result. Paginates with limit (default 25, max 200) + offset; the response carries total_count, returned_count, and offset. Optional filters: {domain, stage, status, limit}. Agents call this first to discover what data Vlada has. Since 2026-09-02 the answer leads with DATA POINTS (data_points: the measure/dimension asked for, with its source, door, table.column and must-read trap) and the table cards follow as physical locations. Every hit carries source_code -- the one public code, which describe_data_source accepts verbatim -- alongside the table's source_fqn. Points and tables are ranked by ONE ranker (the authored data-point scorer). Retired tables are never returned; they appear only as supersedes on the live successor's card. BOUNDED (2026-09-18): the default call is compact and paged -- both the table cards and the data points come back a page at a time, each with its own total and next offset -- so a default call can never truncate. Pass verbosity='full' for the whole point record and the full source_product_card per hit.

Look up the vetted analytic VIEWS for a question before you query. A view is the decision that comes before any table or chart: who is counted (population), against what base, compared to what, over which period and vintage, and what one row is (grain); plus the weight, the named measures, the forms that draw it (draw_as), how to reach the data (reach: the typed tool that carries the population and base first, then the source codes to read with describe_data_source and query_substrate), the rules that must hold and the ways the view goes wrong or contradicts another view (contradicts_if). Pass the user's question in their words; add a domain (ma_market, ma_benefits, hospital_prices, payer_rates, medicare_benchmark, ma_stars, medicaid, marketplace, drug_pricing, formulary, pbm, providers, employer, mlr, hospital_quality, drug_policy, ma_value, cross_domain) or a level (executive for a headline, actuarial for weights, cohorts, decompositions and distributions, detailed for row-level lookups) when you know it. Returns up to 8 views, best first; the default is 4. Use the returned population, base and period in your call and say them in the answer. A view is analytical guidance: it grants no data access and proves no coverage for the places, dates or populations in your question. Verify coverage with the source's own card before you quote a number. A question no view covers is composed from the same fields.

Given a quarter-pair (report_quarter_from, report_quarter_to) AND a formulary or plan filter, returns the formulary delta: drugs added, drugs dropped, drugs re-tiered, and optionally drugs whose control flags (prior auth / step therapy / quantity limit) changed. Diffs drug_silver.fact_drug_formulary across two SPUF report_quarters on (formulary_id, drug) keys, where a drug is its RxCUI by default (grain='rxcui'), so a manufacturer or package NDC swap of the same drug is not churn; grain='ndc' gives the package-level diff. Pass rxcui_filter=[...] to ask whether coverage of specific drugs changed.

Returns: per-category row lists (cap 5000 each), aggregates (formularies_compared, n_added, n_dropped, n_tier_changed, n_control_changed, n_unchanged, churn_rate, tier_movement_distribution), truncated_by_category flags.

READING churn_rate: it is (added + dropped + re-tiered) divided by the number of drugs on the formulary in the FROM quarter — CHANGE EVENTS PER FROM-QUARTER DRUG, not a percentage. It is >= 0 and CAN EXCEED 1 (a formulary that drops everything and adds as many new drugs scores 2.0), because added drugs are not members of the denominator. The answer carries churn_rate_definition saying exactly this, the two denominators (n_in_from_quarter, n_in_to_quarter), and two bounded companions that ARE 0-1: share_dropped (dropped / FROM-quarter drugs) and share_added (added / TO-quarter drugs).

Use cases: year-over-year formulary stability tracking, drop investigations for a specific drug class, IRA-era churn rate (crossing 2025 → 2026 will surface the redesign-driven churn).

KNOWN GAPS: spuf_quarterly_publication_lag (CMS publishes 6 weeks after quarter end; very recent quarter changes won't show); ira_era_break_2026 (IRA Part D redesign in 2026 changed formulary structures; churn comparison crossing this boundary mixes regime changes with normal churn); formulary_churn_truncated (per-category lists capped at 5000).

The locked 2027 Medicare Advantage benefit tables in one call: what each benefit was in 2026 and what it is in 2027 for the SAME members, member-weighted from the CMS Plan Benefit Package filings and CMS September 2026 county enrollment, inside ONE product type, for the market or a parent organization, nationally, in a state or in a county. Premium, MOOP, the medical and Part D deductibles, the medical copays and coinsurance, the Part D tier cost shares, dental / OTC / hearing / eyewear / flex card dollars and offered shares, the Part B giveback and the supplemental services.

ARGUMENTS: product_type (required unless group_by='product_type': non-SNP HMO | non-SNP PPO | D-SNP HMO | D-SNP PPO | C-SNP HMO | C-SNP PPO | I-SNP HMO | I-SNP PPO; 'ALL' is refused, types are never pooled), geography (national | state | county; inferred from the place when omitted), state (two letters), county (the name as CMS spells it, e.g. 'Maricopa', with state) or county_ssa (five digits, e.g. '03060'), parent (the parent organization; a partial name matches, e.g. 'UnitedHealth'), plan_type (default 'ALL'; HMO | HMOPOS | Local PPO | Regional PPO), group_by (none | parent | state | county | plan_type | product_type; state needs geography national, county needs geography state), benefits ('key' default | 'all' | a comma-separated list of benefit names, listed in value.benefits), limit (rows, default 50, max 500, largest 2026 membership first).

RETURNS value.summary (the market of the scope: every benefit for the scope's members) and value.rows (one per group, or per matching parent). Each row: members_2026 (every September 2026 member), members_continuing (the members on both sides of the change), plans, thin (true when the value rests on plans covering under 70% of the members or fewer than five plans) and, per benefit, {2026, 2027_same_members, change, coverage_2026, coverage_2027, 2026_all_members, unit}: 2026 is the continuing members' 2026 design, 2027_same_members those same members' 2027 design, change = 2027_same_members minus 2026; 2026_all_members is every 2026 member, context only, never one side of a change. coverage is the share of the row's members the value describes. A null value is unknown (no member filed it), never $0. Percent benefits are served 0-100. When an allowance is asked, like_for_like carries its dollars on the paired members (same form both years) with the share whose design changed form, which is a design change, never a raise or a cut.

D-SNP figures are the FILED design: a full dual generally pays $0 under Medicaid; the full-dual reading is the Plan Value tool's full-dual column. Employer group plans and stand-alone Part D are not in the tables.

SOURCE: Vlada locked benefit tables (Edition 1.1) from the CMS Plan Benefit Package filings, CMS county enrollment, the plan service area file and the CMS plan crosswalk.

The county-level service area of Medicare Advantage contracts, month by month, from CMS's monthly MA Contract Service Area file (2006-10 on; 2022-11 was never published). Both directions: the counties a contract serves (contract_id) and the contracts serving a county (county_fips, 5 digits) or a state (state_code, 2 letters).

WINDOW: report_month (YYYY-MM) or year; with neither, the newest month held (stated in value.query.report_month).

RETURNS value.summary (distinct contracts, counties, contract-counties and contract-county-months; national, employer-group and partial-county counts; the months read), value.contracts (one row per contract: organization, organization type, plan type, counties served, employer-group and partial counties) and value.rows (one row per contract, county, month and flag combination: state_code, county_fips, county_ssa, county_name, eghp, partial_county, national_service_area). limit bounds both lists (default 100, max 2000); a truncated list carries a caveat.

THREE RULES: (1) eghp (employer-group only) and partial_county are CMS's own flags; eghp_only=true keeps employer-group rows. (2) A contract serving the whole country (National PACE and similar) is one national row with no state or county (national_service_area=true); it is never counted as a county, and a state or county filter leaves it out unless include_national=true. (3) CMS lists a contract-county twice when its plans there differ in the partial or employer flag, so count DISTINCT contract-counties, never rows; the summary already does.

Each month is read at its newest CMS edition. Stand-alone Part D (PDP) service areas are a separate file and are not here.

The whole Medicare Advantage picture of ONE county, over time, in one call: (1) enrollment by parent and product type each September from 2021, with CMS small-cell suppression carried as a floor and a ceiling, and the county's MA penetration where CMS holds it; (2) plan exits for every transition from 2023: continuing, departing, the five Day-One buckets, the true outcome where the crosswalk is held or the calibrated estimate range where not, parents before and parents continuing; (3) the same members' plan design this year against next (total premium, $0 premium share, MOOP, $0 Part D deductible share, D-SNP $0 cost sharing, star), at county grain where held, else the state figures under their own name with a coded note (get_landscape_benefit_change serves twelve metrics at state grain); (4) every plan sold in the county in the plan year with premium, MOOP, deductible and star, the D-SNP fields in their own columns, paged; (5) September members in contracts rated 4+ stars by rating year, with the rating-year to payment-year clock. Every tile is one row per product type with arrays over years or transitions, so the county reads over time in one call.

ARGUMENTS: state (two-letter) and county (the county name as CMS spells it, e.g. 'Cook', 'DuPage'; 'County' may be included or left off; a misspelling is refused naming the nearest CMS spellings), OR county_fips (five digits, e.g. '17031'), OR county_ssa (the five-digit CMS SSA state-county code, e.g. '14140', resolved to its FIPS through the CMS penetration file); year (the plan year for the plan list, default the newest Landscape year held); sections (comma-separated subset of enrollment, exits, benefit_change, plans, stars; default all); detail: the two modes, summary (default, false: the product-type tiles, which fit one answer) and full (true: the tiles plus the parent x product type rows for enrollment and for the newest exits transition, and the plan list itself, paged); limit (rows per detail list per page, default 5, max 200) and offset (default 0), which page every detail list together, so a long page is one section at a time (sections=plans, detail=true, limit=100); include_cost_mmp (default false: industry = every product type but Cost and MMP).

RETURNS value.blocks (one block per section: source, edition, the five clocks, the base, the seconds it took, its caveats, and a status of measured, substituted or unavailable with a code), value.county_by_year, value.enrollment_by_product_type, value.exits_by_product_type, value.benefit_change, value.plans_by_product_type, value.stars_exposure, value.summary; with detail=true also value.enrollment (parent x product type), value.exits (parent x product type, newest transition) and value.plans, each paged by limit and offset.

RULES THE TOOL ENFORCES: the county is resolved by FIPS and the name key the Landscape carries is derived, never typed; the member base is H/R contracts, plans 001-799, September Y, matched to the Y Landscape by plan AND county; stand-alone Part D is never in it; D-SNP is its own product type and is never pooled; suppressed cells are carried as a floor and a ceiling, so every rollup keeps its bounds; parent is CMS's reported parent at each September and a parent's figure is the sum of its members, never a plan count; every section names its clocks.

SOURCE: Vlada analysis of the CMS monthly enrollment by plan and county, the CMS MA state-county penetration file, the CMS MA/Part D Landscape files, the CMS plan crosswalk where held, and the CMS Star Ratings.

Returns CMS monthly enrollment for a Medicare Advantage plan or contract: the member count, the trend over time, and, at contract level, the MA-only vs Part-D split, plus org/parent and plan type. Filter by contract_id (required) + optional plan_id (plan grain vs contract total), and optional year ('2024') or month ('2024-03'); with neither, returns the latest month plus a trailing 13-month trend. Monthly coverage back to 2006. Every row carries the year-over-year change (yoy_change / yoy_pct) vs the same month one year earlier; plan rows carry the plan's SNP class (snp_type) when applicable.

RETURNS a detail payload, not a bare count: value.summary (latest_month, latest_enrollment, yoy_change / yoy_pct, ma_only_count / part_d_count, trend min/max and change over the window), value.months (the per-month trend rows), value.row_counts (matched / returned / truncated / limit) and value.query (the filters actually applied). limit bounds the trend rows returned (default 13 months, max 2000); a truncated list always carries a caveat.

Enrollment is the SPINE every other MA metric joins to (per-member, share-weighted). SUPPRESSION is honest: CMS redacts cells under 11 enrollees, which come back as count=null with a [lower, upper] bound and suppression_reason='redacted_small_cell', never a zero, and the suppression caveat fires only when a returned month is actually redacted. A contract id that does not exist returns found=false with a not_found_reason, never a suppression story.

Pair with get_pbp_benefit or get_stars to weight or normalize by members. SOURCE: CMS Monthly Enrollment by Plan / by Contract.

One ACA Marketplace (healthcare.gov / HIX) plan's profile for a plan year, every field tagged with the CCIIO PUF it came from. Give plan_id (the 14-character HIOS standard component id, e.g. 38344AK1060001) for the plan: issuer, metal level, plan type (HMO/PPO/EPO/POS), Individual vs SHOP, on/off exchange, network, county footprint, premium benchmarks at age 21/40/60 (min across the plan's rating areas, plus the age-40 max), the per-age premium curve from the Rate PUF (include_rate_curve, default true), headline cost shares (PCP / specialist / ER / urgent care / generic drug copay, inpatient coinsurance), CMS quality stars, and the issuer's individual-market MLR. Or give state (+ optional plan_year, metal_level, issuer_id, plan_type, on_off_exchange) for the bounded list of that state's plans, cheapest age-40 premium first. plan_year defaults to the latest year held (PY2014-2026). Deductible / MOOP are returned as not_available (not in the composed profile). FFM states only: a state-based marketplace (CA, NY, PA, GA, ...) is absent at source and the tool says so rather than returning nothing silently.

Returns a Medicare Advantage contract's CMS Health Outcomes Survey (HOS) rates across the four survey topics (fall_risk_management, urinary_incontinence, osteoporosis_testing, physical_activity), each with the two reported rates and the year-over-year change. Filter by contract_id (required) + optional year (defaults to the latest; report years 2019-2025).

RETURNS a detail payload, not a topic count: value.topics is the per-topic row list (topic, report_year, rate1, rate2, rate3, rate1_yoy), value.summary rolls it up (topic_count, which topics reported, the highest and lowest rate1), value.row_counts carries matched / returned / truncated and value.query the filters applied. limit bounds the rows (default 200, max 2000).

HOS is the beneficiary-survey companion to the chart-abstracted HEDIS rates and feeds several Part C Star measures. rate1/rate2 are the survey's two published rates for the topic (e.g. the share who reported the issue and the share who discussed it with a provider); see the CMS HOS documentation for exact definitions. Pair with get_stars. A contract id with no HOS rows returns found=false with a not_found_reason.

SOURCE: CMS Health Outcomes Survey (HOS) Public Use File.

Returns one hospital's CMS Care Compare quality record by CCN: the overall star rating (1-5) with hospital type / ownership; every Care Compare measure for the hospital (mortality and complication rates, unplanned readmission / ED-return rates, timely and effective care, healthcare-associated infections SIRs, outpatient imaging efficiency, maternal health) with the score, CMS's compared-to-national verdict where published, denominator, confidence bounds and measurement window; the HCAHPS patient-experience summary (summary star + per-dimension star ratings and linear mean scores) for the latest reporting year the hospital has; and the HRRP excess readmission ratios per condition for the latest fiscal year (ratio > 1 = more readmissions than nationally expected). Inputs: ccn (required, 6-char CMS certification number); optional measure_group (alias: measure_source) to get ONE group's measure rows (complications_deaths | unplanned_visits | timely_care | healthcare_assoc_infections | outpatient_imaging_efficiency | maternal_health); optional limit and offset to page the measure rows (default limit 25 once detail is asked for).

THE DEFAULT CALL IS A SUMMARY: ccn alone returns the overall rating, the HCAHPS and HRRP blocks, and the measure GROUPS with a count each (summary.measure_groups: measure_count / available / not_available / vs_national per group) — NOT the ~108 measure rows, which exceed the response budget for a single hospital. Totals are still reported (summary.measure_count) and row_counts.measures names what was withheld; ask again with measure_group, or limit / offset, for the rows.

RETURNS a detail payload: value.summary (facility, overall_rating with status + footnote, hcahps_summary_star, counts, measure_groups, measure_detail_mode, and a blocks map saying which of overall_rating / measures / hcahps / hrrp are available for THIS hospital); value.measures, value.hcahps, value.hrrp row lists. Every row carries status = available | not_available (with the CMS footnote or reason), source_table and source_vintage (asserted_at). Nothing is fabricated: a suppressed or unreported measure is not_available, never a zero; an unrated hospital reports overall_rating null with the CMS footnote. All four sources are read WHERE is_current = true. An unknown CCN returns found=false.

SOURCE: CMS Provider Data Catalog (Care Compare) Hospital General Information, hospital measure files, HCAHPS, and the HRRP hospital file.

Returns the CMS Landscape view of a Medicare plan: monthly premium, in-network MOOP, overall star rating, plan type, and the county/state service-area breadth. Filter by contract_id (required) + optional plan_id (1 to 3 digits, zero-padded), segment_id and year; omit plan_id to list all plans on a contract.

RETURNS a detail payload, not a plan-year count: value.plans is the actual PLAN LIST, ONE ROW PER PLAN SEGMENT (report_year, plan_id, segment_id, segment_count, plan_name, org_name, parent_org_name, plan_type, category, snp_type, total_premium, total_premium_basis, premium_as_filed, consolidated_premium, part_c_premium, part_d_premium, moop_in_network, overall_star_rating, overall_star_status, service_area_county_count / state_count), sorted premium ascending so the cheapest lead; value.summary rolls it up (plan_count = distinct plans, segment_row_count, segmented_plan_count, total premium min / median / max, zero-premium count, premium basis counts, star min / max, total distinct counties); value.row_counts carries matched / returned / truncated and value.query the filters applied. limit bounds the row list (default 200, max 2000); a truncated list always carries a caveat.

READING THE PREMIUM. total_premium is the plan's monthly premium on one basis per row, named in total_premium_basis: 'consolidated' (CMS's Part C plus Part D figure), 'part_c_only_no_drug_coverage' (from CY2025 CMS prints the consolidated premium as 'Not Applicable' on every plan without drug coverage, so the Part C premium is the whole premium), 'part_d_only' (a PDP), or null when CMS filed no figure. CMS's own text is carried in premium_as_filed; its '$-' token (CY2014, 2015, 2019-2023) is a $0 premium, never missing. A segment is its own filed design: a segmented plan has one row per segment with its own premium and MOOP.

Covers ALL plan categories (MA, PDP, SNP, MMP, Cost), 2007-2027; the CY2027 file loaded 2026-09-28. The Landscape drops ~early September, ahead of the October benefits drop, so it is the first official view of the upcoming plan year. Stars for 2013-2020 are read from CMS's text form ('3.5 Stars'); a CMS message in place of a star is carried in overall_star_status. Pair with get_pbp_benefit (benefits) for the full picture. A contract / plan / year with no Landscape rows returns found=false with a not_found_reason.

SOURCE: CMS MA/Part-D Landscape source files.

What the plan design looked like for the SAME Medicare Advantage members in year Y and in year Y+1, member-weighted from the CMS Landscape files: total, Part C and Part D premiums and the $0 shares, the premium after full Extra Help, in-network MOOP and the share at or under $5,000, the Part D deductible and its $0 and standard shares, the tier-skips-deductible share, MA-PD and enhanced shares, the D-SNP $0 cost sharing, FIDE and HIDE shares, and the overall star. Both sides of a change are the SAME members: y = the Y design of the members whose plan continues in their county (same_store, Day-One) or is routed through the CMS crosswalk where that crosswalk is held (routed: continues + moved); y1 = those members' Y+1 design; change = y1 minus y. all_members_y = the Y design on every September-Y member (members_y), context only, never one side of a change. The members whose plan departs and is not yet crosswalked are in all_members_y and members_y but NOT in y, y1 or members_y1, and the row says how many.

ARGUMENTS: transition_year (Y, default the newest held), group_by (national | product_type | parent | state | parent_by_product | state_by_product | county; county needs state and returns one row per county of that state, each on its own members), product_type / state / parent (filters), county (filter, the county name as CMS spells it, e.g. 'Maricopa'; with product_type it cuts one county by product), metrics ('key' = the twelve headline metrics, 'all' = every metric, or a comma-separated list of metric names), weight (same_store | routed; any other value is refused by name, and routed is refused where the crosswalk is not held), include_cost_mmp (default false), limit (default 50, max 500, largest members first).

RETURNS value.rows (one per group: members_y (every September-Y member), members_y1 (the same members on both sides of the change) and, per metric, {y, y1, change, all_members_y, unit}), value.summary (the national row for the same scope, the editions, the weight used) and value.metrics (the metric labels and units). Dollars are the filed monthly premium / annual MOOP or deductible in nominal dollars; pct metrics are shares of members in the metric's own domain (Part D metrics over MA-PD members, D-SNP metrics over D-SNP members).

RULES THE TOOL ENFORCES: member base H/R contracts, plans 001-799, matched to the Y file by plan and county; PDP never; industry excludes Cost and MMP unless asked; D-SNP is its own product type; a change is over the same members, never a mix of two populations. Suppressed cells count as zero, so every weight is a floor.

SOURCE: Vlada analysis of the CMS MA/Part D Landscape files, CMS monthly enrollment by plan and county, and the CMS plan crosswalk where held.

Members of Medicare Advantage plans that do NOT continue into the next plan year, from the Landscape disposition: every September member of year Y placed against the Y+1 Landscape file. A member CONTINUES when the same plan is sold in their county next year; otherwise they are DEPARTING, split into the five Day-One buckets the two Landscape files can see (D1 a same-named plan in the county, D2 the plan still sold elsewhere, D3 the contract still in the county, D4 the parent still in the county, D5 the parent gone). When the CMS crosswalk for Y+1 is held, each row also carries the TRUE outcome (moved, split, stranded by a service-area reduction, terminated); when it is not yet held (the newest transition) the answer carries the calibrated estimate range of members who lose their plan, from the buckets' measured rates in the held years.

ARGUMENTS: transition_year (Y, the September enrollment year; default the newest held, 2026 = the 2026 to 2027 transition), group_by (national | product_type | parent | state | parent_by_product | state_by_product | county; default national; county needs state and returns one row per county of that state, each with its own members base), product_type (filter, e.g. 'non-SNP HMO', 'D-SNP HMO'), state (two-letter filter; required when group_by is county), county (filter, the county name as CMS spells it, e.g. 'Cook' or 'Maricopa'; with group_by county it returns that one county), parent (filter, the CMS parent organization as reported), include_cost_mmp (default false: industry = every product type but Cost and MMP), limit (rows, default 50, max 500, largest members first).

RETURNS value.rows (one per group: base_members = THE MARKET, the number to quote as 'members in the market', the base pct_departing is over; continuing, departing, pct_departing, the five buckets, and either the true_* outcomes or est_lost_low / est_lost_high; then members_september = base_members PLUS the members whose plan-county is not in the Y Landscape list or is outside the Landscape, a reconciliation figure, never the market), value.summary (the totals for the same scope, the editions, and the calibration rates used). For 'your county, 2027': group_by county, state and county, then product_type to cut it by product.

RULES THE TOOL ENFORCES: the member base is H/R contracts, plans 001-799, September Y, matched to the Y Landscape by plan AND county (members whose plan-county is not listed are counted separately, never silently); stand-alone Part D (PDP) is never in it; D-SNP is its own product type and is never pooled; parent is CMS's reported parent organization at September Y, not a canonical chain across renames. Suppressed enrollment cells (under 11) count as zero, so every figure is a floor.

SOURCE: Vlada analysis of the CMS MA/Part D Landscape files, CMS monthly enrollment by plan and county, and the CMS plan crosswalk where held.

Returns a Medicare Advantage plan's or contract's county-level enrollment and its SHARE of the local MA market: for each county, the plan's enrollees, the county's total MA enrolled and Medicare-eligible population, the MA penetration rate, the plan's share of county MA enrollment, and the year-over-year change in the plan's county enrollment. Filter by contract_id (required) + optional plan_id (plan vs contract total), optional state (2-letter, e.g. 'FL'), and optional month ('2024-03'); defaults to the latest available month.

RETURNS an actual SHARE with the arithmetic disclosed, not a raw headcount: value.summary.share_pct is the footprint share, and it always ships alongside its numerator (share_numerator_plan_enrollees) and its denominator (share_denominator_county_ma_enrolled), so nobody has to trust a bare percentage. The denominator is the total MA enrollment of the counties this plan actually operates in for the month in scope, NOT the national MA market. value.counties is the per-county row list (plan enrollees, county MA enrolled, county eligibles, penetration, share_pct, yoy_change), largest first; value.row_counts carries matched / returned / truncated and value.query the resolved month. limit bounds the county list (default 200, max 2000).

This is the geography + competition lens; pair with get_enrollment for the plan/contract totals. Suppressed county cells (CMS redacts under 11) come back with null enrollees and null share, never zero, and the summary carries a [low, high] bound on the numerator that brackets them. A contract id with no county rows returns found=false with a not_found_reason.

SOURCE: CMS Monthly Enrollment by CPSC + MA State/County Penetration.

Returns Medicaid managed-care enrollment for ONE state: the annual CMS 'Enrollment by Program and Plan' roster (each managed-care program x plan with SEPARATE Medicaid-only, dual and total member counts and a value_status per count, plus parent organization) for the requested or latest calendar year (2016-2024); the state's TOTAL Medicaid and CHIP enrollment from the CMS monthly state report for the latest 12 reporting months (context: all delivery systems, managed care and fee-for-service, CHIP separate); and, for the four T-MSIS dashboard pilot states (AZ, MI, NV, NM), the MCO roster with county footprint and service categories; and the state's OWN monthly plan-level publication for its latest month (45 jurisdictions). Inputs: state (required, 2-letter USPS code); optional year (plan-roster calendar year, defaults to the latest the state has); optional limit; optional offset (skips that many rows of value.plans and value.monthly_plans in their served order; summary.paging.next_page is the exact next call).

RETURNS a detail payload: value.summary (state, plan_year, plan_count, program_count, the SOURCE-PUBLISHED sum of plan total_enrollment where reported_numeric for the comprehensive_medical benefit scope ONLY, plus per-benefit-scope sums that must never be added together, with the count of rows that are suppressed / not reported, the latest monthly total Medicaid+CHIP / Medicaid / CHIP enrollment with its reporting_period, and a blocks map saying which sources have rows for this state); value.plans (one row per program x plan x region, ordered comprehensive medical first and largest first BEFORE the row cap, summary.plans_page saying how many rows and of which scope are not on the page: benefit_scope (comprehensive_medical, behavioral_health, dental, pharmacy, ltss, pace, nemt, pccm, limited_benefit, unknown) with the rule that set it, medicaid_only / dual / total each with value + value_status, parent_organization = the parent in force through Vlada's effective-dated plan identity decisions (null when no decision covers the filed name), parent_label_as_filed = the parent column as the state filed it (in Florida the plan's own label), calendar_year, source_table); value.monthly (reporting_period, total_medicaid_and_chip_enrollment, total_medicaid_enrollment, total_chip_enrollment, adult / child enrollment, revision + final flags, source_table); value.mco_roster (mco_name, plan_category, county_count, service_categories, source_table; NO enrollment number); value.monthly_plans (the state-published plan rows for the latest monthly observation_period, statewide where the state publishes statewide rows, otherwise sub-state as published, each with reported_value, value_unit, value_status, row_role and source_url; never summed into a state total; per program, statewide rows where the program publishes them, otherwise sub-state rows; each row carries parent_share_segment when it lies inside the parent-share view's basis, and summary.parent_share_reconciliation names that basis and routes to it). The ledger stores 17 states' publisher totals as plan detail: rows whose plan label reads as a total, whose label is fee-for-service (fee_for_service_not_a_plan), whose label is an eligibility, population or unassigned count (population_count_not_a_plan), whose plan label is a bare number, whose program label is a total, or whose value equals a suspected total in the same cell are served with row_role publisher_total_suspected / fee_for_service_not_a_plan / population_count_not_a_plan / plan_label_numeric_suspected / overlapping_summary_suspected / equals_publisher_total_suspected, the stored role kept in row_role_as_published, ordered after plan detail, never dropped; summary.monthly_plans_not_plans lists the page's non-plan rows in their own block; summary.monthly_plans_guard carries the rule and the counts over the whole month. Each monthly_plans row carries cell_check (source_total, sum_of_plans, plan_rows, difference, status): within one cell (one table, measure, program, breakdown and geography) the plan rows are summed, never the re-labelled rows, and set beside the publisher's own total, so a reader sees whether the plans add up; plan rows are never added across cells. A fractional value under value_unit 'members' is an average and the row says so (value_unit_note); a published 0 may be a masked small cell (WA prints 0 for 1 to 10). Every number carries its as-of period and exact source table. Nothing is recomputed or reconciled across sources: Medicaid-only + dual is not re-summed, a published 0 is reported_zero_or_suppressed (never exact zero), and the annual plan roster is a different population and grain from the monthly state total. All sources are read WHERE is_current = true (monthly: is_latest_revision = true). An unknown state returns found=false.

SOURCE: CMS/Data.Medicaid.gov Medicaid Managed Care Enrollment by Program and Plan (state-reported, annual); CMS Medicaid & CHIP Application, Eligibility and Enrollment monthly state report; CMS Medicaid MCO Dashboard (T-MSIS, four pilot states); state Medicaid agencies' monthly managed-care enrollment reports (medicare_semantic.vw_medicaid_mco_enrollment_tracker_reported_observation_v5).

Get the negotiated rate a specific payer pays a specific NPI for a specific billing code, in a state. Resolves at query time through the canonical graph + inverted indexes (no precomputed edge table) and returns the most provider-specific rate with source lineage, methodology, evidence type, and Medicare-PUF corroboration. UHC custom codes are resolved automatically. Covers all built payers. Near-zero dollar rates (positive, under $1 — the ghost class the benchmark path excludes) are never picked over a plausible rate; if one is all that matched, it is served flagged is_ghost_candidate at confidence 0.2 with a caveat, never as a real price.

Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.).

Polymorphic — pass category to route to the right semantic view. All categories share the standard envelope: cost_share_string, copay_amount, coinsurance_pct, limit_text, auth_required, referral_required, network_type, max_oop_applies + category-specific extension fields (e.g., dental_sub_benefit).

Required: contract_id, plan_id, payment_year, category. The category must be one of the 35 live categories (listed below).

The response value is the full benefit-detail object: rows (every matched benefit row, with cost sharing, limits, and category extension fields), row_count, the resolved category/human_label/view_fqn, the audit_chain (CMS source URL + sha256 per row), and a summary sub-field carrying the single-row headline cost_share_string (or the row count when multiple sub-benefit rows match) for a quick read. Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+). Cross-year queries get cross-shift caveats.

When the full answer would not fit in one response, rows come back compact (row_format: "compact"): fields identical on every row sit once in row_common, and a field absent from a row is null.

Live categories are discovered from the contract registry at load time, so this list cannot drift from what the tool serves; an unknown category is refused (INVALID_INPUT) with this same list, never a failure. The 35 live categories are: ambulance, b19_combined_package, cardiac_pulmonary_rehab, clinical_diagnostic_therapeutic, combined_supplemental, dental, dme, dsnp_cost_share, emergency_urgent, health_professionals, hearing, home_health, inpatient_hospital, inpatient_psychiatric, meals, moop, optional_package, otc, outpatient_hospital, partb_rx_drugs, partd_drugs, partd_tier, partial_hospitalization, plan_deductible, plan_premium, preventive, prior_auth_referral, renal_dialysis, section_c_pos_oon, snf, ssbci, supplemental_other, supplemental_services, transportation, vision. The premium is plan_premium (not 'premium'), the deductible is plan_deductible, the out-of-pocket maximum is moop.

summary.value is the one number a reader asks for: for plan_premium the monthly premium in USD; for plan_deductible the in-network annual deductible in USD (or null with the filed reason); for moop the in-network annual MOOP in USD, which on a D-SNP is the plan design before Medicaid and Extra Help, never what a dual pays. summary.label says which. Limits read in words ("6 visits every year"; 999 is CMS's unlimited sentinel and reads "unlimited"); the filed code is kept in limit_text_raw.

A contract/plan/year/category combination with NO rows is REFUSED with code NO_DATA, not answered with an empty complete: the refusal states what was searched and routes to get_landscape (the plan ids that really exist for that contract and year) and names the valid categories. One view is read, so a nonexistent plan and a plan with nothing in this category cannot be told apart here; the refusal says so.

Vlada Plan Value: MODELED value to the member of a Medicare Advantage plan, per member per month, for 2026 and 2027 (never a filed benefit, a bid or a paid claim). The headline is medical cost-sharing value at the expected position in each filed range + extras (the flex card valued by what the money buys) + Part D + the Part B buydown - the member premium, one figure per leg. D-SNP has two columns: the headline is the full-dual column (extras + Part D against the Extra Help comparator, medical $0) and the filed design rides beside it.

THREE MODES, chosen by the arguments. PLAN: contract_id (e.g. 'H0609') + plan_id (e.g. '025') [+ segment_id] -> each plan segment's value 2026 and 2027, the five legs, the range ends, the card bounds, the value without Part D, the filed design, and for a D-SNP the full-dual column, Part D against Extra Help and Medicaid's cost-sharing protection (published beside, never in a total), plus part_d_2027_basis. A contract alone lists its plan segments (largest first). MARKET: product_type (required; non-SNP HMO | non-SNP PPO | D-SNP HMO | D-SNP PPO | C-SNP HMO | C-SNP PPO | I-SNP HMO | I-SNP PPO; 'ALL' is refused) + geography (national | state | county; inferred from the place) + state / county (name as CMS spells it, with state) / county_ssa, optional parent (partial name matches) and plan_type (default 'ALL'), group_by (parent by default | none | state | county | plan_type | product_type) -> value.summary is the market: its levels (2026 = every September 2026 member, 2027 = those members followed to their 2027 plan) and its same-member change (members valued in both years: 2026, 2027, change), every leg; value.rows are the parents (or groups), largest first. RANK: rank=true with product_type and a geography -> who cut and who added most, on two bases side by side: 'same members' (member-weighted, the members followed) and 'plans on the shelf' (the simple average of the plans offered), each with its rank.

limit bounds the rows (default 25, max 500).

READ IT RIGHT: compare only inside one product type; a null is not valued, never $0; levels are not changes (the change is the same-member block); the 2027 Part D leg is interim, the 2027 filed design priced on the 2026 drug list (a brand-new plan with no predecessor is unpriced until CMS posts the 2027 formulary), so quote the value without Part D beside it; the card is the largest open sensitivity (quote the card bounds); 2027 is priced on the 2026 cohort, statute and dollars, a design comparison and not a forecast.

SOURCE: Vlada Plan Value (method signed 2026-10-08, build v18) from the CMS Plan Benefit Package filings, CMS county enrollment, the CMS plan crosswalk and the CMS Part D formulary files.

MA quality bonus dollars by contract or parent and payment year. For each: the star tier CMS pays on (bonus % of the benchmark and the rebate share), members, risk score, rebate, the benchmark bonus, and what the star tier is worth in revenue per member per month and per year, three ways: benefits held (rebate fixed), observed (what carriers did when a contract crossed a tier, 2015-2024), and the 4.0 cliff (4.0 over 3.5).

ARGUMENTS: contract_id (e.g. H5216) or parent (part of the parent organization's name, e.g. 'Humana'), group_by (contract | parent; default contract when contract_id is given, else parent), payment_year (default: every year for one contract, otherwise the newest year), limit (default 50, most members first).

RETURNS value.rows: a contract row per payment year (tier, tier source and check against the tier CMS's payment file implies, members, PMPM and annual dollars), or a parent row per payment year (members, member-weighted star, bonus %, PMPM figures, annual dollars summed, contracts). value.summary carries the scope and which years are measured and which are modeled.

RULES THE TOOL ENFORCES: rating year Y sets the bonus paid in payment year Y+1 (PY2028 uses the RY2027 stars) and every row names both; PY2025-2028 are modeled (period 'forward') and labeled; new contracts of an existing parent take the parent's member-weighted star, not 3.5; all of MA is priced (individual, employer group and regional PPO) and the share not priced is shown; a parent row weights PMPM by members priced and sums dollars.

SOURCE: CMS MA ratebooks, plan payment files (average payment, risk score, rebate), Rate Announcements, Star Ratings and monthly enrollment, through Vlada's QBP financial chain (audited twice; method: STARS-QBP-FINANCIAL-CHAIN).

How a Medicare Advantage contract performs on the Star measures against the market, its peers, its competitors and CMS's cut points, over time. Two views in one answer. FAMILIES: for each measure family (all measures, HEDIS, HOS, CAHPS, pharmacy, complaints and leaving, appeals, call center, plan reporting) and each rating year, the contract's actual performance % (CMS-weighted mean of its measure scores; lower-is-better rates counted as their complement, so 10% readmitted = 90%; complaints per 1,000 and improvement scores are counted, not averaged), the 4-star line over exactly the measures it was scored on, and its weighted star; beside the market (member-weighted and one contract one vote), a cohort (default: its dominant product in its dominant state, e.g. D-SNPs in NY), its peer class (national carrier, Blue Cross Blue Shield plan, Kaiser, provider-sponsored, regional plan, MA-focused entrant) and the average of its five nearest competitors. MEASURES: for the latest rating year, every measure's score, star, CMS message where there is no score, the 2-5 star cut points, the market mean (members and contracts), median and middle half, the cohort mean, the gap to the market (positive = better, direction-aware), the percentile among MA contracts, and each competitor's score.

ARGUMENTS: contract_id (required, H or R contract, e.g. H5549), rating_year (default the newest held), years (1-13, default 5), cohort (one of product_state, product, peer_class, parent, peer_class_product, cai_group, size_band, star_band, state, org_type; default product_state), family (optional: restrict the measures view to one family, e.g. hedis), limit (measure rows, default 60).

RETURNS value.summary (contract, rating year, parent, peer class, product, state, members, the cohort used, the five competitors with their parents and shared-county members), value.families (one row per family per year) and value.measures (one row per measure, latest year).

RULES THE TOOL ENFORCES: every number is read from the stored benchmark tables, never averaged at call time; a score belongs to the whole contract, so a contract sits in the one product and state holding most of its members; text cells (plan too small, not enough data) are counted and never imputed; CAHPS cut points are approximate because CMS also tests significance; stand-alone drug plans are a separate market and are not included.

SOURCE: CMS Part C and D Star Ratings data tables and CMS monthly enrollment, through Vlada's measure benchmark engine (stars_measure_benchmark@1.0.0).

How a contract's star is built, and what moves it to the next line. For one Medicare Advantage contract and rating year: for the Overall, Part C and Part D summaries, the raw score (the weighted mean of the measure stars), the categorical adjustment (CAI), the reward factor, the score before rounding, the published star and the recomputed one, the cushion above the line the star was earned at and the gap to the next half-star line (and to 3.75, which rounds to 4.0). Then every measure: score, star, weight, direction, the next star's cut point and the distance to it in the measure's own units, and what one more star on it adds to each summary's raw score; plus the shortest list of one-star gains that closes the gap to the next line.

ARGUMENTS: contract_id (required, e.g. H5216), rating_year (default the newest held for the contract), limit (measure rows, default 60).

RETURNS value.summary (contract, rating_year, pays_in, parts: one block per summary with its decomposition, gaps and path) and value.measures (one row per measure).

RULES THE TOOL ENFORCES: the arithmetic is CMS's (the raw score over the measure set CMS used, picked so the weights add up to the recompute engine's total; the Overall leaves out the two Part D measures that duplicate Part C); one more star adds weight / total weight to the raw score; the path holds the CAI and the reward factor constant and says so; distances are in the measure's own units and direction (for a lower-is-better measure the score must fall); survey (CAHPS) cut points are approximate, because CMS also tests significance and reliability; improvement measures have no cut point. The recomputed star is the engine's, the published star is CMS's; where they differ the row says why.

SOURCE: CMS Part C and D Star Ratings Data Tables and Technical Notes, through Vlada's recompute engine, which reproduces 98.4% of every star CMS published (RY2015-2027) exactly.

Star Risk: odds a star falls, holds or rises next year. For one Medicare Advantage contract and origin rating year, for the Overall, Part C and Part D summaries, scored on the forecast year's own rules (the final rule's measure set and weights, named in the answer): Down / Same / Up for next year's star, the chance it falls below this year's star (chance to drop), the chance it lands below 4.0 (the quality bonus line; for a contract at 4.0 the same event and the same number as dropping, for one at 3.5 one minus the chance of rising) and the chance it rises (Upside), each with a status saying what it is worth. The Overall headline is a blend of Vlada's simulation (70%) and a statistical model of the outcome with benefit and growth changes (30%), the model locked on 2026-10-13; the simulation's own odds ride beside it, labeled. Also: the expected star and its distribution (simulated), Star Distance (typical years of movement between the score before rounding and the line it earned), the raw score and the reward factor apart (and the chance the reward factor drops), three layers of distance (each measure to its own line, a cut point or for survey measures a modeled effective line; the score before rounding to its half-star lines; the raw mean and spread to the reward factor's thresholds), the Effective Star Cushion and Reach (descriptive), the cheapest sets of measure gains that reach the next half star (up paths), the per-contract Focus list (context) and the protect list (measures with the fewest score points above the line that keeps their star). With parent instead: the parent organization's book, the measures where contracts that improved moved up a star more often (expected members gaining a star, contracts helped; the top 3 are the held-out tested list), its protect list, and each of its contracts' Down / Same / Up.

ARGUMENTS: contract_id (e.g. H5216; H or R contracts, employer direct E contracts are not scored) or parent (a parent organization name such as Humana, or a contract id to use its parent); exactly one. part (Overall, C or D; default all three; contract only), rating_year (the origin rating year; default the newest scored), limit (rows, default 60).

RETURNS for a contract value.summary (contract, rating_year, forecast_year, engine version and runs, the headline model, the rule set, parts: one block per summary, each probability with a _status, down_same_up, and the simulation's own odds under simulation) and value.measures (one row per measure: star, weight this year and next, removed next year, weight share, distances down and up in score points and in typical years, the line they are measured to, lift per typical year); for a parent value.summary (parent, book, focus, protect) and value.contracts (each contract's stars and odds).

WHAT EACH NUMBER IS WORTH, as the answer says: on held-out years 2024-2027, the locked blend's chance to drop ranks contracts well (AUC 0.746) and is sharper than history (Brier skill +0.034, 90% interval +0.014 to +0.051); its odds sit somewhat too close to average (calibration slope 1.33): by origin star it predicted 14% Down for 3.0 contracts against 10% actual, 37% for 4.0 against 41% and 46% for 5.0 against 65%; below 4.0 is tested for contracts within half a star of the line (skill +0.059) and is context further from it; Upside is tested (from 3.5 it is the chance of reaching 4.0); Down / Same / Up is tested as one forecast; the simulation's own odds are shown only for comparison; Part C and Part D are simulated shares, uncalibrated and untested; the expected star is simulated and runs low; the parent focus list is an association tested on held-out years (top 3 only), never a promise of a star; the per-contract focus list did not pass its test and is context only; the protect list is a ranking rule, not a tested prediction, and never lists a measure CMS removes next year; slip paths are not served; the Effective Star Cushion and Reach are descriptive, never predictive; where the path engine does not reproduce CMS's published star its paths are flagged untrusted. Every number is a model forecast, not an observed rating.

SOURCE: CMS Part C and D Star Ratings Data Tables, Technical Notes, cut points and the forecast year's final rule, through Vlada's Star Risk engine (simulation on CMS's exact summary arithmetic, calibrated on development years, blended with a statistical model fitted on development years, judged on held-out years).

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, identity key, part, domain, weight, direction, the raw value and its star, the 4-star line, and the star's YoY change) so you can see exactly which measures moved the rating. The prior-year star is matched by MEASURE IDENTITY through the Stars measure spine, never by code (CMS renumbered 27 of 33 Part C codes for RY2026); prior_year_measure_id names the code the prior star was filed under. Filter by contract_id (required) + optional year (the rating_year, defaults to the latest) + optional limit (max measure rows returned). Rating years 2012-2027 (RY2027 is CMS's final October 2026 release). 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 the plan economics (payment and MLR) and is reported at the CONTRACT level (no plan_id).

Scores are served at the precision CMS publishes (float32 storage noise is removed on the wire). Each measure row's four_star_ladder names the cut point ladder its four-star line came from: CMS calculates MA-PD and PDP Part D cut points separately, so an MA contract (H, R) reads the MA-PD ladder and a stand-alone drug plan contract (S) the PDP ladder; ALL is a ladder CMS published for every organisation (Part C).

RESTATED OVERALL. CMS restated 50 contracts' RY2026 Overall rating on July 22, 2026 (after the Clover Health ruling) without changing any measure star, so for those contracts the measure breakdown reflects the original calculation and can round to a different star than the served Overall. The answer says so in a caveat and names the original value in summary.overall_restated_from (summary.overall_restated_from_text carries CMS's text when the original was a message such as 'Not enough data available').

SOURCE: CMS Star Ratings (summary + measure-level) and the Vlada measure spine medicare_semantic.dim_stars_measure_identity_v6.

Returns CMS-published per-measure star-level cut points (the threshold a contract must reach for stars 2 to 5) for a rating_year, read through the Stars measure spine so a measure keeps its identity across years even when CMS renumbers its code (27 of 33 Part C codes moved for RY2026).

TWO SHAPES. Pass measure_id (that year's code, e.g. C09; a trailing ':' as stored is accepted) or measure_identity_key (the stable key, e.g. 'c:controlling_blood_pressure') for ONE measure: value.measure carries the identity, the star_2 to star_5 thresholds with their ops, the prior and next year's code and the ladder direction; value.cutpoints carries the raw CMS rows; include_history=true adds value.history, the same identity's ladder in every rated year (cut point drift). With neither, value.measures is a paged index of the year's measures (limit, offset; default 50 rows) and the answer names the per-measure call.

LADDER. CMS calculates MA-PD and PDP Part D cut points separately. The header (value.measure and the index rows) reads the ladder for org_subtype: MA-PD by default (the Medicare Advantage question), PDP for a stand-alone drug plan question; cutpoint_org_subtype names the ladder read, and it is ALL only where CMS published one ladder for every organisation (Part C). org_subtype (MA-PD | PDP | ALL) and star_level (1-5) also filter the raw rows.

Use cases: 'what is the 4-star line for Controlling Blood Pressure in RY2027?'; 'how did that line move since RY2024?'; 'how much would contract H1234 need to improve to reach 5 stars on D08?'.

SOURCE: CMS Tech Notes Attachment H (Tukey-aware threshold tables) for RY2024+, Attachment H pre-Tukey for RY2017-RY2023, pre-fixed cut points for RY2015-RY2016. RY2027 is CMS's final release (the 2027 Data Tables, 2026-10-08); the plan-preview rows it replaced stay readable as superseded (is_current = false). Spine: medicare_semantic.dim_stars_measure_identity_v6 (tools/ma_brain/stars_measure_spine_publish.py), whose direction flag agrees with CMS's own cut point ladder in every rated year.

HOLDINGS ARE NAMED, NEVER IMPLIED. When a rating year holds only ONE Part D ladder the answer says so and which population it is for. A measure with no cut point rows in a year is reported as not held in this edition, with the years held named; CMS publishes cut points every year. Thresholds are served at the precision CMS publishes (float32 storage noise is removed on the wire).

MA Star Ratings by parent, product type or state, year over year. For a rating year against the year before: members in rated and unrated contracts, the member-weighted Overall star, the share of members (and of contracts) at 4 stars or more, and members by Overall star. Optionally the weighted measure star for a measure group, like for like.

ARGUMENTS: rating_year (default the newest with Overall stars), compare_year (default rating_year minus 1), group_by (national | parent | product_type | parent_by_product | state | state_by_product), parent (filter: part of the parent organization's name, e.g. 'UnitedHealth'), product_type (filter: nonsnp_hmo | nonsnp_ppo | dsnp_hmo | dsnp_ppo | csnp_hmo | csnp_ppo | isnp | other), state (filter: two-letter code), measure_group (optional: all | part_c | part_d | patient_safety | domain:<CMS domain code, e.g. HD3 or DD4> | source:<CMS data source, e.g. HEDIS, CAHPS, HOS, PDE> | measure:<measure identity key, e.g. c:controlling_blood_pressure>), limit (default 50, largest rated members first).

RETURNS value.rows (one per group), each with members_rated, members_unrated, contracts_rated, contracts_unrated, pct_members_4plus, wtd_avg_star, pct_contracts_4plus, members_by_star, prior (the same fields for compare_year) and change; with measure_group, a measure_group block {measures, contracts, wtd_measure_star, wtd_measure_star_prior, change}. value.summary is the national row for the same filters, with each year's weight month.

RULES THE TOOL ENFORCES: rating year Y is weighted by December of the payment year (Y+1), or the latest month when that December is not published, and says which (the certified house convention); the parent is the enrollment file's parent at the weight month; stand-alone drug plans are out; unrated contracts are counted apart, never as zero stars; product types are the fixed buckets (non-SNP, D-SNP, C-SNP by HMO and PPO; I-SNP; other), never pooled; a star belongs to the contract, so a product type or state row weights the contract's star by its members there; a measure group change compares the same contracts, measures, weights (the rating year's) and members, and leaves out new measures, re-specified measures and the improvement measures. Measure stars are CMS's normalization; raw scores are never averaged across measures.

SOURCE: CMS Part C and D Star Ratings Data Tables and CMS monthly enrollment (contract, plan, SNP and county files).

Return the fail-closed measured way to join two Vlada substrate tables, including an explicit DIRECT_OK, DIRECT_DECLARED_KEY, NEEDS_GRAIN, ROUTE_THROUGH_DIM, ROUTE_MULTIHOP, or DO_NOT_SERVE directive. Direct joins come from (in order) the measured connection registry, the VALIDATED join graph (catalog.json join_edges: uniqueness >= 0.999 and match >= 0.80, measured live), or the semantic layer's declared shared surrogate key (DIRECT_DECLARED_KEY, labelled not-live-measured); a validated or declared direct join is always preferred over a route and never refused. Route coverage (min_coverage) is the weaker side of the weakest hop; a route under 50% is labelled low_coverage_route. Unproved composite, NEEDS_GRAIN, quarantined, impossible, or N:M direct evidence cannot be served. With only table_a, it lists every executable connection from that table.

Look up the negotiated rates a payer pays a specific provider (NPI), resolved at query time through the canonical graph: NPI → provider groups → pg_sets → rates (no precomputed edge table). Returns matching rates with evidence_type (provider_specific vs broad applicability) and Medicare-PUF corroboration (presence ⇒ real; absence ⇒ unverified, NOT ghost). Optional code filter. Covers all built payers. PAGED: limit (default 25, max 500) and offset bound both matching_rates and provider_groups; rate_count / provider_group_count are the full totals and paging names what was cut plus the call that returns the next page. value is a COUNT, never a price: it is the TOTAL number of matching rates, unit says so, and headline spells it out in fields (kind=count, is_a_price=false). The prices themselves are one per row in matching_rates.