insurance-coverage-summary - SKILL.md Agent Skill

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:

Use Coverage.order field if populated (1 = primary, 2 = secondary)
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:

fhir_search Coverage?patient=22334 -- returns 2 active Coverage resources
fhir_read Organization/[payor-id-1] -- Blue Cross Blue Shield
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: (800) 521-2227
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:

fhir_search Coverage?patient=55667 -- returns 3 Coverage resources (1 active, 1 expired still marked active, 1 cancelled)
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: (800) 872-3862
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:

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)