Skip to main content
Glama
cambroussard9

trail-factors

run_walk_cycles

Evaluates whether walk breaks benefit running pace by pairing each walk with the next run block's pace and tracking run pace decay across cycles.

Instructions

M3 run/walk cycle economics — does the walk buy anything? (§17.2)

Args:
    run: run_id, activity_id or Garmin file id. Empty means the latest run.

CHOICE, NOT CAPACITY (§6.6). This is how the athlete elected to structure
the run; it says nothing about what they could have done.

`purchase` pairs each walk with the NEXT run block's pace; `decay` is run
pace by cycle index. Both are PAIRED SERIES, never a fitted slope — time
into the run confounds both, and a coefficient over four points is wider
than itself. Read `elapsed_at_*` before concluding the walk caused anything.

Run blocks under the 120 s pace gate report duration but no pace.

WHAT GOVERNED THE WALKS DECIDES WHAT THIS MEASURES, and this build does
not know. If a rule (an HR cap, a clock) decided them, purchase and decay
measure what the STRUCTURE delivered; if the athlete walked when they felt
like it, identical arithmetic measures WILLINGNESS. `walk_protocol` is
"not collected" here, so `poolable_with_other_runs` is false on every run:
structure that has not been established cannot be assumed. Read each run
on its own.

Input Schema

NameRequiredDescriptionDefault
runNo
last_nNo
clusterNo
end_dateNo
run_typeNo
directionNo
segment_idNo
start_dateNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.3/5.0
Behavior5/5

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

With no annotations provided, the description carries the behavioral burden and does so richly: it states that walk protocol is not collected, `poolable_with_other_runs` is false, sub-120s blocks lack pace, and the measures are paired series rather than fitted slopes. It also warns that identical arithmetic can mean structure or willingness depending on what governed the walks.

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 description is front-loaded with the purpose and important caveats, and much of the length is justified by the complexity. However, it includes dense internal references and rhetorical framing, while its Args section covers only one of eight parameters, making the structure uneven.

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 values do not need full explanation in the description. But with no annotations, eight mostly undocumented parameters, and only partial usage guidance, an agent still lacks enough context to confidently use all filtering options.

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% and there are eight parameters, but the description explains only `run`, including accepted ID types and that an empty value means the latest run. The other seven parameters (`last_n`, `cluster`, date bounds, `run_type`, `direction`, `segment_id`) are left undocumented.

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 description clearly states the tool computes run/walk cycle economics and explains the `purchase` and `decay` measures. It is specific but relies on internal labels like M3 and §17.2, and does not explicitly differentiate itself from sibling analytics tools.

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

Usage Guidelines2/5

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

The description gives interpretation caveats, such as reading `elapsed_at_*` before concluding causation and reading each run on its own. However, it does not explicitly say when to use this tool versus alternatives like `mile_splits`, `drift_onset`, or other pacing analytics.

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