trail-factors

Overview Schema Source Related Servers Discussions Admin

sync

Fetch new Garmin activities and process them, returning a job ID to poll for status. Processes only new files without modifying existing ones.

Instructions

Fetch new Garmin activities and process them. Returns a JOB ID at once.

This takes minutes and holds the database's exclusive write lock while it
runs, so it cannot be awaited: a synchronous version would make every other
tool call fail for the duration. Poll `sync_status` instead.

NEW FILES ONLY. Downloads APPEND to data/raw/; nothing in this path
modifies, moves, renames or deletes an existing raw file (§3).

A FILE THAT DID NOT INGEST IS REPORTED BY NAME. A finished job with
`clean: false` lists each rejected file under `rejected` with the reason
and a `next_step` carrying the exact command: a recording with a drive or
a forgotten stop at one end is cleared by confirming the window that is
the run (`confirm-file <garmin-id> --end '...'`) and syncing again.
Confirming a window is CLI-ONLY -- no tool here does it -- so relay the
command to the athlete rather than looking for one.

A STEP THAT FAILS COSTS ONLY ITSELF. Each step's outcome is in `steps`
(done / skipped / failed); a failure is in `step_errors` and `problems`
by step name and makes the job `clean: false`, and the rejections are
still reported. With no DEM tiles on disk the terrain steps (dem, silver,
match, recovery) are SKIPPED with the reason in `skipped_steps` -- the
normal state of a fresh install, not a failure.

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 2, 2026

TDQS

A4.6/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 so: it discloses runtime of minutes, an exclusive database write lock, why it cannot be awaited, append-only writes that never modify/move/rename/delete raw files, and per-step partial-failure semantics. It even pre-empts a false alarm — DEM-dependent steps being skipped is described as normal on a fresh install.

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: the first two lines give purpose, return value and the polling alternative. Each subsequent block covers a distinct failure mode, though the detailed field-by-field recounting of `steps`, `step_errors`, `problems`, `rejected` and `skipped_steps` partially duplicates what the existing output schema already conveys, and the all-caps emphasis is loud.

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

Completeness5/5

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

For a long-running, lock-holding job with no annotations, the description supplies everything an agent needs: async contract, polling target, write-scope guarantees, partial-failure interpretation, and the CLI-only escape hatch for stuck recordings. No material gaps remain.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No stray parameter claims are made.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Fetch new Garmin activities and process them') and immediately states the return contract ('Returns a JOB ID at once'). The asynchronous nature cleanly separates it from the sibling `sync_status`, which is explicitly named as the polling counterpart.

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?

Explicitly routes the agent away from awaiting the call and toward `sync_status`, and warns that `confirm-file` is CLI-only so the agent should relay a command rather than hunt for a tool. Missing only a positive trigger ('call this when new recordings are on disk').

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