trail-factors

Overview Schema Source Related Servers Discussions Admin

hr_above

Finds contiguous heart-rate excursions at or above a threshold and reports each bout's span, peak, mean, and context, so sustained efforts can be distinguished from single spikes.

Instructions

Every contiguous excursion at or above a heart-rate threshold (§14e-ter).

THE UNIT IS THE EXCURSION, NOT THE RECORD. A sustained bout would otherwise
arrive as hundreds of rows and a single spike as one, with nothing in the
shape to tell them apart — which is the whole question when deciding
whether a ceiling is demonstrated or merely recorded.

Each excursion carries the run and date, start offset, span, peak with its
timestamp, mean, the 30 s window CENTRED on the peak, record count,
§15.4 flag count, sampling regime, and pace / grade / cadence. **The same
peak reached while climbing at a walking pace and while running fast on
the flat are different facts about the same heart.**

RAW heart rate, never lag-shifted. FLAGS ARE REPORTED, NOT APPLIED: at the
top of the range a flag may mark a real artifact or a real spike and cannot
settle which. **A run whose peak has unresolved provenance (§14e-bis;
`unresolved_peak_run` in config/athlete.yaml, when set) is MARKED and never
dropped, and every total is reported a second time without it** under
`without_unresolved_peak`.

Args:
    threshold: bpm. 0 (the default) means the configured threshold,
        `hr_above_default_bpm` in config/athlete.yaml -- set it near the
        top of your own HR distribution. `threshold_bpm` in the result
        says which value was used.

Input Schema

Name	Required	Description	Default
`last_n`	No
`cluster`	No
`end_date`	No
`run_type`	No
`direction`	No
`threshold`	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 unusually well: it discloses that HR is raw and never lag-shifted, that flags are reported but not applied, that runs with unresolved peak provenance are marked and never dropped, and that totals are re-reported under without_unresolved_peak. These are exactly the behavioral facts an agent could not infer from 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.

Conciseness3/5

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

The core statement is front-loaded and the key caveats are legible, but the prose is padded with emphatic asides and a rhetorical line about climbing versus flat running that consume space without adding callable information. The heavy capitalization and bold formatting also fight the reader rather than helping.

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 the long enumeration of returned fields (run, date, offset, span, peak, 30 s window, flags, pace/grade/cadence) is largely redundant, while the 7 undocumented filter parameters are the real gap. For an 8-parameter query tool the description is complete on semantics of the data but incomplete on how to scope the query.

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?

Schema description coverage is 0% across 8 parameters, so the description must compensate. It documents only threshold (0 means the configured hr_above_default_bpm, and threshold_bpm in the result echoes the value used); last_n, cluster, start_date, end_date, run_type, direction, and segment_id are left entirely undefined.

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?

States a specific resource and scope: 'Every contiguous excursion at or above a heart-rate threshold,' and explicitly frames the unit of return as an excursion rather than a record. That distinguishes it conceptually from row-per-reading tools, though it never names a sibling like time_above_hr or max_hr_over.

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?

It motivates the tool ('deciding whether a ceiling is demonstrated or merely recorded') and explains the threshold parameter's default, which implies when to reach for it. But it gives no explicit when-not guidance and does not say how it differs from the closely named time_above_hr or max_hr_over siblings.

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