ham.run

Marathon pacing — cardiac drift, hydration, sodium

pacing_strategy

Read-onlyIdempotent

Simulate marathon HR drift and fluid/sodium balance under given heat, sweat, and aid-station conditions. Returns total drift split by cause, decoupling %, kilometre at LT₂ breach, the kilometre where holding pace would demand more than HRmax, plasma sodium, and body-weight loss. Pace at the target %HRR is derived from the athlete's own VO₂max and cost of running, so supply marathonPr or vo2max for a pace specific to them. Source: ham.run HR pacing module. Pass useMyData:true to overlay age + restingHr + weight + VO₂max + PR from the connected athlete profile.

Input Schema

TableJSON Schema

Name	Required	Description
`age`	No	Age in years.
`sex`	No	Athlete sex — affects sweat rate and thermoregulation.
`maxHr`	No	Measured maximum heart rate, bpm. Falls back to age-predicted if omitted.
`tempC`	Yes	Air temperature, °C.
`hrRest`	No	Resting heart rate, bpm.
`vo2max`	No	Used to derive pace at the target %HRR when no marathon PR is given.
`useMyData`	No	Overlay age, resting HR, and weight from the connected athlete profile.
`marathonPr`	No	Marathon PR. Preferred over vo2max for deriving pace: the athlete's cost of running is back-solved from it, so their marathon-effort intensity reproduces this time exactly.
`bodyWeightKg`	No	Body weight in kilograms.
`intensityPct`	Yes	Target effort as % of HRR.
`fluidPerStationMl`	Yes	Fluid intake per aid station, mL.
`sodiumPerStationMg`	Yes	Sodium intake per aid station, mg.
`sweatSodiumMmolPerL`	Yes	Sweat sodium concentration in mmol/L (typical 30–60).
`baselineSweatRateLPerHr`	Yes	Baseline sweat rate, L/hr.

Output Schema

TableJSON Schema

Name	Required	Description
`lt1`	Yes	LT1 heart rate, bpm.
`lt2`	Yes	LT2 heart rate, bpm.
`hrMax`	Yes	Age-predicted or measured max HR, bpm.
`input`	Yes	Echo of resolved input parameters.
`hrStart`	Yes	Starting HR at target intensity, bpm.
`pacingKmh`	Yes	Average pacing speed, km/h.
`finishTime`	Yes	Predicted finish time.
`paceSource`	Yes	What the pace was derived from. "assumed" means neither marathonPr nor vo2max was supplied and a recreational reference VO₂max was used — say so when reporting the finish time.
`vo2maxUsed`	Yes	VO₂max the pace was derived from, mL·kg⁻¹·min⁻¹.
`checkpoints`	Yes	5-km checkpoint data.
`hrCeilingKm`	Yes	Kilometre from which holding this pace would demand a heart rate above HRmax, or null. Non-null means the pace is not sustainable: the athlete slows instead.
`lt2BreachKm`	Yes	Kilometre where HR breaches LT2, or null.
`decouplingPct`	Yes	Cardiac decoupling, %.
`finalPlasmaNa`	Yes	Final plasma sodium, mmol/L.
`totalDriftBpm`	Yes	Total cardiac drift over the marathon, bpm.
`driftBpmByCause`	Yes	Total drift split by cause. Decoupling % alone conflates pacing strain with dehydration, and the two move in opposite directions with intensity.
`pctBodyWeightLost`	Yes	Body weight lost, %.
`dominantDriftCause`	Yes	Which cause contributes the most drift.
`totalFluidDeficitL`	Yes	Total fluid deficit at finish, L.
`marathonEffortPctHrr`	Yes	The %HRR that reproduces this athlete's marathon-effort oxygen uptake — their marathon race intensity.
`totalSodiumDeficitMg`	Yes	Total sodium deficit at finish, mg.
`actualSweatRateLPerHr`	Yes	Temperature-adjusted sweat rate, L/hr.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare this a read-only, idempotent, non-destructive tool. The description adds meaningful behavioral context beyond that: it specifies the computation is a simulation, lists the exact outputs, and reveals that pace is derived from VO₂max/cost of running or marathon PR. It also documents the useMyData overlay behavior, which isn't apparent from annotations or schema.

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 a single, dense paragraph that front-loads the primary purpose, then lists outputs, then explains key derivation logic, then provides source and overlay instruction. Every sentence contributes: no filler or repetition of schema field descriptions. It is longer than two sentences but warranted given the tool's complexity.

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

Completeness4/5

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

Given the tool's complexity (14 params, 6 required) and the presence of an output schema and annotations, the description covers the essential context: what the tool simulates, what it returns, and the critical input relationships. It could go deeper on precedence rules (e.g., if both marathonPr and vo2max are supplied) or interaction with useMyData, but those are edge cases not needed for basic selection and invocation.

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

Parameters4/5

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

The input schema has 100% description coverage, so baseline is 3. The description enhances this by clarifying the relationship between marathonPr and vo2max ('Pace ... is derived ... so supply marathonPr or vo2max'), and by explaining the effect of useMyData in overlaying multiple linked parameters. This goes beyond individual field descriptions.

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 uses the specific verb 'Simulate' with a clear resource: marathon HR drift and fluid/sodium balance. It lists concrete return values (drift split, decoupling %, LT2 breach, plasma sodium, body-weight loss), which distinguishes it from sibling tools like fueling_plan or heat_acclimation_plan.

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

Usage Guidelines4/5

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

The description clearly states its context: 'Simulate marathon HR drift and fluid/sodium balance under given heat, sweat, and aid-station conditions,' which tells an agent when to use it. It also explains how to get a personalized pace ('supply marathonPr or vo2max') and how to overlay athlete data via 'useMyData:true.' However, it does not explicitly name alternatives or exclusion criteria, so it earns a 4 rather than 5.

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?