# get_market_share

Get Market Share · v0.3.1 · medicare

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.

**Inputs.**
- `contract_id` (required): 
- `plan_id`: 
- `state`: 
- `month`: 
- `limit`: 

**Known limits.**
- County cells under 11 enrollees are CMS-redacted (null enrollees, null share).
- Share = plan county enrollees / total MA enrolled in county (penetration file).

**A real answer** (customer seat, 6.33 s, args `{"contract_id":"H1036","limit":5}`):

```json
{
 "value": {
  "found": true,
  "not_found_reason": null,
  "summary": {
   "contract_id": "H1036",
   "plan_id": null,
   "grain": "contract",
   "state": null,
   "month": "2026-10-01",
   "share_pct": 3.24,
   "share_definition": "plan enrollees in the counties in scope / total MA enrollment of those same counties, for the month in scope",
   "share_numerator_plan_enrollees": 856969,
   "share_numerator_basis": "bound_floor_published_plus_1_per_suppressed_county",
   "share_numerator_published_cells": 856312,
   "share_denominator_county_ma_enrolled": 26489733,
   "share_numerator_bound": [
    856969,
    862882
   ],
   "share_pct_bound": [
    3.24,
    3.26
   ],
   "counties_medicare_eligibles": 50029743,
   "footprint_ma_penetration_pct": 52.95,
   "county_count": 1006,
   "suppressed_county_count": 657,
   "best_county_share_pct": 40.82,
   "median_county_share_pct": 6.13,
   "largest_county": {
    "state": "FL",
    "county": "Broward",
    "plan_enrollees": 88173,
    "share_pct": 35.59
   },
   "unit": "percent_of_county_ma_enrollment"
  },
  "counties": [
   {
    "state": "FL",
    "county": "Broward",
    "plan_enrollees": 88173,
    "county_ma_enrolled": 247731,
    "county_eligibles": 383369,
    "penetration": 0.6462,
    "share_pct": 35.59,
    "yoy_change": 11388,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Miami-Dade",
    "plan_enrollees": 65998,
    "county_ma_enrolled": 397170,
    "county_eligibles": 528794,
    "penetration": 0.7511,
    "share_pct": 16.62,
    "yoy_change": 10681,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Palm Beach",
    "plan_enrollees": 52582,
    "county_ma_enrolled": 179484,
    "county_eligibles": 371693,
    "penetration": 0.4829,
    "share_pct": 29.3,
    "yoy_change": 2638,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Hillsborough",
    "plan_enrollees": 40211,
    "county_ma_enrolled": 172547,
    "county_eligibles": 274972,
    "penetration": 0.6275,
    "share_pct": 23.3,
    "yoy_change": 4387,
    "county_ma_is_group_figure": false
   },
   {
    "state": "FL",
    "county": "Pinellas",
    "plan_enrollees": 35353,
    "county_ma_enrolled": 160487,
    "county_eligibles": 265560,
    "penetration": 0.6043,
    "share_pct": 22.03,
    "yoy_change": 2021,
    "county_ma_is_group_figure": false
   }
  ],
  "row_counts": {
   "counties": {
    "matched": 1006,
    "returned": 5,
    "truncated": true,
    "limit": 5,
    "kept": "head"
   }
  },
  "query": {
   "contract_id": "H1036",
   "plan_id": null,
   "grain": "contract",
   "state": null,
   "month": "2026-10-01",
   "limit": 5
  },
  "query_id": "6cbad2cb-aa86-4233-9a31-ad924caed7eb"
 },
 "unit": "market_share_detail",
 "result_status": "answered",
 "methodology_era": null,
 "methodology_blend_factors": null,
 "source": {
  "source_url": "medicare://get_market_share"
 },
 "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": "65641d3dce1dec285d899b1bdea42f34a48a1d42c9e6184e25ee05a9142e60ad",
 "semantic_version": 1,
 "tool_version": "0.3.1",
 "parser_artifact_hash": "0b11193fb97519397f53ffe2917938b1bf95f408fccb5bae6d356b17ef22a148",
 "parser_artifact_hash_basis": "tool_source_sha256",
 "signature": null,
 "tenant_id": "probe-customer-canary",
 "status": "complete",
 "audit_id": "20c32f7c-c513-4d31-9421-20fda03154e8",
 "timestamp": "2026-11-09T21:36:54.622950Z",
 "request_id": "e9c3ca90-15fe-45d5-b90e-62ec96cdbf40",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "market_share_detail",
  "scope": {
   "tool": "get_market_share",
   "filters": {
    "contract_id": "H1036",
    "limit": 5
   }
  }
 },
 "method": "Read from the CMS publication at the contract level. The published values are reported as published, with no adjustment or modelling applied.",
 "evidence": {
  "query_id": "6cbad2cb-aa86-4233-9a31-ad924caed7eb",
  "response_hash": "65641d3dce1dec285d899b1bdea42f34a48a1d42c9e6184e25ee05a9142e60ad",
  "audit_id": "20c32f7c-c513-4d31-9421-20fda03154e8",
  "request_id": "e9c3ca90-15fe-45d5-b90e-62ec96cdbf40"
 }
}
```

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