Skip to main content
Glama

upload_workout

Create a new Garmin Connect workout from structured JSON data, including steps, repeat groups, sport types, and heart rate, pace, or power targets.

Instructions

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.
    - stepOrder is one depth-first counter over the whole workout: a repeat
      group takes the next number and its nested steps continue from there
      (group 2, children 3 and 4, cooldown 5). Do not restart at 1 inside a group.

    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.
    Pace targets are speeds in meters per second, not min/km:
    5:00/km = 1000 m / 300 s = 3.333 m/s.
    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) OR "power.between" (cycling)

    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).
    - Custom % FTP range (e.g. 76-81% FTP): use workoutTargetTypeId 2, key "power.zone",
      "targetValueOne"/"targetValueTwo" as percentages and
      "targetValueUnit": {"unitKey": "percent"}. Garmin Connect shows it as
      "Custom Power 76-81% FTP" with the matching watts.
    - Absolute watt range (e.g. 200-250 W): use workoutTargetTypeId 6, key "power.between",
      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_training, 12 = 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.)
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workout_data": "<workout_data>"
    },
    "name": "upload_workout"
  }
}

Input Schema

NameRequiredDescriptionDefault
workout_dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare write/openWorld/non-idempotent, and the description adds far more: it discloses which malformed payloads are rejected before upload (ID/key mismatches), which are silently corrupted (missing conditionTypeId on repeat groups, power.between stored as power.zone), and that a safety check silently rewrites targetValueOne 1-5 to zoneNumber. This is exactly the kind of non-obvious behavior that cannot be read off annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the body is organized into labeled IMPORTANT sections with concrete examples, so it is scannable. It is still long for a one-parameter tool and repeats itself: the custom HR range rule (targetValueOne/targetValueTwo vs zoneNumber) is stated twice in near-identical wording, which could be consolidated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity payload builder with no output schema, the definition covers inputs exhaustively and warns about silent failures. The main gap is the outcome side: it never says what a successful upload returns (e.g., a workout ID) or whether the workout is immediately scheduled, leaving the agent to guess after the write.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter is a free-form object with additionalProperties:true, so the description carries the entire burden — and it does, documenting DTO step types, stepOrder rules, target type IDs/keys, sport type IDs, end condition IDs, strength-specific fields, and two full worked examples. This meaning is available nowhere in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening lines state a specific verb and resource: 'Upload a workout from JSON data' / 'Creates a new workout in Garmin Connect from structured workout data.' That is unambiguous. However, it never distinguishes itself from the many sibling creation tools (create_run_workout, create_strength_workout, create_run_interval_workout, upload_workouts), so an agent cannot tell from the description alone which creator to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is abundant guidance on HOW to build the payload (templates, resources, DTO formats, examples), which implies usage, but no explicit statement of when this tool should be chosen over the specialized create_*_workout siblings or when-not to use it. Tool-selection guidance is absent; format guidance is excellent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools