intervals-icu-mcp

by hhopke

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

icu_create_workout

Save a reusable workout to a library folder or training plan, without scheduling it on the calendar.

Instructions

Save ONE new reusable workout into a LIBRARY folder or training plan — it does not go on the calendar.

To schedule a workout on a date use icu_create_event. For two or more library workouts use icu_bulk_create_workouts; to change a saved one use icu_update_workout. Make a new folder or plan with icu_create_workout_folder, and put a plan's workouts on the calendar with icu_apply_training_plan.

Input Schema

TableJSON Schema

Name	Required	Description
`day`	No	PLAN folders only: day offset from plan start (0 = day 1 of week 1, 7 = day 1 of week 2). Omit for plain folders.
`name`	Yes	Workout name
`tags`	No	Tags for organizing the library
`color`	No	Custom display color (hex string)
`indoor`	No	Mark as an indoor workout
`target`	No	Device target type: AUTO, POWER, HR, or PACE
`folder_id`	Yes	Existing library folder or plan ID (from icu_get_workout_library)
`athlete_id`	No	Athlete ID (for coaches managing multiple athletes)
`description`	No	Workout steps, parsed the same way as a WORKOUT calendar event. For WORKOUT events the server parses this into structured, device-syncable steps with zones and a training load. Use Intervals.icu workout syntax: one step per line as '- <duration> <target>' (duration FIRST), grouped under Warmup / Main / Cooldown headers. Targets: bike '- 5m 85%', '- 5m Z4', or absolute '- 5m 210w'; HR '- 10m 70-80% HR' or '- 10m 145bpm'; run/swim pace '- 5m Z2 Pace', absolute only with a trailing 'pace' word: '- 5m 4:45/km pace', '- 200mtr 1:45/100m pace' (bare '5:00/km' or '1:45/100m' silently drops); threshold is relative — run '- 25m 100% pace', swim CSS '- 200mtr 100% pace' — the words 'threshold'/'CSS'/'5K pace' are NOT parsed as targets. Add cadence to any step: '- 3m Z2 90rpm'. No target: '- 20m free'. Repeats: put 'Nx' after a section name with steps flat beneath, and leave a blank line before and after the repeat block (without it the repeat silently runs only once) — e.g. 'Main 5x' then '- 3m 110%' / '- 3m 50%'. Ramps: '- 10m ramp 50-70%'. Rest: append 'Ns rest' to a step ('- 200mtr Z2 20s rest') or use a separate '- 20s intensity=rest' step (only intensity=rest exports as a device rest step) — never a bare '- 20s' step (that becomes work, not rest). Durations: 'm'=minutes, 's'=seconds; distance steps use 'mtr'=meters / 'km' / 'yrd' (e.g. swim '- 400mtr Z2 Pace'). Do NOT write '[repeat 5x ...]', nested bullets, or 'Z5 3m' (target before duration). Runs need a pace or HR target — a bare 'Z2' gives no load. Full reference: intervals-icu://workout-syntax resource.
`workout_type`	No	Activity discipline: Ride, Run, Swim, Walk, Hike, WeightTraining, Workout, VirtualRide, VirtualRun, Other (full discipline list: intervals-icu://event-categories resource)
`training_load`	No	Planned training load
`distance_meters`	No	Planned distance in meters
`duration_seconds`	No	Planned duration in seconds

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv5.1.0Sep 17, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a non-read-only, non-destructive write operation. The description adds useful behavioral context beyond that: it saves a single reusable workout to a library or plan, does not touch the calendar, and is not bulk. It doesn't detail potential side effects like duplicate creation on repeated calls, but the idempotentHint=false annotation already signals that risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loads the core purpose and key exclusion, and then efficiently routes to all relevant sibling tools in three sentences. Every sentence adds actionable value with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter write tool with an output schema and 100% schema coverage, the description adequately covers the operation's scope, destination, and sibling alternatives. The detailed parameter semantics and return structure are already handled by the schema, so nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The outer description does not add parameter-level semantics beyond the schema, though the schema itself contains an extensive workout syntax reference for the description parameter. The description's main contribution is clarifying the destination (library folder or plan), which is already partially reflected by folder_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Save'), a precise resource scope ('ONE new reusable workout into a LIBRARY folder or training plan'), and an explicit exclusion ('it does not go on the calendar'). It also differentiates itself from related siblings by naming create_event, bulk_create_workouts, and update_workout.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit routing guidance for exactly when to use this tool versus alternatives: calendar scheduling goes to icu_create_event, multiple library workouts go to icu_bulk_create_workouts, edits go to icu_update_workout, and folder/plan creation goes to icu_create_workout_folder. This leaves no ambiguity about the intended use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server