> ## 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.

# Routine tools — manage Hevy workout routines and folders

> Reference for all 5 Hevy MCP routine tools: search-routines, get-routines, get-routine, create-routine, update-routine, plus 3 routine folder tools.

Hevy MCP provides **5 routine tools** for browsing, searching, and managing saved workout plans, plus **3 folder tools** for organizing routines into named groups. Read-only tools are safe for exploration at any time; write tools create or replace data and are annotated as mutations so compatible MCP clients can request confirmation before executing.

<CardGroup cols={2}>
  <Card title="search-routines" icon="magnifying-glass" href="#search-routines">
    Find routine IDs by title substring with compact metadata
  </Card>

  <Card title="get-routines" icon="list" href="#get-routines">
    Paginated list of routines with full exercise configuration
  </Card>

  <Card title="get-routine" icon="eye" href="#get-routine">
    Single routine with full exercise configuration by ID
  </Card>

  <Card title="create-routine" icon="plus" href="#create-routine">
    Create a new reusable workout plan
  </Card>

  <Card title="update-routine" icon="pen" href="#update-routine">
    Replace an existing routine's content
  </Card>

  <Card title="Folder tools" icon="folder" href="#get-routine-folders">
    Browse, fetch, and create routine folders
  </Card>
</CardGroup>

***

## search-routines

**Read-only.** Discovers routines by title and returns compact metadata without full set payloads. Scans all routine pages (at `pageSize` 10 internally) and filters by title substring.

* **Kind:** Read-only

<Tip>
  Use `search-routines` first to find a routine ID or shortlist plans, then call `get-routine` for the full exercise configuration of a specific routine.
</Tip>

### Input parameters

<ParamField query="query" type="string">
  Optional case-insensitive substring to match against routine titles. Omit to return the first `limit` routines across all pages.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum number of compact routines to return. Must be between **1** and **100**.
</ParamField>

### Response fields

Each result in the returned array contains:

| Field           | Type           | Description                                  |
| --------------- | -------------- | -------------------------------------------- |
| `id`            | string         | Routine ID, usable directly in `get-routine` |
| `title`         | string         | Routine title                                |
| `folderId`      | number \| null | Folder the routine belongs to, or `null`     |
| `updatedAt`     | string         | ISO 8601 timestamp of last modification      |
| `exerciseCount` | integer        | Number of exercises in the routine           |
| `setCount`      | integer        | Total number of sets across all exercises    |

<Note>
  Full set payloads (weights, reps, distances, etc.) are intentionally omitted from results. Call `get-routine` with the returned `id` to access the complete exercise configuration.
</Note>

***

## get-routines

**Read-only.** Lists custom and default workout routines with their full exercise configuration, paginated.

* **Kind:** Read-only

### 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 routines per page. Must be between **1** and **10**.
</ParamField>

<Note>
  `pageSize` is capped at **10**. Use `search-routines` when you need to scan across all routines for a specific title.
</Note>

***

## get-routine

**Read-only.** Retrieves one routine and its complete exercise configuration by ID.

* **Kind:** Read-only

### Input parameters

<ParamField query="routineId" type="string" required>
  The ID of the routine to retrieve. Must be a non-empty string. Obtain this from `get-routines`, `search-routines`, or a prior `create-routine` response.
</ParamField>

***

## create-routine

**Write (mutation).** Creates a new workout routine in the Hevy account, including its exercise list and set configuration.

* **Kind:** Write

<Warning>
  This operation **cannot be undone**. Retrying on failure can create duplicate routines with identical titles. Verify the routine does not already exist with `search-routines` before calling this tool.

  Non-fixed rep ranges (where `repRange.start` ≠ `repRange.end`) may not display correctly in Hevy mobile and web apps, even though the data is stored.
</Warning>

### Input parameters

<ParamField body="title" type="string" required>
  Routine title. Must be at least **1 character**.
</ParamField>

<ParamField body="notes" type="string">
  Optional free-text notes attached to the routine.
</ParamField>

<ParamField body="folderId" type="number | null">
  Optional ID of the routine folder to place this routine in. Use `get-routine-folders` to discover valid folder IDs.
</ParamField>

<ParamField body="exercises" type="array" required>
  Array of exercise objects. Each exercise requires the following fields:

  <Expandable title="Exercise object fields">
    <ParamField body="exerciseTemplateId" type="string" required>
      Non-empty ID of the exercise template. Use `search-exercise-templates` to look up IDs by name.
    </ParamField>

    <ParamField body="supersetId" type="number | null">
      Numeric superset group identifier. Exercises sharing the same `supersetId` are grouped as a superset. Pass `null` for no superset.
    </ParamField>

    <ParamField body="restSeconds" type="integer">
      Rest period after this exercise in seconds. Must be **≥ 0**.
    </ParamField>

    <ParamField body="notes" type="string">
      Optional per-exercise notes.
    </ParamField>

    <ParamField body="sets" type="array" required>
      Array of set objects for this exercise.

      <Expandable title="Set object fields">
        <ParamField body="type" type="string" default="normal">
          Set type. One of `warmup`, `normal`, `failure`, or `dropset`.
        </ParamField>

        <ParamField body="weightKg" type="number">
          Load in kilograms. Pass `null` or omit for bodyweight or duration exercises.
        </ParamField>

        <ParamField body="reps" type="integer | null">
          Target rep count. Pass `null` for duration-based sets.
        </ParamField>

        <ParamField body="distanceMeters" type="integer">
          Distance in meters, for distance-based exercises.
        </ParamField>

        <ParamField body="durationSeconds" type="integer">
          Duration in seconds, for timed exercises.
        </ParamField>

        <ParamField body="customMetric" type="number">
          Custom numeric metric value when the exercise type uses a custom metric.
        </ParamField>

        <ParamField body="repRange" type="object">
          Optional target rep range object. When provided, overrides a fixed `reps` value in the Hevy UI.

          <Expandable title="repRange fields">
            <ParamField body="start" type="integer | null">
              Lower bound of the rep range (e.g., `8` for "8–12 reps").
            </ParamField>

            <ParamField body="end" type="integer | null">
              Upper bound of the rep range (e.g., `12` for "8–12 reps").
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Example

```json theme={null}
{
  "title": "Upper Body Push",
  "notes": "Monday session",
  "folderId": null,
  "exercises": [
    {
      "exerciseTemplateId": "A10D7A3C-B607-4B4B-B85D-5C9C86C71C63",
      "supersetId": null,
      "restSeconds": 120,
      "notes": "Focus on chest stretch",
      "sets": [
        { "type": "warmup", "weightKg": 40, "reps": 15 },
        { "type": "normal", "weightKg": 80, "repRange": { "start": 8, "end": 12 } },
        { "type": "normal", "weightKg": 80, "repRange": { "start": 8, "end": 12 } }
      ]
    }
  ]
}
```

***

## update-routine

**Write (mutation).** Replaces an existing routine's title, notes, and complete exercise list.

* **Kind:** Write

<Warning>
  The `exercises` array is a **full replacement** — exercises not included in the payload are permanently removed from the routine. Always pass the complete desired exercise list.

  Non-fixed rep ranges (where `repRange.start` ≠ `repRange.end`) may not display correctly in Hevy mobile and web apps.
</Warning>

### Input parameters

<ParamField body="routineId" type="string" required>
  ID of the routine to update. Must be a non-empty string. Obtain this from `get-routines` or `search-routines`.
</ParamField>

<ParamField body="title" type="string" required>
  Updated routine title. Must be at least **1 character**.
</ParamField>

<ParamField body="notes" type="string">
  Optional free-text notes. Omit to clear existing notes.
</ParamField>

<ParamField body="exercises" type="array" required>
  Complete replacement list of exercise objects. Uses the same shape as [`create-routine`](#create-routine) exercises — see that section for the full field reference including `sets`, `restSeconds`, `supersetId`, and `repRange`.
</ParamField>

***

## Routine folder tools

Routine folders let you group related routines (e.g., "Strength Block", "Cardio Week"). Use `get-routine-folders` to discover folder IDs before creating routines that reference a `folderId`.

***

## get-routine-folders

**Read-only.** Lists all default and custom routine folders, paginated.

* **Kind:** Read-only

### 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 folders per page. Must be between **1** and **10**.
</ParamField>

***

## get-routine-folder

**Read-only.** Retrieves metadata for a single routine folder by ID.

* **Kind:** Read-only

### Input parameters

<ParamField query="folderId" type="string" required>
  The ID of the folder to retrieve. Must be a non-empty string. Obtain this from `get-routine-folders` or a prior `create-routine-folder` response.
</ParamField>

***

## create-routine-folder

**Write (mutation).** Creates a new routine folder in the Hevy account.

* **Kind:** Write

<Warning>
  Retrying on failure, or reusing a folder name, can create **duplicate folders**. Check for an existing folder with `get-routine-folders` before creating a new one.
</Warning>

### Input parameters

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

### Example

```json theme={null}
{
  "name": "Strength Block – Q1"
}
```

***

## Recommended workflow

```text theme={null}
1. search-routines (query="push")       → find the routine ID
2. get-routine (routineId="abc123")     → inspect full exercise details
3. update-routine (routineId="abc123")  → make changes with the full exercises list
```

For creating a new routine inside a folder:

```text theme={null}
1. get-routine-folders                            → list folders
2. create-routine-folder (name="New Block")       → create if needed
3. search-exercise-templates (query="bench press") → resolve template IDs
4. create-routine (folderId=..., exercises=[...]) → create the routine
```