trail-factors

Overview Schema Source Related Servers Discussions Admin

session_load

Calculate Foster session load (Garmin RPE x timer minutes) for one run or a selection of activities, flagging unpriced sessions so totals read as a lower bound.

Instructions

Foster session load: Garmin's own post-run RPE x timer minutes, in AU.

Args:
    run: run_id, activity_id or Garmin file id -- ONE activity. Empty,
        with no selection filter, means the latest run.
    start_date, end_date, cluster, last_n: a SELECTION instead of one
        activity -- of EVERY SPORT, since load is a dose and a rated
        ride is load the legs carried (`summary.n_by_sport`). Name a run
        OR a selection, never both.
    run_type: REJECTED when non-empty -- this build has no run_type source.

THE RPE IS GARMIN'S. Some watches ask "how hard was that?" when an
activity is saved; an activity where the device did not ask, or the
rating was declined, is `unavailable` with that reason -- NEVER priced at
0 and never filled from another activity. `garmin_feel` is SHOWN and
never used: it is a different question, and its 1-5 direction is
unverified.

TIMER TIME, NOT MOVING TIME: load is a session DOSE, not a rate, so
standing time counts. Read `filters` for the formula and its basis.

OVER A SELECTION, `summary.sum_foster_load_au_priced` sums the priced
sessions. When any session is unpriced -- unrated (`n_unrated`), or rated
with no timer time (`n_rated_unpriced`, each with its reason) -- it is a
LOWER BOUND and `is_lower_bound` says so; unpriced sessions are left out,
never counted as zero. No GPS coverage gate applies -- load is volume,
not a terrain comparison.

Input Schema

Name	Required	Description	Default
`run`	No
`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

A4.2/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 it well: it discloses that unrated sessions are 'unavailable' with a reason and never priced at 0, that garmin_feel is shown but unused, that timer time (not moving time) is the basis system, and that selection sums may be lower bounds flagged by is_lower_bound. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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 definition and an Args block, and every paragraph addresses a distinct behavioral risk. It is longer than most definitions but the density is justified by the number of pitfalls; the heavy all-caps emphasis is slightly noisy but not wasteful.

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?

For a complex eight-parameter tool with no annotations, the description covers semantics, selection logic and aggregation caveats, and an output schema exists so return shape need not be spelled out (though it usefully names key summary fields). The only real hole is the undocumented direction and segment_id parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate; it documents the meaning, exclusivity and defaults of run, start_date, end_date, cluster, last_n and the run_type rejection in useful detail. However, two of the eight parameters, direction and segment_id, are never mentioned at all, leaving an agent to guess whether they apply to this tool.

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 opening sentence names the specific metric, its source, its formula (Garmin RPE x timer minutes) and its unit (AU), so an agent knows exactly what this tool returns. It does not, however, distinguish itself from siblings such as session_series or basic_metrics, which also operate on sessions.

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?

Clear operating rules for choosing one activity versus a selection, the explicit exclusivity ('Name a run OR a selection, never both'), the empty-means-latest default, and the run_type rejection. What is missing is when to reach for this tool instead of a sibling for related load/dose questions.

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