trail-factors

Overview Schema Source Related Servers Discussions Admin

list_runs

List and filter recorded activities newest first by date range, sport, cluster, or result limit to locate specific runs for review or analysis.

Instructions

Corpus listing, newest first. All filters optional and AND-ed.

Args:
    start_date: inclusive YYYY-MM-DD.
    end_date: inclusive YYYY-MM-DD.
    run_type: REJECTED when non-empty -- this build has no run_type
        source. Each row reports run_type null, labelled "not collected";
        a later version re-enables it through user-defined run types.
    cluster: a cluster name from config/athlete.yaml, or NO_GPS / OTHER.
    limit: maximum rows.
    sport: empty means running. "any" lists every sport; otherwise one
        sport by name (cycling, hiking, ...).

Each row carries `local_date`, the day the athlete would call it.

Input Schema

Name	Required	Description	Default
`limit`	No
`sport`	No
`cluster`	No
`end_date`	No
`run_type`	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/5.0

Behavior4/5

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

With no annotations, the description does real work: it discloses that run_type filters are REJECTED, that rows report run_type as null labelled 'not collected', and that rows carry local_date. These are non-obvious behaviors an agent could not derive from schema or annotations. Gaps remain around permissions and limit edge behavior, preventing a 5.

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 lead sentence front-loads purpose and ordering before the parameter block. The docstring-style 'Args:' formatting and the multi-line run_type explanation are somewhat verbose, but every clause conveys actionable semantics rather than filler.

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 need not be described, and the description covers filter interaction, ordering, and the notable run_type degradation. Minor gaps (pagination ceiling, whether results are truncated silently) remain for a 6-parameter query tool.

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

Parameters5/5

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

Schema coverage is 0%, so the description must carry all parameter meaning, and it does: date formats and inclusivity, the rejected run_type path, cluster special values (NO_GPS / OTHER) sourced from config, and the critical sport semantics ('empty' = running, 'any' = all sports). Only 'limit: maximum rows' is thin, but it is sufficient.

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 verb and resource ('Corpus listing') plus ordering ('newest first') and scoping semantics ('All filters optional and AND-ed'). It never names the nearest sibling (list_segments) or explicitly says 'runs', so differentiation is left to inference, which keeps it below a 5.

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 by the sport/cluster semantics ('empty means running', 'a cluster name from config/athlete.yaml'), so an agent can infer when this tool applies. However, there is no explicit when-to-use/when-not guidance and no reference to alternatives such as list_segments.

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