# get_network_breadth

Get Network Breadth · v0.2.0 · medicare

How broad a Medicare Advantage plan's published provider network is, county by county, against the other plans sold there: for a contract or CMS plan id and plan year (2026 or 2027), each county in its service area with the providers it lists there, the county's listed universe (every MA plan's published directory in that county), breadth (the share), its rank among the county's individual plans, and the rivals' median and best. Narrow to one specialty in CMS's network-adequacy vocabulary (Primary Care, Cardiology, Psychiatry, ...), a state, or one county; with a county, the rival plans are returned ranked.

Use cases: 'Is H5938's network narrower than its rivals in Leon County?'; 'Where does this PPO rank on cardiologists in Florida?'; 'Which plan in Cook County lists the most psychiatrists for 2027?'.

Breadth is a share of what MA plans list, not of every practising clinician. Every row carries the share of the plan's providers found by name match and the share carried from the other year's list, so a printed-PDF plan is not silently compared with an API plan. Specialty comes from NPPES's taxonomy, not the directory's label. The publish is pinned by dataset_id.

SOURCE: medicare_silver.ma_network_plan_county_v1, built from the Data Tracker's directory table (medicare_bronze.ma_directory_plan_npi_site_v1), NPPES, and the CMS plan service area.

**Inputs.**
- `contract_id`: CMS contract id (H5938). One of contract_id / cms_plan_id.
- `cms_plan_id`: CMS plan id H1234-001 or H1234-001-000.
- `plan_year` (required): 2026 or 2027 (the directory year).
- `limit`: Rows to return (default 50, max 500); summaries are always whole.
- `county_fips`: 5-digit county FIPS (12073); with it, the rival plans in that county are returned.
- `state`: 2-letter state; narrows to the plan's counties in that state.
- `specialty`: Normalized specialty (CMS MA network-adequacy type, e.g. 'Cardiology', 'Primary Care'); omit for every provider.

**Known limits.**
- Coverage follows the directory build (stage 25: 99.17% of 2026 MA members, 96.42% of 2027 members from 2027 sources); an uncovered contract answers no_coverage, and a plan with listings only outside its CMS service area has no breadth rows.
- Name-matched lists under-count: names that resolve to no single NPI are dropped, so a printed-PDF plan can read narrower than it is (matched_share says how much of the list is name-matched).
- About 2.5% of listings have a ZIP with no county and sit outside every county count.
- Contract-level directories (one network for every plan in the contract) are applied to each plan sold in the county (contract_level_share).

**A real answer** (customer seat, 1.75 s, args `{"contract_id":"H5938","plan_year":2027,"county_fips":"12073","limit":5}`):

```json
{
 "value": {
  "found": false,
  "not_found_reason": "no_row_matches_filters",
  "query": {
   "contract_id": "H5938",
   "plan_year": 2027,
   "county_fips": "12073",
   "specialty": "*",
   "limit": 5
  },
  "dataset_id": "7bceef45cc9e5910e64caa428a1f3e40869f91d149c4e19f08cc55f5e468ba7c",
  "rows": [],
  "query_ids": [
   "17379d90-8526-401e-993f-bb9fad731bc9"
  ]
 },
 "unit": "network_breadth",
 "vintage": null,
 "source": {
  "dataset": "MA plan networks, 2026 and 2027 (Data Tracker): plan year x CMS plan x NPI x listed location",
  "publisher": "vlada",
  "catalog_updated_at": "2026-11-02"
 },
 "caveats": [
  "Absence is a claim only for a covered contract, and only 'not listed in the published directory'; a contract with no rows is UNCOVERED (the open-gap list), never 'no network'."
 ],
 "response_hash": "03b829582391960f745551c9a41e61423768a62060c912209ae78a56538d7f09",
 "semantic_version": 1,
 "tool_version": "get_network_breadth@0.2.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "network_breadth",
  "scope": {
   "tool": "get_network_breadth",
   "filters": {
    "contract_id": "H5938",
    "plan_year": 2027,
    "limit": 5,
    "county_fips": "12073"
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included.",
 "evidence": {
  "sources": [
   {
    "dataset": "MA plan networks, 2026 and 2027 (Data Tracker): plan year x CMS plan x NPI x listed location",
    "publisher": "vlada",
    "catalog_updated_at": "2026-11-02"
   }
  ],
  "response_hash": "03b829582391960f745551c9a41e61423768a62060c912209ae78a56538d7f09"
 },
 "freshness": {
  "state": "unknown",
  "why": "This tool does not report an edition for its answer, and the door could not derive one from what the answer reads. Treat the result as current to no stated date."
 }
}
```

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