Skip to main content
Glama
cambroussard9

trail-factors

cadence_by_grade

Compute cadence per 5% grade bin for a selection, split by run and walk, so you can compare cadence on climbs and descents without pooling incompatible modes.

Instructions

§6.0 cadence per 5% grade bin over a selection, split by split_type.

Never pooled across run and walk — running and walking cadence sit tens of
spm apart, so a pooled bin reports a number neither mode took.

Needs a DEM tile for the grade, so it sees only DEM-covered runs;
`n_runs_without_grade` says how many of the selection had none.

Input Schema

NameRequiredDescriptionDefault
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.4/5.0
Behavior4/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 well: it warns that run and walk are never pooled and explains why, and it discloses the DEM-coverage constraint plus the `n_runs_without_grade` counter for excluded runs. It omits any statement on read-only semantics, cost, or result shape, but the data-coverage caveats are exactly the kind of context an agent cannot get elsewhere.

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?

Three short sentences, front-loaded with the operation, with zero filler — the pooling rationale earns its space by justifying the split. The leading '§6.0' reference is cryptic overhead but negligible.

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 needn't be explained, and the coverage caveat is handled well. But for a 7-parameter tool with zero schema descriptions, the description should say what the selection, cluster, direction, and date arguments do; that gap is material.

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 at 0% schema description coverage (titles only) — last_n, cluster, end_date, run_type, direction, segment_id, start_date are all undocumented in both places. The description mentions `split_type` and `n_runs_without_grade`, neither of which appears in the input schema, so it adds confusion rather than meaning for the actual callable arguments.

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 metric (cadence), a specific bucketing (per 5% grade bin), a selection scope, and a grouping key (split_type). That is enough to distinguish it from siblings like grade_binned_pace, though it never names an alternative directly.

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 is implied through 'over a selection' and the split_type grouping, and the 'never pooled' note tells the agent how results behave. However, there is no explicit when-to-use or when-not guidance relative to siblings such as grade_binned_pace, leaving the agent to infer the choice.

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