get_hospital_quality

Get Hospital Quality

What it answers

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.

Inputs

ccn

string · required

limit

integer · optional

measure_group

string · optional

measure_source

string · optional

offset

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_hospital_quality 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_hospital_quality \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ccn":"<ccn>"}'

curl https://api.vladahealth.com/v1/tools/get_hospital_quality/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.dim_hospital_quality
medicare_silver.fact_hospital_quality_measure
medicare_silver.fact_hcahps
medicare_silver.fact_hrrp

tables: medicare_silver.dim_hospital_quality · medicare_silver.fact_hospital_quality_measure · medicare_silver.fact_hcahps · medicare_silver.fact_hrrp

Known limits

overall_rating is null for hospitals CMS does not rate (~40% of CCNs) — unrated, not 0.
score_numeric is null for suppressed / categorical / footnoted measures; the row is returned as not_available with the footnote.
HCAHPS answer-percent distribution rows are not returned (star + linear mean summary only); HRRP is the latest fiscal year only.
Measure semantics differ per measure_id; do not compare scores across unlike measures.

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.