trail-factors

Overview Schema Source Related Servers Discussions Admin

max_hr_over

Find the peak heart rate across selected runs, report the run that produced it, and compare the recorded peak with the 30-second sustained peak.

Instructions

The highest heart rate in a selection, and the run that produced it (§6.0).

TWO CEILINGS, and the difference between them is the point.
`max_hr_recorded` is the single highest sample -- what the watch displayed,
and a SPIKE CANDIDATE, because a maximum selects for positive measurement
error. `max_hr_30s` is the highest 30 s rolling mean with §15.4-flagged
records excluded, and it is the defensible figure. When the two come from
DIFFERENT runs, the corpus's highest spike and its highest sustained effort
are not the same session, and `same_run` says so.

EACH WINNER CARRIES ITS CIRCUMSTANCES: date, run_id and dew point. **A
maximum found on a hot run is a different fact from one found on a hard
effort** -- neither disqualifies a peak, and both change what anchoring a
zone scale to that peak would mean. run_type is null and labelled "not
collected": this build has no source for it.

`declared_ceiling` compares the corpus peak against the max HR the athlete's
zones are actually anchored to (§14e). It is REPORTED, never corrected:
re-anchoring zones is an athlete decision with a coach behind it.

THE COMPARISON IS GATED ON THE SELECTION ITSELF. It is reported only when
a run IN THIS SELECTION reached within the ceiling band of the
demonstrated 30 s ceiling; otherwise it is REFUSED, naming the
selection's best 30 s value and the band. Over easy runs the gap measures
the selection, not the heart.

Input Schema

Name	Required	Description	Default
`last_n`	No
`cluster`	No
`end_date`	No
`run_type`	No
`direction`	No
`segment_id`	No
`start_date`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 2, 2026

TDQS

A3.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it flags max_hr_recorded as a spike candidate selected for positive measurement error, discloses that §15.4-flagged records are excluded from the 30 s ceiling, states that run_type is null by design, and explains that declared_ceiling is reported but never corrected. It also documents the gated/refusal behavior of the comparison and names what it returns when refused, which is exactly the behavioral context structured fields don't supply.

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

Conciseness3/5

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

The first sentence is well front-loaded, but the body is long for a small result object and spends much of its length on emphasized editorial framing (ALL CAPS, bold, §-references) rather than new information. The core facts are present but padded.

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

Completeness3/5

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

An output schema exists, so return-value explanation is legitimately omitted, and the behavioral/semantic side of the result is thoroughly covered. What is missing is the input side: with seven undocumented optional parameters and no required ones, an agent lacks enough guidance to construct a meaningful selection, which is the one thing this tool cannot work without.

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

Parameters2/5

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

Seven parameters with 0% schema description coverage, and the description never mentions any of them by name. It repeatedly refers to 'a selection' and 'IN THIS SELECTION' but never says which of last_n, cluster, start_date, end_date, run_type, direction, or segment_id define that selection or how they combine. For a tool whose entire output depends on the selection boundary, this is a significant compensation failure.

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

Purpose4/5

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

The opening sentence names a specific resource ('the highest heart rate in a selection') and states that it returns the producing run, then splits the result into two named measures (max_hr_recorded vs max_hr_30s). It is a clear verb+resource statement, but it never positions itself against siblings like delta_hr, hr_above, or basic_metrics, so an agent must infer that this is the peak-value tool rather than a distribution or threshold tool.

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?

Usage context is implied rather than stated: 'Over easy runs the gap measures the selection, not the heart' is a caution about interpreting the result, not an instruction on when to call this versus delta_hr or hr_above. No explicit when/when-not/alternatives appear anywhere in the text.

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