Skip to main content
Glama

get_activity_fit_data

Read-only

Download and parse an activity's FIT file to extract advanced cycling metrics—DI2 shifting, cycling dynamics, climb detection, HR drift, and grade-based stats—not available through the standard API.

Instructions

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 the latest Garmin weigh-in on or before the ride,
      up to 90 days back; rider_weight_date says which weigh-in was used)
    - Grade-correlated stats: avg power, cadence, HR broken down by terrain steepness
    - Grade comes from the device's per-record grade field when present; otherwise
      it is derived from altitude and distance (~100 m window). grade_source
      ("device" | "derived") says which
    - 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

    Multisport files (triathlon, duathlon) contain one session per leg. For
    these, the response adds multisport=true and a sessions list with every
    leg; session and the record-based analyses (power curve, climbs, grade,
    HR drift, temperature) describe one leg only — the cycling leg if there
    is exactly one, else the longest — given by analyzed_session_index and
    explained in analysis_note. Laps and records still cover all legs.

    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.
    

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": {
      "activity_id": "<activity_id>"
    },
    "name": "get_activity_fit_data"
  }
}

Input Schema

NameRequiredDescriptionDefault
activity_idYes
include_recordsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/openWorld annotations, it discloses cost (include_records adds 'significant data volume for long rides'), multisport leg-selection behavior with analyzed_session_index/analysis_note, grade_source provenance, and which weigh-in rider_weight_date reflects. These are exactly the non-obvious behaviors an agent needs before committing to the call.

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 bulleted return-value list is scannable, but the description is long relative to a 2-parameter tool; the shift-quality definitions and terrain breakdowns could be trimmed if an output schema were available.

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

Completeness5/5

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

With no output schema, the description must explain returns, and it does so exhaustively while also covering the multisport edge case and hardware/derivation caveats. Nothing material for correct invocation is missing.

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

Parameters4/5

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

Schema coverage is 0%, so the Args block carries the load: include_records is documented with default and a volume warning, and activity_id is identified as a Garmin activity ID. The only gap is that the schema allows integer OR string for activity_id and the description does not clarify acceptable formats.

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

Purpose5/5

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

Opens with a specific verb+resource+scope: 'Download and parse FIT file for an activity to expose advanced cycling data,' and immediately frames the value as data 'not available through the standard REST API,' which separates it from the plain get_activity / activity-summary siblings.

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

Usage Guidelines4/5

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

The enumerated data categories (Di2 shift events, cycling dynamics, climb/VAM, PDC, HR drift) make the use case clear — reach for this when the standard API lacks the metric — and the hardware prerequisites (Di2/eTap, compatible power meter) tell the agent when the tool's richer output won't materialize. It stops short of explicit exclusions or naming a cheaper sibling to try first.

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