# get_pbp_benefit Get PBP Benefit · v0.5.0 · medicare Returns Plan Benefit Package (PBP) benefit detail for an MA plan for a specific category (dental, inpatient_hospital, ER, etc.). Polymorphic — pass `category` to route to the right semantic view. All 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). Required: contract_id, plan_id, payment_year, category. The category must be one of the 35 live categories (listed below). The 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. Plus any methodology-shift caveats (e.g., 'B16 dental restructured CY2025' when querying dental for 2025+). Cross-year queries get cross-shift caveats. When 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. Live 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. The 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. The premium is `plan_premium` (not 'premium'), the deductible is `plan_deductible`, the out-of-pocket maximum is `moop`. `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. `summary.label` says which. Limits read in words ("6 visits every year"; 999 is CMS's unlimited sentinel and reads "unlimited"); the filed code is kept in `limit_text_raw`. A 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. One 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.** - `contract_id` (required): - `plan_id` (required): - `payment_year` (required): - `category` (required): - `segment_id`: **Known limits.** - PBP-PK-PRE-2010 - PBP-QUARTERLY-PRE-2018 **A real answer** (customer seat, 0.12 s, args `{"contract_id":"H0028","plan_id":"014","segment_id":"0","payment_year":2026,"category":"health_professionals"}`): ```json { "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 ... (truncated) ``` REST: `POST https://api.vladahealth.com/v1/tools/get_pbp_benefit` with the inputs as the JSON body. MCP: the tool by name.