get_pbp_benefit

What it answers

1. 1Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.).
2. 2Polymorphic — pass `category` to route to the right semantic view.
3. 3All categories share the standard envelope: cost_share_string, copay_amount, coinsurance_pct, limit_text, auth_required, referral_required, network_type, max_oop_applies + category-specific extension fields (e.g., dental_sub_benefit).
4. 4Required: contract_id, plan_id, payment_year, category.
5. 5The category must be one of the 35 live categories (listed below).
6. 6The response `value` is the full benefit-detail object: `rows` (every matched benefit row, with cost sharing, limits, and category extension fields), `row_count`, the resolved `category`/`human_label`/`view_fqn`, the `audit_chain` (CMS source URL + sha256 per row), and a `summary` sub-field carrying the single-row headline cost_share_string (or the row count when multiple sub-benefit rows match) for a quick read.
7. 7Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+).
8. 8Cross-year queries get cross-shift caveats.
9. 9When the full answer would not fit in one response, `rows` come back compact (`row_format: "compact"`): fields identical on every row sit once in `row_common`, and a field absent from a row is null.
10. 10Live categories are discovered from the contract registry at load time, so this list cannot drift from what the tool serves; an unknown category is refused (INVALID_INPUT) with this same list, never a failure.
11. 11The 35 live categories are: ambulance, b19_combined_package, cardiac_pulmonary_rehab, clinical_diagnostic_therapeutic, combined_supplemental, dental, dme, dsnp_cost_share, emergency_urgent, health_professionals, hearing, home_health, inpatient_hospital, inpatient_psychiatric, meals, moop, optional_package, otc, outpatient_hospital, partb_rx_drugs, partd_drugs, partd_tier, partial_hospitalization, plan_deductible, plan_premium, preventive, prior_auth_referral, renal_dialysis, section_c_pos_oon, snf, ssbci, supplemental_other, supplemental_services, transportation, vision.
12. 12The premium is `plan_premium` (not 'premium'), the deductible is `plan_deductible`, the out-of-pocket maximum is `moop`.
13. 13`summary.value` is the one number a reader asks for: for plan_premium the monthly premium in USD; for plan_deductible the in-network annual deductible in USD (or null with the filed reason); for moop the in-network annual MOOP in USD, which on a D-SNP is the plan design before Medicaid and Extra Help, never what a dual pays.
14. 14`summary.label` says which.
15. 15Limits read in words ("6 visits every year";
16. 16999 is CMS's unlimited sentinel and reads "unlimited"); the filed code is kept in `limit_text_raw`.
17. 17A contract/plan/year/category combination with NO rows is REFUSED with code NO_DATA, not answered with an empty complete: the refusal states what was searched and routes to get_landscape (the plan ids that really exist for that contract and year) and names the valid categories.
18. 18One view is read, so a nonexistent plan and a plan with nothing in this category cannot be told apart here; the refusal says so.

Inputs (5)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
get_pbp_benefit(contract_id="H0028", plan_id="014", segment_id="0", payment_year=2026, category="health_professionals")

curl -X POST https://api.vladahealth.com/v1/tools/get_pbp_benefit \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"H0028","plan_id":"014","segment_id":"0","payment_year":2026,"category":"health_professionals"}'

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

A real answer

{
 "value": {
  "category": "health_professionals",
  "human_label": "Health professional visits (PCP + Specialist)",
  "contract_id": "H0028",
  "plan_id": "014",
  "payment_year": 2026,
  "segment_id": "0",
  "semantic_emulator": {
   "emulator_id": "pbp_semantic_emulator",
   "policy_id": "pbp_semantic_policy",
   "policy_version": 1,
   "policy_status": "locked_for_next_category_gate",
   "required_output_fields": [
    "offered_status",
    "numeric_amount_observability",
    "null_amount_reason",
    "annualization_policy",
    "combined_limit_policy",
    "consumer_document_reconciliation_status",
    "confidence_tier"
   ],
   "semantic_danger_audit_required_steps": [
    "source_surface_audit",
    "offered_policy",
    "amount_policy",
    "timing_policy",
    "combined_limit_policy",
    "moop_policy",
    "geography_enrollment_policy",
    "cross_document_policy",
    "required_agent_fields",
    "caveat_policy"
   ],
   "hard_rule_ids": [
    "null_numeric_not_zero",
    "explicit_zero_is_data",
    "offered_and_numeric_are_separate",
    "no_unsafe_rollups",
    "preserve_raw_timing",
    "bridge_moop",
    "source_fidelity_not_consumer_truth"
   ],
   "category_id": "health_professionals",
   "benefit_risk_matrix_entry": {
    "onboarded": true,
    "onboarded_scope_version": 1,
    "source_family": "B7 professional services including PCP, specialist, therapies, Medicare-covered podiatry, and atomic routine-podiatry supplemental cost share/frequency",
    "core_risks": [
     "PCP and specialist visit cost share filed as MIN/MAX bands \u2014 multi-tier-network plans differ between min and max. Canonical copay_amount = mc_min.",
     "specialist referral_required flag varies plan-by-plan; many PPOs allow direct specialist access (referral_required=false).",
     "Routine podiatry is a supplemental B7F stripe with its own offered flag, cost share, and visit periodicity; it must not be merged with Medicare-covered podiatry.",
     "Routine-podiatry visit counts may be annualized only from known CMS periodicity codes; an unknown period stays null.",
     "Pre-2018 single-value copay encoding (without _min/_max suffix) is glob-out; affects historical analysis only."
    ],
    "v1_caveats": [
     "Remaining B7 services and deeper variants, including chiropractic, SUD, and opioid-treatment detail, are deferred.",
     "In-area non-Medicare-covered (IA NUC) cost share variants on B7A deferred to v2.",
     "B7C medical-management (mm) auth/coins/copay variants deferred to v2."
    ],
    "required_bridges": [
     "moop_service_category",
     "service_area",
     "enrollment_member_months"
    ]
   }
  },
  "rows": [
   {
    "contract_id": "H0028",
    "plan_id": "014",
    "segment_id": "0",
    "version": 3.0,
    "report_year": 2026.0,
    "quarter": 1.0,
    "benefit_category": "health_professionals",
    "cost_share_string": "$0 copay",
    "copay_amount": 0.0,
    "coinsurance_pct": null,
    "limit_text": null,
    "auth_required": null,
    "referral_required": null,
    "network_type": "in_network",
    "max_oop_applies": null,
    "limit_quantity": null,
    "limit_unit": null,
    "limit_period_code": null,
    "limit_period_label": null,
    "limit_quantity_per_year": null,
    "benefit_amount": null,
    "benefit_amount_kind": null,
    "benefit_amount_period_code": null,
    "benefit_amount_period_label": null,
    "benefit_amount_annualized": null,
    "benefit_amount_pmpm": null,
    "normalization_status": null,
    "normalization_basis": null,
    "aggregation_policy": null,
    "offered_status": "offered",
    "numeric_amount_observability": "all_offered_numeric",
    "null_amount_reason": "not_null_numeric_amount",
    "annualization_policy": "preserve_raw_only",
    "combined_limit_policy": "none_detected",
    "consumer_document_reconciliation_status": "not_checked",
    "confidence_tier": "source_faithful",
    "benefit_layer": "medicare_covered",
    "benefit_unlimited": null,
    "coinsurance_pct_max": null,
    "coinsurance_pct_min": null,
    "copay_amount_max": 0.0,
    "copay_amount_min": 0.0,
    "deductible_amount": null,
    "deductible_basis": "no_service_specific_deductible",
    "filed_service_name": null,
    "has_coinsurance": false,
    "has_copay": true,
    "has_deductible": false,
    "has_max_enrollee_oop": false,
    "health_professionals_offered": null,
    "health_professionals_sub_benefit": "primary_care",
    "label_note": "7a Medicare-covered primary care physician visit.",
    "limit_period_text": null,
    "max_enrollee_oop_amount": null,
    "max_enrollee_oop_period_code": null,
    "max_enrollee_oop_period_label": null,
    "max_enrollee_oop_period_text": null,
    "max_plan_benefit_amount": null,
    "max_plan_benefit_offered": null,
    "max_plan_benefit_period_code": null,
    "max_plan_benefit_period_label": null,
    "registry_l2_id": "7a",
    "routine_chiropractic_unlimited": null,
    "routine_podiatry_offered": null,
    "routine_podiatry_unlimited": null,
    "routine_podiatry_visit_count": null,
    "routine_podiatry_visit_period_code": null,
    "routine_podiatry_visit_period_label": null,
    "routine_podiatry_visits_per_year": null,
    "supplemental_benefit_type": null,
    "telehealth_service_categories": null,
    "source_pbp_section": "B7A",
    "lmi_authorities": "https://mabenefitsmailbox.lmi.org/MABenefitsMailbox/S3Browser/GetFile?path=CY%202026%20PBP%20Service%20Category%20Descriptions.pdf|https://mabenefitsmailbox.lmi.org/MABenefitsMailbox/S3Browser/GetFile?path=Final%20CY%202026%20Part%20C%20Bid%20Review%20Memorandum%20and%20Appendix-4-15-25.pdf",
    "source_url": "https://www.cms.gov/files/zip/pbp-benefits-2026.zip",
    "sha256_content_hash": "1720048e668f6c9e4abc47c512e537c013600de12860d28aea4f8308b5e51de4",
    "source": "filing",
    "served_from": "filing",
    "evidence_grade": "cms_filed",
    "as_of": "CY2026 plan benefit filing, Q1 2026 release"
   },
   {
    "contract_id": "H0028",
    "pl
…

What comes back

Sources

Known limits (2)

1. 1PBP-PK-PRE-2010
2. 2PBP-QUARTERLY-PRE-2018