Get Health Scores

Overview

get_health_scores retrieves pre-computed body system health scores — a 0-100 rating of health in specific body systems, derived from wearable device data by b.well's Health Scoring Framework. An agent should call this tool when the user asks about an overall health score, a specific body system score (cardiovascular, sleep, respiratory, musculoskeletal), whether their health is improving or worsening, what's dragging a score down, or how to improve a score. It returns an overall score, per-system scores with component breakdowns, trend direction, daily score history, and personalized recommendations.

This tool returns computed scores, not raw metrics. For raw wearable data (heart rate, steps, sleep duration), use get_wearables_summary instead. For clinical vitals from doctor visits, use get_vitals.

Optional Parameters

person_id (string)

• Default: None
• The FHIR identifier (patient ID) of the person whose health scores are to be retrieved. If not provided, the tool attempts to extract the patient ID from the user's access token.

body_systems (list of string)

• Default: None
• Optional list of body systems to retrieve scores for. Valid options: cardiovascular, sleep, respiratory, musculoskeletal. If not specified, all available body system scores are returned.

start_date (date)

• Default: None
• The earliest date (inclusive) to include health score records. Format: YYYY-MM-DD.

end_date (date)

• Default: None
• The latest date (inclusive) to include health score records. Format: YYYY-MM-DD.

count (integer)

• Default: 10
• Number of records to fetch.

debug (boolean)

• Default: False
• Enable debug mode to include additional diagnostic information in the response.

output_formats (list of string)

• Default: ["scores_summary"]
• List of output formats for the health score data. Options: scores_summary, trend_view, contextual_interpretation. Multiple formats can be requested at once.

ignore_cache (boolean)

• Default: False
• If true, bypasses any cached data and fetches fresh records from the FHIR server.

Returns

Returns a result object containing:

• result — the formatted health score text (or an error/no-data message if no health score data was found for the patient). When output_formats includes scores_summary, this contains the overall health score, its letter grade, and a per-body-system breakdown (score, tier, weight, and completeness). Score tiers are derived from the numeric score: 90-100 Excellent, 75-89 Good, 60-74 Fair, below 60 Poor.
• error — an error message if retrieval failed.
• urls — the FHIR server URLs queried, included only when debug is true.
• meta — retrieval metadata, including records_returned, record_limit, record_limit_reached, and from_cache.
• debug — additional diagnostic detail, included only when debug is true.

Underlying score data (per body system) includes: score, letter grade, calculation date, weight, data quality, whether the score is complete, scored/missing components, component-level breakdowns, daily score history, and recommendations.

Notes

Scores are sourced from FHIR Composition resources (Tier 1: overall health summary; Tier 2: per-body-system summaries) rather than computed on the fly. If no wearable device is connected, or if one was recently connected, the tool returns a message noting that scores may take up to 24 hours to appear after initial data sync.