ham.run

Running economy (Cr) calculator

running_economy

Read-onlyIdempotent

Compute oxygen cost of running (Cr in mL O₂·kg⁻¹·m⁻¹) given pace, gradient, surface, shoe type, and athlete characteristics. Returns full multiplicative breakdown. Source: ham.run running-economy module (Barnes & Kilding 2015 + Minetti 2002).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sex`	No	Athlete sex — affects economy baseline.
`shoes`	Yes	Shoe type — "super" = carbon-plated race shoes.	standard
`vo2max`	No	Estimated VO₂max in mL O₂ · kg⁻¹ · min⁻¹.
`surface`	Yes	Running surface.	road
`gradient`	Yes	Slope as a decimal (0.05 = 5% uphill).
`heightCm`	No	Height in centimetres.
`weightKg`	No	Body weight in kilograms.
`useMyData`	No	Overlay athlete profile data.
`marathonPr`	No	Marathon PR for caliber estimation.
`paceMperMin`	Yes	Running pace in metres per minute. 267 = 16 km/h reference.

Output Schema

TableJSON Schema

Name	Required	Description
`Cr`	Yes	Running economy cost, mL O₂·kg⁻¹·m⁻¹.
`input`	Yes	Echo of resolved input parameters.
`caliber`	Yes	Runner caliber classification.
`kJperKm`	Yes	Energy cost per km, kJ (requires weight).
`breakdown`	Yes	Multiplicative factor breakdown.
`vo2at16kmh`	Yes	Estimated VO₂ at 16 km/h reference pace, mL/kg/min.
`classification`	Yes	Economy tier (e.g. "elite", "good", "average").

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is handled. The description adds value by stating that it returns a 'full multiplicative breakdown' and citing the underlying model sources, giving insight into the calculation and output structure beyond the 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 two sentences, front-loaded with the core action, and includes a source citation that adds credibility without redundancy. Every sentence contributes to understanding the tool's purpose and behavior.

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?

The description is sufficient for selection and invocation: it states purpose, key inputs, and output behavior. With a comprehensive schema and output schema, it doesn't need to explain return values in detail. It could mention scientific limitations or that it's a reference implementation, but that's not essential.

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?

Input schema coverage is 100%, with each parameter having a clear description. The tool description only lists broad parameter categories (pace, gradient, surface, shoe type, athlete characteristics) without adding new meanings or relationships, so it adds minimal value over the 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 uses the specific verb 'Compute' and clearly identifies the resource (running economy/Cr) and what it returns ('full multiplicative breakdown'). It is distinctly different from sibling tools like pacing_strategy or predict_race_time, which address entirely different running metrics.

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 context for use is clear: calculate oxygen cost of running given pace, gradient, surface, shoe type, and athlete characteristics. It doesn't explicitly name alternatives or exclusions, but no sibling tool covers this specific calculation, making the implied usage obvious.

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?