Fit File Forge

Use this when the athlete wants structured workouts made — one session or up to seven (a week). Describe each session in plain words ("4 × 8 min at threshold with 2 min jog", "60 min easy ride Z2", "swim 10 × 100 on 1:45", strength, multisport) with its date; Fit File Forge builds a valid Garmin workout in the athlete's units, using the thresholds saved in their profile, and saves it to their Fit File Forge calendar. When get_athlete shows a threshold as estimated or missing, put the target in the description ("at 4:35/km", "at 250 W", "HR 150–160"). Don't write steps or JSON yourself. A request Fit File Forge can't build (such as a whole multi-week plan as one session) comes back unbuilt with a suggestion. Builds count toward the athlete's Fit File Forge usage limits. Each call creates new workouts, so calling it again for the same sessions makes duplicates. Nothing is sent to the watch: show the result and use send_to_garmin when the athlete asks. Don't use this for advice the athlete didn't ask to have built.

build_workouts

Use this to compare two sessions of the same kind side by side (pace or power, heart rate, efficiency, decoupling, load, laps): "is this tempo better than last month's?". Put the earlier or baseline session first; ids come from find_activities.

compare_activities

Use this only when the athlete asks to change a specific saved workout, in plain words ("make the reps 3 minutes", "ease it to Z2", "rename it", "move the cooldown to 15 min"). Fit File Forge rebuilds and re-validates it, replacing the saved version and keeping its date. Find the id with get_calendar. Don't use this to move it to another day (schedule_workouts) or to make a different workout (build_workouts).

edit_workout

Use this to find the athlete's synced activities by date range, sport, minimum distance or name ("my long run two Sundays ago", "rides over 80 km in August") or to list a period, newest first. Each hit has an id and a one-line summary (time, distance, normalised pace or power, heart rate avg/max, training load, decoupling, climb). Pass ids to get_activity or compare_activities; never ask the athlete for ids. For weekly totals or volume over weeks use get_trends instead. Defaults: last 90 days, all sports, 10 results (max 25). Dates are the athlete's local YYYY-MM-DD.

find_activities

Use this to look inside one activity. depth: summary (headline numbers, load, decoupling, efficiency), laps (per lap with per-lap normalised power for rides), zones (time in heart-rate/pace/power zones on the athlete's own thresholds), efforts (best efforts inside the session), full (all of it). Laps list up to 25; for more, use get_activity_splits by lap. Activities Garmin sent only as a summary have no laps or zones (dataNotes says so). When the athlete asks how a session went or to analyse it, use full together with get_activity_splits and, when it's available, get_activity_series; use a smaller depth for a quick question about one number.

get_activity

Use this for pacing and execution questions: an analysis-ready table of one activity split by km, mile, lap, minute or 5 minutes — elapsed and moving time, distance, pace (and grade-adjusted pace for runs), average/max heart rate, power, cadence, climb and descent per split. Optional from_s/to_s (seconds from the start) to look at part of the session, e.g. the last 10 minutes. Compact enough for any session; prefer it over the time series unless you need per-second detail.

get_activity_splits

Use this when the athlete wants one activity analysed in detail or charted — how it went, pacing, heart-rate drift, climbs, interval execution, cadence vs pace: Fit File Forge's cleaned time series, units in the column names, t_s = seconds from the start. format: json (default — one array per column, index-aligned to t_s, null = not recorded; load it straight into a dataframe) or csv. Pick only the channels you need. resolution_s: 1, 2, 5, 10, 15, 30 or 60; omit for the finest that fits the whole activity on one page. Long results come in pages — pass next_cursor to continue. Never includes location. For splits or summaries use get_activity_splits or get_activity instead.

get_activity_series

Use this first in a conversation about the athlete's training: thresholds and zones inputs (max/threshold heart rate, threshold pace, FTP, swim CSS, each with its source), units and time zone, their Fit File Forge plan and whether the connector's tools are available to them, Garmin connection and sharing state, and how much activity history Fit File Forge holds. Not for sleep, HRV, stress or other health data (not collected).

get_athlete

Use this for "what's on this week" and before planning, moving or sending anything: every workout the athlete has scheduled in Fit File Forge between two dates (name, sport, planned minutes, whether it's already on their Garmin watch, the goal it belongs to), plus rest days and empty days. Default: today and the next 13 days; max 120 days. Refer to workouts by name and date, not id.

get_calendar

Use this for what the athlete can do now. kind: best_efforts (fastest times or highest powers over standard distances/durations, with the session each came from), race_prediction (running only: 5k, 10k, half, marathon or a custom distance, with confidence and the effort it rests on), thresholds (estimated max/threshold heart rate, threshold pace, FTP and swim CSS from their activities, to compare with what's in their profile), power_curve (best power for each duration, cycling). range: 4w, 12w, 26w or 52w (best_efforts, power_curve).

get_performance