Validate Insurance Coverage

Overview

validate_insurance_coverage checks whether a patient has active insurance coverage and identifies which benefit plan(s) apply. Call this tool whenever a user asks anything about their insurance, coverage, benefits, copays, deductibles, or what they pay — it establishes which plan they have, whether coverage is currently active, and the coverage period, and this context is required before answering any plan-related question correctly (a plan question cannot be answered without naming the plan and its coverage period). Internally, the tool first checks whether any insurance policy documents exist for the patient, then queries FHIR Coverage resources to determine active coverage, combining both signals into a single result.

Optional Parameters

person_id (string)

• Default: None
• The identifier of the person whose insurance coverage is to be validated.
• If not provided, it is extracted from the caller's access token.

Returns

Returns a CoverageValidationResult with the following fields:

• is_active (boolean) — whether any coverage is confirmed active for this patient.
• status (string) — aggregate validation status: one of active, no_coverage_found, expired, or unknown.
• coverage_state (string) — a combined signal from coverage validation and document availability, used to determine disclaimer behavior: one of verified, unverified_docs_exist, expired_docs_exist, or no_coverage_no_docs.
• coverages (array) — all active Coverage resources found (up to 10), each with:
  • coverage_id — the FHIR Coverage resource ID.
  • benefit_plan_id — the benefit plan identifier from Coverage.class[type='plan'].value.
  • benefit_plan_name — the benefit plan display name from Coverage.class[type='plan'].name.
  • status — date-derived status for this specific coverage (active, no_coverage_found, expired, or unknown).
  • period_start — coverage effective date.
  • period_end — coverage termination date; None means ongoing coverage.
  • order — Coverage.order if present (1 = primary, 2 = secondary, etc.).
• warning (string, optional) — a human-readable warning to surface to the user, based on coverage_state. None when coverage_state is verified.

Notes

Routing based on the returned coverage_state:

• no_coverage_no_docs: stop here and inform the user that no coverage or documents were found. Do not call list_available_insurance_docs or search_insurance_policy.
• Any other value: proceed to list_available_insurance_docs to identify available policy documents.