get_plan_network

What it answers

1. 1The provider network a Medicare Advantage plan publishes: the NPIs its directory lists for a plan year (2026 or 2027), by contract or CMS plan id, with the source of every listing (the payer's own Plan-Net API, the printed directory, a name match to NPPES with its grade, or the Medicare Plan Finder export), the counts by source and grade, and a page of listings with name, specialty, location and the file and page each came from.
2. 2Filter by state, ZIP or specialty.
3. 3Use cases: 'How many providers does H5959 list for 2027?'; 'Which cardiologists are in H5938's network in Tallahassee?'; 'Is this plan's directory API-served or printed?'.
4. 4Membership is DISTINCT NPIs, never row counts.
5. 5Name-matched rows are flagged by grade and never presented as printed; listings whose name resolves to no single NPI are kept without an NPI and are not members.
6. 6A contract with no rows is UNCOVERED (the open-gap list), never 'no network'.
7. 72027 rows carried back from a 2026 directory are labelled (plan_key_basis).
8. 8The publish is pinned by dataset_id.
9. 9SOURCE: medicare_bronze.ma_directory_plan_npi_site_v1 (the Data Tracker's directory build; every row names its url, page and raw_sha256).

Inputs (7)

Call it

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

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

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

A real answer

{
 "value": {
  "found": false,
  "not_found_reason": "query_failed",
  "query": {
   "contract_id": "H5938",
   "plan_year": 2027,
   "limit": 5
  },
  "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": "a38a4df116e0dac275e5762743df6de0743e0062f1adbd238b5d50f43b293c0e",
 "semantic_version": 1,
 "tool_version": "get_plan_network@0.2.0",
 "explanation": null,
 "status": "complete",
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "plan_network",
  "scope": {
   "tool": "get_plan_network",
   "filters": {
    "contract_id": "H5938",
    "plan_year": 2027,
    "limit": 5
   }
  }
 },
 "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": "a38a4df116e0dac275e5762743df6de0743e0062f1adbd238b5d50f43b293c0e"
 },
 "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": "PlanNetworkResponse",
 "type": "object"
}

Sources

Known limits (4)

1. 1Coverage: 99.1% of 2026 MA members and 96.1% of 2027 members from 2027 sources (stage 21, 2026-11-02); the open-gap contracts (HCSC, Geisinger 2027, Highmark Wholecare, Elderplan, Mercy Care, Elevate, CarePartners CT, six thin Elevance contracts) are UNCOVERED and answer NO_COVERAGE.
2. 2Listings whose printed name does not resolve to a single NPI (about 11.3M rows, grade C or D, mostly Humana PDFs) are kept without an NPI and are not counted as members.
3. 3Matched grade N rows can lack city, state and ZIP; page is a string.
4. 442 contracts' (1,132,045 members') 2027 rows are their 2026 directory applied through the CMS crosswalk (plan_key_basis *_2026_plan_via_crosswalk): labelled, not a 2027 directory.