MCP Tools Reference

get_health_summary(days: int) → {steps, hrv_sdnn_ms, resting_heart_rate_bpm, sleep_hours, workout_count}

Overview of key metrics across a date range.

{
  "steps": 8432,
  "hrv_sdnn_ms": 52.1,
  "resting_heart_rate_bpm": 58,
  "sleep_hours": 7.3,
  "workout_count": 4
}

get_sleep(days: int) → [{date, duration_hours, rem_hours, core_hours, deep_hours, awake_hours, efficiency_pct}]

Per-night sleep stage breakdown.

[{
  "date": "2026-06-17",
  "duration_hours": 7.5,
  "rem_hours": 1.8,
  "core_hours": 4.2,
  "deep_hours": 1.1,
  "awake_hours": 0.4,
  "efficiency_pct": 94.7
}]

get_hrv_trend(days: int) → {daily: [{date, hrv_sdnn_ms}], trend_vs_prior_week_pct}

Daily HRV (SDNN) with trend delta vs prior period.

{
  "daily": [
    {"date": "2026-06-17", "hrv_sdnn_ms": 54.2},
    {"date": "2026-06-16", "hrv_sdnn_ms": 49.8}
  ],
  "trend_vs_prior_week_pct": 6.3
}

get_daily_snapshot(date: str) → {date, ...all metrics recorded that day}

All HealthKit samples recorded for a specific date.

{
  "date": "2026-06-15",
  "steps": 9241,
  "hrv_sdnn_ms": 51.4,
  "resting_hr_bpm": 57,
  "sleep_hours": 7.8,
  "active_calories": 612
}

get_workouts(days: int) → [{date, type, duration_min, distance_km, active_calories}]

Workout log with type and intensity metrics.

[{
  "date": "2026-06-17",
  "type": "Running",
  "duration_min": 42,
  "distance_km": 6.8,
  "active_calories": 487
}]

query_metric(metric_type: str, days: int) → [{timestamp, value, unit}]

Raw time series for any HKQuantityType identifier. See identifier table below.

[{
  "timestamp": "2026-06-17T07:14:22Z",
  "value": 48.3,
  "unit": "mL/kg/min"
}]

get_long_term_trend(metric_type: str, months: int) → [{month, avg_value, sample_count}]

Multi-year monthly aggregates. Automatically uses the summary data tier beyond 180 days for query efficiency.

[{
  "month": "2026-06",
  "avg_value": 51.8,
  "sample_count": 17
}]

get_coaching_brief() → {recovery_score, sleep_quality, training_load, recommendation}

Structured coaching context for AI agents. Suitable as a system prompt prefix or daily brief.

{
  "recovery_score": 78,
  "sleep_quality": "good",
  "training_load": "moderate",
  "recommendation": "Ready for intensity. HRV elevated vs baseline."
}

search_records(metric_type: str, threshold: float, operator: str, days: int) → [{date, value}]

Filter records by threshold. Answers "worst HRV days", "nights under 6h", "days over 10k steps".

[{"date": "2026-03-12", "value": 28.4},
 {"date": "2026-01-08", "value": 31.2}]

get_metric_stats(metric_type: str, days: int) → {mean, median, p10, p90, std_dev}

Your personal baseline and percentiles. Answers "is 42ms HRV good for me?"

{
  "mean": 52.1, "median": 51.4,
  "p10": 38.2,  "p90": 67.8,
  "std_dev": 9.3
}

compare_periods(metric_type: str, period_a_start: str, period_a_end: str, period_b_start: str, period_b_end: str) → {period_a, period_b, delta_pct, verdict}

Compare two date ranges with a plain-language verdict. Answers "did my sleep improve after I started lifting?"

{
  "period_a": {"avg": 6.8, "label": "before"},
  "period_b": {"avg": 7.4, "label": "after"},
  "delta_pct": 8.8,
  "verdict": "Improved"
}