---

name: garmin-cli description: Extract health, activity, workout, and performance data from Garmin Connect. Use when users need Garmin fitness data including sleep, HRV, weight, stress, activities, workouts, and performance metrics. argument-hint: [command] [options] allowed-tools: Bash

garmin-cli

Extract health, activity, workout, and performance data from Garmin Connect.

Prerequisites

• Python 3.10+
• Install: pip install garmin-py (or pip install . from a repo checkout)
• Authentication: run garmin-cli login, or use a saved session at ~/.garminconnect, or set env vars GARMIN_EMAIL / GARMIN_PASSWORD

Agent Usage

Always use --json for machine-readable output. The tool returns a JSON envelope on stdout with exit code 0 (success) or 1 (error).

Success envelope

{
  "ok": true,
  "command": "<group> <subcommand>",
  "date_range": null,
  "count": 7,
  "data": [...]
}

date_range is null for commands that are not scoped to a date range. When a command is date-scoped, it is an object with from and to ISO dates.

Error envelope

{
  "ok": false,
  "command": "<group> <subcommand>",
  "error": "Human-readable message",
  "error_code": "RATE_LIMITED"
}

Error codes

| Code | Meaning | Retry? | |------|---------|--------| | AUTH_MISSING | No credentials or session found | No -- configure auth | | AUTH_FAILED | Credentials rejected | No -- fix credentials | | MFA_REQUIRED | Garmin sent a one-time MFA code | Ask the user for the code, then submit_mfa_code (MCP) or garmin-cli login (CLI) | | NOT_FOUND | Endpoint returned 404 | No | | RATE_LIMITED | 429 after 3 retries | Yes -- wait and retry | | SERVER_ERROR | 5xx after 3 retries | Yes -- wait and retry | | INVALID_INPUT | Bad arguments or conflicting options | No -- fix arguments | | INTERNAL_ERROR | Unexpected error, including uncategorized connection/timeout failures | Maybe |

Commands

Date range options (health range commands + workout calendar)

| Option | Effect | Example | |--------|--------|---------| | --date YYYY-MM-DD | Single day | --date 2026-03-11 | | --days N | Past N days (inclusive of today) | --days 7 | | --from YYYY-MM-DD --to YYYY-MM-DD | Explicit range (both inclusive) | --from 2026-03-01 --to 2026-03-07 | | --ahead N | Next N days (workout calendar only) | --ahead 7 | | (none) | Defaults to today | |

Max range: 90 days. Conflicting options produce INVALID_INPUT.

---

Health

All health commands except health status accept the shared date range options. health status only accepts --date and defaults to today.

# Sleep -- fields: date, bedtime, wake_time (local ISO), duration_hours, deep_min, light_min, rem_min, awake_min, score
garmin-cli --json health sleep --days 7

# HRV -- fields: date, weekly_avg, last_night, status
garmin-cli --json health hrv --date 2026-03-11

# Weight -- fields: date, weight_kg, bmi, body_fat_pct
garmin-cli --json health weight --days 30

# Body battery -- fields: date, start_level, end_level, max_level (intraday peak); single ranged API call
garmin-cli --json health body-battery --days 7

# Stress -- fields: date, avg_stress, max_stress
garmin-cli --json health stress --days 7

# SpO2 -- fields: date, avg_spo2, lowest_spo2
garmin-cli --json health spo2 --days 7

# Resting heart rate -- fields: date, resting_hr
garmin-cli --json health resting-hr --days 7

# Training readiness -- fields: date, score, level
garmin-cli --json health readiness --days 7

# Training status (single day only) -- Garmin's full training-load picture:
# fields: date, training_status, acute_load, chronic_load, acwr, acwr_status,
# load_tunnel_min/max, monthly_load_aerobic_low/high, monthly_load_anaerobic,
# aerobic_low/high_target_min/max, anaerobic_target_min/max, load_balance_status
garmin-cli --json health status --date 2026-03-11

# Steps -- fields: date, total_steps, total_distance, step_goal
garmin-cli --json health steps --days 7

# Daily summary -- fields: date, total_steps, distance_km, calories, floors, moderate_intensity_minutes, vigorous_intensity_minutes, resting_hr
# Note: one API call per day — large ranges may be slow
garmin-cli --json health daily-summary --days 7

# Intensity minutes -- fields: date, moderate_value, vigorous_value, weekly_goal
garmin-cli --json health intensity-minutes --days 7

Activities

# List recent activities -- fields: id, date, name, type, distance_km, duration_min, avg_hr, training_load
garmin-cli --json activity list --limit 10
garmin-cli --json activity list --limit 10 --type running
garmin-cli --json activity list --limit 10 --search "morning run"
garmin-cli --json activity list --from 2026-03-01 --to 2026-03-31
garmin-cli --json activity list --days 7

# Get a single activity by ID -- same fields as list
garmin-cli --json activity get 12345678901

# Sport-aware detail. Cycling rides surface power suite (avg/max/normalized,
# TSS, IF); running activities surface cadence_spm, GCT, vertical
# oscillation/ratio, stride length, training effect; pool swims surface
# SWOLF, total strokes, average stroke rate, distance per stroke. JSON
# uses a stable union schema -- every key present (null for sport-
# inapplicable). Includes a top-level `unavailable` array when any
# registry-known metric is not produced.
garmin-cli --json activity get 12345678901 --detail

# Detail + lap data in one envelope (--laps appends `laps` array).
# Pool-swim activities auto-route to per-pool-length rows.
garmin-cli --json activity get 12345678901 --detail --laps

# Lap-by-lap data (run/bike) or per-pool-length data (lap_swimming)
garmin-cli --json activity laps 12345678901

# HR time-in-zone breakdown -- fields: zone, zone_low_bpm, zone_high_bpm, seconds_in_zone, minutes_in_zone
garmin-cli --json activity zones 12345678901

# Weather for an activity -- fields: temperature, apparent_temp, dew_point, humidity, wind_speed, wind_gust, wind_direction, wind_direction_compass, condition
# Temperature fields are in the Garmin account's display unit (often Fahrenheit). No precipitation-probability or icon-code field.
garmin-cli --json activity weather 12345678901

# Metric descriptors for an activity's detail stream -- fields: key, unit, metricsIndex
# Use to discover what metrics a watch recorded before requesting samples
garmin-cli --json activity metrics-describe 12345678901

# Raw per-sample metric time series (one row per sample, ~2000 typical)
# Columns are the watch's metric keys; use --metric (repeatable) to select
garmin-cli --json activity detail-metrics 12345678901 --metric directTimestamp --metric directHeartRate --metric directPower

# Download an activity file to disk -- fields: id, format, path, size_bytes
# --fmt: original (FIT in a ZIP, default), tcx, gpx, kml, csv. Never prints
# binary to stdout; refuses to overwrite unless --force.
garmin-cli --json activity download 12345678901 --fmt gpx --output run.gpx

# Upload an activity file (.fit / .gpx / .tcx) -- fields: file, status, activity_id
garmin-cli --json activity upload run.fit

# Delete an activity (--confirm skips the interactive prompt) -- fields: id, status
garmin-cli --json activity delete 12345678901 --confirm

--limit defaults to 20, max 100. --type filters by Garmin activity type key (e.g., running, cycling, swimming).

Detailed sport-specific metrics glossary

| Metric (output key) | Unit | Sport applicability | What it is | |---------------------|------|---------------------|------------| | norm_power_w | W | Cycling | Normalized Power -- weighted average that accounts for variable effort | | tss | -- | Cycling | Training Stress Score (depends on FTP being set in Garmin Connect) | | intensity_factor | -- | Cycling | NP / FTP ratio for the ride | | avg_cadence_rpm | rpm | Cycling | Pedal cadence | | avg_cadence_spm | spm | Running | Step cadence | | avg_ground_contact_time | ms | Running | Time foot is in contact with the ground per stride (requires HRM-Pro/Run/Tri or RD pod) | | avg_vertical_oscillation | cm | Running | Vertical "bounce" per stride | | avg_vertical_ratio | % | Running | Vertical oscillation as a percentage of stride length | | avg_stride_length | cm | Running | Average stride length | | swolf | -- | Lap swimming | Strokes + seconds per pool length (lower is better) | | total_strokes | -- | Lap swimming | Total stroke count | | avg_stroke_rate | strokes/min | Lap swimming | Average stroke rate | | distance_per_stroke | m | Lap swimming | Average distance covered per stroke | | aerobic_training_effect | 0.0-5.0 | All sports | Aerobic load impact score | | anaerobic_training_effect | 0.0-5.0 | All sports | Anaerobic load impact score | | training_effect_label | -- | All sports | Garmin's primary-benefit label (e.g. TEMPO, VO2MAX, RECOVERY) | | training_load | -- | All sports | Per-activity training load (EPOC-based); feeds acute/chronic load | | workout_id | -- | All sports | Structured workout this activity executed (null if unplanned) — links plan to execution | | vo2max | mL/kg/min | Run, Bike | Sport-specific vO2max estimate | | recovery_time_h | h | Run, Bike | Recommended recovery hours after the activity |

Capability manifest

activity_get(detail=True) returns an unavailable array (omitted when empty) describing why a metric isn't in the response:

| Reason | Meaning | What an LLM agent should do | |--------|---------|-----------------------------| | not_applicable_to_sport | The metric doesn't apply to this sport (e.g. SWOLF on a bike ride) | Skip this metric for cross-sport rollups | | absent_in_response | The metric applies to this sport but isn't in the payload (typically: missing FTP/LTHR profile, hardware that doesn't track it, or recent firmware change) | Mention the gap; do not infer a value |

Multisport parents (triathlon, duathlon) union per-child manifests with leg_index (0-based) attached to each entry.

Workouts

# List saved workouts -- fields: id, name, sport, duration_min, description
garmin-cli --json workout list --limit 10

# Get workout detail -- fields: id, name, sport, duration_min, description, steps_summary, steps[]
garmin-cli --json workout get 12345678901

# Workout calendar (planned workouts + races/events) -- fields: date, id, name,
# type, duration_min, description, item_type, is_race, primary_event, event_time, location
# item_type distinguishes workouts from events; is_race/primary_event flag target races
garmin-cli --json workout calendar --ahead 7
garmin-cli --json workout calendar --from 2026-03-01 --to 2026-03-14
garmin-cli --json workout calendar --days 7

# Create a workout from JSON file -- fields: id, name, sport, duration_min, status
garmin-cli --json workout create workout.json

# Create from stdin (pipe from LLM output)
echo '{"name":"Easy Run","sport":"running","steps":[{"type":"warmup","duration":{"type":"time","value":300},"target":{"type":"no.target"}}]}' | garmin-cli --json workout create --stdin

# Create from YAML file
garmin-cli --json workout create workout.yaml

# Update an existing workout (partial -- only fields provided are changed)
garmin-cli --json workout update 12345678901 changes.json

# Delete a workout (--confirm skips interactive prompt)
garmin-cli --json workout delete 12345678901 --confirm

# Schedule a workout to a calendar date
garmin-cli --json workout schedule 12345678901 2026-04-01

workout get includes a steps array with structured step data (step_order, step_type, duration_type, duration_value, target_type, target_value_low, target_value_high) and a steps_summary string.

workout create / workout update output fields: id, name, sport, duration_min, status

workout delete output fields: id, status

workout schedule output fields: workoutScheduleId, date, status

---

Workout JSON Schema Reference

The simplified input schema for workout create and workout update. All fields use human-readable string keys — no numeric IDs needed.

Top-level structure

{
  "name": "string (required on create, max 256 chars)",
  "sport": "string (required on create, see sport types)",
  "description": "string (optional)",
  "steps": [ "...step objects (required on create, non-empty)" ]
}

Sport types

| Key | Description | |-----|-------------| | running | Running / jogging | | cycling | Road / mountain cycling | | swimming | Pool / open water swimming | | walking | Walking | | hiking | Hiking | | fitness_equipment | Gym / strength / treadmill | | multi_sport | Triathlon / duathlon | | other | Any other sport |

Step types

| Type | Purpose | Example | |------|---------|---------| | warmup | Warm-up period | {"type":"warmup","duration":{"type":"time","value":600},"target":{"type":"heart.rate.zone","zone":1}} | | interval | High-intensity work | {"type":"interval","duration":{"type":"distance","value":400},"target":{"type":"speed.zone","min":3.5,"max":4.0}} | | recovery | Low-intensity recovery | {"type":"recovery","duration":{"type":"time","value":90},"target":{"type":"no.target"}} | | rest | Complete rest | {"type":"rest","duration":{"type":"time","value":60}} | | cooldown | Cool-down | {"type":"cooldown","duration":{"type":"time","value":300},"target":{"type":"open"}} | | repeat | Repeat group N times | {"type":"repeat","count":4,"steps":[...]} |

Max nesting: 2 levels (no repeats inside repeats).

Duration types

| Type | Value unit | Example | |------|-----------|---------| | time | seconds | {"type":"time","value":600} — 600 = 10 min | | distance | meters | {"type":"distance","value":1000} — 1000 = 1 km |

Target types

| Type | Fields | Example | |------|--------|---------| | no.target | (none) | {"type":"no.target"} | | open | (none) | {"type":"open"} | | heart.rate.zone | zone (1-5) | {"type":"heart.rate.zone","zone":3} | | speed.zone | min, max (m/s) | {"type":"speed.zone","min":3.33,"max":4.17} | | power.zone | zone (1-7) | {"type":"power.zone","zone":4} | | cadence.zone | min, max (spm) | {"type":"cadence.zone","min":170,"max":180} |

Pace/speed reference (running)

| Pace (min/km) | Speed (m/s) | Use | |---------------|-------------|-----| | 7:00 | 2.38 | Easy / recovery | | 6:00 | 2.78 | Easy / base | | 5:30 | 3.03 | Tempo | | 5:00 | 3.33 | Threshold | | 4:30 | 3.70 | Interval / VO2max | | 4:00 | 4.17 | Fast interval | | 3:30 | 4.76 | Sprint |

Formula: speed_ms = 1000 / (pace_min * 60)

---

Complete Workout Examples

Easy 30-minute run

{
  "name": "Easy 30min Run",
  "sport": "running",
  "description": "Recovery run at easy pace",
  "steps": [
    {"type":"warmup","duration":{"type":"time","value":300},"target":{"type":"heart.rate.zone","zone":1}},
    {"type":"interval","duration":{"type":"time","value":1500},"target":{"type":"heart.rate.zone","zone":2}},
    {"type":"cooldown","duration":{"type":"time","value":300},"target":{"type":"heart.rate.zone","zone":1}}
  ]
}

5x1km intervals

{
  "name": "5x1km Intervals",
  "sport": "running",
  "description": "VO2max interval session",
  "steps": [
    {"type":"warmup","duration":{"type":"time","value":600},"target":{"type":"heart.rate.zone","zone":1}},
    {
      "type":"repeat","count":5,
      "steps": [
        {"type":"interval","duration":{"type":"distance","value":1000},"target":{"type":"speed.zone","min":3.70,"max":4.17}},
        {"type":"recovery","duration":{"type":"time","value":120},"target":{"type":"no.target"}}
      ]
    },
    {"type":"cooldown","duration":{"type":"time","value":600},"target":{"type":"heart.rate.zone","zone":1}}
  ]
}

Cycling power workout

{
  "name": "Sweet Spot Cycling",
  "sport": "cycling",
  "description": "Sweet spot intervals at power zone 3-4",
  "steps": [
    {"type":"warmup","duration":{"type":"time","value":600},"target":{"type":"power.zone","zone":2}},
    {
      "type":"repeat","count":3,
      "steps": [
        {"type":"interval","duration":{"type":"time","value":600},"target":{"type":"power.zone","zone":4}},
        {"type":"recovery","duration":{"type":"time","value":300},"target":{"type":"power.zone","zone":1}}
      ]
    },
    {"type":"cooldown","duration":{"type":"time","value":300},"target":{"type":"open"}}
  ]
}

---

Workflow for LLM agents

1. Check auth:      garmin-cli --json login status
2. Create workout:  echo '<json>' | garmin-cli --json workout create --stdin
3. Parse response:  extract "id" from response data[0]
4. Schedule:        garmin-cli --json workout schedule <id> 2026-04-01
5. Verify:          garmin-cli --json workout calendar --from 2026-04-01 --to 2026-04-01

---

Write-specific error codes

| Code | Context | Meaning | |------|---------|---------| | INVALID_INPUT | workout create/update | JSON schema validation failed — check required fields and enum values | | NOT_FOUND | workout update/delete/schedule | Workout ID does not exist | | AUTH_FAILED | Any write command | Session expired (401) or insufficient permissions (403) — re-login |

Performance

# Thresholds -- fields: sport, lt_hr_bpm, lt_pace, ftp_watts, weight_kg
garmin-cli --json performance thresholds

# VO2 max -- fields: date, vo2max, sport
garmin-cli --json performance vo2max
garmin-cli --json performance vo2max --date 2026-03-11

# Lactate threshold zones -- fields: sport, lt_hr_bpm, lt_pace
garmin-cli --json performance zones

# Race predictions -- fields: race_type, predicted_time_seconds, distance_meters
garmin-cli --json performance race-predictions

# Endurance score -- fields: date, overall_score, endurance_classification
# Note: one API call per day — large ranges may be slow
garmin-cli --json performance endurance-score --days 7

# Hill score -- fields: date, overall_score, endurance_score, strength_score
# Note: one API call per day — large ranges may be slow
garmin-cli --json performance hill-score --days 7

# Personal records (all-time PRs) -- fields: type_id, label, value, activity_type,
# date, activity_id, activity_name. Labels: fastest_1km_s...fastest_marathon_s,
# longest_run_m, longest_ride_m, total_ascent_m, max_avg_power_20min_w,
# most_steps_day/week/month, longest_goal_streak_days; unmapped typeIds (11, swim
# records 16-22) have label null. Units per suffix: _s seconds, _m meters, _w watts
garmin-cli --json performance personal-records

Devices

# List registered devices -- fields: device_id, display_name, device_type, last_sync_time
garmin-cli --json device list

Patterns for agents

Login and check authentication

# Interactive login (saves session to ~/.garminconnect)
garmin-cli login

# Non-interactive login (for scripting)
garmin-cli login --email user@example.com --password secret

# Check if a session is active
garmin-cli --json login status

login status returns {"ok": true, ..., "data": [{"authenticated": true, "garmin_home": "..."}]} when a session is present and "authenticated": false when not. Exit code is always 0 (it is an informational command).

After login, verify the session is usable:

garmin-cli --json health status

If this returns ok: true, the session is valid. If AUTH_MISSING or AUTH_FAILED, run garmin-cli login first.

Parse JSON output

import json
import subprocess

result = subprocess.run(
    ["garmin-cli", "--json", "health", "sleep", "--days", "7"],
    capture_output=True, text=True
)
envelope = json.loads(result.stdout)
if envelope["ok"]:
    for row in envelope["data"]:
        print(row["date"], row["score"])
else:
    print(f"Error: {envelope['error_code']} - {envelope['error']}")

Rate limiting

Garmin Connect enforces rate limits. The CLI retries 3 times with backoff (2s, 4s, 8s) for 429/5xx. If you still get RATE_LIMITED, wait 30-60 seconds before retrying. Space sequential calls by at least 1 second.

CSV output

Use --format csv instead of --json when piping to data tools:

garmin-cli --format csv health sleep --days 30 > sleep.csv

Output format reference

| Flag | Format | Stdout content | |------|--------|---------------| | (default) | Table | Human-readable table | | --json | JSON | Envelope with ok, command, count, data, date_range | | --format csv | CSV | Header row + data rows | | --format json | JSON | Same as --json |

---

MCP Server (Alternative)

For Claude Code/Desktop integration via MCP protocol instead of shell commands. Uses MCP Python SDK v2 (MCPServer).

Install

pip install "garmin-py[mcp]"

Register with Claude Code (stdio)

claude mcp add --transport stdio garmin -- garmin-cli mcp-server

Or with a custom session directory:

claude mcp add --transport stdio garmin -- garmin-cli --garmin-home /path/to/.garminconnect mcp-server

HTTP transports (SSE / streamable-http)

--host defaults to 127.0.0.1. Non-loopback binds require the GARMIN_MCP_BEARER_TOKEN environment variable; when set, the MCP SDK gates every tool call (read and write) through Authorization: Bearer <token>.

garmin-cli mcp-server --transport streamable-http --port 8000
garmin-cli mcp-server --transport sse --port 8000

# Non-loopback (requires bearer token):
export GARMIN_MCP_BEARER_TOKEN="<long-random-token>"
garmin-cli mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

See README.md for full HTTP transport options and authentication notes.

Available tools

Read tools plus write tools for workouts (workout_create, workout_schedule, workout_update, workout_delete, workout_unschedule) and activities (activity_download, activity_upload, activity_delete, activity_rename, activity_set_type) are exposed. AI-coaching tools add bounded snapshots, plan reconciliation, read-only preview, and stateless application. Mutating write tools carry the SDK destructive_hint annotation; workout create and update accept dry_run=True for a no-write preview.

| Tool | Parameters | Returns | |------|-----------|---------| | health_sleep | start_date, end_date | {count, rows} | | health_hrv | start_date, end_date | {count, rows} | | health_weight | start_date, end_date | {count, rows} | | health_daily_summary | start_date, end_date | {count, rows} — steps, floors, intensity minutes, calories, resting HR (one API call per day) | | health_steps | start_date, end_date | {count, rows} — steps, distance, step goal (native range API) | | health_intensity_minutes | start_date, end_date | {count, rows} — moderate/vigorous minutes, weekly goal (native range API) | | health_body_battery | start_date, end_date | {count, rows} — date, start_level, end_level, max_level (intraday peak); single ranged API call | | health_stress | start_date, end_date | {count, rows} | | health_spo2 | start_date, end_date | {count, rows} | | health_resting_hr | start_date, end_date | {count, rows} | | health_readiness | start_date, end_date | {count, rows} | | health_training_status | date | {count, rows} — training status plus acute/chronic load, ACWR, load tunnel, monthly load-focus buckets and targets, load-balance status | | activity_list | limit?, start?, activity_type?, search?, start_date?, end_date? | {count, rows} — start_date/end_date (YYYY-MM-DD) must be provided together | | activity_get | activity_id, detail? | {count, rows, children?, unavailable?} — detail=true projects sport-aware metrics (running dynamics, cycling power, swim aggregates, training response) under a stable union schema and adds an unavailable[] capability manifest when non-empty | | activity_weather | activity_id | {count, rows} | | activity_laps | activity_id | {count, rows} — per-lap rows (run/bike) or per-pool-length rows (lap_swimming) with sport-aware fields. Auto-routes pool swim to typed_splits backend method. Multisport parents fan out to each child leg's laps with a 0-based leg_index stamped on every row | | activity_hr_zones | activity_id | {count, rows} — one row per HR zone with zone, zone_low_bpm, zone_high_bpm, seconds_in_zone, minutes_in_zone | | activity_metrics_describe | activity_id | {count, rows} — descriptors for the metric stream: key, unit, metricsIndex. Use to discover what metrics a watch recorded for a specific activity | | activity_detail_metrics | activity_id, metrics? | {count, rows} — raw per-sample time series, one row per sample keyed by metric key (~2000 samples typical). Pass metrics as a comma-separated key list (from activity_metrics_describe) to keep the response small, e.g. "directTimestamp,directHeartRate,directPower". Use for intra-activity analyses (aerobic decoupling, drift) | | workout_list | limit? | {count, rows} | | workout_get | workout_id | {count, rows} | | workout_calendar | start_date, end_date | {count, rows} — scheduled workouts plus races/events. Rows retain compatibility id and add workout_id for template/activity joins plus workout_schedule_id for unscheduling. | | workout_create | workout, dry_run? | {count, rows} — ok: true, action: "created", workout_id on success; ok: true, dry_run: true, wire_payload, validation_report on dry-run; ok: false, error_code: "INVALID_INPUT", errors on validation failure. Dry-run skips all Garmin contact. | | workout_schedule | workout_id, date | {count, rows} — ok: true, action: "scheduled", workout_id, workout_schedule_id, date. Destructive. | | workout_update | workout_id, workout, dry_run? | {count, rows} — ok: true, action: "updated", workout_id on success; dry-run returns the merged wire payload (one Garmin read, no write). Merge semantics preserve workoutId/ownerId/createdDate/atpPlanId. Destructive. | | workout_delete | workout_id | {count, rows} — ok: true, action: "deleted", workout_id. Destructive. | | workout_unschedule | schedule_id | {count, rows} — ok: true, action: "unscheduled", schedule_id. Removes a calendar entry (the workout template is preserved); schedule_id is the workout_schedule_id returned by workout_schedule, not the workout id. Destructive. | | coach_snapshot | date?, baseline_days?, recent_daily_days?, include_extended_daily_baselines?, sports? | Bounded recovery baselines, activity-derived weekly load, current Garmin training status, upcoming plan (today plus six days), wellness rows (readiness, SpO2, steps, weight), execution, data quality, and request provenance. Default cost is 30 Garmin calls, which is also the hard cap. A terminal 429 preserves fetched sections with complete=false, aborted=true. Read-only. | | training_plan_reconcile | start_date, end_date, detail?, max_activities? | Planned-versus-actual entries with exact/inferred/ambiguous match state and request provenance. Range max 28 days; activity cap max 100. Every examined activity requires one detail call because list rows lack workout_id. targets currently reports explicit insufficient_data pending metric-stream coverage. Read-only. | | training_plan_preview | plan | Strict validation (one entry per date, canonical YYYY-MM-DD) plus a live, normalized create_template/schedule/keep/move/replace/unschedule diff; conflicts report source_schedule_changed or destination_occupied. Already-applied moves and removals preview as keep/no_op. Performs no write. Read-only. | | training_plan_apply | plan | Revalidates and rereads live state, writes destinations first, removes sources last, and reports per-operation state plus complete, no_op, compensated, partial, or unknown. Compensation only touches identifiers returned by this call's own writes. No confirm parameter exists; client approval must precede invocation. Destructive. | | training_plan_reschedule | schedule_id, new_date, expected_date | Verifies the expected source date, schedules/verifies the destination before source removal, and compensates a failed move when possible. Destructive. | | activity_download | activity_id, fmt? (original|tcx|gpx|kml|csv), output_path?, overwrite? | {count, rows} — ok: true, action: "downloaded", activity_id, format, path, size_bytes. Writes the file to disk (default activity_<id><ext> in the cwd); raw bytes are never returned. Refuses to overwrite an existing file unless overwrite=true. | | activity_upload | file_path (.fit/.gpx/.tcx) | {count, rows} — ok: true, action: "uploaded", status, activity_id. status is rejected when Garmin declines the import (e.g. duplicate); activity_id is then null. | | activity_delete | activity_id | {count, rows} — ok: true, action: "deleted", activity_id. Destructive. | | activity_rename | activity_id, name | {count, rows} — ok: true, action: "renamed", activity_id, name. Destructive (replaces the stored title). | | activity_set_type | activity_id, type_key | {count, rows} — ok: true, action: "type-updated", activity_id, type. type_key is resolved against Garmin's live sport-type table; unknown keys are rejected before any write. Destructive (replaces the sport classification). | | performance_race_predictions | (none) | {count, rows} — predicted times for 5K, 10K, half marathon, marathon | | performance_endurance_score | start_date, end_date | {count, rows} — endurance score and classification (one API call per day) | | performance_hill_score | start_date, end_date | {count, rows} — hill score, endurance score, strength score (one API call per day) | | performance_thresholds | (none) | {count, rows} | | performance_vo2max | date? | {count, rows} | | performance_zones | (none) | {count, rows} | | performance_personal_records | (none) | {count, rows} — all-time PRs with human-readable label (null for unmapped typeIds) | | device_list | (none) | {count, rows} — registered devices with type and last sync | | login_status | (none) | {authenticated, garmin_home} | | submit_mfa_code | mfa_code | {authenticated, garmin_home} — completes a login that failed with MFA_REQUIRED; ask the user for the one-time code Garmin sent them. Codes are single-use: on failure, retry the original tool call to trigger a fresh code | | report_snapshot | kind (morning|evening|weekly), date? | {kind, date_range, sections, unavailable?} — one composite call that fans out the day's (or week's) reads server-side. sections maps section name → rows (same shapes as the per-domain tools). Sections with no data are empty and listed in unavailable with a reason (not_found|no_data). date (YYYY-MM-DD) defaults to today; weekly covers the anchor day and the six prior days. |

Dates use YYYY-MM-DD format. Max primitive date range: 90 days. Garmin failures surface as MCP ToolError text containing a JSON object with error_code, category, message, and recovery_hint so clients can branch without parsing prose.

AI-coaching tool sequence

Use coach_snapshot for evidence and training_plan_reconcile(detail="summary") for adherence. Keep coaching judgments in the AI host: the server reports neutral deltas, sample counts, Garmin status values, and missing-data state. If a plan change is requested, call training_plan_preview, present its live diff to the user, and invoke training_plan_apply only after the MCP client obtains human approval. Reapplying an already completed plan is a no-op when the calendar or normalized inline workout is equivalent.

The training-plan schema is closed: unknown fields fail validation. Each entry has a stable entry_id, a date, and exactly one of workout_id or an inline simplified workout; moves, replacements, and removals also require the source schedule ID and expected source date. Preview and apply are stateless and always treat live Garmin calendar state as authoritative.

report_snapshot section composition

Use report_snapshot to build a recurring morning/evening/weekly report in a single tool call instead of orchestrating a dozen individual reads. Each kind returns a fixed set of sections:

| kind | Sections | |--------|----------| | morning | sleep, hrv (last night), readiness, body_battery, planned_today | | evening | steps, intensity_minutes, stress, body_battery, activities_today, planned_tomorrow | | weekly | sleep, hrv, stress, steps, resting_hr, body_battery (7-day), activities, endurance_score, race_predictions |

Because the section set is fixed, a report can never silently drop a metric: an absent metric is an empty section plus an unavailable entry, so the agent can state the gap rather than infer a value. Auth, rate-limit, and server/network failures fail the whole call (the snapshot would be untrustworthy); only per-day "no data" gaps degrade to unavailable.

date_range reports the anchor day (or the 7-day window for weekly). The evening planned_tomorrow section deliberately holds the day after the anchor and so falls outside date_range — it is a forward-looking section, not part of the reported window.

Latency note: weekly (and the daily-summary/endurance-score/hill-score reads generally) fan out one upstream request per day; snapshot sections and per-day requests now run on bounded thread pools (GARMIN_CLI_FETCH_CONCURRENCY, default 4), so a weekly snapshot takes a few seconds instead of 10-20s. GARMIN_CLI_DAILY_CALL_DELAY (seconds, default 0.5) still throttles how fast per-day requests are submitted — tune it down if your MCP client times out, up (or set concurrency to 1) to be gentler on Garmin's rate limits.

activity_get(detail=true) may carry an unavailable[] array (omitted when empty) annotating registry-known metrics with not_applicable_to_sport (the metric isn't meaningful for the sport) or absent_in_response (the metric applies but the upstream payload didn't include it). Multisport parents union per-child manifests with a 0-based leg_index attached. activity_laps, activity_hr_zones, and activity_metrics_describe do not carry the manifest in this release; use activity_get(detail=true) for sport-applicability checks.

Planned but not yet implemented: activity_swim_lengths (covered by activity_laps for lap_swimming) and activity_metrics_series (down-sampling policy pending). Hardware/profile manifest reasons (requires_hardware, requires_profile_config) will land alongside a future profile/threshold fetch.

SKILL.md remains the default and simpler integration method. Use MCP when you want native tool semantics without shell command parsing.