Check Insurance Coverage

Overview

check_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.

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.
  • benefit_plan_name — the benefit plan display 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 — order of this coverage 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.

no_coverage_no_docs does not imply the patient lacks active coverage — it is also returned whenever a patient has active coverage but no policy documents have been ingested for them. Before telling the user no coverage was found, check is_active/status first, and only report no coverage if those are also negative.