Search Insurance Policy

Overview

search_insurance_policy searches insurance policy documents (Summary of Benefits, Evidence of Coverage, plan booklets, etc.) using semantic similarity, and returns raw policy passages. Internally, it filters to notes with note_category set to "Insurance Policy". These passages are only meaningful once the plan context has been established: validate_insurance_coverage (to identify the plan name and coverage period) and list_available_insurance_docs (to identify the document and obtain its chunk_group_id) must be called first in the conversation — without that prior context, the returned passages cannot be correctly attributed to a plan or verified as current, and this tool should not be called first. Results include chunk_group_id and chunk_index in each note's metadata; if a returned chunk appears incomplete (starts mid-sentence, references a section header not visible, or mentions exclusions that continue beyond the chunk), call explore_policy_context with the chunk_group_id and an index range around the matched chunk_index to retrieve surrounding context before answering.

Required Parameters

search_text (string)

• Text describing the insurance topic to search for (e.g., "copay for surgery", "deductible", "out-of-network coverage").

Optional Parameters

person_id (string)

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

start_date (date)

• Default: None
• The earliest date (inclusive) for filtering policy documents. Format: YYYY-MM-DD.

end_date (date)

• Default: None
• The latest date (inclusive) for filtering policy documents. Format: YYYY-MM-DD.

number_of_notes (integer)

• Default: 10
• Number of top matching policy chunks to return.

use_similarity_search (boolean)

• Default: True
• If True, performs semantic similarity search. If False, uses traditional keyword search.

debug (boolean)

• Default: False
• Whether to display debugging information.

Returns

Returns a FhirNotesSearchOutput with the following fields:

• notes (array) — matching policy chunks as FhirNote objects, each with note_id, patient_id, text, data_availability_reason, data_availability_message, and meta. If a note's text is unavailable, text contains an explanatory message instead of policy content. The meta object includes (among other fields) chunk_group_id, chunk_index, total_chunks, note_category, and note_type — chunk_group_id and chunk_index are needed to call explore_policy_context for surrounding context.
• query (string, optional) — the search query used to find the notes; only populated when debug is True.

FhirNotesSearchOutput also inherits common result fields: result (summary text), error (error message, e.g. when no insurance policy documents are found for the given search criteria, or when no patient records exist for the user), urls, and meta.

Notes

When composing an answer from the returned passages:

• State the plan name (benefit_plan_name from validate_insurance_coverage) and coverage period (period_start through period_end) at the top of the response — the tool description treats this as a hard obligation, since a plan question cannot be answered correctly without naming the plan and its coverage period.
• Include the document title. If it is generic (e.g. just "Summary of Benefits and Coverage"), call explore_policy_context with start_index=0, end_index=1 to read the document header for the actual plan name.
• Quote relevant policy language when possible.
• Always append a reminder for the user to verify this is their current active policy.