# get_network_change

Get Network Change · v0.2.0 · medicare

Who joined and who left a Medicare Advantage plan's published network between two directory years (2026 to 2027): the NPIs that stayed, joined and left, with rates, on published units only. The method: members are NPIs the payer printed, served by API or exported to Plan Finder, or name-matched at grade A/B; 2027 rows carried back from a 2026 directory are excluded; only ZIP3 areas the unit lists in both years count, so a service-area change does not read as an exit. By contract or by the publisher's own plan id.

Use cases: 'Did H5938 lose providers for 2027?'; 'How much of Wellcare H1416's Texas network turned over?'.

A directory signal is never evidence of a contract ending on its own (the method's public-confirmation rule); the health-system rollup and the exit signal are not served here. Both years must be covered or the answer is NO_COVERAGE.

SOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build).

**Inputs.**
- `contract_id`: CMS contract id (H5938). One of contract_id / cms_plan_id.
- `cms_plan_id`: CMS plan id (H1234-001-000): the publisher's own unit when it attached one.
- `from_year`: The earlier directory year.
- `to_year`: The later directory year.
- `state`: 2-letter state of the listed location; optional.

**Known limits.**
- No health-system rollup and no exit signal here (the method's steps 4-5 need the facility affiliation and dim_facility_system tables and a public confirmation); counts are by contract or plan.
- Humana's 2027 joined rate reads high in the method's own scale table and may be a printing or matching artifact; treat a large joined count as unverified.
- A contract uncovered in either year answers NO_COVERAGE.

**A real answer** (customer seat, 2.3 s, args `{"contract_id":"H5938"}`):

```json
{
 "value": {
  "found": false,
  "not_found_reason": "query_failed",
  "query": {
   "contract_id": "H5938",
   "from_year": 2026,
   "to_year": 2027
  },
  "dataset_id": "7bceef45cc9e5910e64caa428a1f3e40869f91d149c4e19f08cc55f5e468ba7c",
  "query_ids": []
 },
 "unit": "plan_network",
 "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": [],
 "response_hash": "e0e51a201837bd11840f4f6273e1da61c88770f39bbbb120a6ab97a827bdc5f2",
 "semantic_version": 1,
 "tool_version": "get_network_change@0.2.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "plan_network",
  "scope": {
   "tool": "get_network_change",
   "filters": {
    "contract_id": "H5938",
    "from_year": 2026,
    "to_year": 2027
   }
  }
 },
 "method": "Computed over the filters shown in this answer's scope, from the sources listed in its evidence. Nothing outside those filters was included. You did not specify from_year; 2026 was used. You did not specify to_year; 2027 was used.",
 "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": "e0e51a201837bd11840f4f6273e1da61c88770f39bbbb120a6ab97a827bdc5f2"
 },
 "defaults_applied": [
  {
   "param": "from_year",
   "used": 2026,
   "reason": "The earlier directory year."
  },
  {
   "param": "to_year",
   "used": 2027,
   "reason": "The later directory year."
  }
 ],
 "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_change` with the inputs as the JSON body. MCP: the tool by name.