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. check_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. Results include chunk_group_id and chunk_index in each note's metadata; if a returned chunk appears incomplete, call search_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. The meta object includes chunk_group_id, chunk_index, total_chunks, note_category, and note_type — chunk_group_id and chunk_index are needed to call search_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, error, urls, and meta.

Notes

When composing an answer from the returned passages:

• State the plan name (benefit_plan_name from check_insurance_coverage) and coverage period at the top of the response.
• Include the document title. If it is generic, call search_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.