get_network_change

What it answers

1. 1Who 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.
2. 2The method: members are NPIs the payer printed, served by API or exported to Plan Finder, or name-matched at grade A/B;
3. 32027 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.
4. 4By contract or by the publisher's own plan id.
5. 5Use cases: 'Did H5938 lose providers for 2027?'; 'How much of Wellcare H1416's Texas network turned over?'.
6. 6A 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.
7. 7Both years must be covered or the answer is NO_COVERAGE.
8. 8SOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build).

Inputs (5)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_network_change(contract_id="H5938")

curl -X POST https://api.vladahealth.com/v1/tools/get_network_change \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H5938"}'

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

A real answer

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

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": "NetworkChangeResponse",
 "type": "object"
}

Sources

Known limits (3)

1. 1No 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.
2. 2Humana'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.
3. 3A contract uncovered in either year answers NO_COVERAGE.