Overview of key health metrics for the past N days. Returns avg steps, avg sleep, avg HRV, avg resting HR, workout count.

Sleep analysis for the past N days. Returns per-night breakdown with stage durations (REM, Deep/Core, Light, Awake).

HRV (SDNN) trend over the past N days. Returns daily averages, 7-day rolling comparison, and trend direction. Tier-aware: windows beyond 30 days transparently use daily summaries.

Time-series for any HealthKit metric type. metric_type: e.g. 'HKQuantityTypeIdentifierStepCount', 'HKQuantityTypeIdentifierHeartRate' Windows <= 30 days return raw samples; longer windows return daily aggregates (raw samples beyond 30 days are summarized and no longer stored individually).

Recent workouts with type, duration, distance, and calories.

Everything recorded for a specific date (YYYY-MM-DD). Defaults to today. Returns steps, sleep, workouts, HRV, resting HR, active energy, and all other metrics.

Long-term trend for any metric. Tier-aware: merges recent raw data (last 30 days, aggregated to daily) with historical daily summaries, so the trend has no recency gap. Best for multi-year / seasonal analysis. metric_type examples: HKQuantityTypeIdentifierHeartRateVariabilitySDNN, HKQuantityTypeIdentifierRestingHeartRate, HKQuantityTypeIdentifierBodyMass, HKQuantityTypeIdentifierStepCount months: how many months of history to return (default 24)

Pre-session coaching brief for Brett — combines recent trends across all key metrics. Returns a structured summary optimized for performance coaching context: recovery status, sleep quality, training load, and fitness trajectory. Call this at the start of every coaching session.

Find days where a health metric crossed a threshold. For cumulative metrics (steps, calories) filters on daily total. For rate metrics (HRV, heart rate) filters on daily average.

Examples:

• All days with HRV below 40ms: metric_type='HKQuantityTypeIdentifierHeartRateVariabilitySDNN', max_value=40

• Days with 10k+ steps: metric_type='HKQuantityTypeIdentifierStepCount', min_value=10000

• Nights under 6 hours sleep (360 min): metric_type='HKCategoryTypeIdentifierSleepAnalysis', max_value=360

Results sorted highest-to-lowest so outliers surface first.

Personal baseline statistics for any health metric. Returns min, max, mean, std dev, and percentile distribution (p10-p90).

Use to answer: 'Is today's reading good or bad for me personally?' Pair with get_daily_snapshot to compare today's value against your baseline.

The 'thresholds' field translates percentiles into plain English: good_day_above = your 75th percentile (a genuinely above-average day) poor_day_below = your 25th percentile (a below-average day worth noting)

Compare a health metric between two date ranges. Dates: YYYY-MM-DD.

Examples:

• Sleep before vs after starting magnesium: period_a = two weeks before, period_b = two weeks after

• HRV this month vs last month: period_a_start='2026-05-01', period_a_end='2026-05-31', period_b_start='2026-06-01', period_b_end='2026-06-18'

• Steps during a work trip vs home baseline

Returns per-period stats and a delta showing which period was better.