Medicare Advantage, Part D, Medicaid

prove_ma_enrollment_trend

Prove MA Enrollment Trend·v0.1.0·L2·read-only·MCP + REST·admitted 2026-09-19

Inputs

83 required

Sources

Known limits

Real answer

4.48scomplete

What it answers

1Execute a bounded MA enrollment-trend proof.
2Returns the answer value plus a receipt with substrate, source snapshots, filters, guardrails, caveats, input hash, response hash, and replay pointer.
3Reads three silver tables (CPSC county, monthly-enrollment-plan, plan-crosswalks) at their published snapshots.

Inputs (8)

Name	Type	Required	Default	Accepts
`parent_org`	string	required
`year_range_end`	integer	required
`year_range_start`	integer	required
`acknowledge_era_break`	boolean	optional	false	Retained for backward compat. The pre/post-2018 grain pivot was empirically falsified 2026-05-11; no era break is enforced. See docs/research/2026-05-11-cpsc-verification-ledger.md.
`max_contributing_rows`	integer	optional	5000000
`plan_types`	any	optional	null
`snp_types`	any	optional	null
`states`	any	optional	null

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
prove_ma_enrollment_trend(parent_org="Humana Inc.", year_range_start=2024, year_range_end=2024, states=["FL"])

curl -X POST https://api.vladahealth.com/v1/tools/prove_ma_enrollment_trend \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent_org":"Humana Inc.","year_range_start":2024,"year_range_end":2024,"states":["FL"]}'

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

A real answer

customer seat, 2026-11-09·over REST·4.48s·status complete·complete·verbatim

{
 "value": {
  "proof_kind": "ma_enrollment_trend",
  "parent_org_query": "Humana Inc.",
  "parent_org_canonical": "Humana Inc.",
  "year_range": [
   2024,
   2024
  ],
  "enrollment_count_months_point": 12402836,
  "enrollment_count_months_lower": 12402836,
  "enrollment_count_months_upper": 13236536,
  "suppressed_cell_count": 83370,
  "contributing_row_count": 99615,
  "per_month_count": 12,
  "row_count": 99615,
  "status": "ok",
  "verdict": "ok"
 },
 "unit": "enrollment_count_months",
 "vintage": "2024-2024",
 "source": {
  "dataset": "MA / Part D monthly enrollment reports (contract, plan, CPSC county, penetration, SNP, service area)",
  "publisher": "cms",
  "catalog_updated_at": "2026-05-13"
 },
 "caveats": [],
 "response_hash": "4b564c9644d93ce3f133fdc9079aa8b5081eaa3fe5225a0fff7704fe4c73dffe",
 "semantic_version": 1,
 "tool_version": "prove_ma_enrollment_trend@0.1.0",
 "explanation": null,
 "status": "complete",
 "proof_id": "maenrolltrendproof_b3116de04f64d91d",
 "receipt": {
  "receipt_version": "ma_enrollment_trend_receipt.v0",
  "proof_id": "maenrolltrendproof_b3116de04f64d91d",
  "substrate": "medicare_advantage",
  "proof_kind": "ma_enrollment_trend",
  "tool_name": "prove_ma_enrollment_trend",
  "tool_version": "0.1.0",
  "source_descriptor": {
   "tables": [
    "medicare_silver.enrollment_monthly_county",
    "medicare_silver.enrollment_monthly_plan",
    "medicare_silver.monthly_contract_enrollment_summary",
    "medicare_silver.plan_crosswalks_annual"
   ],
   "primary_table": "medicare_silver.enrollment_monthly_plan",
   "geography_table": "medicare_silver.enrollment_monthly_county",
   "lineage_table": "medicare_silver.plan_crosswalks_annual"
  },
  "read_snapshot_set": {
   "medicare_silver.enrollment_monthly_county": "3859245805449167937",
   "medicare_silver.enrollment_monthly_plan": "635122163549307464",
   "medicare_silver.plan_crosswalks_annual": "4686686039624534381",
   "medicare_silver.monthly_contract_enrollment_summary": "1413691709052438763"
  },
  "filters": {
   "parent_org": "Humana Inc.",
   "year_range_start": 2024,
   "year_range_end": 2024,
   "states": [
    "FL"
   ],
   "acknowledge_era_break": false
  },
  "guardrails": {
   "ma_vs_pdp_scope": "ma_only_or_explicit_pdp_inclusion",
   "suppression_bounds_applied": "lower_upper_bounds_required_on_suppressed_cells",
   "lineage_snapshot_required": "plan_crosswalks_snapshot_pinned",
   "published_snapshot_required": "silver_published_tag_resolved",
   "county_native_key_required": "cpsc_county_ssa_non_null",
   "no_unbounded_current_head_reads": "all_reads_use_pinned_snapshot"
  },
  "known_gap_status": {
   "cpsc_small_cell_suppression": {
    "registry_status": "active",
    "active": true,
    "gating_type": "suppressed_below_threshold",
    "resolved_at": null
   },
   "cpsc_2011_04_broomfield_duplicate_native_keys": {
    "registry_status": "resolved",
    "active": false,
    "gating_type": "parser_strategy_required",
    "resolved_at": null
   },
   "cpsc_2008_bareform_columns": {
    "registry_status": "resolved",
    "active": false,
    "gating_type": "parser_strategy_required",
    "resolved_at": null
   },
   "enrollment_grain_pre_2018": {
    "registry_status": "falsified",
    "active": false,
    "gating_type": "disabled",
    "resolved_at": null
   },
   "cpsc_2016_12_publication_gap": {
    "registry_status": "resolved",
    "active": false,
    "gating_type": "disabled",
    "resolved_at": "2026-05-11"
   },
   "cpsc_2021_06_wrong_file_uploaded": {
    "registry_status": "resolved",
    "active": false,
    "gating_type": "disabled",
    "resolved_at": "2026-05-11"
   },
   "cpsc_2025_03_wrong_file_uploaded": {
    "registry_status": "resolved",
    "active": false,
    "gating_type": "disabled",
    "resolved_at": "2026-05-11"
   }
  },
  "plan_or_query_evidence": {
   "max_contributing_rows": 5000000,
   "evidence_kind": "stub_pending_silver_planner"
  },
  "row_count": 99615,
  "status": "ok",
  "caveats": [
   "lineage_via_plan_crosswalks_when_crossing_plan_year_boundary",
   "ma_enrollment_only_not_ffs",
   "suppression_bounds_required_for_county_rollups",
   "suppression_warning_present"
  ],
  "input_hash": "b3116de04f64d91db3f2cb28ded3ba9e03e0571ee9da7e913f0e208a9a8171bc",
  "response_hash": "4b564c9644d93ce3f133fdc9079aa8b5081eaa3fe5225a0fff7704fe4c73dffe",
  "replay_pointer": {
   "tool": "prove_ma_enrollment_trend",
   "inputs": {
    "parent_org": "Humana Inc.",
    "year_range_start": 2024,
    "year_range_end": 2024,
    "states": [
     "FL"
    ],
    "acknowledge_era_break": false,
    "max_contributing_rows": 5000000
   },
   "receipt_id": "maerp_4b564c9644d93ce3f133fdc9",
   "athena_query_id_first_run": "cfc88f9b-b142-4302-abc1-9913c18e9273"
  },
  "receipt_id": "maerp_4b564c9644d93ce3f133fdc9"
 },
 "audience": "customer",
 "answer": {
  "value_ref": "value",
  "unit": "enrollment_count_months",
  "scope": {
   "tool": "prove_ma_enrollment_trend",
   "filters": {
    "parent_org": "Humana Inc.",
    "year_range_start": 2024,
    "year_range_end": 2024,
    "acknowledge_era_break": false,
    "max_contributing_rows": 5000000
   }
  }
 },
 "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 acknowledge_era_break; no was used. You did not specify max_contributing_rows; 5000000 was used.",
 "evidence": {
  "sources": [
   {
    "dataset": "MA / Part D monthly enrollment reports (contract, plan, CPSC county, penetration, SNP, service area)",
    "publisher": "cms",
    "catalog_updated_at": "2026-05-13"
   }
  ],
  "response_hash": "4b564c9644d93ce3f133fdc9079aa8b5081eaa3fe5225a0fff7704fe4c73dffe"
 },
 "defaults_applied": [
  {
   "param": "acknowledge_era_break",
   "used": false,
   "reason": "Retained for backward compat"
  },
  {
   "param": "max_contributing_rows",
   "used": 5000000,
   "reason": "tool default"
  }
 ]
}

What comes back

Field	Holds
`status`	complete · partial · refused · failed · queued
`value`	the shape below
`source · caveats · invariants_applied · response_hash`	the public file and vintage; what to know before citing; the rules honoured; replayable
`refusal`	code (15), message, recover_with

{
 "$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": "ok",
   "enum": [
    "planned",
    "ok",
    "no_match",
    "rejected_guardrail"
   ],
   "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"
  },
  "proof_id": {
   "default": "",
   "title": "Proof Id",
   "type": "string"
  },
  "receipt": {
   "additionalProperties": true,
   "title": "Receipt",
   "type": "object"
  }
 },
 "title": "MAEnrollmentTrendProofResponse",
 "type": "object"
}

Sources

Kind	Name
source	medicare_silver.enrollment_monthly_county
source	medicare_silver.enrollment_monthly_plan
source	medicare_silver.plan_crosswalks_annual
source	medicare_silver.monthly_contract_enrollment_summary
table	`medicare_silver.enrollment_monthly_county`
table	`medicare_silver.enrollment_monthly_plan`
table	`medicare_silver.plan_crosswalks_annual`
table	`medicare_silver.monthly_contract_enrollment_summary`

Known limits (0)

Known limits
none recorded

Admitted with a known defect
Its own demo call (Humana Inc., 2024, FL) took 41-46s on the first machine walk (run 35516039355, 2026-09-20) — past the 40s synchronous dispatch budget — so a customer asking the documented question gets a SCAN_LIMIT_EXCEEDED refusal rather than the number, not on every call but whenever the estate is cold. Since 2026-09-20 that refusal is a real envelope with a working route (the tool is now in ASYNC_HEAVY_TOOLS, so it names submit_query with the same arguments); before that it was a bare error object with no status at all. Making the sync path finish is the actual fix and it is not done.

Admitted with a known defect

Its own demo call (Humana Inc., 2024, FL) took 41-46s on the first machine walk (run 35516039355, 2026-09-20) — past the 40s synchronous dispatch budget — so a customer asking the documented question gets a SCAN_LIMIT_EXCEEDED refusal rather than the number, not on every call but whenever the estate is cold. Since 2026-09-20 that refusal is a real envelope with a working route (the tool is now in ASYNC_HEAVY_TOOLS, so it names submit_query with the same arguments); before that it was a bare error object with no status at all. Making the sync path finish is the actual fix and it is not done.

This page as markdown: /docs-md/tools/prove_ma_enrollment_trend.md · every page in one file: /llms-full.txt