Workout Tracking tools
Every tool in this module, with its full description, parameters, and return value. All of them require the module to be active first. See the Workout Tracking overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
workout_tracking_log_setLog one or more sets for an exercise in the user's active Workout Tracking module. Finds or creates the workout session for the given date (defaults to today) and finds or creates the exercise within it, then appends set(s). IMPORTANT: when sets share identical reps/weight/RPE, pass sets: N once (e.g. '3 sets of 8 reps at 185 lbs' -> sets: 3, reps: 8, weight_lbs: 185) instead of calling this tool three times. Only call this tool once per set when reps/weight/RPE actually vary set-to-set (e.g. a descending set of sit-ups: 13, 15, 20 reps -> call three times, once per set, passing the first call's returned exercise.id as workout_exercise_id on the 2nd and 3rd calls so they land under the same exercise instead of creating duplicates). Requires the module to be active — see create_database. Resolves the exercise against the exercise catalog automatically when the name is a confident match.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| exercise | string | No | Name of the exercise, e.g. 'Bench Press' or 'Squat'. Required unless workout_exercise_id is given. |
| exercise_id | string | No | Exact exercises.id from workout_tracking_search_exercises, if already known. Skips automatic matching. |
| workout_exercise_id | string | No | Exact workout_exercises.id (from a prior call's response) to append this set to an exercise already logged, instead of resolving by name. |
| workout_id | string | No | Exact workouts.id to log against a specific existing session, instead of resolving by date. |
| date | string | No | Calendar date of the workout session (defaults to today). Finds or creates that day's workout. |
| sets | number | No | Number of identical set rows to insert in this call (default 1). Use for uniform sets. |
| reps | number | No | Number of reps performed per set. |
| weight_lbs | number | No | Weight lifted, in pounds. |
| rpe | number | No | Rate of perceived exertion, 1-10 scale. |
| is_pr | boolean | No | True if this set was a personal record. |
| duration_minutes | number | No | Duration of a cardio effort, in minutes. |
| distance_miles | number | No | Distance covered during a cardio effort, in miles. |
| plan_exercise_id | string | No | Exact workout_plan_exercises.id (from workout_tracking_get_scheduled_workout or workout_tracking_get_plan) this exercise fulfills, if logging against a plan. |
Returns
The workout, the exercise, and the created set(s) as JSON, plus today's scheduled plan exercises if an active plan has any.
workout_tracking_update_setUpdate fields on a single logged set.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| set_id | string | Yes | ID of the workout_sets row to update. |
| reps | number | No | Number of reps performed. |
| weight_lbs | number | No | Weight lifted, in pounds. |
| rpe | number | No | Rate of perceived exertion, 1-10 scale. |
| is_pr | boolean | No | True if this set was a personal record. |
| duration_minutes | number | No | Duration of a cardio effort, in minutes. |
| distance_miles | number | No | Distance covered during a cardio effort, in miles. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
workout_tracking_delete_setDelete a single logged set from an exercise.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| set_id | string | Yes | ID of the workout_sets row to delete. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
workout_tracking_delete_exerciseDelete an exercise logged within a workout, along with all of its sets.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| workout_exercise_id | string | Yes | ID of the workout_exercises row to delete. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
workout_tracking_list_workoutsList logged workout sessions in the user's active Workout Tracking module, most recent date first.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Max entries to return (default 100, max 500). |
Returns
Every workout session in the active database, as a JSON array.
workout_tracking_get_workoutGet a logged workout session along with every exercise logged in it and each exercise's sets.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| workout_id | string | Yes | ID of the workouts row to fetch. |
Returns
The workout nested with its exercises and each exercise's sets, as JSON.
Purpose-built tools
Shortcuts and queries shaped around how Workout Tracking is actually used, so your agent doesn't have to fetch every entry and filter them itself.
workout_tracking_attach_photoAttach a photo to an existing Workout Tracking entry (replacing any photo already on it). If you have the image's raw bytes, pass photo_base64. If the user attached the image in a chat client (e.g. claude.ai), you cannot read its bytes: call this WITHOUT photo_base64 to get a one-time upload link, and give that link to the user so they can upload the photo themselves. The link expires in 30 minutes. Photos are stored privately; the returned viewPath is only viewable signed into the connacto web app as this user.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Workout Tracking entry to attach the photo to. |
| photo_base64 | string | No | The photo, base64-encoded (no data: URI prefix). Omit when you cannot read the image bytes — the tool then returns an upload link for the user instead. |
| photo_content_type | image/jpeg | image/png | image/webp | image/heic | No | MIME type of the photo, if photo_base64 is set. Defaults to image/jpeg. |
Returns
JSON with a private viewPath when photo_base64 was given, or an uploadUrl to hand the user when it was not.
workout_tracking_update_exerciseUpdate fields on an exercise logged within a workout. Its sets are managed separately via workout_tracking_update_set/delete_set.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| workout_exercise_id | string | Yes | ID of the workout_exercises row to update. |
| exercise | string | No | Name of the exercise, e.g. 'Bench Press' or 'Squat'. |
| exercise_id | string | No | Exact exercises.id from workout_tracking_search_exercises. Skips automatic matching. |
| order_index | number | No | Sort order within the workout, lower first. |
| plan_exercise_id | string | No | Exact workout_plan_exercises.id this exercise fulfills, if logging against a plan. |
| notes | string | No |
Returns
Returns the result of this tool call as JSON.
workout_tracking_update_workoutUpdate fields on a logged workout session: its date, label, notes, or which plan day it fulfills.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| workout_id | string | Yes | ID of the workouts row to update. |
| date | string | No | |
| label | string | No | |
| notes | string | No | |
| plan_day_id | string | No | Exact workout_plan_days.id this session fulfills. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_delete_workoutDelete a logged workout session, along with every exercise and set it contains.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| workout_id | string | Yes | ID of the workouts row to delete. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_exercise_historyList every logged set for a specific exercise in the user's active Workout Tracking module, ordered oldest to newest, to show progression over time.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| exercise | string | Yes | Name of the exercise to look up history for, e.g. 'Bench Press'. |
Returns
Every logged set for that exercise, oldest first, as a JSON array.
workout_tracking_personal_recordsList all sets marked as a personal record (PR) in the user's active Workout Tracking module, newest first.
Parameters
None. Call it with an empty object.
Returns
Every set with is_pr true, newest first, as a JSON array.
workout_tracking_search_exercisesLook up candidate exercises by name or alias when the exact match for an entry is unclear. Use the returned id as exercise_id in workout_tracking_log_set or workout_tracking_update_exercise.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| query | string | Yes | Free-text exercise name to search for, e.g. 'bench' or 'goblet squat'. |
| limit | number | No | Max candidates to return (default 5, max 20). |
Returns
Candidate exercises with their muscle group, equipment, and match score, as a JSON array.
workout_tracking_volume_by_muscle_groupSum training volume (reps times weight, summed across every logged set) in the active Workout Tracking module, grouped by primary muscle, joined against the exercise catalog. Sets whose exercise never resolved to the catalog are excluded and counted separately.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| startDate | string | No | |
| endDate | string | No |
Returns
Per-muscle-group volume totals plus a count of sets excluded for lacking a resolved exercise, as JSON.
workout_tracking_list_program_templatesList built-in named workout program templates (e.g. Push/Pull/Legs, PHUL, PHAT, Upper/Lower, Full Body) the user can start with workout_tracking_start_program instead of building a plan by hand. Does not require an active database.
Parameters
None. Call it with an empty object.
Returns
Every template's slug, name, description, and days-per-week, as a JSON array.
workout_tracking_get_program_templateGet the full weekly schedule (every day, its label, rest days, and prescribed exercises with target sets/reps) for one built-in program template. Use this to show the user what a template involves before starting it.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| template_slug | string | Yes | Slug from workout_tracking_list_program_templates, e.g. 'ppl-6day' or 'phul'. |
Returns
The template's full schedule with target sets/reps per exercise, as JSON.
workout_tracking_start_programInstantiate a built-in program template (see workout_tracking_list_program_templates) into a real workout plan for the user's active Workout Tracking module: creates the plan, every scheduled day, and every prescribed exercise in one call. Once started, workout_tracking_get_scheduled_workout (or the scheduledPlan on workout_tracking_log_set) tells you what's prescribed on any given day.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| template_slug | string | Yes | Slug from workout_tracking_list_program_templates, e.g. 'ppl-6day' or 'phul'. |
| start_date | string | Yes | Date the program's weekly schedule is anchored to. The template's day-of-week labels apply from this date forward. |
| name | string | No | Override the plan's name. Defaults to the template's name. |
| deactivate_other_plans | boolean | No | Mark every other plan in this database inactive when starting this one, so there's a single unambiguous current program (default true). Pass false to run this alongside existing plans. |
Returns
The created plan nested with its scheduled days and each day's prescribed exercises, as JSON.
workout_tracking_create_planCreate a workout program in the user's active Workout Tracking module: a name, a start date anchoring day-of-week resolution, and an optional multi-week cycle length for ramping/periodized programs. Add scheduled days with workout_tracking_add_plan_day once created.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | Name of the plan, e.g. '5/3/1 Ramping Block'. |
| description | string | No | Free-text description of the plan. |
| start_date | string | Yes | Date the plan's week 1 / day-of-week schedule is anchored to. |
| num_weeks | number | No | Number of distinct weeks in one cycle, for ramping/periodized plans. Omit for a single weekly template that repeats indefinitely. |
| repeat_cycle | boolean | No | When num_weeks is set, whether the whole block repeats after it ends (default true). false runs the program once. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_list_plansList workout plans in the user's active Workout Tracking module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Max entries to return (default 100, max 500). |
Returns
Returns the result of this tool call as JSON.
workout_tracking_update_planUpdate fields on an existing workout plan. To end/stop/finish the user's current program, set is_active: false here rather than deleting it. To switch to a different program, use workout_tracking_start_program instead, which deactivates the old one automatically.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row to update. |
| name | string | No | |
| description | string | No | |
| start_date | string | No | |
| num_weeks | number | No | |
| repeat_cycle | boolean | No | |
| is_active | boolean | No | Set false to end/stop/pause/retire the plan without deleting it or its history. Set true to resume a previously ended plan. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_delete_planDelete a workout plan and all of its scheduled days and prescribed exercises.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row to delete. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_add_plan_dayAdd a scheduled day to a workout plan: either a recurring weekday slot (day_of_week) or a one-off override for an exact calendar date (specific_date). Exactly one of the two must be given.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row this day belongs to. |
| week_number | number | No | 1-based week within the plan's cycle, for ramping plans. Defaults to 1. |
| day_of_week | number | No | Recurring weekday slot, 0=Sunday..6=Saturday. |
| specific_date | string | No | One-off override for an exact calendar date. Takes precedence over day_of_week on that date. |
| label | string | No | Label for the day, e.g. 'Push Day' or 'Rest'. |
| is_rest_day | boolean | No | |
| notes | string | No |
Returns
Returns the result of this tool call as JSON.
workout_tracking_update_plan_dayUpdate fields on an existing scheduled day of a workout plan.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planDayId | string | Yes | ID of the workout_plan_days row to update. |
| week_number | number | No | |
| day_of_week | number | No | |
| specific_date | string | No | |
| label | string | No | |
| is_rest_day | boolean | No | |
| notes | string | No |
Returns
Returns the result of this tool call as JSON.
workout_tracking_delete_plan_dayDelete a scheduled day from a workout plan, along with its prescribed exercises.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planDayId | string | Yes | ID of the workout_plan_days row to delete. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_add_plan_exerciseAdd a prescribed exercise target to a scheduled workout plan day. Supports strength targets (sets/reps/weight or %1RM/RPE) and cardio targets (duration/distance).
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planDayId | string | Yes | ID of the workout_plan_days row this exercise belongs to. |
| exercise | string | Yes | Name of the exercise, e.g. 'Bench Press' or 'Tempo Run'. |
| exercise_id | string | No | Exact exercises.id from workout_tracking_search_exercises. Skips automatic matching. |
| order_index | number | No | Sort order within the day, lower first. Defaults to 0. |
| target_sets | number | No | |
| target_reps | number | No | |
| target_weight_lbs | number | No | |
| target_percent_1rm | number | No | Prescribed load as a percentage of 1-rep max. |
| target_rpe | number | No | |
| target_duration_minutes | number | No | |
| target_distance_miles | number | No | |
| notes | string | No |
Returns
Returns the result of this tool call as JSON.
workout_tracking_update_plan_exerciseUpdate fields on an existing prescribed exercise target within a workout plan.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planExerciseId | string | Yes | ID of the workout_plan_exercises row to update. |
| exercise | string | No | |
| exercise_id | string | No | |
| order_index | number | No | |
| target_sets | number | No | |
| target_reps | number | No | |
| target_weight_lbs | number | No | |
| target_percent_1rm | number | No | |
| target_rpe | number | No | |
| target_duration_minutes | number | No | |
| target_distance_miles | number | No | |
| notes | string | No |
Returns
Returns the result of this tool call as JSON.
workout_tracking_delete_plan_exerciseDelete a prescribed exercise target from a workout plan day.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planExerciseId | string | Yes | ID of the workout_plan_exercises row to delete. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_get_planGet a workout plan along with all of its scheduled days and each day's prescribed exercises.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row to fetch. |
Returns
Returns the result of this tool call as JSON.
workout_tracking_get_scheduled_workoutResolve what's scheduled on a given date (defaults to today) for a workout plan: a specific_date override if one exists, otherwise the recurring day-of-week template for the plan's current week (accounting for ramping/multi-week cycles). Returns the matched day and its prescribed exercises, or null if nothing is scheduled.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row to resolve against. |
| date | string | No | Date to resolve. Defaults to today (UTC). |
Returns
Returns the result of this tool call as JSON.
workout_tracking_plan_vs_actualFor every prescribed exercise in a workout plan, show its target alongside any logged exercises (and their sets) linked to it via plan_exercise_id on workout_tracking_log_set, plus which prescribed exercises have no matching logged exercise yet.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| planId | string | Yes | ID of the workout_plans row to compare. |
| startDate | string | No | Only consider workouts on or after this date. |
| endDate | string | No | Only consider workouts on or before this date. |
Returns
Returns the result of this tool call as JSON.