Add body composition data

Args: date: Date in YYYY-MM-DD format weight: Weight in kg percent_fat: Body fat percentage percent_hydration: Hydration percentage visceral_fat_mass: Visceral fat mass bone_mass: Bone mass muscle_mass: Muscle mass basal_met: Basal metabolic rate active_met: Active metabolic rate physique_rating: Physique rating metabolic_age: Metabolic age visceral_fat_rating: Visceral fat rating bmi: Body Mass Index

Associate gear with an activity

Links a specific piece of gear (like shoes, bike, etc.) to an activity.

Args: activity_id: ID of the activity gear_uuid: UUID of the gear to add (get from get_gear)

Add a hydration entry for a date.

Entries accumulate: logging 500 then 250 leaves the day at 750. A NEGATIVE value_in_ml subtracts, which is how an over-log is corrected — verified live.

A day cannot go below zero: Garmin answers a further subtraction with "Daily hydration is already at 0 and cannot be reduced." There is no delete for hydration in the Garmin API, so zeroing a day is as close to removing it as the platform allows — the entry stays, reading 0 mL.

Args: value_in_ml: Amount of liquid in millilitres. Negative subtracts from the day's running total. date: Date in YYYY-MM-DD format. (Named to match get_hydration_data; the argument was once called cdate.) timestamp: Timestamp in YYYY-MM-DDThh:mm:ss.sss format

Add a new weight measurement

Args: weight: Weight value unit_key: Unit of weight — 'kg' or 'lbs'. Not 'lb': the underlying client validates against {'kg', 'lbs'} and rejects anything else with "unitKey must be one of {'kg', 'lbs'}".

Add a new weight measurement with specific timestamps

Args: weight: Weight value unit_key: Unit of weight — 'kg' or 'lbs'. Not 'lb'; see add_weigh_in. date_timestamp: Local timestamp in format YYYY-MM-DDThh:mm:ss gmt_timestamp: GMT timestamp in format YYYY-MM-DDThh:mm:ss

Get total count of activities in the user's Garmin account

Returns the total number of activities recorded.

Create a brick workout (bike → run) and upload it to Garmin Connect.

Multi-sport workout with two segments. Garmin auto-adds T1/T2 transitions.

Args: name: Workout name (e.g. "Brick 60m/20m") bike_duration_min: Bike segment duration in minutes (default 60) run_duration_min: Run segment duration in minutes (default 20) bike_hr_zone: HR zone for bike (default Z2) run_hr_zone: HR zone for run (default Z3) bike_warmup_min: Bike warmup in minutes (default 15) run_cooldown_min: Run cooldown in minutes (default 5)

Create a swim → bike brick workout and upload it to Garmin Connect.

Multi-sport workout: swim segment with pace target → bike segment with HR zone.

Args: name: Workout name (e.g. "Brick Swim/Bike") swim_distance_m: Swim distance in meters (default 1500) bike_duration_min: Bike segment duration in minutes (default 60) swim_pace: Target swim pace as "M:SS/100m" bike_hr_zone: HR zone for bike (default Z2) swim_warmup_m: Swim warmup distance in meters (default 400) bike_cooldown_min: Bike cooldown in minutes (default 10) pool_length: Pool length in meters (default 25)

Create a custom food in the user's Garmin nutrition library

Creates a new food item with nutritional information per serving. On success the response includes foodId and servingId needed for log_custom_food. If the API returns no data (204), use get_custom_foods(search=food_name) to retrieve those IDs.

All nutrient amounts are ABSOLUTE values per serving, not %DV. Nutrition labels often print %DV for calcium/iron/vitamin D — convert to absolute units before passing.

Args: food_name: Name of the custom food (e.g. "Homemade Chocolate Cookies") calories: Calories per serving serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G" number_of_units: Serving size in the specified unit. Default 100 brand_name: Brand or vendor name (e.g. "Three Bridges") carbs: Carbohydrates in grams per serving protein: Protein in grams per serving fat: Total fat in grams per serving fiber: Fiber in grams per serving sugar: Sugar in grams per serving saturated_fat: Saturated fat in grams per serving sodium: Sodium in mg per serving cholesterol: Cholesterol in mg per serving potassium: Potassium in mg per serving trans_fat: Trans fat in grams per serving calcium: Calcium in mg per serving (NOT %DV) iron: Iron in mg per serving (NOT %DV) vitamin_d: Vitamin D in mcg per serving (NOT %DV)

Create a steady endurance cycling workout and upload it to Garmin Connect.

Builds a single continuous aerobic ride with HR zone target.

Args: name: Workout name (e.g. "Z2 Endurance 90m") duration_min: Duration of the main ride in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z2) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 15)

Create a 20-minute FTP test cycling workout and upload it to Garmin Connect.

No power target — free effort. The athlete rides at maximum sustainable pace and records the average watts from the test block.

Args: name: Workout name (default "FTP Test") warmup_min: Warmup duration in minutes (default 20) test_min: FTP test duration in minutes (default 20) cooldown_min: Cooldown duration in minutes (default 15)

Create a power-based VO2max cycling interval workout and upload it to Garmin Connect.

Uses exact watt targets (power.between, ID 6) — the device displays "250-270W" not "Zone X".

Args: name: Workout name (e.g. "VO2max 5x3m") reps: Number of intervals (default 5) work_sec: Duration of each interval in seconds (default 180) rest_sec: Recovery duration between intervals in seconds (default 180) power_low: Lower power target in watts (default 250) power_high: Upper power target in watts (default 270) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 10)

Create an over/under threshold cycling workout and upload it to Garmin Connect.

Alternates between above-threshold (over) and sub-threshold (under) power targets based on FTP percentages.

Args: name: Workout name (e.g. "Over/Under 3x(1m/2m)") reps: Number of over/under pairs (default 3) over_sec: Duration of the over segment in seconds (default 60) under_sec: Duration of the under segment in seconds (default 120) over_pct: FTP percentage for over segment (default 105) under_pct: FTP percentage for under segment (default 90) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 10)

Create a sweet spot interval cycling workout and upload it to Garmin Connect.

Repeated sweet spot blocks (Z4) with active recovery between.

Args: name: Workout name (e.g. "Sweet Spot 3x20") reps: Number of sweet spot repeats (default 3) work_min: Duration of each sweet spot block in minutes (default 20) rest_min: Recovery duration between blocks in minutes (default 5) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 10)

Create a tempo/threshold cycling workout and upload it to Garmin Connect.

Same structure as endurance but with a higher HR zone default (Z3).

Args: name: Workout name (e.g. "Tempo 60m") duration_min: Duration of the main tempo block in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z3) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 15)

Log a manual activity in Garmin Connect — useful for activities done without a watch.

The type_key must match a Garmin activity type. Use get_activity_types to see the full list. Common values: yoga, strength_training, meditation, indoor_cycling, pilates, bouldering, fitness_equipment.

Args: type_key: Activity type key (e.g. "yoga", "strength_training") date: Date of the activity in YYYY-MM-DD format duration_minutes: Duration of the activity in minutes start_time: Start time as HH:MM (24-hour, default 09:00) activity_name: Optional title; defaults to the type_key if not provided distance_km: Distance in kilometres (default 0.0 for non-distance activities) time_zone: IANA time zone for the activity (default UTC)

Create an easy aerobic run workout and upload it to Garmin Connect.

Simpler than create_run_workout — defaults to Z2 with shorter warmup/cooldown.

Args: name: Workout name (e.g. "Easy Run 45m") duration_min: Duration of the main run in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z2) warmup_min: Warmup duration in minutes (default 10) cooldown_min: Cooldown duration in minutes (default 10)

Create a hill repeat running workout and upload it to Garmin Connect.

Hill reps with jog-down recovery. No target — effort-based.

Args: name: Workout name (e.g. "Hills 8x1m") reps: Number of hill repeats (default 8) hill_sec: Duration of each hill effort in seconds (default 60) jog_down_sec: Jog-down recovery duration in seconds (default 90) warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 10)

Create a track-style running interval workout and upload it to Garmin Connect.

Uses distance-based end condition for the work intervals (e.g. 400m).

Args: name: Workout name (e.g. "Track 6x400m") reps: Number of intervals (default 6) distance_m: Distance per interval in meters (default 400) rest_sec: Recovery duration between intervals in seconds (default 120) hr_zone: Target heart-rate zone for intervals (Z1-Z5, default Z5) warmup_min: Warmup duration in minutes (default 10) cooldown_min: Cooldown duration in minutes (default 10)

Create a long run with custom BPM range and upload it to Garmin Connect.

Uses targetValueOne/Two for a custom HR band — the device displays "130-145 bpm" instead of "Zone X". This fixes the old encoder's silent-drop bug on heart.rate custom ranges.

Args: name: Workout name (e.g. "Long Run 90m") duration_min: Duration of the long run in minutes hr_min: Lower HR target in bpm (default 130) hr_max: Upper HR target in bpm (default 145) warmup_min: Warmup duration in minutes (default 10) cooldown_min: Cooldown duration in minutes (default 10)

Create a progressive run workout and upload it to Garmin Connect.

Sequential blocks (e.g. Z2→Z3→Z4) without recovery between them. The athlete progresses through increasing intensity zones.

Args: name: Workout name (e.g. "Progression Z2-Z3-Z4") blocks: List of dicts with keys: - duration_sec (int): duration in seconds - hr_zone (str): target HR zone (Z1-Z5) Example: [{"duration_sec": 900, "hr_zone": "Z2"}, {"duration_sec": 900, "hr_zone": "Z3"}, {"duration_sec": 900, "hr_zone": "Z4"}] warmup_min: Warmup duration in minutes (default 15) cooldown_min: Cooldown duration in minutes (default 10)

Create a tempo/threshold run workout and upload it to Garmin Connect.

Same structure as easy run but with a higher HR zone default (Z4).

Args: name: Workout name (e.g. "Tempo Run 30m") duration_min: Duration of the tempo block in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z4) warmup_min: Warmup duration in minutes (default 10) cooldown_min: Cooldown duration in minutes (default 10)

Create a continuous run workout and upload it to Garmin Connect.

Builds a single uninterrupted run interval with warmup and cooldown walks.

Targets a named Garmin heart-rate zone by default. Named zones (Z1-Z5) don't line up with every real training target -- e.g. a 136-148 bpm Zone 2 goal straddles Garmin's Z2 (118-137) and Z3 (138-157). Pass hr_min and hr_max together to target that exact bpm range instead; the watch will then show "in range" only for the range you actually want, not a whole zone that over- or under-shoots it.

Args: name: Workout name (e.g. "Step 8 - 30min continuous") run_seconds: Duration of the run in seconds warmup_min: Warmup walk duration in minutes cooldown_min: Cooldown walk duration in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z3). Ignored if hr_min/hr_max are given. hr_min: Optional custom target heart rate range, minimum bpm (must be given with hr_max) hr_max: Optional custom target heart rate range, maximum bpm (must be given with hr_min)

Create a strength workout and upload it to Garmin Connect.

Each exercise becomes a reps-based step. The name is kept in the step description; it is also sent as exerciseName, which Garmin only retains when it matches one of its own exercise keys (e.g. "FARMERS_CARRY").

Args: name: Workout name exercises: List of dicts with keys: name, sets, reps, rest_seconds and an optional category. Category is omitted from the payload when not given; Garmin accepts that. When given it must be one of Garmin's exercise categories (e.g. SQUAT, DEADLIFT, PUSH_UP, CARRY, SLED) — anything else, including "UNASSIGNED" and "OTHER", is rejected with 400 Invalid category. Full list: https://connect.garmin.com/web-data/exercises/Exercises.json

Create a swim drill set and upload it to Garmin Connect.

Each drill step includes name, distance, equipment, and stroke.

Args: name: Workout name (e.g. "Drills 1200m") drills: List of dicts with keys: - name (str): drill name (e.g. "Catch-up") - distance_m (int): drill distance - equipment (str): "none", "fins", "paddles", "pull_buoy", "kickboard" - stroke (str): stroke type warmup_m: Warmup distance in meters (default 300) cooldown_m: Cooldown distance in meters (default 200) pool_length: Pool length in meters (default 25)

Create a continuous swim workout with pace target and upload it to Garmin Connect.

Args: name: Workout name (e.g. "Endurance Swim 1500m") distance_m: Main set distance in meters (default 1500) pace: Target pace as "M:SS/100m" (default "1:45/100m") stroke: Stroke type — freestyle, backstroke, breaststroke, butterfly warmup_m: Warmup distance in meters (default 400) cooldown_m: Cooldown distance in meters (default 200) pool_length: Pool length in meters — 25 or 50 (default 25)

Create a CSS threshold swim interval workout and upload it to Garmin Connect.

Args: name: Workout name (e.g. "CSS 4x200m") reps: Number of intervals (default 4) distance_m: Distance per interval in meters (default 200) rest_sec: Rest between intervals in seconds (default 30) pace: Target pace as "M:SS/100m" (default "1:40/100m") stroke: Stroke type warmup_m: Warmup distance in meters (default 400) cooldown_m: Cooldown distance in meters (default 200) pool_length: Pool length in meters (default 25)

Create a single threshold swim set and upload it to Garmin Connect.

Good for CSS testing — one continuous threshold block after warmup.

Args: name: Workout name (e.g. "CSS Test 800m") distance_m: Threshold set distance in meters (default 800) pace: Target pace as "M:SS/100m" stroke: Stroke type warmup_m: Warmup distance in meters (default 400) cooldown_m: Cooldown distance in meters (default 200) pool_length: Pool length in meters (default 25)

Create a walk/run interval workout and upload it to Garmin Connect.

Builds the internal Garmin JSON automatically and returns the new workout ID.

Args: name: Workout name (e.g. "W3 Mié 2:2") run_seconds: Duration of each run interval in seconds walk_seconds: Duration of each walk/recovery interval in seconds repeats: Number of run/walk repetitions warmup_min: Warmup duration in minutes cooldown_min: Cooldown duration in minutes hr_zone: Target heart-rate zone (Z1-Z5, default Z3)

Create and schedule a full week of workouts from a plan file.

Parses a JSON/YAML plan file, maps each entry to the appropriate workout builder, uploads all workouts, schedules each on its own date, and returns a summary.

Plan file format (JSON): [ { "date": "2026-07-13", "sport": "cycling", "type": "endurance", "name": "Z2 Endurance 90m", "duration_min": 90, "hr_zone": "Z2" } ]

Every entry needs its own date; an entry without one is uploaded but reported with schedule_error rather than scheduled.

Args: plan_yaml_path: Absolute path to the plan JSON/YAML file

Create a steady Z2 walking workout and upload it to Garmin Connect.

Args: name: Workout name duration_min: Main walking block duration in minutes hr_min: Minimum heart rate in bpm (used for description; target is Z2) hr_max: Maximum heart rate in bpm (used for description; target is Z2)

Permanently delete an activity from Garmin Connect.

This cannot be undone — the activity and its recorded data are gone. Intended for removing a manual activity logged in error; think twice before pointing it at a recorded session.

Exists because create_manual_activity could write a record the server had no way to remove (§D9k).

Args: activity_id: ID of the activity to delete

Delete a single blood pressure measurement.

set_blood_pressure returns the date and version of the reading it wrote; pass both back here to remove it. Without this the server could create a record it had no way to delete (§D9k).

Args: date: Date of the measurement in YYYY-MM-DD format version: The measurement's version, as returned by set_blood_pressure or get_blood_pressure

Delete a course from Garmin Connect.

Args: course_id: ID of the course to delete (get IDs from get_courses).

Delete a custom food from the user's Garmin nutrition library

Permanently removes a custom food entry. The food must not be actively referenced in a logged meal to be deleted. Use get_custom_foods to find the foodId.

Args: food_id: ID of the custom food to delete — a 32-char hex string (from get_custom_foods or create_custom_food)

Delete a food log entry

Permanently removes a logged food item from the nutrition log. Works for both QUICK_ADD and REGULAR_LOG entry types. Use get_nutrition_daily_food_log to find the logId and date.

Args: log_id: Log entry ID to delete — a 32-char hex UUID (from get_nutrition_daily_food_log) meal_date: Date of the log entry in YYYY-MM-DD format

Delete weight measurements for a specific date

Args: date: Date in YYYY-MM-DD format delete_all: Whether to delete all measurements for the day

Delete a workout from Garmin Connect

Permanently removes a workout from your Garmin Connect workout library.

Args: workout_id: ID of the workout to delete (get IDs from get_workouts)

Delete multiple workouts from Garmin Connect in a single call

Permanently removes multiple workouts from your Garmin Connect workout library.

Args: workout_ids: List of workout IDs to delete (get IDs from get_workouts)

Download an activity and save it to disk as a file.

Saves the activity in the requested format. Defaults to the original .fit file; Garmin also supports gpx, tcx, and csv.

Directory resolution (first match wins):

1. output_dir argument (one-off; not persisted)

2. GARMIN_FIT_DOWNLOAD_DIR environment variable

3. persisted config (set via set_fit_download_dir) If none is configured, returns status "needs_setup" with a suggested default (the server's current working directory). In that case, ask the user where to save, call set_fit_download_dir(path), then call this tool again.

Files are named "{activity_id}.{ext}" and overwrite any existing file.

Args: activity_id: Garmin activity ID format: One of fit, gpx, tcx, csv (default fit) output_dir: Optional one-off directory override (not persisted)

Download a workout as a FIT file

Downloads the workout in FIT format. The binary data cannot be returned directly through the MCP interface, but this confirms the workout is available.

Args: workout_id: ID of the workout to download

Get activities with pagination support.

Retrieves a paginated list of activities ordered newest-first. Use this for browsing through large activity lists when you do not need to filter by date range, or as a complement to get_activities_by_date.

Each activity includes an event_type field. Common values: "race", "training", "uncategorized" (no event type set by the user — common for Peloton imports and untagged runs). Filter for races with event_type == "race" rather than excluding "training", as many non-race activities appear as "uncategorized" rather than "training".

Args: start: Starting index (default 0) limit: Maximum number of activities to return (default 20, max 100)

Get activities between specified dates with pagination support.

For accounts with large activity histories, broad date ranges can return thousands of activities in a single response. Use page and page_size to retrieve activities in manageable chunks and avoid "result too large" errors. Activities are ordered newest-first.

Pagination: when has_more is true the response includes next_page — pass that value as page on the next call to retrieve the following page. Repeat until has_more is false.

Note: total_count for a date range is not available from the Garmin API without fetching all results. Use has_more / next_page to walk pages.

Each activity includes an event_type field with values such as:

• "race" — explicitly tagged as a race by the user

• "training" — explicitly tagged as a training activity

• "uncategorized" — no event type set; common for Peloton imports and untagged outdoor runs. Distinct from "training": filter for races with event_type == "race" rather than excluding "training", since many non-race activities appear as "uncategorized" not "training"

• field absent — API returned no eventType for this activity; not observed in practice in any activity back to 2012 (oldest activities sampled on this account)

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format activity_type: Optional activity type filter (e.g., cycling, running, swimming) page: Zero-based page number (default 0) page_size: Number of activities per page, max 200 (default 100)

Get activities for a specific date

Args: date: Date in YYYY-MM-DD format

Get detailed information for a single activity.

Returns a comprehensive summary including timing, distance, heart rate, elevation, training effect, and an event_type field. Common event_type values: "race", "training", "uncategorized" (no event type set by the user). The field is omitted for very old activities that pre-date event type support in the Garmin API.

Args: activity_id: ID of the activity to retrieve

Get the GPS track and per-point route data for an activity.

Returns the recorded GPS polyline (latitude, longitude, altitude, time, distance, speed per point) plus the track's bounding box and start/end coordinates. Garmin downsamples the track server-side to at most max_points points, evenly spread over the activity, so the route shape survives at any size.

Use get_activity for the summary metrics and get_activity_fit_data for full per-second sensor series; this tool is for the route itself (mapping, course analysis, where a climb or interval happened).

Indoor activities carry no GPS track; the response then says so and still lists which per-point metric keys Garmin recorded.

Args: activity_id: ID of the activity to retrieve the track for max_points: Maximum number of track points to return (default 500). Raise it (e.g. 4000) for a finer trace on long routes.

Get exercise sets for strength training activities

Args: activity_id: ID of the activity to retrieve exercise sets for

Download and parse FIT file for an activity to expose advanced cycling data.

Returns data not available through the standard REST API, including:

• DI2 / electronic shifting events with cadence at time of shift, grade at shift, gear combinations, shift quality classification, and terrain-grouped shift analysis

• Cycling dynamics per session and lap: platform center offset (PCO), left/right power balance, torque effectiveness, pedal smoothness

• Variability Index (NP / avg_power) per session and lap

• Climb detection with VAM (vertical ascent rate), avg power/cadence/HR per climb, and W/kg per climb (using auto-fetched body weight from Garmin)

• Grade-correlated stats: avg power, cadence, HR broken down by terrain steepness

• HR drift / cardiac drift coefficient (aerobic decoupling for rides ≥60 min)

• Temperature correlation: avg HR/power in hottest vs. coolest portions of ride

• Power Duration Curve: best mean maximal power at 5s, 30s, 1min, 5min, 10min, 20min, 60min

• Optional full per-second time series when include_records=True

Shift quality:

• proactive: shifted at 70-100 rpm (ideal cadence range)

• reactive: shifted below 70 rpm (already grinding before shifting)

• coasting: shifted at 0 rpm (mid-stop or freewheeling)

• spun_out: shifted above 100 rpm (waited too long in easy gear)

Note: DI2 data requires Shimano Di2 / SRAM eTap. Cycling dynamics require a compatible power meter (e.g., Garmin Rally, Favero Assioma, PowerTap P1 pedals).

Args: activity_id: Garmin activity ID include_records: Include full per-second time series (default False). Warning: adds significant data volume for long rides.

Get gear data used for an activity

Args: activity_id: ID of the activity to retrieve gear data for

Get heart rate data in different time zones for an activity

Args: activity_id: ID of the activity to retrieve heart rate time zone data for

Get power distribution across training zones for an activity.

Returns time spent in each power zone with watt thresholds and duration. Requires a power meter. Zones are based on the athlete's FTP configured in Garmin Connect.

Args: activity_id: ID of the activity to retrieve power zone data for

Get raw per-activity measurements for a date range, with no interpretation.

One record per activity: date, discipline, duration, distance, average and max HR, power, elevation and Garmin's training effect. Pace is deliberately not computed — what counts as a comparable effort is a coaching decision.

Activities are returned oldest-first (Garmin serves them newest-first, which silently reverses anything treating list position as time).

Args: start_date: Start date in YYYY-MM-DD format (inclusive) end_date: End date in YYYY-MM-DD format (inclusive) sports: Optional filter, any of ["running", "cycling", "swimming"]. Activities outside the three triathlon disciplines have sport: null and are excluded when this filter is set. include_hr_zones: Attach per-zone seconds. Costs one extra Garmin request per activity — HR zones are not in the activity payload. Off by default.

Get splits for an activity

Args: activity_id: ID of the activity to retrieve splits for

Get split summaries for an activity

Args: activity_id: ID of the activity to retrieve split summaries for

Get typed splits for an activity

Args: activity_id: ID of the activity to retrieve typed splits for

Get all available activity types

Returns a list of all activity types supported by Garmin Connect, useful for filtering activities by type.

Get weather data for an activity.

Garmin's weather endpoint returns temperatures in Fahrenheit (from the weather-station source) with no unit indicator, regardless of account settings. This tool converts them to the account's display unit: metric accounts get Celsius, statute_us accounts keep Fahrenheit. The temperature_unit field ("F" or "C") states which unit was returned.

Wind speed, unlike temperature, is already returned in the account's display unit (km/h for metric, mph for statute_us), so it is passed through unconverted and labeled via the wind_speed_unit field.

Args: activity_id: ID of the activity to retrieve weather data for

Get user-created social/group challenges (e.g., step competitions with friends)

Returns challenges created by users to compete with connections. These are different from official Garmin badge challenges.

Args: start: Starting index for pagination (default 0) limit: Maximum number of challenges to return (default 20, max 100)

Get daily wellness events data

Args: date: Date in YYYY-MM-DD format

Get all-day stress data

Args: date: Date in YYYY-MM-DD format

Get the athlete's own thresholds, HR zones and physical profile.

Returns LTHR, cycling and running FTP, per-sport HR zone floors, VO2max, weight, height and unit preferences — the numbers that make an absolute heart rate or power target meaningful for this athlete rather than for a generic one.

Thresholds carry as_of and is_stale. Garmin marks a threshold stale once it has stopped reflecting the athlete; prescribing against a stale FTP means prescribing against a test nobody has repeated.

not_available names what Garmin does not expose, so a missing field reads as a platform limitation rather than a gap in this profile.

No arguments.

Get a point-in-time athlete snapshot with baseline deviations.

Current HRV, body battery, resting HR, readiness and sleep, each alongside Garmin's own seven-day baseline and the deviation from it. Deviation against a published baseline is arithmetic; what a −22% HRV deviation means for today's session is not, and no gate is applied.

Args: date: Date in YYYY-MM-DD format. Defaults to today — but before the watch syncs, today holds nothing, so pass yesterday when a morning call comes back empty.

Get official Garmin badge challenges available to join

Returns monthly/seasonal challenges from Garmin that the user can join. These challenges award badges and points upon completion.

Args: start: Starting index for pagination (starts at 1) limit: Maximum number of challenges to return (default 20, max 100)

Get all badge challenges the user has joined (completed and in-progress)

Returns the user's history of badge challenges including progress, completion status, and earned dates.

Args: start: Starting index for pagination (starts at 1) limit: Maximum number of challenges to return (default 20, max 100)

Get blood pressure data

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get body battery data with events

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get body battery events data

Args: date: Date in YYYY-MM-DD format

Get body composition data for a single date or date range

Args: start_date: Date in YYYY-MM-DD format or start date if end_date provided end_date: Optional end date in YYYY-MM-DD format for date range

Measure cardiac drift (aerobic decoupling) for a specific activity.

Returns the percentage change in the power:HR ratio from the first half of the activity to the second. Where the boundary between "coupled" and "decoupled" sits is a coaching decision, so no label is attached — a common reading is that beyond about 5% the athlete was decoupling, but that number belongs in the coaching layer.

TWO PRECONDITIONS, both checked before you waste a call:

1. The activity must carry POWER. Drift is a power:HR ratio, so heart rate alone cannot produce it. Cycling needs a power meter. Running usually does not — most modern Garmin watches estimate running power natively and record it on every sample.

2. At least 3600 records with both power and heart rate, which is 60 minutes at 1-second sampling. Shorter sessions do not qualify, and a device set to smart recording rather than 1-second sampling may not reach it even on a long one.

When either fails the response is an error with a reason naming which, plus records_total, records_with_power and records_usable so the gap is visible. That is a limitation of the recorded data, not a fault in the activity — do not report it as a training finding.

Args: activity_id: Garmin activity ID (numeric or string)

List all courses saved on Garmin Connect.

Returns a curated list of courses with id, name, distance, activity type and creation date.

Search or list user's custom foods

Returns custom foods the user has created. Use the search parameter to find existing foods by name before creating duplicates — the response includes foodId and servingId needed for log_custom_food.

For branded catalog foods (FatSecret), use search_foods instead.

Args: search: Search term to filter foods by name (default: list all) start: Starting index for pagination (default 0) limit: Maximum number of results (default 20)

Get available serving units for custom foods

Returns the list of valid serving units (e.g. G, ML, OZ) that can be used when creating custom foods.

Get the latest cycling Functional Threshold Power (FTP) data.

Returns the most recent cycling FTP estimate available from Garmin.

Get steps data for a date range

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get weight measurements for a specific date

Args: date: Date in YYYY-MM-DD format

Get alarms from all Garmin devices

Returns all configured alarms with their schedules, sounds, and enabled status.

Get information about the last used Garmin device

Get all Garmin devices associated with the user account

Get settings for a specific Garmin device

Returns device configuration including time/date format, units, activity tracking settings, and alarm information.

Args: device_id: Device ID (optional; defaults to the most recently used device when omitted; can be obtained from get_devices or get_device_last_used)

Get solar data for a specific device

Returns solar charging data for devices with solar panels (e.g., Instinct Solar, Fenix Solar). Only applicable to solar-capable devices.

Args: device_id: Device ID (can be obtained from get_devices) date: Date in YYYY-MM-DD format

Get earned badges for user

Get endurance score data between dates

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get fitness age data

Args: date: Date in YYYY-MM-DD format details: If True, include component breakdown (BMI, RHR, vigorous activity) with targets and improvement suggestions

Get floors climbed data

Args: date: Date in YYYY-MM-DD format

Get user's full name from profile

Get Garmin Coach workouts around the given date

Returns workouts from the active Garmin Coach/training plan, including plan metadata, workout identifiers, dates, sport, duration, completion status, rest days, race days, and workout intent when Garmin provides them. Adaptive plans expose only Garmin's currently generated window, typically the current week; future dates may return no workouts even while a plan is active. The count includes rest-day entries.

Garmin's standalone Daily Suggested Workouts are generated on compatible devices. As of July 31, 2026, no supported or known Garmin Connect web/API endpoint, including those exposed by this project's python-garminconnect dependency, returns the device's upcoming DSW schedule. This tool returns Garmin Coach/training-plan workouts and does not synthesize device-generated suggestions.

This is the preferred tool for Garmin Coach requests. The legacy get_training_plan_workouts tool returns the same data; do not call both.

Adaptive Coach plans typically expose workout_uuid; other plan families may expose numeric workout_id. Pass whichever identifier is present to get_workout_by_id. Rest-day UUIDs may return minimal detail without workout segments.

Args: calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)

Get all gear registered with the user account

Returns complete gear inventory including usage statistics and default activity associations. No parameters required - user profile is fetched automatically.

Args: include_stats: Include usage statistics for each gear item (default True). Set to False for faster response with large gear collections.

Get Garmin Connect goals (active, future, or past)

Args: goal_type: Type of goals to retrieve. Options: "active", "future", or "past"

Get raw multi-day health measurements in one call, with no interpretation.

Returns one record per day carrying only what Garmin measured. No thresholds are applied and no verdict is rendered — this is the input a coaching layer reasons over.

Days with no data are absent from days. Days whose fetch FAILED are listed in errors; an empty errors array is what makes a short series trustworthy. Never read a gap as a negative finding when errors is non-empty.

Body Battery returns all four values Garmin records — at_wake is the overnight recharge, most_recent is the end-of-day drain. They mean different things; pick deliberately.

Args: start_date: Start date in YYYY-MM-DD format (inclusive) end_date: End date in YYYY-MM-DD format (inclusive, max 60 days) metrics: Subset of ["body_battery", "hrv", "resting_hr", "sleep", "stress", "training_load", "readiness"]. Defaults to all seven. Fewer metrics means fewer Garmin requests; body_battery and stress share one endpoint.

Get full heart rate time-series data

Note: This returns detailed 2-minute interval data (~25KB). For a compact summary, use get_heart_rates_summary().

Args: date: Date in YYYY-MM-DD format

Get heart rate summary with essential metrics (lightweight version)

Returns a compact summary (~500 bytes) instead of full time-series data (~25KB). Ideal for daily health checkups and LLM integrations.

Args: date: Date in YYYY-MM-DD format

Get hill score data between dates

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get Heart Rate Variability (HRV) data

Args: date: Date in YYYY-MM-DD format return_timeseries: If True, include detailed 5-minute HRV readings (can be large)

Get HRV (Heart Rate Variability) trend over a date range.

Returns daily HRV values and weekly rolling averages. Single-day HRV is too noisy to act on — use this tool to identify baseline shifts that signal accumulated fatigue or recovery. A drop of >10ms from the 7-day baseline warrants reducing training load.

Recommended range: 7-21 days. Maximum: 30 days.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get hydration data

Args: date: Date in YYYY-MM-DD format

Get in-progress virtual challenges/expeditions

Returns virtual challenges (like walking expeditions on famous trails) that the user is currently participating in.

Args: start: Starting index for pagination (default 1, must be >= 1; garminconnect 0.3.2 rejects 0 for this endpoint) limit: Maximum number of challenges to return (default 20, max 100)

Get lactate threshold data

Returns lactate threshold information, which is the exercise intensity at which lactate starts to accumulate in the blood. This is a key metric for endurance training.

Args: start_date: Start date in YYYY-MM-DD format (optional, omit for latest) end_date: End date in YYYY-MM-DD format (optional, omit for latest)

Get lifestyle logging data for a specific date

Returns lifestyle logging data which allows users to track behaviors and their impact on health metrics.

Args: date: Date in YYYY-MM-DD format

Get menstrual calendar data between specified dates

Automatically chunks requests longer than 92 days, Garmin's server-side limit, and stitches the responses together.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get menstrual data for a specific date

Args: date: Date in YYYY-MM-DD format

Get the morning's measurements in a single call.

Aggregates sleep, recovery (body battery, HRV, resting HR), Garmin's training readiness and today's scheduled workout — five endpoints in one round trip. Body battery is reported both at wake and most-recent, because they answer different questions.

No alerts and no recommendation: those thresholds live in the coaching skill, where they can be read and changed in one place.

Args: date: Date in YYYY-MM-DD format

Get morning training readiness score

Returns the morning training readiness assessment, which evaluates recovery status and readiness to train based on overnight metrics.

Args: date: Date in YYYY-MM-DD format

Get badge challenges currently in progress (not yet completed)

Returns active challenges the user has joined but hasn't completed yet. Useful for tracking current progress toward badge goals.

Args: start: Starting index for pagination (starts at 1) limit: Maximum number of challenges to return (default 20, max 100)

Get daily food consumption records for a date

Returns food items logged throughout the day including calories, macronutrients, and meal associations.

Args: date: Date in YYYY-MM-DD format

Get daily meal summaries for a date

Returns meal-level summaries (breakfast, lunch, dinner, snacks) with nutritional totals for each meal. Each meal includes a mealId needed for logging food items to that meal.

Args: date: Date in YYYY-MM-DD format

Get nutrition plan/settings for a date

Returns the user's nutrition goals and targets including calorie targets, macronutrient goals, and plan configuration.

Args: date: Date in YYYY-MM-DD format

Get per-activity pace or power over time, with the regression slope.

Returns each activity's raw value and average HR, plus the slope across them. No HR normalisation is applied — normalise against the athlete's own thresholds from get_athlete_context if you want that.

Args: metric: Metric to track — "pace" (default) or "power" sport: Sport type — "running" or "cycling" days: Number of days to analyze (default 90)

Get personal records for user

Get season-best Power Duration Curve across recent activities.

Downloads FIT files for recent cycling activities and computes best mean maximal power at each standard duration. Returns season bests with which activity and date each best came from.

Durations: 5s (sprint), 30s, 1min, 5min (VO2 max proxy), 10min, 20min (FTP proxy), 60min

Use the 20-minute best × 0.95 as a strong FTP estimate without a formal test.

Warning: downloads multiple FIT files — may take 30-60 seconds for 20 activities.

Args: num_activities: Number of recent activities to analyze (default 20, max 50) activity_type: Activity type to filter (default "cycling")

Get pregnancy summary data

Get information about the primary training device

Returns details about the device designated as primary for training metrics, along with other wearable devices on the account.

Get progress summary for a metric between dates

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format metric: Metric to get progress for (e.g., "elevationGain", "duration", "distance", "movingDuration")

Get predicted race times based on current fitness level

Returns Garmin's predictions for 5K, 10K, half marathon, and marathon finish times based on the user's recent training data and VO2 max.

Get full respiration time-series data

Note: This returns detailed interval data (~20KB). For a compact summary, use get_respiration_summary().

Args: date: Date in YYYY-MM-DD format

Get respiration summary with essential metrics (lightweight version)

Returns a compact summary (~300 bytes) instead of full time-series data (~20KB).

Args: date: Date in YYYY-MM-DD format

Get overnight respiration rate trend over a date range.

Elevated resting respiration rate (compared to personal baseline) is an early warning sign for overreaching, illness, or poor recovery. Use this alongside HRV trend for a complete recovery picture.

Recommended range: 7-21 days. Maximum: 30 days.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get resting heart rate data

Args: date: Date in YYYY-MM-DD format

Get scheduled workouts between two dates with curated summary list

Returns workouts that have been scheduled on the Garmin Connect calendar, including their scheduled dates and completion status.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get full sleep data with all details

Note: This returns detailed sleep data (~50KB). For a compact summary, use get_sleep_summary().

Args: date: Date in YYYY-MM-DD format

Get sleep summary with only essential metrics (lightweight version)

This endpoint returns a compact summary of sleep data (~350 bytes) instead of the full granular data (~50KB). Ideal for daily health checkups and LLM integrations where the full time-series data would overwhelm the context window.

Args: date: Date in YYYY-MM-DD format

Get SpO2 (blood oxygen) data

Args: date: Date in YYYY-MM-DD format

Get daily activity stats with curated essential metrics

Returns a summary of daily health and activity data including steps, calories, heart rate, stress, body battery, and sleep metrics.

Args: date: Date in YYYY-MM-DD format

Get stats and body composition data

Args: date: Date in YYYY-MM-DD format

Get detailed steps data with 15-minute intervals

Note: This returns full interval data (~14KB). For a compact summary, use get_stats() which includes total_steps.

Args: date: Date in YYYY-MM-DD format

Get full stress time-series data

Note: This returns detailed interval data (~35KB) including body battery. For a compact summary, use get_stress_summary().

Args: date: Date in YYYY-MM-DD format

Get stress summary with essential metrics (lightweight version)

Returns a compact summary (~400 bytes) instead of full time-series data (~35KB). Ideal for daily health checkups and LLM integrations.

Args: date: Date in YYYY-MM-DD format

Get training effect data for a specific activity

Args: activity_id: ID of the activity to retrieve training effect for

Get Garmin's Load Focus — the distribution of the trailing-month training load across Aerobic Low, Aerobic High, and Anaerobic intensity bands, plus the system's feedback phrase (e.g. AEROBIC_HIGH_SHORTAGE, BALANCED, ANAEROBIC_SHORTAGE).

Use this to assess whether the athlete's training mix is balanced or deficient in a particular intensity band. Each band reports its load alongside Garmin's target range; a status of "below", "within", or "above" is computed from the load relative to that range.

Args: date: Date in YYYY-MM-DD format

Get training load breakdown by sport for a date range.

Returns total minutes and percentage distribution across running, cycling, swimming and other sports, plus Garmin's acute/chronic load, ACWR and TSB as of the end date.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get the Performance Management Chart (CTL/ATL/TSB) over a date range.

Returns Chronic Training Load (CTL, 42-day fitness), Acute Training Load (ATL, 7-day fatigue), Training Stress Balance (TSB = CTL - ATL, form/freshness), and Acute:Chronic Workload Ratio (ACWR) per day. Use this to assess whether the athlete is building fitness, peaking, or accumulating too much fatigue.

Recommended range: 4-8 weeks. Maximum: 90 days.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Compatibility alias for get_garmin_coach_workouts

Prefer get_garmin_coach_workouts for new requests. This legacy tool returns the same Garmin Coach/training-plan data; do not call both for one request. Adaptive plans expose only Garmin's currently generated window, typically the current week; future dates may return no workouts even while a plan is active.

Adaptive training plans typically expose workout_uuid; other plan families may expose numeric workout_id. Pass whichever identifier is present to get_workout_by_id. The returned count includes rest days.

Args: calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)

Get training readiness data with curated metrics

Returns training readiness score and contributing factors.

Args: date: Date in YYYY-MM-DD format

Get Garmin's training readiness score with its factor breakdown.

Returns Garmin's own score and the percentage each of its six factors contributed — sleep, recovery time, HRV, acute load, sleep history, stress history. No interpretation: what the score means for today's session is a coaching decision.

Args: date: Date in YYYY-MM-DD format

Get training status with curated metrics

Returns comprehensive training status including load, VO2 max, recovery, and training readiness indicators.

Args: date: Date in YYYY-MM-DD format

Get user's preferred unit system from profile

Get user profile information

Get user profile settings

Get user summary data (compatible with garminconnect-ha)

Args: date: Date in YYYY-MM-DD format

Get VO2 max trend over a date range.

Returns daily VO2 max estimates from Garmin's FirstBeat algorithm. Use this to track whether training is producing fitness gains over weeks or months. Flat or declining VO2 max over 4+ weeks suggests insufficient training stimulus or overreaching.

Note: VO2 max estimates are smoothed and update gradually — daily changes of <0.5 are within normal noise. Focus on the 4-6 week trend direction.

Garmin records a new VO2 max value only on days with a recompute (after an activity). Days in between carry the last known value forward and are marked with "carried_forward": true, matching the trend chart in Garmin Connect.

If historical values are unavailable, the current profile estimate is returned separately and is not represented as a historical trend point.

Recommended range: 4-12 weeks. Maximum: 90 days.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get weekly intensity minutes data aggregates

Returns weekly intensity minutes (moderate and vigorous) for the specified number of weeks ending at end_date.

Args: end_date: End date in YYYY-MM-DD format weeks: Number of weeks to fetch (default 4, max 52)

Get training minutes per ISO week and the week-over-week change.

Arithmetic only. Whether a given ramp rate is too fast is a coaching decision.

Args: weeks: Number of weeks to analyze (default 12, max 52)

Get weekly step data aggregates

Returns weekly step totals for the specified number of weeks ending at end_date.

Args: end_date: End date in YYYY-MM-DD format weeks: Number of weeks to fetch (default 4, max 52)

Get weekly stress data aggregates

Returns weekly stress values for the specified number of weeks ending at end_date.

Args: end_date: End date in YYYY-MM-DD format weeks: Number of weeks to fetch (default 4, max 52)

Get weight measurements between specified dates

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get detailed information for a specific workout

Returns workout details including segments and step structure.

Accepts either:

• Numeric workout ID (from get_workouts, get_scheduled_workouts, or training-plan families that expose workout_id)

• Workout UUID (from adaptive Garmin Coach/training-plan workouts)

Rest-day UUIDs can resolve to a minimal record without a workout name or segments.

Args: workout_id: Workout ID (numeric) or UUID (for training plan workouts)

List scheduled workouts alongside activities recorded the same day.

Returns the pairing, not a compliance score. Matching is on date only — Garmin's schedule query returns no sport to match against — so whether a given activity completes a given workout is left to the caller.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Get all workouts with curated summary list

Returns a count and list of workout summaries with essential metadata only. For detailed workout information including segments, use get_workout_by_id.

Get heart rate zone distribution across sports for a date range.

Calculates the percentage of time spent in each HR zone (Z1-Z5) for running, cycling, and swimming activities.

Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Log a food item to a meal on a date

Adds a food entry to the nutrition log. The meal is determined automatically by matching meal_time against each meal's startTime/endTime window; falls back to SNACKS if no window matches.

Food sources:

• "GARMIN" (default): user's custom food library. Use get_custom_foods to find food_id and serving_id.

• "FATSECRET": branded/catalog food from FatSecret. Use search_foods to find food_id and serving_id. Pass the source value from the search_foods result (e.g. "FATSECRET").

Garmin custom food IDs are 32-char hex UUIDs; FatSecret IDs are numeric strings (e.g. "4132350"). Passing the wrong source for a given food_id returns a 400 from Garmin.

Args: meal_date: Date in YYYY-MM-DD format meal_time: Time in HH:MM:SS format (e.g. "12:30:00", account timezone) food_id: Food ID from get_custom_foods (GARMIN) or search_foods (FATSECRET) serving_id: Serving ID from get_custom_foods or search_foods serving_qty: Number of servings (default 1) source: Food namespace — "GARMIN" (default) or "FATSECRET"

Quick-add a food entry with macro values to the nutrition log

Logs food directly by name and macros without requiring a food ID. Uses Garmin's Quick Add feature. The meal is determined automatically by matching meal_time against each meal's startTime/endTime window; falls back to SNACKS if no window matches.

Args: meal_date: Date in YYYY-MM-DD format name: Display name for the food entry calories: Calories (kcal) carbs: Carbohydrates in grams protein: Protein in grams fat: Fat in grams meal_time: Time in HH:MM:SS format (account timezone)

Remove gear association from an activity

Unlinks a specific piece of gear from an activity.

Args: activity_id: ID of the activity gear_uuid: UUID of the gear to remove

Ask Garmin to re-process the epoch data for a date.

Use when a day's metrics look incomplete after a sync. The response says whether the reload was accepted, not whether new data appeared — re-read the day afterwards to see that.

Args: date: Date in YYYY-MM-DD format

Schedule a list of workouts for the week in a single call.

Idempotent: if a workout is already scheduled for that date, it is reported as already scheduled and the POST is skipped (avoids duplicating calendar entries).

A bad entry is reported and the rest of the batch continues; nothing aborts the whole week.

Args: week: List of dicts with keys: calendar_date (YYYY-MM-DD) and workout_id (int). The key is calendar_date, matching schedule_workout and schedule_workouts.

Schedule a workout to a specific calendar date

This adds an existing workout from your Garmin workout library to your Garmin Connect calendar on the specified date.

Idempotent: if the workout is already scheduled for that date, this is a no-op that reports success without creating a duplicate entry.

Args: workout_id: ID of the workout to schedule (get IDs from get_workouts) calendar_date: Date to schedule the workout in YYYY-MM-DD format

Schedule multiple workouts to specific calendar dates

This adds workouts to your Garmin Connect calendar in a single call. Each item can either reference an existing workout by ID, or provide inline workout_data to upload-and-schedule in one step.

Args: schedules: List of workout schedules, each with: - calendar_date (str): Date to schedule the workout in YYYY-MM-DD format (required) - workout_id (int): ID of an existing workout to schedule (required unless workout_data is provided) - workout_data (dict): Inline workout JSON to upload first, then schedule (optional). When provided, workout_id is not required. Uses the same structure and target-value rules as upload_workout.

Examples: Schedule existing workouts by ID: [{"workout_id": 123456, "calendar_date": "2024-01-15"}, {"workout_id": 789012, "calendar_date": "2024-01-17"}]

Upload and schedule inline:
[{"calendar_date": "2024-01-15", "workout_data": {"workoutName": "Easy Run", ...}},
 {"workout_id": 789012, "calendar_date": "2024-01-17"}]

Search Garmin's general food catalog (FatSecret + Garmin custom foods)

Searches across the entire food catalog including FatSecret-sourced branded and generic foods, not just the user's Garmin custom foods. Use this to find branded packaged foods by name before logging them.

Returns food_id, source, name, brand, and all available servings with macros. The source field ("FATSECRET" or "GARMIN") and food_id together identify the right routing for log_custom_food — pass both to log_custom_food's food_id and source parameters respectively.

For the user's own custom foods only, use get_custom_foods instead.

Args: query: Food name or brand to search for (e.g. "Cheerios", "Greek yogurt") start: Starting index for pagination (default 0) limit: Maximum number of results per page (default 20)

Set or update the free-text description (notes) of an activity.

This is the notes field shown on the activity page — useful for recording how a session felt, kit used, conditions, niggles, etc. Pass an empty string to clear an existing description.

Args: activity_id: ID of the activity to update description: New description text (empty string clears it)

Set the event type of an activity.

Event type categorises the activity's purpose. Valid keys: race, recreation, specialEvent, training, transportation, touring, geocaching, fitness, uncategorized.

Args: activity_id: ID of the activity to update event_type: Target event type key (e.g. 'race', 'training')

Set how an activity felt ('How did you feel?').

Mirrors Garmin Connect's 5-point feel rating, stored as one of: 0 = very tired / poor 25 = tired 50 = normal 75 = good 100 = strong Higher is better.

Args: activity_id: ID of the activity to update feel: One of 0, 25, 50, 75, 100

Set or update the name of an activity.

Args: activity_id: ID of the activity to update activity_name: New activity name

Change the activity type (sport) of an activity.

Useful for reclassifying a mislabelled activity, e.g. flipping a run logged as 'trail_running' to 'running', or a 'treadmill_running' walk to 'treadmill_walking'. Call get_activity_types to see all valid type keys.

Args: activity_id: ID of the activity to update type_key: Target activity type key (e.g. 'running', 'trail_running', 'treadmill_running', 'cycling', 'lap_swimming')

Set blood pressure values

Args: systolic: Systolic pressure (top number) diastolic: Diastolic pressure (bottom number) pulse: Pulse rate notes: Optional notes

Set and persist the default directory for downloaded activity files.

Stores the absolute path in a small JSON config file (~/.garminconnect_fit_config.json, overridable via GARMIN_FIT_CONFIG) so download_activity_file can save files without asking again.

Args: path: Directory where activity files (.fit/.gpx/.tcx/.csv) are saved. Pass the current working directory to keep files where the server runs.

Update daily nutrition goals (calorie target and macronutrient targets).

Reads the current settings for the date, applies the supplied overrides, and writes the merged result back. Only the fields you provide are changed; omitted fields keep their existing values.

Garmin stores macros as grams. The calorie goal should match 4carbs + 4protein + 9*fat to within a small rounding margin — Garmin accepts minor mismatches but will silently correct large discrepancies.

Args: date: Date in YYYY-MM-DD format (settings are typically set once and inherited across days, but Garmin accepts per-day overrides) calorie_goal: Daily calorie target in kcal carbs_grams: Daily carbohydrate target in grams fat_grams: Daily fat target in grams protein_grams: Daily protein target in grams

Set the perceived effort (RPE) for an activity.

Mirrors Garmin Connect's 'Perceived Effort' rating on a 0-10 scale, where 0 clears the rating. Internally Garmin stores this multiplied by 10 (so RPE 7 is stored as 70); this tool handles the conversion.

Args: activity_id: ID of the activity to update rpe: Perceived effort from 0 to 10 (0 clears the rating)

Remove a scheduled workout from the Garmin Connect calendar

Deletes a calendar entry without deleting the underlying workout template — the workout stays in your library and can be re-scheduled.

IMPORTANT: scheduled_workout_id is the calendar-entry id, which is different from the workout's id. Get it from get_scheduled_workouts (the "scheduled_workout_id" field), not from get_workouts.

Note: the scheduled-workouts listing is an eventually-consistent index. If you just scheduled this workout, allow a moment before unscheduling so the id is available.

Args: scheduled_workout_id: Calendar-entry id from get_scheduled_workouts

Remove multiple scheduled workouts from the Garmin Connect calendar

Deletes multiple calendar entries in a single call. The underlying workout templates are left intact in your library.

IMPORTANT: each id is a calendar-entry id (the "scheduled_workout_id" field from get_scheduled_workouts), not a workout id.

Args: scheduled_workout_ids: List of calendar-entry ids from get_scheduled_workouts

Update an existing custom food in the user's Garmin nutrition library

Fetches the food's current record before writing so that omitted optional fields (brand, carbs, protein, fat, micros, etc.) preserve their existing values rather than being cleared. Only the fields you explicitly pass are changed; everything else is carried forward from the current record.

All nutrient amounts are ABSOLUTE values per serving, not %DV. Nutrition labels often print %DV for calcium/iron/vitamin D — convert to absolute units before passing.

Use get_custom_foods first to find the foodId and servingId.

Args: food_id: ID of the custom food to update (from get_custom_foods) serving_id: Serving ID of the food (from get_custom_foods) food_name: Name of the custom food calories: Calories per serving serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G" number_of_units: Serving size in the specified unit. Default 100 brand_name: Brand or vendor name; omit to preserve the existing value carbs: Carbohydrates in grams per serving protein: Protein in grams per serving fat: Total fat in grams per serving fiber: Fiber in grams per serving sugar: Sugar in grams per serving saturated_fat: Saturated fat in grams per serving sodium: Sodium in mg per serving cholesterol: Cholesterol in mg per serving potassium: Potassium in mg per serving trans_fat: Trans fat in grams per serving calcium: Calcium in mg per serving (NOT %DV) iron: Iron in mg per serving (NOT %DV) vitamin_d: Vitamin D in mcg per serving (NOT %DV)

Upload a GPX file as a Garmin Connect Course.

The course can then be loaded onto the watch (sync or "Send to Device") and used as a navigation course or to build a PacePro strategy.

Args: gpx_path: Absolute path to the .gpx file on disk. course_name: Override the course name. Defaults to the name parsed from the GPX file. activity_type: One of running, cycling, hiking, walking, trail_running, mountain_biking, road_biking, gravel_cycling. Defaults to running. description: Optional description shown on the course detail page.

Upload a workout from JSON data

Creates a new workout in Garmin Connect from structured workout data.

IMPORTANT: Step types must use Garmin's DTO format:

• Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)

• Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations. Always include endCondition with conditionTypeId 7 and conditionTypeKey "iterations"; omitting conditionTypeId causes the API to silently corrupt the repeat count.

IMPORTANT: Heart rate targets come in two forms:

• Named zone (e.g. Zone 2): set targetType to "heart.rate.zone" and use "zoneNumber" (1-5). Do NOT put the zone number in targetValueOne.

• Custom HR range (e.g. 105-143 bpm): set targetType to "heart.rate.zone" and use "targetValueOne" (low bpm) / "targetValueTwo" (high bpm). Do NOT set "zoneNumber". This matches Garmin Connect's "Custom" heart rate target. For non-HR targets (pace, power, cadence), use targetValueOne/targetValueTwo directly. Target values are fields on the workout step, alongside targetType; do not put targetValueOne, targetValueTwo, or zoneNumber inside the targetType object. Use either zoneNumber or targetValueOne/targetValueTwo, not both. Garmin silently discards a custom range when a named zone is also present.

Note: a safety check converts targetValueOne 1-5 to zoneNumber when zoneNumber is missing, to catch the common mistake of putting a zone index in targetValueOne. Typical bpm values (e.g. 105, 143) are not affected.

IMPORTANT: Target type IDs and keys must match Garmin's canonical mapping. Garmin treats workoutTargetTypeId as authoritative, so mismatches are rejected before upload. Known mappings:

• workoutTargetTypeId 1 -> "no.target"

• workoutTargetTypeId 2 -> "power.zone" (cycling power zone 1-7, use zoneNumber)

• workoutTargetTypeId 4 -> "heart.rate.zone"

• workoutTargetTypeId 6 -> "pace.zone" (running/swim). NOT power: a cycling upload with "power.between" is stored as pace.zone.

IMPORTANT: For cycling power targets use the correct target type:

• Power zone (zone 1-7 based on FTP %): use workoutTargetTypeId 2, key "power.zone", and "zoneNumber" (1-7).

• Absolute watt range (e.g. 200-250 W): use workoutTargetTypeId 2, key "power.zone", and "targetValueOne" (low watts) / "targetValueTwo" (high watts). Using workoutTargetTypeId 2 with key "power.between" is a silent Garmin bug: the workout uploads but Garmin stores it as "power.zone" and the intent is lost.

Use {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"} with targetValueOne/targetValueTwo for custom heart-rate ranges.

IMPORTANT: Sport type IDs for workouts (different from activity API!):

• 1 = running, 2 = cycling, 5 = strength_training, 6 = cardio, 11 = walking

IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping. Garmin treats conditionTypeId as authoritative, so mismatches such as {"conditionTypeId": 4, "conditionTypeKey": "heart.rate"} are rejected before upload because Garmin would interpret them as "calories". Use {"conditionTypeId": 6, "conditionTypeKey": "heart.rate"} for heart-rate end conditions.

Available Templates: Instead of building workout JSON from scratch, you can use these MCP resources as starting points:

• workout://templates/simple-run - Basic warmup/run/cooldown structure

• workout://templates/interval-running - Interval training with repeat groups

• workout://templates/tempo-run - Tempo run with heart rate zone targets

• workout://templates/strength-circuit - Strength training with exercises, reps, rest

• workout://reference/structure - Complete JSON structure reference with all fields

Access these resources using your MCP client's resource reading capability, modify the template as needed, and pass the resulting JSON as the workout_data parameter.

Strength training workouts require these additional fields on each exercise step:

• "category": exercise category (e.g. "BENCH_PRESS", "PULL_UP", "CURL", "SHOULDER_PRESS", "ROW", "SQUAT", "DEADLIFT", "TRICEPS_EXTENSION", "PLANK", "LUNGE", "CARDIO")

• "exerciseName": specific exercise (e.g. "BARBELL_BENCH_PRESS", "PULL_UP", "DUMBBELL_BICEPS_CURL", "DUMBBELL_SHOULDER_PRESS", "BENT_OVER_ROW_WITH_DUMBELL", "BODY_WEIGHT_DIP", "BARBELL_SQUAT", "BARBELL_DEADLIFT")

• "weightValue" (optional): weight as number (e.g. 24.0)

• "weightUnit" (optional): {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0} Use endCondition reps (conditionTypeId: 10) for exercises, rest (stepTypeId: 5) between sets.

Example strength exercise step: { "type": "ExecutableStepDTO", "stepOrder": 1, "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"}, "endCondition": {"conditionTypeId": 10, "conditionTypeKey": "reps"}, "endConditionValue": 10.0, "targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"}, "category": "BENCH_PRESS", "exerciseName": "BARBELL_BENCH_PRESS", "weightValue": 60.0, "weightUnit": {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0} }

Example running workout with HR zone target: { "workoutName": "My Workout", "sportType": {"sportTypeId": 1, "sportTypeKey": "running"}, "workoutSegments": [{ "segmentOrder": 1, "sportType": {"sportTypeId": 1, "sportTypeKey": "running"}, "workoutSteps": [{ "type": "ExecutableStepDTO", "stepOrder": 1, "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"}, "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"}, "endConditionValue": 1200.0, "targetType": {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"}, "zoneNumber": 3 }] }] }

Args: workout_data: Dictionary containing workout structure (name, sport type, segments, etc.)

Upload multiple workouts from JSON data in a single call

Creates multiple new workouts in Garmin Connect. Each item in the list uses the same structure as upload_workout.

IMPORTANT: Step types must use Garmin's DTO format:

• Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)

• Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations. Always include endCondition with conditionTypeId 7 and conditionTypeKey "iterations"; omitting conditionTypeId causes the API to silently corrupt the repeat count.

IMPORTANT: For named heart rate zone targets, use "zoneNumber" (1-5), NOT targetValueOne/targetValueTwo. For custom heart-rate ranges, use targetType {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"} with targetValueOne/targetValueTwo. Target values belong on the workout step, alongside targetType, not inside it. For cycling power zone targets (zone-based), use workoutTargetTypeId 2, key "power.zone". For cycling absolute watt range targets, use workoutTargetTypeId 2, key "power.zone", with targetValueOne (low watts) and targetValueTwo (high watts). Target type IDs and keys must match Garmin's canonical mapping.

IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping. Garmin treats conditionTypeId as authoritative, so mismatches are rejected before upload.

Args: workouts: List of workout dictionaries, each containing workout structure (name, sport type, segments, etc.) — same format as upload_workout.

Find-or-create a custom food then log it in one step

Searches the user's custom food library for food_name. If found, logs it immediately. If not found, creates it with the provided nutrition data and then logs it. This avoids duplicate food entries and removes the need for separate search → create → log round-trips.

Args: meal_date: Date in YYYY-MM-DD format meal_time: Time in HH:MM:SS format (account timezone); used to determine the meal automatically food_name: Name of the food to find or create calories: Calories per serving carbs: Carbohydrates in grams per serving protein: Protein in grams per serving fat: Total fat in grams per serving serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G" number_of_units: Serving size in the specified unit. Default 100 serving_qty: Number of servings to log (default 1)