MCP server to read Garmin activities and create/schedule structured workouts and training plans on Garmin Connect.
Strong tool naming (verb-first, clear intent) and comprehensive parameter schemas with types and descriptions. Most tools have good descriptions (100-300 chars). However, output schemas are not documented in the source code, LLMs cannot predict return structures. Error handling is minimal; no recovery guidance or actionable error messages visible. Some complex tools (create_marathon_plan, create_hs_track_plan) have dense descriptions that could be clearer. No tool annotations (readOnlyHint, destructiveHint) despite clear risk stratification in comments.
Read-only: summarise recent training, and size the gap to a marathon goal. With no goal, returns the fitness snapshot alone (weekly mileage, longest run, run frequency, best recent effort). With `goal_time` ('3:15:00') and `race_date` ('2027-04-19'), also returns what the goal asks for, what a safe ramp from here actually reaches, and — when those disagree — the goal this runway does support.
Remove all scheduled workouts from the calendar. Use with caution.
Build the Chevron Houston Marathon 24-week block (Aug 2026 - Jan 2027, sub-3:00 goal). Reads recent Garmin activity to confirm the athlete is in the ballpark, then schedules the full hand-written block with all race-week adjustments, heat allowances, and nutrition/recovery guidance. dry_run=True validates without sending to Garmin.
Build a high-school track block toward a goal time for 800m, 1600m, 3200m, or 5K. Reads recent Garmin activity (unless `use_garmin_history=False` or `current_weekly_miles` is supplied), sizes the gap between current fitness and the goal, and builds a plan with conservative mileage ceilings, mandatory rest days, no doubles, and quality capped at two sessions a week plus a meet. Nutrition guidance runs at `level='hs'` (adequacy-only, no weight targets). dry_run=True validates without sending to Garmin.
Output schemas not documented. LLMs cannot predict return structures for any tool. create_workout returns {workoutId, name, scheduled?}, but this is inferred from code, not declared in schema. Agents cannot plan downstream calls or extract fields reliably.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Server code clearly stratifies tools by risk (read, write, plan, destructive), but this is not exposed to the MCP client. Agents cannot distinguish safe from dangerous operations.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2026-07-28+ | v2 |
Build a marathon block for ANY race and ANY goal, scaled to current fitness. Reads recent Garmin activity (unless `use_garmin_history=False` or `current_weekly_miles` is supplied), compares that to what the goal asks for, and builds a plan that ramps from where the runner actually is — 8%/week ceiling, 3-up-1-down, 3-week taper, ending on race day. When the goal doesn't fit the weeks available, the plan is built toward the goal that does, and the report says exactly what the original would have needed. `force_goal=True` overrides that. Two strength sessions land on the calendar every week. The report carries weekly nutrition, hydration and recovery guidance. `heat_penalty_s_per_mile` (25-40 for a Gulf Coast summer) softens early-phase quality paces. dry_run=True validates and reports without sending anything to Garmin.
Create a structured strength/core workout from a spec; optionally schedule it. Exercises are Garmin category/exerciseName pairs (e.g. category 'PLANK', exercise 'SIDE_PLANK'). Each exercise takes either `reps` or `hold` ('45s'), plus sets and rest_s. Lands on the watch as a guided strength workout with named exercises and a rep/hold counter.
Create + schedule a multi-week plan. `items` is a list of {"date": "YYYY-MM-DD", "spec": <WorkoutSpec>}. dry_run=True validates and reports without sending anything to Garmin.
Create a structured running workout from a spec; optionally schedule it. schedule_date is 'YYYY-MM-DD'. With replace=True a same-named workout is overwritten instead of duplicated.
Delete a workout template by id.
Full detail for one activity by id.
Heart-rate zones and related training settings for the athlete.
List recent activities (id, name, type, start time, distance, duration).
Marathons in the catalogue whose next running falls inside the window. Dates are computed from each race's usual scheduling rule and carry a `date_certainty` — confirm with the organiser before entering or booking.
List workouts currently scheduled on the Garmin calendar.
Pick a marathon at random from the catalogue — the 'surprise me' path. The 16-week floor keeps the draw to races there is still time to build for; lower it deliberately if you want a short-runway race.
Schedule an existing workout id on a date ('YYYY-MM-DD').
Remove a scheduled workout occurrence from the calendar.
Complex parameter schemas lack nested documentation. create_marathon_plan accepts 'current_weekly_miles' (optional) but description does not explain units (miles vs km), valid range, or interaction with 'use_garmin_history'. create_hs_track_plan's 'aerobic_reference' is an object with no schema detail visible.
No error handling or recovery guidance in tool descriptions. If create_workout fails (e.g. invalid spec, duplicate name), the description does not explain what went wrong or how to retry. Agents have no guidance on retryability or user-fixable errors.
Descriptions for complex plan-building tools (create_marathon_plan, create_hs_track_plan) are dense and assume domain knowledge. 'heat_penalty_s_per_mile (25-40 for a Gulf Coast summer)' is specific but unclear to non-runners. Descriptions should be self-contained and explain when/why to use each parameter.