ham.run

Generate a single structured running workout

generate_workout

Read-onlyIdempotent

Produce one concrete running session from the desired stimulus (recovery, endurance, marathon pace, threshold, VO2max, speed, or mixed) and training phase, scaled to fitness anchored by any recent race time via the Riegel power law. Prescriptions follow Daniels-style time-domain quality windows converted to track-friendly distances at the athlete’s own paces. Deterministic for a given seed — vary the seed for a different workout of the same type. Source: ham.run workout generator module.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`seed`	Yes	Random seed. Same inputs + same seed reproduce the identical workout; change it to regenerate.
`phase`	Yes	Training phase — shapes eligible workouts, doses, and the reference copy.	build
`raceTime`	Yes	Recent race time for that distance (current fitness, not a goal).
`stimulus`	Yes	What the session should train: recovery \| endurance \| marathon \| threshold \| vo2max \| speed \| mixed.
`raceDistance`	Yes	Distance of the anchor race used to derive paces.	marathon
`timeBudgetMin`	No	Total session cap in minutes (including warm-up/cool-down). Omit for no cap.
`speedAdjustPct`	Yes	Shift all paces together; positive = faster (feeling sharp), negative = slower.

Output Schema

TableJSON Schema

Name	Required	Description
`why`	Yes	Physiological purpose of the session.
`text`	Yes	The full workout as shareable plain text.
`input`	Yes	Echo of resolved input parameters.
`paces`	Yes	Resolved target paces by name (min/km), after any speed adjustment.
`phase`	Yes	Training phase.
`title`	Yes	Workout title.
`totals`	Yes
`citation`	Yes	Literature anchor for the session type.
`shareUrl`	Yes	ham.run link that reproduces this exact workout (seed included) with a Garmin .fit download.
`stimulus`	Yes	Stimulus trained.
`template`	Yes	Template id (stable across regenerations of the same workout type).
`hamFactor`	Yes	How much of a day this session is.
`reference`	Yes	Ability-anchored framing, e.g. which marathoner runs this and when.
`structure`	Yes	The workout, section by section.
`marathonEquivalent`	Yes	Marathon-equivalent time implied by the anchor race (Riegel).

TDQS

A4/5.0

Behavior4/5

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful methodological context (Riegel power law, Daniels-style quality windows) and confirms deterministic behavior via the seed, going beyond annotation-provided information.

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

Conciseness4/5

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

Four sentences that front-load the purpose and each contribute meaning. The source line ('Source: ham.run...') is slightly extraneous, but overall it is well-structured and concise.

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?

Given a rich output schema and comprehensive annotations, the description effectively covers the tool's purpose, scaling method, and determinism. No major gaps for a generation tool of this complexity.

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 coverage is 100% with all parameters described. The description adds some relational context (e.g., race time scaling via Riegel, stimulus/phase interplay), but parameter-level specifics remain primarily in the schema. Modest added value beyond schema.

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 clearly states it produces one concrete running session from a specified stimulus and training phase, with a list of stimulus options. The phrase 'one concrete running session' distinguishes it from the sibling tool generate_training_plan, which presumably generates a full plan.

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

Usage Guidelines3/5

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

The description implies usage for generating a single session but does not explicitly mention when to prefer this over alternatives such as generate_training_plan or pacing_strategy. The 'one concrete running session' provides clear context, but no explicit alternatives or exclusions are stated.

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

All ham.run tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a distinct aspect of endurance running performance: caffeine modeling, fueling, pacing, athlete data, activities, training load, heat acclimation, pacing strategy, periodization, race prediction, and running economy. No overlap.

Naming Consistency3/5

Names use snake_case but mix verb_noun (e.g., get_my_athlete, predict_race_time), noun_verb (periodization_compare), and pure noun (caffeine_protocol, fueling_plan). Inconsistent pattern but still understandable.

Tool Count5/5

11 tools cover the domain of running performance modeling without being too many or too few. Each tool serves a clear purpose within the server's scope.

Completeness4/5

Covers most core areas: personal data retrieval, activity history, training load, and multiple performance models. Minor gaps like workout creation or nutrition beyond fueling plan, but the surface is largely complete for modeling.

Resources

Need Help?