Tools
Reference for the 27 tools of the GymUp MCP server.
Every tool acts on the signed-in athlete's own data and needs an active subscription. tools/list returns each tool's description and input schema; this page says what each one is for and how the tools fit together.
- Dates are
YYYY-MM-DD calendar dates. Ranges are half-open: from is included, to is not.
day_index 0 is Monday and 6 is Sunday; 7 is a one-off session added to a single date.day_names has 7 entries, one per weekday, "" for a rest day.- Durations and rest are in seconds, except
log_activity's duration_minutes. Weights are in kilograms.
- A program is either a
draft (off the calendar) or active. An alternating program is an A/B pair: two programs, week A and week B, linked together.
| Tool | What it does |
|---|
search_exercises | Searches the catalog by name (typo-tolerant), muscle, type, equipment or difficulty. Pages of up to 50 (limit, offset, hasMore). Rows carry movement_pattern, mechanic and force; detailed: true adds the parsed muscles. Left/right mirror rows are hidden. |
propose_exercises | Returns the three exercises to offer, best first, each with its probability, plus none_fits. mode: "replace" ranks replacements for exercise_id within its muscle group; mode: "add" ranks additions from the muscles named, or else from the groups the session does not train. Pass the athlete's words in request, a date or day_index, and optionally equipment_for_this_session and declined_exercise_ids. Ranked by a model; see AI usage allowance. |
resolve_exercise_names | Resolves up to 30 English exercise names to catalog ids: up to 3 candidates per name with a similarity score, or no_match. The first step of an import. |
| Tool | What it does |
|---|
get_athlete_profile | The profile (null where unset): name, age, height, weight, gender, training days, volume level, measurements, notes and hard constraints. Also every memory with its id, newest first, up to 200 (memories, memories_truncated), and the periodization state (periodization). |
save_athlete_profile | Updates name, weightKg, measurements, availableTrainingDays, notes and volumeIndicator (1 to 5: 6 to 10 exercises per day). Omitted fields keep their value. A weight or measurement write is also logged as a body-metrics entry; metrics_date logs a past entry without changing the current values. |
get_body_metrics | Body weight and measurements history, one entry per day, newest first. Filters: from, to. Default 90 rows, at most 365. |
save_constraint | Saves a hard constraint applied to every later generation and edit: equipment whitelist (set_equipment, clear_equipment: true lifts it), avoided exercises, avoided muscles, favorite exercises. |
save_memory | Saves a long-term fact about the athlete (a preference, an injury's context), up to 2,000 characters. |
delete_memory | Deletes a memory by the id get_athlete_profile lists. Answers deleted: false for an unknown id. |
| Tool | What it does |
|---|
generate_smart_program | Builds the athlete's next program from their profile, constraints and program history, and saves it as a draft (two drafts for an A/B pair). Main inputs: days_per_week, phase_hint, ab_rotation, day_type_overrides (session types such as legs or push, optionally on a named weekday), region_emphases, muscle_exclusions, sets_per_exercise (2 to 6), exclude_exercise_ids, program_name. freeform_wishes and notes come back verbatim in wishes_without_effect: apply them to the draft with edit_program_day. Returns program_ids, the programs, and where each requested session landed (applied_day_types). |
prepare_user_program | Saves a program the athlete supplies (pasted text, a photo, a PDF, a described workout) as a draft, values kept verbatim. Missing reps and rest get coach defaults, listed in filled_prescriptions; RPE and tempo are never filled. Two alternating weeks go in one call as two programs. phase stores the training phase. |
commit_program_draft | Activates drafts by program_ids at their scheduled dates; an A/B pair activates together. Overlapping active programs stay as they are. |
get_programs | Lists programs, most recently edited first. detail: "summary" (default) gives the 5 most recently edited programs, each with its dates, phase, status, is_current and per-day exercise counts; detail: "rows" gives one row per exercise with its prescription, at most limit rows (default 200, max 1000). Filters: program_id, status, phase_type, from, to, muscle (rows only). Drafts are left out unless status: "draft" or a program_id asks for them (drafts_hidden counts them). |
update_program | Rewrites a whole program with the prescriptions given: name, day_names, dates and every exercise. Left/right pairs are completed and each day is re-ordered by the coach layout; saved constraints are not applied. Refused on the week A program of an A/B pair (AB_PAIR_LEADER_REWRITE): edit pairs day by day. |
edit_program_day | Changes the weekly template with ops applied in order, all or nothing: swap, set (sets, reps, rest, RPE, tempo, duration, note), add, remove, move, group (superset). An add takes the coach's prescription for any field it omits; a swap or a set keeps the row's value for any field it omits. An op can target another day with its own day_index. Applies to both weeks of an A/B pair unless this_week_only: true. |
reschedule_program | Changes a program's start and end dates without touching its exercises. target: "latest_draft" or "active_today" picks the program without an id. An A/B pair moves together. Reports any other active program the new window overlaps (conflicts). Never activates a draft. |
delete_program | Deletes a program, and week B too when deleting week A. Logged workouts stay. Reversible with restore_program. |
restore_program | Restores a deleted program, and its A/B twin when restoring week A. |
| Tool | What it does |
|---|
get_day_session | With date: the sessions the athlete's calendar shows that day, with the full prescription, estimated weights from history, done flags and the athlete's note for the date (logged_note). Without date: the template day of program_id and day_index, drafts included. Dates changed by edit_session show swapped_from and added_for_date. response_format: "detailed" adds media, tutorials and equipment. |
edit_session | Changes the session of one date with the edit_program_day ops plus reset; the weekly template and every other date stay as planned. The first change copies that date's session, so later template edits no longer reach it; reset returns to the plan. An add on a date with no session creates a one-off session (day_index 7, named with name). Adding or removing one side of a left/right pair takes the other unless single_side: true. |
move_session | Moves one planned session to to_date, skips it (no to_date), copies it (copy: true) or trades it with another date's session (swap_with). Logged sets of a session dated today or later move with it. A target that already has a session is refused unless stack: true. Returns a batch_id for revert_session_move. |
revert_session_move | Undoes one move_session or swap_rotation_weeks (scope: "this_week") call by batch_id. Refused with NEWER_BATCHES while a later change touches the same dates. |
swap_rotation_weeks | Inverts weeks A and B of a pair. scope: "this_week" swaps one week (week_of), leaving past, logged and moved dates as planned (skipped), undone by revert_session_move. scope: "permanent" inverts the rest of the program, undone by calling it again. |
| Tool | What it does |
|---|
log_activity | Logs one exercise on a date, replacing any earlier log of it that day. activity_type: "strength" takes up to 20 sets of { reps, weight, rpe?, rest? }; "cardio" takes duration_minutes. Marks it done unless done: false. |
set_exercise_done | Marks an exercise done or not done on a date, keeping its sets. |
delete_activity_log | Deletes the log of one exercise on one date. |
get_activity_logs_raw | Logged exercises, newest first, each with e1rm (Epley, best set of 1 to 15 reps) and volume_load. Filters: exercise_id, from, to, exercise_type, muscle, done (default true). Default 200 rows, at most 1000; continue with cursor set to the previous next_cursor. Aggregate the rows for any custom analysis. |
A write or a refusal returns { success, error_code?, <facts>, suggested_tool?, written? }, with at most one sentence in message. Exceptions: read tools return their data directly, save_memory returns { saved, memory }, delete_memory returns { deleted, memory_id }, and the failures of generate_smart_program and commit_program_draft carry their sentence in error. A refusal names its error_code and, when another tool gets there, suggested_tool. Every write that changes a program, a session, the calendar or a log carries written: { program_ids, dates }. The error reference lists the responses every tool can return.
Every tool declares the standard MCP annotations, so your client can ask before a call or filter tools.
| Annotation | true for |
|---|
readOnlyHint | search_exercises, resolve_exercise_names, get_athlete_profile, get_body_metrics, get_programs, get_day_session, get_activity_logs_raw |
destructiveHint | update_program, edit_program_day, edit_session, move_session, revert_session_move, swap_rotation_weeks, reschedule_program, delete_program, delete_activity_log, delete_memory |
idempotentHint | the read tools, propose_exercises, save_athlete_profile, save_constraint, update_program, reschedule_program, delete_program, restore_program, revert_session_move, log_activity, set_exercise_done, delete_activity_log, delete_memory |
openWorldHint | generate_smart_program, propose_exercises |
The other tools are false on that annotation: generate_smart_program, prepare_user_program, commit_program_draft, save_memory, edit_program_day, edit_session, move_session and swap_rotation_weeks are not idempotent.