Integrates with Garmin Connect to sync and analyze running data, providing readiness scores, intensity bands, interval detection, and training insights.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@runcoach should I train today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local-first AI running coach for your Garmin data — powered by the Claude subscription you already have.
No cloud backend, no API key, no Docker. One Python package that syncs your Garmin data into a SQLite file on your machine, shows it in a small web app, and lets Claude act as your coach — with a deterministic readiness engine underneath, so the AI explains decisions instead of inventing them.
If you came for the engineering rather than the running, the five decisions this repository is
actually about — each with the measurement behind it — are in
Design decisions. The short version: the verdict is
pure code and only the explanation is AI · the agent runs on
an allowlist, not a denylist (--tools "", one MCP server, empty temp cwd) ·
prompts are regression-tested by an LLM-as-judge suite whose last run is
in the repo · quantities that exist in two languages are pinned by
executing the shipped JavaScript against the Python · and the
release gate scans binaries too, with a false-positive counter-case. CI runs lint,
480 tests, 56 frontend tests and that gate on three operating systems and two Python versions, with every
action pinned to a commit SHA.
The built-in synthetic athlete (runcoach serve --demo). Every image is regenerated by
python scripts/screenshots.py, and the coach card is an unedited agent run against that same
demo database, kept in demo-card.json so the picture cannot
drift from the app — the numbers it cites (HRV balanced, Body Battery 66, resting HR 48, ACWR 1.17) are the
ones on the Today tab beside it. docs/screenshots/ has each of the four tabs full-length, in both
themes — e.g. today.png and
today-light.png.
Not affiliated with Garmin. Uses the unofficial python-garminconnect library against your own account. This is a training tool, not medical advice.
# 1. install (needs uv: https://docs.astral.sh/uv/)
uv tool install git+https://github.com/edxleon/runcoach-ai
# 2. look around without any account
runcoach serve --demo
# 3. the real thing
runcoach login # once: Garmin e-mail, password, MFA code -> only session tokens are stored
runcoach serve # opens http://127.0.0.1:8765 right away, syncs in the backgroundCoach cards need the Claude Code CLI, signed in with your Claude
subscription. runcoach doctor tells you what is missing — it checks the Garmin session by actually
using it, and reports the data age, because a token that quietly expired is how this kind of app dies.
Use runcoach doctor --offline to skip the Garmin call. Exit 1 means something needs fixing, so
runcoach doctor || notify-me works in a cron; a missing Claude CLI is reported but does not set it,
since everything except the coach cards works without it.
Use the same data in Claude Code or Claude Desktop as an MCP server:
claude mcp add runcoach -- runcoach mcp
# then just ask: "should I train today?"Keep it fresh without the app (cron / Task Scheduler): runcoach sync.
Related MCP server: garmin-mcp-server
Tab | What it answers |
Today | GO / EASY / REST with the signals behind it, one decision sentence for today, this week planned vs. done, last night's sleep, your zone bounds with their origin |
Runs | Every run with its intensity band, real interval structure ( |
Trend | VO2max as honest steps, lactate threshold history, weekly hard-minute share vs. an 80/20 target, aerobic efficiency (pace at a fixed heart rate) with spread and trend, volume, polarisation, ACWR |
Coach | One-tap analyses by Claude as short cards that remember the previous card of their kind, accept your 👍/👎, take follow-up questions and can be deleted. Two start here (Why is VO2max moving? · Review my week); the other two start where their subject is — Should I train today? on the Today tab, Analyze this run on a run |
flowchart LR
G[Garmin Connect] -- "token resume, read-only" --> S[sync.py]
S --> DB[(SQLite<br/>~/.runcoach)]
DB --> L[logic.py<br/>readiness · decision<br/>intervals · bands]
L --> SNAP[snapshot.py]
SNAP --> WEB[web app<br/>127.0.0.1:8765]
L --> MCP[MCP server<br/>10 tools<br/>9 read-only + sync]
WEB -- "spawn job" --> A["claude --print<br/>(your subscription)"]
A -- "only mcp__runcoach__*" --> MCP
A -- "JSON card" --> WEB
MCP --- CC[Claude Code / Desktop]The verdict is code, the explanation is AI. GO/EASY/REST, today's decision, interval detection and
intensity bands are pure functions in logic.py — unit-tested, no network, no
LLM. The facts and the decision are computed once there, and the agent is handed the finished
decision through get_training_readiness rather than left to derive its own: a coach card is a reading
of that decision, not a second, independently produced verdict. Claude may explain it, add the context a
rule cannot — or disagree, in which case it has to say which number it disagrees with. Claude's job is
the part rules are bad at: weighing a conflict, phrasing a plan, answering a follow-up.
Your subscription, not an API key. Coach jobs run claude --print as a subprocess. There is no key
to leak, no per-token bill, nothing to configure. If your quota is exhausted the job waits for the next
window instead of failing.
The agent gets an allowlist, not a denylist. Workout titles are attacker-controlled text that ends
up in a prompt. So the coach agent runs with --tools "" (no Bash, no file access, no web),
--strict-mcp-config with exactly one server — this one — and only mcp__runcoach__* pre-approved, in an
empty temp directory. The card comes back as JSON and is validated and written by the app, not by the
agent — and an answer produced without a single tool round trip is discarded: a model that cannot reach
the data will otherwise invent it (this was measured, not assumed).
See web/agent.py.
What that does and does not buy, stated plainly: an injected workout title cannot reach anything but
this app's own tools — no shell, no filesystem, no network, no other MCP server, and no write path,
because every tool is read-only except sync_garmin, which triggers authenticated requests to your own
Garmin account and so is worth a rate limit rather than nothing. What it can still do is influence
what a card says — and the card is the product. And cards are remembered: the previous card of the same
kind is fed back as context for the next one, so a bad card echoes forward until you delete it (the UI
has a delete button per card).
Aggregates for the model, series for the UI. MCP tools never return day-by-day rows for a period — daily series bloat a context window and get misread. The agent sees summaries and weekly buckets; only the frontend, which draws curves, gets points.
Honest numbers. A few examples of what that means in practice:
Garmin carries VO2max forward on days without a measurement, so a change is only reported when the value actually varied — never as a difference of window endpoints.
A self-computed ACWR needs ≥ 21 days and ≥ 8 workouts, is labelled computed, and may dampen a
verdict to EASY but never drive REST.
A GO from fewer than two recovery signals is downgraded: thin data is not green.
If the sync is stale, today's decision is unknown rather than yesterday's verdict in today's clothes.
An incompletely fetched calendar month does not replace the local mirror ("nothing planned" would be a lie from a degraded source).
Garmin's lactate-threshold pace field is off by a factor of ten; it is normalised, range-checked, and loudly dropped if the unit ever changes.
Prompts are tested like code. The coach's behaviour lives in two Markdown files
(skills/) with an LLM-as-judge regression suite (evals/):
13 cases such as "a run already happened today → no second hard session", "warning signs of low energy
availability are not explained away", "an instruction inside a workout name is not followed". They run
without Garmin data against the real CLI — though only over those two files, not over the other two
pieces of the shipped prompt (templates.json and the JSON-card frame in web/agent.py, which
tests/test_web.py covers deterministically instead), and under --safe-mode on whichever model the
suite is pointed at, neither of which production can use. The framing itself is imported from the app
rather than copied, so the suite cannot drift from what ships. --no-skills re-runs a case with the
skill files removed: a case that still passes is testing the model, not the prompt.
Boring technology. Python stdlib HTTP server, sqlite3, vanilla ES modules, inline SVG charts. No
framework, no build step, no ORM. ~40 SQL queries, all in store.py.
Runs on Windows, macOS and Linux (CI matrix).
More detail: docs/architecture.md.
Everything stays in ~/.runcoach/ (override with RUNCOACH_HOME): the SQLite database, Garmin session
tokens, coach cards. Your password is never stored. On Linux and macOS the directory is created 0700,
so on a shared machine other local accounts cannot read your training data or replay your Garmin session
tokens; Windows inherits the user profile's ACL instead. The only outbound connections are to Garmin
(sync) and — when you trigger a coach card — to Claude through your own CLI session, carrying
aggregated training data. The server binds to 127.0.0.1; listening on the network requires
RUNCOACH_TOKEN and the server refuses to start without it. Note that --host 0.0.0.0 serves plain
HTTP with no TLS, so on that network the token and everything the app returns travel unencrypted and
readable by anyone who can see the traffic — it is meant for your own phone on your own LAN, not for a
network you do not control.
Variable | Default | Purpose |
|
| data directory |
| system zone | IANA zone for "which day was this run" |
| – | required for |
| CLI default | model for coach cards |
|
| reuse an existing python-garminconnect token dir |
|
| how long a job waits for subscription quota |
|
| hard timeout for a single coach job |
|
| minimum window of workouts a sync fetches (the ACWR fallback needs ~28 days) |
|
| how far back the lactate-threshold history is fetched |
|
| log level — set |
Four more (RUNCOACH_DB, RUNCOACH_DEMO, RUNCOACH_CLAUDE_CMD, RUNCOACH_PII_EXTRA) exist for
internal plumbing and tests; they are not part of the supported surface.
Optional athlete profile: runcoach profile --max-hr 182 --goal "sub-50 10k".
git clone https://github.com/edxleon/runcoach-ai && cd runcoach-ai
uv run pytest -q # no database server, no network, no Garmin account needed
node --test "web-tests/*.test.mjs" # frontend logic
uv run ruff check # lint — config is real and the backlog is zero
uv run python evals/run_evals.py # prompt regression (uses your Claude subscription)
uv run python scripts/pii_gate.py # release gatev0.1 is read-only towards Garmin by design. Next: adaptive planning — the coach proposes a changed workout and, after explicit confirmation in the UI, writes it to the Garmin calendar.
MIT
Deep dive into ONE run: time in each HR zone, interval structure (rep count, rep length, work vs recovery HR), weather, performance condition, plus rule-based notes. Default: the latest run with detail. The interval structure is Garmin's auto-detection — if the athlete states a different structure, the athlete is right.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | ISO date YYYY-MM-DD. Omit for the latest. | |
| activity_id | No | Garmin activity id; wins over `day`. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does meaningful work: it discloses reliance on Garmin's auto-detected interval structure and provides a fallback rule that the athlete's stated structure wins. It does not cover side effects, auth, or failure modes, but the tool is a read-only analysis and an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the purpose, compactly list the outputs, and close with an important caveat. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 do not need describing. The description covers the operation, default selection, and an interpretation rule; minor gaps remain around what 'rule-based notes' contain and when activity_id is necessary beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the default latest-run behavior and the single-run focus, but it does not add semantics beyond what the schema already provides for 'day' and 'activity_id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific task, 'Deep dive into ONE run', and enumerates concrete outputs: HR zones, interval structure, weather, performance condition, and rule-based notes. It is distinguishable from siblings like get_trend or get_intensity_distribution by its single-run scope, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Default: the latest run with detail' gives a clear default invocation, and the wording implies this is for granular single-run analysis. However, it does not state when to prefer this tool over siblings such as get_recent_activities or get_intensity_distribution, nor any exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every recorded recovery value for ONE day (default: latest day with data). Use when a single night/day is in question, not for trends.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | ISO date YYYY-MM-DD. Omit for the latest. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that all recorded recovery values for one day are returned, that the default is the latest day with data, and that trends are out of scope. It does not mention what happens when no data exists for the requested day, but the output schema likely covers return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core behavior and then provide the usage rule. Every word contributes meaning and there is no fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one optional parameter, no nested objects, and an output schema, so the description does not need to explain return values. It covers purpose, default behavior, and scope. The main gap is that it does not explicitly mention sibling tools like get_recovery_summary or get_trend, though 'not for trends' handles the most important distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the 'day' parameter fully, including ISO format and the omit-for-latest behavior. The description adds semantic value by clarifying that the default is the latest day with data, not merely the latest calendar day, and by framing the selection as a single night/day. This goes beyond the schema's own parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns every recorded recovery value for exactly one day, defaulting to the latest day with data. It also distinguishes itself from trend tools with 'not for trends.' It lacks an explicit verb in the description, but the tool name 'get' supplies the action, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use it when a single night/day is in question and not for trends, providing a clear when/when-not rule. However, it does not name specific sibling alternatives such as get_trend or get_recovery_summary, so it stops short of fully explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time in heart-rate zones across all runs (easy Z1-2 / moderate Z3 / hard Z4-5 / Z5) with percentages — the basis for the 80/20 polarisation question. States how many runs have zone detail, so an incomplete picture is visible.
| Name | Required | Description | Default |
|---|---|---|---|
| period_days | No | Window length in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It explains that the tool returns time in heart-rate zones grouped by intensity buckets, includes percentages, and reveals a non-obvious data-quality behavior: it states how many runs have zone detail so an incomplete picture is visible. It does not mention period filtering in prose, but the schema documents the period_days parameter without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with no wasted words. It front-loads the core output and follows with a useful caveat. Every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and only one optional parameter, the description covers the tool's purpose, aggregation scope, and a data-completeness caveat. The only minor gap is not explicitly connecting the result to the period_days window in prose, but the schema handles that detail, making the description nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one optional parameter, and schema description coverage is 100%, so the schema already documents period_days with default, minimum, and maximum. The description adds no additional parameter semantics; 'across all runs' could even slightly obscure the period-window behavior, though the schema clarifies it. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (heart-rate zone time across all runs), the output form (percentages), and the organizing question (80/20 polarisation). This is specific enough to distinguish it from siblings like analyze_workout, which targets a single workout, and get_training_load, which is about load rather than zone distribution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the use case: it is the basis for the 80/20 polarisation question. This gives an agent a clear trigger for when to use the tool. It does not mention alternatives or exclusion conditions, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Workout digest: totals per sport plus the latest workouts, each run classified Quality / Long Run / Easy (from training effect and duration). Use to see what was actually trained before recommending the next session.
| Name | Required | Description | Default |
|---|---|---|---|
| period_days | No | Window length in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It signals a read-only digest ('Use to see') and discloses non-obvious classification logic ('Quality / Long Run / Easy, from training effect and duration'), which is genuinely useful. It doesn't address auth or side effects, but none are suggested by the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first packs the output shape and classification rule, the second gives the use case. Every phrase earns its place and there is no redundant or generic filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with an output schema, the description covers the essential return content, the classification behavior, and the intended use context. It could be slightly stronger by tying period_days to 'recent' or noting any limit on how many workouts are returned, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter's meaning ('Window length in days') plus min/default/max is fully documented in the schema. The description adds no extra parameter-level information, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool returns: 'totals per sport plus the latest workouts' with runs classified into Quality / Long Run / Easy. It stops short of a 5 because it uses a noun-phrase ('Workout digest') rather than an explicit verb, and it doesn't name sibling tools to sharpen differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use to see what was actually trained before recommending the next session' gives a clear, practical when-to-use context. It does not explicitly mention alternatives or when-not-to-use, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Averages of sleep, HRV, resting HR, stress, Body Battery and steps over the last N days plus a snapshot of the latest day. Use for "how has my recovery been?". Aggregates only — never a day-by-day list.
| Name | Required | Description | Default |
|---|---|---|---|
| period_days | No | Window length in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It clearly discloses the aggregation behavior, the inclusion of a latest-day snapshot, and the explicit absence of day-by-day output. It does not discuss data-source assumptions or edge cases, but the core non-obvious behavior is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the result shape, the intended use case, and the critical scope exclusion. There is no filler or redundancy, and the most important information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema and no annotations, the description is sufficient to select and invoke the tool correctly. It explains the aggregate result, the window, and the non-aggregate exclusion. Naming sibling alternatives or caveats such as timezone handling would improve it further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes period_days as 'Window length in days.' The description adds only the semantic link that N controls the aggregation window and latest snapshot, which is marginal value beyond the schema. Thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact metrics covered (sleep, HRV, resting HR, stress, Body Battery, steps) and the precise output form: averages over N days plus a latest-day snapshot. It also explicitly contrasts itself with a day-by-day list, which distinguishes it from sibling tools like get_daily_metrics or get_trend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear trigger phrase ('how has my recovery been?') and a clear exclusion ('never a day-by-day list'). However, it does not name any sibling tool explicitly as the alternative for day-level detail, so an agent must infer which sibling to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Training-load picture: ACWR with its SOURCE (Garmin's EWMA ratio, or a self-computed fallback that is less reliable), Garmin training status, VO2max with change, and weekly load buckets. VO2max change is only reported when the value actually varied (Garmin carries the last value forward).
| Name | Required | Description | Default |
|---|---|---|---|
| period_days | No | Window length in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it adds real value by disclosing that the ACWR source may be Garmin's EWMA or a less-reliable self-computed fallback and that VO2max change is only reported when the value actually varied. It does not explicitly state read-only behavior, but 'picture' and the absence of any mutation language make that clear enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, with the core scope front-loaded and the source/fallback caveats kept in a separate short note. Every sentence adds information; there is no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with an output schema, the description covers the meaningful behavioral caveats (source reliability and conditional VO2max reporting). It stops short of being fully complete because it doesn't explain when period_days should be customized, though the schema's default and range largely compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single period_days parameter is already documented with range and default. The description adds no parameter-specific semantics beyond the implicit weekly granularity, which matches the baseline for schema-covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Training-load picture' and lists exactly what is included (ACWR with source, Garmin training status, VO2max with change, weekly load buckets), so an agent can tell what it returns. It does not explicitly contrast itself with siblings like get_vo2max_history or get_training_readiness, so it misses the top bar for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The content list gives a strong implied use case: any request for a training-load overview or ACWR. It offers no explicit when/when-not guidance or mention of alternatives, so an agent still has to infer the boundary against get_training_readiness, get_recovery_summary, or get_vo2max_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Today's readiness verdict GO / EASY / REST with the signals behind it (HRV status, sleep score, Body Battery, resting HR vs 27-day baseline, ACWR, days since the last hard workout). Rule-based and conservative. START HERE for "should I train today?". Flags stale data explicitly.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool is 'rule-based and conservative' and that it 'flags stale data explicitly,' which are useful traits for interpreting outputs. It does not discuss errors, latency, or edge cases, but for a 0-parameter informational tool this is solid coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The opening sentence delivers the verdict and signal list, the second adds the algorithmic tone, and the third gives usage guidance and data-freshness behavior. Every sentence earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters and an output schema exists, so return values are structurally covered. The description provides purpose, decision context, behavioral traits, and staleness handling, making it complete for an agent to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty, so there is nothing for the description to explain about parameters. The baseline of 4 applies because parameter semantics are trivially covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: provide a GO/EASY/REST readiness verdict for today, with the key signals behind it. This differentiates it from siblings like get_recovery_summary and get_daily_metrics, and the 'START HERE' phrasing reinforces its role as the primary readiness decision tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs usage with 'START HERE for "should I train today?"' giving a strong contextual signal about when to use the tool. It stops short of naming alternatives or stating when not to use it, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weekly averages of ONE recovery metric over the last N days — for "is my HRV / resting HR / sleep trending up or down?".
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | ||
| period_days | No | Window length in days. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does disclose the core behavior: one metric, weekly averaging, trailing N days. However, it is silent on how trend direction is determined, missing-data handling, and whether weeks are calendar-aligned — details an agent might need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence conveys the computation, scope, and motivating use case with concrete examples. Every clause earns its place and the key constraint ('ONE') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, two-parameter tool with an output schema, the description plus schema is sufficient for an agent to invoke it correctly. It lacks explicit guidance on which sibling to choose instead, but the stated use case makes the selection path reasonably clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
period_days is already explained in the schema, and metric's enum values are largely self-explanatory; the description reinforces that exactly one metric is selected. This adds some meaning but does not materially compensate for the metric parameter lacking its own schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete computation — weekly averages of a single recovery metric over a trailing window — and frames it around a clear question ('trending up or down?'). It distinguishes itself from broader summary/daily sibling tools without being a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use context: answering whether HRV, resting HR, or sleep is trending over time. It does not name sibling tools or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
VO2max over the last 8 weeks as STEPS (only the days the value really changed — Garmin carries it forward in between) plus a descriptive comparison of the last 28 days with the 28 before (distance, Z5 minutes, easy share, temperature). Use for "why is my VO2max moving?". Descriptive, not causal.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job: it explains the data shape (STEPS, only changed days, Garmin carry-forward), the time windows (8 weeks, 28 days vs 28 before), and the specific metrics included (distance, Z5 minutes, easy share, temperature). It also explicitly states the tool is descriptive, not causal, which is a key behavioral trait. The only minor gap is that it doesn't describe the output format or whether the comparison is computed server-side, but the output schema exists and the description is already quite rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly packed with useful information. It front-loads the core purpose (VO2max over last 8 weeks as STEPS), then adds the comparison detail, and ends with the use case and a caveat. Every sentence earns its place; there is no fluff or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters and an output schema exists, the description is complete for an agent to decide whether to call it and what to expect. It covers the data granularity, time windows, metrics, and the descriptive-not-causal nature. The sibling context (get_trend, get_training_load) makes the use-case sentence particularly valuable for routing. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the schema provides no parameter semantics. The description compensates by explaining what data the tool returns and the time windows involved. Since there are no parameters to document, the description's role is to clarify the tool's scope and output, which it does well. A 4 is appropriate because the description fully covers the tool's behavior despite having no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns VO2max history over the last 8 weeks as STEPS, with a specific data format (only days where the value changed, because Garmin carries it forward). It also includes a descriptive comparison of the last 28 days versus the 28 before, covering specific metrics. The final sentence explicitly ties it to the use case 'why is my VO2max moving?', which distinguishes it from sibling tools like get_trend or get_training_load.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use for "why is my VO2max moving?".' It also clarifies what the tool is not: 'Descriptive, not causal.' This gives an agent clear guidance on when to select this tool over siblings like get_trend or get_training_load, and sets expectations that it won't provide causal analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull the latest days and workouts from Garmin Connect NOW. Call this first when today's run or last night's sleep is missing. Takes 10-40 s. Read-only towards Garmin; writes only to the local database.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days back to re-fetch. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the key behavioral traits: duration (10-40 s), read-only behavior toward Garmin, and the only side effect (writes to local database). It does not mention failure modes or repeated-call safety, but the side-effect boundary is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. Each sentence adds useful information, though the capitalized 'NOW' is minor filler. Overall it is appropriately sized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and an output schema, the description covers what it does, when to call it, how long it takes, and its side effects. Nothing essential is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single optional 'days' parameter, including range and default. The description adds minimal parameter nuance, but the 100% schema coverage means the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Pull'), names the resource ('Garmin Connect'), and specifies the data scope ('latest days and workouts'). It is clearly distinguishable from the sibling get_* tools, which read local data, while this tool performs a sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Call this first when today's run or last night's sleep is missing') and adds timing expectations. It does not explicitly name alternatives or say when not to use it, but the sibling context and 'call this first' phrasing make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_workoutget_daily_metricsget_intensity_distributionget_recent_activitiesget_recovery_summaryget_training_loadget_training_readinessget_trendget_vo2max_historysync_garminScored across 10 tools
Each tool maps to a distinct analytical question: readiness verdict, aggregate recovery, single-day detail, trend, load, activity digest, intensity split, single-workout analysis, VO2max history, and sync. Overlapping data sources are explicitly scoped in the descriptions, so an agent can reliably pick the right one.
Nine of ten tools follow the uniform get_<domain> pattern, and the one exception (sync_garmin) is a clearly distinct imperative action. There is no mixing of naming styles or vague generic verbs.
Ten tools is a well-scoped number for a running/recovery analytics server. Each tool covers a distinct data-retrieval concern and none feels redundant or unnecessary.
The surface thoroughly covers retrospective training and recovery analysis: readiness, load, trends, activities, intensity, and single-workout details. The main gap is forward-looking coaching functionality such as workout prescription or race prediction, but the stated analytics workflows are essentially complete.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
