get_network_breadth

What it answers

1. 1How 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.
2. 2Narrow 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.
3. 3Use 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?'.
4. 4Breadth is a share of what MA plans list, not of every practising clinician.
5. 5Every 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.
6. 6Specialty comes from NPPES's taxonomy, not the directory's label.
7. 7The publish is pinned by dataset_id.
8. 8SOURCE: 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 (7)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_network_breadth(contract_id="H5938", plan_year=2027, county_fips="12073", limit=5)

curl -X POST https://api.vladahealth.com/v1/tools/get_network_breadth \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H5938","plan_year":2027,"county_fips":"12073","limit":5}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/get_network_breadth/schema

A real answer

{
 "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."
 }
}

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "NetworkBreadthResponse",
 "type": "object"
}

Sources

Known limits (4)

1. 1Coverage 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.
2. 2Name-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).
3. 3About 2.5% of listings have a ZIP with no county and sit outside every county count.
4. 4Contract-level directories (one network for every plan in the contract) are applied to each plan sold in the county (contract_level_share).