insurance-coverage-summary

name	insurance-coverage-summary
description	Retrieves and analyzes FHIR Coverage and Organization resources to produce a structured insurance summary with coordination of benefits analysis. Use when user asks to "check insurance", "coverage details", "verify coverage", "insurance summary", "what plan is the patient on", "primary vs secondary insurance", or "coverage status". Do NOT use for clinical data, demographics beyond insurance, or billing claim submission.
metadata	{"author":"LangCare","version":"1.0.0","mcp-server":"langcare-mcp-fhir","category":"patient-data"}

Insurance Coverage Summary

Overview

Pull Coverage and Organization resources to produce a consolidated insurance summary. Identify primary and secondary coverage, extract plan details, policy and group numbers, coverage periods, and payor organizations. Flag expired coverage, missing authorization data, coverage gaps, and coordination of benefits issues. Output a structured summary suitable for front-desk verification, prior authorization workflows, or care coordination.

FHIR Resources Used

Resource	Purpose	Search Parameters
Coverage	Insurance plan details	patient, status
Organization	Payor/insurer details	Direct read by reference
Patient	Subscriber info, managing org	Direct read by ID
RelatedPerson	Subscriber if not self	Direct read by reference

Instructions

Step 1: Pull All Coverage Resources

Tool: fhir_search
resourceType: "Coverage"
queryParams: "patient=[patient-id]"

Retrieve all Coverage resources regardless of status to capture full history. For each entry extract:

• status: active, cancelled, draft, entered-in-error
• type: Coverage type from type.coding (system http://terminology.hl7.org/CodeSystem/v3-ActCode)
• policyHolder: Reference to the policyholder (may be Patient, RelatedPerson, or Organization)
• subscriber: Reference to the subscriber
• subscriberId: Subscriber ID / Member ID
• beneficiary: Reference to the patient
• dependent: Dependent number
• relationship: Subscriber-to-beneficiary relationship (self, spouse, child, other)
• period: Coverage effective period (start and end dates)
• payor: Reference to the insurance Organization
• class[]: Coverage classification array, each with:
  • type.coding.code: "group", "subgroup", "plan", "subplan", "class", "subclass", "sequence", "rxbin", "rxpcn", "rxid", "rxgroup"
  • value: The identifier value
  • name: Human-readable name
• order: Coverage order (1 = primary, 2 = secondary, 3 = tertiary)
• network: Network name or identifier
• costToBeneficiary[]: Copay and coinsurance information
  • type.coding.code: "copay", "coinsurance", "deductible"
  • valueMoney or valueQuantity

Step 2: Resolve Payor Organizations

For each Coverage resource, resolve the payor reference:

Tool: fhir_read
resourceType: "Organization"
id: "[payor-reference-id]"

Extract from the Organization:

• name: Insurance company name
• telecom: Phone number, website
• address: Mailing address
• identifier: NPI, Tax ID, payer ID
• type: Insurance company type classification

Step 3: Determine Coverage Hierarchy

Establish primary vs secondary coverage:

1. Use Coverage.order field if populated (1 = primary, 2 = secondary)
2. If order is absent, apply coordination of benefits rules:
   • Self-employed / Individual: The patient's own employer plan is primary
   • Spouse coverage: Apply Birthday Rule for dependent children (plan of parent whose birthday falls earlier in calendar year is primary)
   • Medicare: Medicare is primary when patient is 65+ with no employer group health plan (EGHP) for 20+ employees. Medicare is secondary when patient has EGHP coverage.
   • Medicaid: Almost always secondary (payer of last resort)
   • Workers' Compensation: Primary for work-related injuries/illnesses
   • Auto Insurance / Liability: Primary for accident-related claims

Step 4: Validate Coverage Status

For each Coverage resource, check:

Active Coverage Validation:

• status = "active"
• period.start <= today
• period.end is null OR period.end >= today
• subscriberId is populated
• payor reference resolves to a valid Organization

Flag: Expired Coverage

• period.end < today but status still = "active"
• Flag: "Coverage [plan name] has end date [date] in the past but status is still active. Verify with payor."

Flag: Missing Subscriber ID

• subscriberId is null or empty
• Flag: "Coverage [plan name] is missing subscriber/member ID. Required for claims submission."

Flag: Missing Group Number

• No class entry with type = "group"
• Flag: "Coverage [plan name] is missing group number."

Flag: No Primary Coverage

• Zero Coverage resources with order = 1 or no active coverage at all
• Flag: "No primary insurance coverage identified. Verify coverage status with patient."

Flag: Dual Coverage Without Coordination

• Multiple active coverages but order field not set on any
• Flag: "Multiple active coverages found but primary/secondary order not specified. Coordination of benefits determination required."

Step 5: Extract Benefit Details (If Available)

Check for cost-to-beneficiary information:

• Copay amounts per visit type
• Coinsurance percentages
• Deductible amounts (individual and family)
• Out-of-pocket maximum

Note: Most FHIR servers do not populate costToBeneficiary in Coverage resources. If absent, note: "Benefit details not available in FHIR record. Verify with payor or eligibility check system."

Step 6: Check for Related Authorization References

Tool: fhir_search
resourceType: "Claim"
queryParams: "patient=[patient-id]&status=active&_count=5&_sort=-created"

If Claim resources are available, check for:

• insurance[].coverage: References to Coverage resources
• insurance[].preAuthRef: Prior authorization numbers
• insurance[].focal: Which coverage is primary for this claim

If no Claim resources, skip this step.

Step 7: Format Output

INSURANCE COVERAGE SUMMARY
============================
Patient: [name] ([patient-id])
Reviewed: [timestamp]
Total Coverage Records: [count] ([active count] active)

PRIMARY COVERAGE
================
Plan: [plan name from class]
Insurer: [Organization name]
Insurer Phone: [telecom]
Member ID: [subscriberId]
Group: [group class value] / [group class name]
Subscriber: [subscriber relationship] - [subscriber name if not self]
Network: [network]
Effective: [period.start] - [period.end or "Ongoing"]
Status: Active

Benefit Details (if available):
  Copay: $[amount] per [visit type]
  Coinsurance: [percentage]%
  Deductible: $[amount] (Individual) / $[amount] (Family)
  Out-of-Pocket Max: $[amount]

SECONDARY COVERAGE
==================
Plan: [plan name]
Insurer: [Organization name]
Member ID: [subscriberId]
Group: [group class value]
Effective: [period.start] - [period.end or "Ongoing"]
Status: Active

EXPIRED / INACTIVE COVERAGE
============================
1. [Plan name] - Expired: [period.end] - Status: [status]
   (Retained for historical reference)

FLAGS
=====
[!] [Any flagged issues from Step 4]

COORDINATION OF BENEFITS
=========================
Primary: [plan name] (Order: 1)
Secondary: [plan name] (Order: 2)
Determination method: [Coverage.order field / Birthday Rule / Medicare rules]

Examples

Example 1: Dual Coverage With Clear Hierarchy

User says: "What insurance does patient 22334 have?"

Actions:

1. fhir_search Coverage?patient=22334 -- returns 2 active Coverage resources
2. fhir_read Organization/[payor-id-1] -- Blue Cross Blue Shield
3. fhir_read Organization/[payor-id-2] -- Medicare

Result:

INSURANCE COVERAGE SUMMARY
============================
Patient: Margaret Thompson (22334)
Reviewed: 2026-02-07T09:00:00Z
Total Coverage Records: 2 (2 active)

PRIMARY COVERAGE
================
Plan: Blue Cross Blue Shield PPO
Insurer: Blue Cross Blue Shield of Texas
Insurer Phone: [phone]
Member ID: XYZ123456789
Group: GRP-88901 / Acme Corporation Employee Plan
Subscriber: Self
Network: PPO National
Effective: 2025-01-01 - 2025-12-31
Status: Active

SECONDARY COVERAGE
==================
Plan: Medicare Part B
Insurer: Centers for Medicare & Medicaid Services
Member ID: 1EG4-TE5-MK72
Group: N/A
Subscriber: Self
Effective: 2023-08-01 - Ongoing
Status: Active

COORDINATION OF BENEFITS
=========================
Primary: Blue Cross Blue Shield PPO (Order: 1)
  Reason: Patient has active employer group health plan (EGHP).
  Medicare is secondary when EGHP coverage exists.
Secondary: Medicare Part B (Order: 2)

Example 2: Coverage Issues Detected

User says: "Check insurance for patient 55667"

Actions:

1. fhir_search Coverage?patient=55667 -- returns 3 Coverage resources (1 active, 1 expired still marked active, 1 cancelled)
2. fhir_read Organization/[payor-id] -- Aetna

Result:

INSURANCE COVERAGE SUMMARY
============================
Patient: Kevin Nguyen (55667)
Reviewed: 2026-02-07T09:15:00Z
Total Coverage Records: 3 (1 truly active)

PRIMARY COVERAGE
================
Plan: Aetna HMO
Insurer: Aetna Inc.
Insurer Phone: [phone]
Member ID: W123456789
Group: 0012345 / State University Health Plan
Subscriber: Self
Network: HMO Open Access
Effective: 2025-09-01 - 2026-08-31
Status: Active

EXPIRED / INACTIVE COVERAGE
============================
1. United Healthcare PPO - Status shows "active" but period ended 2025-08-31
   -> DATA QUALITY ISSUE: Status not updated to reflect termination
2. Medicaid - Status: Cancelled - Ended: 2025-08-31

FLAGS
=====
[!] EXPIRED COVERAGE NOT UPDATED: United Healthcare PPO (Coverage/cov-002) has
    period.end = 2025-08-31 but status remains "active". Update to "cancelled".
[!] SINGLE COVERAGE ONLY: No secondary insurance identified.
[!] MISSING BENEFIT DETAILS: No copay, coinsurance, or deductible data in
    FHIR record. Contact Aetna for benefit verification.

RECOMMENDATION
==============
Update Coverage/cov-002 status to reflect expiration:
  Tool: fhir_update
  resourceType: "Coverage"
  id: "cov-002"
  resource: { "status": "cancelled", ... }

Example 3: No Coverage Found

User says: "Does patient 99888 have insurance?"

Actions:

1. fhir_search Coverage?patient=99888 -- returns 0 entries

Result:

INSURANCE COVERAGE SUMMARY
============================
Patient: Carlos Mendez (99888)
Reviewed: 2026-02-07T09:30:00Z
Total Coverage Records: 0

FLAGS
=====
[!] NO INSURANCE COVERAGE ON FILE
    No Coverage resources found for this patient. This may indicate:
    - Self-pay / uninsured patient
    - Coverage data not yet entered
    - Coverage stored in a different system not connected to this FHIR server

RECOMMENDATION
==============
1. Verify insurance status with patient
2. Check if coverage is documented in the practice management system
3. Screen for Medicaid/marketplace eligibility if uninsured
4. Document self-pay status if confirmed uninsured

Troubleshooting

Coverage Resources Lack Class Details (No Plan Name, No Group Number)

• Some EHR systems store minimal coverage data. The class array may be empty.
• Check type field for coverage type (HMO, PPO, Medicare, Medicaid).
• Resolve the payor Organization reference -- the organization name may be the only plan identifier available.
• For EPIC systems, coverage details may be in extensions rather than standard class elements.

Multiple Coverage Resources With Same Payor

• This can happen when coverage is renewed annually and each period creates a new Coverage resource.
• Deduplicate by checking period overlap. The most recent non-expired Coverage is the current one.
• If periods overlap with the same payor and plan, take the one with the later period.start.

Coverage.order Not Populated

• Many FHIR servers do not populate the order field.
• Apply coordination of benefits rules from Step 3 to determine primary vs secondary.
• If determination is ambiguous, flag for manual review: "Unable to determine primary vs secondary coverage programmatically. Manual coordination of benefits determination required."

Related Skills

• patient-demographics-summary -- for complete demographics including insurance at a high level
• clinical-summary-generator -- for full clinical summary (does not include insurance details)