Skip to main content
Glama
cambroussard9

trail-factors

hill_pace

Computes mean pace and best 30 seconds for every uphill and downhill effort in a run, split by direction, so you can see how each climb and descent was actually run.

Instructions

§6.0g pace on every slope effort of one run, split by direction.

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

Each effort carries mean pace (whole effort, summit to col, moving time)
AND best 30 s (the part actually run fast). They are different quantities —
a slow mean beside a much faster best 30 s is a description of how the
effort was run (walked in part, run in part), not a contradiction.

READ `comparable_ground.length_ratio` BEFORE COMPARING THE DIRECTIONS.
Ascents and descents need not cover the same ground — plateau absorption
can glue flat ground onto one direction (§14k) — so part of
any ascent-vs-descent difference is terrain rather than the athlete.

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.1/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does add substantive behavioral context: it explains that mean pace and best 30 s are different quantities, that a slow mean beside a fast best is not a contradiction, and that ascent-vs-descent comparisons are terrain-confounded. It does not explicitly state read-only behavior or side-effect profile, but for an analytics tool the non-obvious output semantics are well disclosed.

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?

The description is front-loaded with purpose and structured with an Args section, and the interpretive caveats are relevant rather than filler. It is somewhat prose-heavy, but each paragraph serves a real comprehension purpose.

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

Completeness2/5

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

The core output interpretation is covered, and an output schema exists, but the description is not complete for an 8-parameter tool with 0% schema description coverage: most filters are never explained. An agent can understand the headline metric but not how to correctly 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, and the description explains only `run` (run_id/activity_id/Garmin file id, empty means latest). It leaves `last_n`, `cluster`, `start_date`, `end_date`, `run_type`, `direction`, and `segment_id` entirely undocumented, so an agent must guess their semantics.

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 states a precise resource and scope: pace on every slope effort of one run, split by direction. It is clear what the tool computes, but it does not differentiate itself from siblings such as grade_binned_pace or segment-based 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 only guidance is interpretive: read comparable_ground.length_ratio before comparing directions. There is no explicit statement of when to choose this tool over siblings, nor any when-not-to-use or alternative-tool guidance.

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