Retrieve health and insurance data

Start with the patient summary, read one record type, or call a specialized tool; then answer coverage and claims questions

These tools answer the user's questions from the records they've connected through health.network: their health record, their device data, and their insurance coverage, policy documents, and claims.

Before you start

The tools on this page only read. They return the user's records once a data source has connected and finished retrieving; see Search, connect, and manage data connections. MCP server reference shows how an empty result, a partial read, and a failed call each look.

Health records

Start with the patient summary

get_patient_summary returns the user's International Patient Summary (IPS) as Markdown, one heading per section, such as the problem list, medications, and allergies. It's the best first call for a broad question, such as "Give me a summary of my health." Pass only the sections the question needs in include_sections, because a full summary can be large.

Read one kind of record

When the question is about one kind of record, call get_fhir_record once per FHIR resource type, such as MedicationRequest with active_only: true for current medications. It also reaches older records. The summary's Medication Summary and Results Summary sections cover only the past 2 years, with one result per lab test. When a response's meta.has_more is true, call again with the arguments in meta.next_call.

Call a specialized tool for a direct question

When a filter or format matters, a specialized tool answers in one call.

ToolUse it for
get_labsSpecific lab tests or panels, with trends
get_vitalsVital signs from the health record
get_wearables_summaryWearable and fitness tracker data
get_health_scoresBody system scores computed from wearable data
search_clinical_notesText inside clinical notes
list_document_references, then get_document_reference_contentA document, such as a discharge summary
get_assigned_care_needsScreenings, vaccines, and checkups that are due, where enabled for your client
get_medication_knowledgeWhat a medication is, its warnings, or its dosing
get_record_changesWhat's new in the record since a given time

Insurance

What the plan covers comes from the user's policy documents, and what the user was billed or paid comes from their claims.

Check coverage first

Call check_insurance_coverage. It returns the user's plans and a coverage_state that decides the next step. When it's no_coverage_no_docs, there are no policy documents to search, so tell the user that no policy documents are on file instead of searching. That state doesn't mean the user has no coverage. When it's unverified_docs_exist or expired_docs_exist, show the user the warning with your answer.

Answer coverage questions from the policy

  1. Call list_available_insurance_docs with the plan's benefit_plan_id. To name a passage's source in the answer, match the passage's meta.chunk_group_id to a document's chunk_group_id.
  2. Call search_insurance_policy with the coverage topic as search_text, such as "copay for specialist visits", rather than the user's whole message. The search covers every policy document the user has.
  3. When a passage starts or ends mid-sentence, call search_policy_context to read the chunks around it before you answer.

Answer cost questions from claims

Call get_claims for what was billed, what the plan paid, and what the user owes. Without start_date or another filter, it returns only the last 12 months, so pass an earlier start_date for older claims.

Guide the model

The base guidance covers health-record questions. When your assistant also answers coverage and cost questions, add these points if your host accepts your own instructions. They reinforce the tool descriptions and don't replace them.

  • For coverage questions, call check_insurance_coverage first and follow its coverage_state. When there are no policy documents, say so instead of searching, and don't say the user has no coverage.
  • Search policy documents with a short coverage topic, such as "copay for specialist visits", not the user's whole message, and say which plan and document the answer comes from.
  • For cost questions, use get_claims, and pass an earlier start_date for claims older than the default window.

Did this page help you?