trail-factors

Overview Schema Source Related Servers Discussions Admin

segment_effort_drift

Computes slope-matched effort heart-rate drift by normalising average HR change over the gap between segment starts; use only when you specifically need this measure instead of matched_terrain_drift.

Instructions

Effort-level HR drift on a matched slope. NOT §6.7 — a DIFFERENT quantity.

Pairs whole effort averages with no speed match and no split_type filter,
and normalises by the gap between effort starts, so a short gap amplifies:
+10 bpm over 10 min reads as +60 bpm/hour. On the same run it can read
several times larger than matched_terrain_drift.

Use `matched_terrain_drift` unless you specifically want the slope-matched
measure. NEVER present either as "the" drift. Read `applied_filters`.

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

Behavior3/5

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

No annotations, so the description carries the full burden. It does disclose real behavioural traits — the gap normalisation amplifies short gaps (+10 bpm over 10 min reads as +60 bpm/hour), the value can be several times larger than matched_terrain_drift on the same run, and the agent should read applied_filters. That is meaningful, but it doesn't state freshness, data source, or what happens when no matched segment exists.

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?

Front-loaded with the metric definition, then the formula caveat, then the routing advice. Prose is compact. The 'NOT §6.7 — a DIFFERENT quantity' line assumes internal spec knowledge and costs a sentence without adding interpretable meaning.

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?

An output schema exists, so return values needn't be described. The description covers what the measure is, how it is scaled, and the caveat against presenting it as canonical drift. It falls short only on the seven undocumented parameters.

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 explains none of them. last_n, cluster, run_type, direction, segment_id, start_date and end_date are all undocumented in both schema and prose. The mention of 'no split_type filter' hints at a filter dimension but doesn't clarify which parameter governs it.

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?

Names a specific metric (effort-level HR drift on a matched segment) and states exactly how it is computed: whole effort averages paired with no speed match, normalised by the gap between effort starts. It is differentiated from its sibling matched_terrain_drift by naming it and describing the divergence. The 'NOT §6.7' framing adds ambiguity for an agent that doesn't know what §6.7 refers to.

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?

Explicit routing: 'Use matched_terrain_drift unless you specifically want the slope-matched measure.' That tells the agent when to prefer the sibling. There is no guidance on the date/cluster/run_type filters or what conditions make this measure the right call beyond the slope note.

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