# get_hos

Get Hos · v0.2.0 · medicare

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.

**Inputs.**
- `contract_id` (required): 
- `year`: 
- `limit`: 

**Known limits.**
- rate1/rate2 semantics are topic-specific; consult the CMS HOS documentation.

**A real answer** (customer seat, 7.56 s, args `{"contract_id":"H1036","year":2025}`):

```json
{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "contract_id": "H1036",
   "year": 2025,
   "topic_count": 3,
   "topics_reported": [
    "fall_risk_management",
    "physical_activity",
    "urinary_incontinence"
   ],
   "topics_missing": [
    "osteoporosis_testing"
   ],
   "highest_rate1": {
    "topic": "physical_activity",
    "rate1": 58.76
   },
   "lowest_rate1": {
    "topic": "fall_risk_management",
    "rate1": 29.78
   },
   "unit": "hos_topic_rows"
  },
  "topics": [
   {
    "topic": "fall_risk_management",
    "report_year": 2025,
    "rate1": 29.78,
    "rate2": 60.99,
    "rate3": null,
    "rate1_yoy": 1.75
   },
   {
    "topic": "physical_activity",
    "report_year": 2025,
    "rate1": 58.76,
    "rate2": 51.99,
    "rate3": null,
    "rate1_yoy": -1.83
   },
   {
    "topic": "urinary_incontinence",
    "report_year": 2025,
    "rate1": 54.55,
    "rate2": 45.08,
    "rate3": 15.57,
    "rate1_yoy": -13.36
   }
  ],
  "row_counts": {
   "topics": {
    "matched": 3,
    "returned": 3,
    "truncated": false,
    "limit": 200,
    "kept": "head"
   }
  },
  "query": {
   "contract_id": "H1036",
   "year": 2025,
   "limit": 200
  },
  "query_id": "61bcdae1-ec58-4d9e-a8f6-14b73871903f"
 },
 "unit": "hos_detail",
 "result_status": "answered",
 "methodology_era": null,
 "methodology_blend_factors": null,
 "source": {
  "source_url": "medicare://get_hos"
 },
 "vintage": "as_restated",
 "cms_vintage_sequence": 1,
 "parse_revision": 1,
 "as_of_observed": null,
 "as_of_asserted": null,
 "as_of_effective": null,
 "caveats": [],
 "confidence": null,
 "finality_confidence": null,
 "response_hash": "a9fa4cb399d65eaee81dab89f3df3a108fef1b03b1806a16f7de94ce10244b4d",
 "semantic_version": 1,
 "tool_version": "0.2.0",
 "parser_artifact_hash": "0b11193fb97519397f53ffe2917938b1bf95f408fccb5bae6d356b17ef22a148",
 "parser_artifact_hash_basis": "tool_source_sha256",
 "signature": null,
 "tenant_id": "probe-customer-canary",
 "status": "complete",
 "audit_id": "cf761391-badd-48ae-94da-7167f68c188c",
 "timestamp": "2026-11-09T21:37:21.882599Z",
 "request_id": "00340683-b65c-423e-8671-f6bdf1978032",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "hos_detail",
  "scope": {
   "tool": "get_hos",
   "filters": {
    "contract_id": "H1036",
    "year": 2025
   }
  },
  "period": {
   "year": 2025
  }
 },
 "method": "Read from the CMS publication for 2025 at the contract level. The published values are reported as published, with no adjustment or modelling applied.",
 "evidence": {
  "query_id": "61bcdae1-ec58-4d9e-a8f6-14b73871903f",
  "response_hash": "a9fa4cb399d65eaee81dab89f3df3a108fef1b03b1806a16f7de94ce10244b4d",
  "audit_id": "cf761391-badd-48ae-94da-7167f68c188c",
  "request_id": "00340683-b65c-423e-8671-f6bdf1978032"
 }
}
```

REST: `POST https://api.vladahealth.com/v1/tools/get_hos` with the inputs as the JSON body. MCP: the tool by name.