List the user's workouts in reverse-chronological order.

Use this first when the user asks about "recent workouts", "last N sessions", "what did I train on Monday", etc. Each item is a summary; call get_workout(workout_id) for full set-by-set detail when the user asks about specific weights, RPE, or progression.

Fetch a single workout with every set, rep, weight, RPE, and note.

Use this when the user asks about a specific workout or wants to compare sets across sessions. Pair with list_workouts to discover the id first.

Total number of workouts the user has logged. Cheap; safe to call eagerly.

Stream of workout change events (created/updated/deleted).

Use to detect new workouts since a previous interaction without re-paginating the full list. The since parameter is ISO-8601 (e.g. 2025-01-01T00:00:00Z).

Log a completed workout to Hevy.

workout shape: { title, description?, start_time, end_time, is_private?, exercises: [ { exercise_template_id, notes?, superset_id?, sets: [ { type, weight_kg?, reps?, rpe?, distance_meters?, duration_seconds? } ] } ] }

Resolve exercise_template_id values via search_exercise_templates before calling this tool — never invent IDs.

Replace the contents of an existing logged workout. Same payload shape as create_workout.

List the user's saved routines (templates they follow). Paginated.

Fetch a single routine with every exercise and target set.

Create a new routine.

Required routine shape: { title, folder_id?, notes?, exercises: [ { exercise_template_id, rest_seconds?, notes?, sets: [ { type, weight_kg?, reps?, rpe? } ] } ] }

WORKFLOW for natural-language requests:

1. Resolve every exercise name to a template id with search_exercise_templates.

2. (Optional) Create or look up the target folder with the folder tools.

3. Call this tool. If a routine with the same title already exists in the folder you'll get back a duplicate_of payload — confirm with the user, then re-call with force=True (or call update_routine instead).

Update an existing routine in place.

Same payload shape as create_routine.routine, with one important caveat: Hevy's PUT endpoint does NOT accept folder_id, and there is no public API endpoint for moving a routine between folders. If folder_id is present in the payload it is silently stripped and a warning is included in the response. To 'move' a routine, create a new copy in the target folder and delete the old one in the Hevy app.

List the user's routine folders (e.g. 'Push/Pull/Legs', 'Hypertrophy Block').

Fetch a single routine folder by id.

Create a new routine folder. Returns the new folder including its id, which you can pass to create_routine as folder_id.

Paginated browse of the Hevy exercise library (~400 entries). Cached for 24h.

Prefer search_exercise_templates when looking up a specific exercise — it's far faster than scanning pages.

Fetch a single exercise template by id (the Hevy library entry, not a logged set).

Fuzzy-search the Hevy exercise library. Use this before create_routine or create_workout — it returns the exercise_template_id you need.

• query: free-text exercise name. e.g. "barbell back squat", "incline db press".

• equipment: optional filter, e.g. "barbell", "dumbbell", "cable", "machine", "bodyweight".

• muscle_group: optional filter on primary_muscle_group, e.g. "chest", "lats", "quads".

Returns ranked candidates with id, title, equipment, primary_muscle_group, and a match score 0-100. Pick the top hit unless the user disambiguates.

Return the user's current webhook subscription, if any.

Create or replace the user's webhook subscription.

• url: HTTPS endpoint Hevy will POST events to.

• event_type: e.g. "workout_created". Hevy only accepts one subscription per key.

Delete the active webhook subscription.

Estimate the user's 1RM on a given exercise from their recent top sets.

Walks the user's workouts (newest first), gathers every set of the target exercise, and applies a strength formula:

• "epley": weight * (1 + reps/30)

• "brzycki": weight * 36 / (37 - reps)

Returns the highest e1RM observed plus the contributing set, plus a short recent history. Skips warmups and reps>15 (formulas are unreliable past that).

Aggregate working-set volume (kg lifted) by primary muscle group over a window.

Useful for "which muscle groups have I been neglecting?" prompts. Volume per set = weight_kg * reps; warmups excluded. Requires the template list to be loaded (it will be cached on first call).

Top-set e1RM over time for a single exercise. Returns a per-session series suitable for charting.