> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chrisdoc.dev/hevy-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Exercise template tools — search and manage Hevy exercises

> Reference for all 5 Hevy MCP exercise template tools: get-exercise-templates, get-exercise-template, search-exercise-templates, create-exercise-template, and get-exercise-history.

Hevy MCP provides **5 exercise template tools** for browsing, searching, and creating exercises in your Hevy catalog, plus querying the historical performance of any individual movement. Read-only tools are safe for exploration at any time; `create-exercise-template` is a write tool that adds a custom exercise to your account.

<CardGroup cols={2}>
  <Card title="search-exercise-templates" icon="magnifying-glass" href="#search-exercise-templates">
    Find templates by name substring across the full catalog
  </Card>

  <Card title="get-exercise-templates" icon="list" href="#get-exercise-templates">
    Paginated catalog browsing with muscle and equipment metadata
  </Card>

  <Card title="get-exercise-template" icon="eye" href="#get-exercise-template">
    Complete metadata for one template by ID
  </Card>

  <Card title="create-exercise-template" icon="plus" href="#create-exercise-template">
    Create a custom exercise template
  </Card>

  <Card title="get-exercise-history" icon="chart-line" href="#get-exercise-history">
    Past performed sets for a single exercise
  </Card>
</CardGroup>

***

## get-exercise-templates

**Read-only.** Lists default and custom exercise templates with equipment and muscle metadata, paginated.

* **Kind:** Read-only

<Note>
  `pageSize` supports up to **100** for exercise templates — a higher limit than other paginated tools. Use `search-exercise-templates` for a name-based lookup that scans the full catalog without paging manually.
</Note>

### Input parameters

<ParamField query="page" type="integer" default="1">
  Page number to retrieve. Must be **≥ 1**.
</ParamField>

<ParamField query="pageSize" type="integer" default="5">
  Number of templates per page. Must be between **1** and **100**.
</ParamField>

### Response fields

Each template in the list includes:

| Field                  | Type      | Description                                                         |
| ---------------------- | --------- | ------------------------------------------------------------------- |
| `id`                   | string    | Template ID usable in workouts and routines                         |
| `title`                | string    | Display name of the exercise                                        |
| `exercise_type`        | string    | How the exercise is tracked (see [enum values](#valid-enum-values)) |
| `equipment_category`   | string    | Equipment type (see [enum values](#valid-enum-values))              |
| `primary_muscle_group` | string    | Primary muscle targeted (see [enum values](#valid-enum-values))     |
| `other_muscles`        | string\[] | Secondary muscles involved                                          |
| `is_custom`            | boolean   | `true` for user-created templates                                   |

***

## get-exercise-template

**Read-only.** Retrieves complete metadata for a single exercise template by ID.

* **Kind:** Read-only

### Input parameters

<ParamField query="exerciseTemplateId" type="string" required>
  The ID of the exercise template to retrieve. Must be a non-empty string. Obtain this from `get-exercise-templates`, `search-exercise-templates`, a workout, or a routine.
</ParamField>

***

## search-exercise-templates

**Read-only.** Searches the full exercise template catalog by case-insensitive title substring. Results are served from an in-memory cache that is refreshed at most once every 5 minutes, avoiding repeated full-catalog fetches.

* **Kind:** Read-only

<Tip>
  Always call `search-exercise-templates` before creating a workout or routine to resolve exercise names to their `exerciseTemplateId` values. This is the fastest way to find IDs without paging through the full catalog.
</Tip>

### Input parameters

<ParamField query="query" type="string" required>
  Case-insensitive substring to match against exercise template titles. Must be at least **1 character**. For example, `"bench"` matches "Barbell Bench Press", "Dumbbell Incline Bench Press", and similar.
</ParamField>

<ParamField query="primaryMuscleGroup" type="string">
  Optional filter. When provided, only templates whose primary muscle group matches this value are returned. Must be one of the valid [muscle group enum values](#muscle-group-musclegroup).
</ParamField>

<ParamField query="refresh" type="boolean" default="false">
  Set to `true` to invalidate the in-memory catalog cache and re-fetch all exercise templates from the Hevy API before searching. Use this when you suspect recently created templates are missing from results.
</ParamField>

### Cache behavior

| Property         | Detail                                                        |
| ---------------- | ------------------------------------------------------------- |
| TTL              | 5 minutes from last fetch                                     |
| Capacity         | One catalog (all templates) per server instance               |
| Concurrent loads | Shared in-flight fetch — parallel requests wait on one load   |
| Invalidation     | Pass `refresh: true`, or wait for the TTL to expire           |
| Hosted endpoint  | Each Worker request gets a fresh cache — no cross-key sharing |

<Note>
  `get-exercise-templates` (paginated) always bypasses the cache and fetches directly from the API. The cache is shared only by `search-exercise-templates` and the `hevy://exercise-templates` resource.
</Note>

***

## create-exercise-template

**Write (mutation).** Creates a custom exercise template in the Hevy account.

* **Kind:** Write

<Warning>
  Run `search-exercise-templates` first — Hevy ships hundreds of built-in templates and the exercise you need likely already exists. Retrying on failure, or reusing a title, can create **duplicate templates** in your catalog.
</Warning>

### Input parameters

<ParamField body="title" type="string" required>
  Display name of the new exercise. Must be at least **1 character**.
</ParamField>

<ParamField body="exerciseType" type="string" required>
  How the exercise is tracked. Must be one of the valid [exercise type enum values](#exercise-type-exercisetype).
</ParamField>

<ParamField body="equipmentCategory" type="string" required>
  Equipment used for the exercise. Must be one of the valid [equipment category enum values](#equipment-category-equipmentcategory).
</ParamField>

<ParamField body="muscleGroup" type="string" required>
  Primary muscle group targeted. Must be one of the valid [muscle group enum values](#muscle-group-musclegroup).
</ParamField>

<ParamField body="otherMuscles" type="string[]" default="[]">
  Secondary muscles involved. Each value must be a valid [muscle group enum value](#muscle-group-musclegroup). Defaults to an empty array.
</ParamField>

### Example

```json theme={null}
{
  "title": "Reverse Nordic Curl",
  "exerciseType": "bodyweight_reps",
  "equipmentCategory": "none",
  "muscleGroup": "quadriceps",
  "otherMuscles": ["hamstrings"]
}
```

***

## get-exercise-history

**Read-only.** Retrieves past performed sets for a single exercise template, optionally filtered by date range.

* **Kind:** Read-only

<Tip>
  Use `get-exercise-history` to analyze the performance trend for a single movement — e.g., progressive overload on bench press over 12 weeks. For complete session details, use `get-workouts` instead.
</Tip>

### Input parameters

<ParamField query="exerciseTemplateId" type="string" required>
  The ID of the exercise template whose history you want. Must be a non-empty string. Use `search-exercise-templates` to resolve a name to an ID.
</ParamField>

<ParamField query="startDate" type="string">
  Optional start of the date range. Must be an **ISO 8601 datetime with timezone offset**, e.g. `2024-01-01T00:00:00+00:00`. Workouts before this timestamp are excluded.
</ParamField>

<ParamField query="endDate" type="string">
  Optional end of the date range. Must be an **ISO 8601 datetime with timezone offset**, e.g. `2024-03-31T23:59:59+00:00`. Workouts after this timestamp are excluded.
</ParamField>

### Example

```json theme={null}
{
  "exerciseTemplateId": "A10D7A3C-B607-4B4B-B85D-5C9C86C71C63",
  "startDate": "2024-01-01T00:00:00+00:00",
  "endDate": "2024-03-31T23:59:59+00:00"
}
```

***

## Valid enum values

The following enum values are the only accepted strings for the `exerciseType`, `equipmentCategory`, and `muscleGroup` parameters. All values are taken directly from the server source.

### Exercise type (`exerciseType`)

| Value                      | Description                                                    |
| -------------------------- | -------------------------------------------------------------- |
| `weight_reps`              | Weighted exercise tracked by reps (e.g., barbell squat)        |
| `reps_only`                | Rep-counted exercise with no load (e.g., pull-ups with weight) |
| `bodyweight_reps`          | Bodyweight exercise tracked by reps (e.g., push-ups)           |
| `bodyweight_assisted_reps` | Assisted bodyweight exercise tracked by reps                   |
| `duration`                 | Timed exercise with no distance or load (e.g., plank)          |
| `weight_duration`          | Weighted timed exercise (e.g., weighted wall sit)              |
| `distance_duration`        | Distance and time exercise (e.g., running, cycling)            |
| `short_distance_weight`    | Short distance with load (e.g., sled push)                     |

### Equipment category (`equipmentCategory`)

| Value             | Description                    |
| ----------------- | ------------------------------ |
| `none`            | No equipment / bodyweight      |
| `barbell`         | Barbell                        |
| `dumbbell`        | Dumbbell                       |
| `kettlebell`      | Kettlebell                     |
| `machine`         | Weight machine                 |
| `plate`           | Weight plate                   |
| `resistance_band` | Resistance band                |
| `suspension`      | Suspension trainer (e.g., TRX) |
| `other`           | Other / unlisted equipment     |

### Muscle group (`muscleGroup`)

Used for both `muscleGroup` (primary) and `otherMuscles` (secondary) fields on `create-exercise-template`, and for `primaryMuscleGroup` on `search-exercise-templates`.

| Value        | Muscle / Region          |
| ------------ | ------------------------ |
| `abdominals` | Abdominals / core        |
| `shoulders`  | Shoulders (deltoids)     |
| `biceps`     | Biceps                   |
| `triceps`    | Triceps                  |
| `forearms`   | Forearms                 |
| `quadriceps` | Quadriceps               |
| `hamstrings` | Hamstrings               |
| `calves`     | Calves                   |
| `glutes`     | Glutes                   |
| `abductors`  | Hip abductors            |
| `adductors`  | Hip adductors            |
| `lats`       | Latissimus dorsi         |
| `upper_back` | Upper back (rhomboids)   |
| `traps`      | Trapezius                |
| `lower_back` | Lower back / erectors    |
| `chest`      | Chest (pectorals)        |
| `cardio`     | Cardiovascular / general |
| `neck`       | Neck                     |
| `full_body`  | Full body / compound     |
| `other`      | Other / unlisted         |

***

## Recommended workflow

```text theme={null}
# Discover a template ID before building a workout or routine
1. search-exercise-templates (query="squat", primaryMuscleGroup="quadriceps")
   → returns matching templates with IDs

# Inspect a specific template
2. get-exercise-template (exerciseTemplateId="...")
   → full metadata including exercise type and muscle groups

# Analyze performance over time
3. get-exercise-history (exerciseTemplateId="...", startDate="...", endDate="...")
   → all logged sets for that movement in the date window

# Create a custom exercise only if it doesn't already exist
4. create-exercise-template (title="...", exerciseType="...", ...)
   → new template added to your Hevy catalog
```