Skip to main content
Glama

garmin-owl

garmin-owl lets Claude Desktop, ChatGPT Desktop, or another MCP client answer questions about your Garmin health and training data: sleep, HRV, recovery, activities, training load, and more. It runs entirely on your computer, can only read from Garmin Connect, and never uploads a separate copy of your data anywhere.

It works on macOS and Ubuntu Linux and uses the unofficial python-garminconnect client, so a change on Garmin's side can occasionally break a read until garmin-owl is updated.

Want to change the code or build a release? See CONTRIBUTING.md.

What you need

  • macOS or Ubuntu Linux

  • Claude Desktop with Extensions support, ChatGPT Desktop, or another MCP client

  • A Garmin Connect account with data from a Garmin device

  • uv and Git. uv installs Python 3.12+ for you, so you never need to set up or activate an environment.

Related MCP server: garmin-mcp

Setup

1. Sign in to Garmin (once)

In a terminal, run this as the same OS user that runs Claude Desktop:

git clone https://github.com/xichen-de/garmin-owl.git
cd garmin-owl
uv sync --locked
uv run garmin-owl-auth

You'll be asked for your Garmin email, password, and MFA code if your account uses one. Your password is not stored: only a reusable session token is saved, to ~/.garminconnect (or to the directory in the GARMINTOKENS environment variable, if you set it). Treat that directory like a password.

Re-run uv run garmin-owl-auth any time to check your sign-in. It only asks for credentials again if the saved session no longer works.

Garmin has no public API for personal data, so the unofficial client signs in the way the Garmin Connect website does. Your credentials are used once, in the terminal, to obtain session tokens. They never enter an MCP conversation, and Claude never sees them.

2. Install the Claude Desktop extension

Using ChatGPT Desktop instead? Skip to ChatGPT Desktop.

  1. Download the latest .mcpb file from Releases.

  2. Open Claude Desktop → Settings → Extensions and drag the .mcpb file in.

  3. Enable the extension, restart Claude Desktop if prompted, and start a new chat.

The extension reuses the session saved in step 1. It contains the program only, never credentials, tokens, or health data.

For clients that accept mcpServers JSON, add the entry below. Replace the two placeholder paths with the output of command -v uv and of pwd run inside your garmin-owl folder. Where the config file lives depends on your client.

{
  "mcpServers": {
    "garmin-owl": {
      "command": "/absolute/path/to/uv",
      "args": ["--directory", "/absolute/path/to/garmin-owl", "run", "garmin-owl"]
    }
  }
}

Use absolute paths, because desktop apps often don't inherit your terminal's PATH. Running uv run garmin-owl by hand just waits silently for an MCP client, so it isn't an interactive program.

3. Try it

Ask Claude things like:

  • "Summarize my recovery today."

  • "How did I sleep last night?"

  • "Compare my last two runs."

  • "Show my 28-day recovery trend."

  • "What did my training week look like around 3 March 2025?"

  • "How has my weight changed over the last year?"

  • "How does my cycle day line up with my recovery?"

ChatGPT Desktop

garmin-owl can also run as a local plugin in ChatGPT Desktop. It is the same Python server, packaged for ChatGPT's local plugin marketplace. It does not work in ChatGPT on the web or on mobile, and a URL-based developer-mode connector can't run it.

ChatGPT requirements

  • A current ChatGPT Desktop build on macOS or Ubuntu with Work mode or Codex, local plugin marketplaces, and stdio MCP plugins. Availability can vary by app version, account, and workspace policy.

  • The codex CLI with marketplace support. Check with codex plugin marketplace add --help.

  • Git and uv, as in What you need.

See OpenAI's local plugin documentation and the Agent Plugins 1.0.0 specification for background.

Install

  1. In your garmin-owl folder, as the same OS user that runs ChatGPT, sign in (skip if you did step 1 already) and build the local marketplace:

    uv sync --locked
    uv run garmin-owl-auth
    uv run --locked python scripts/build-chatgpt-plugin.py
  2. Register the marketplace (once):

    codex plugin marketplace add ./dist/chatgpt-marketplace
  3. Restart ChatGPT Desktop, open the Plugins Directory, choose Garmin Owl Local, then install and enable Garmin Owl.

  4. Start a new local Work/Codex chat and ask, for example, "Summarize my recovery today."

The first launch needs internet access: it installs the locked Python dependencies into the plugin's private data folder (PLUGIN_DATA/venv). After that it runs offline apart from reading Garmin.

scripts/build-chatgpt-plugin.py writes dist/chatgpt-marketplace/, containing the plugin under plugins/garmin-owl and a catalog at .agents/plugins/marketplace.json that uses only relative paths. It copies an explicit list of program files and never your .venv, tokens, credentials, SQLite files, or other checkout state. Register this generated folder, not the checkout itself.

Updating the ChatGPT plugin

ChatGPT runs its own installed copy of the plugin, so after git pull:

  1. Rebuild with uv run --locked python scripts/build-chatgpt-plugin.py.

  2. Restart ChatGPT Desktop.

  3. Uninstall Garmin Owl and install it again from Garmin Owl Local.

codex plugin marketplace upgrade only refreshes Git marketplaces, so it doesn't apply here.

Sign-in, data, and settings

  • Sign in only with uv run garmin-owl-auth in your terminal. Never type your Garmin password into ChatGPT.

  • The plugin reuses ~/.garminconnect and the same local cache as the terminal commands. Both stay outside the plugin package.

  • Tool results are sent to ChatGPT as part of your conversation, as with any MCP client.

  • GARMINTOKENS and GARMIN_OWL_DB exported in your shell don't reach GUI apps such as ChatGPT. The plugin uses the default locations unless those variables are set in ChatGPT's own environment.

ChatGPT troubleshooting

  • "uv was not found": desktop apps often don't inherit your shell's PATH. The launcher looks for uv on PATH and in ~/.local/bin, ~/.cargo/bin, /opt/homebrew/bin, /home/linuxbrew/.linuxbrew/bin, /usr/local/bin, /usr/bin, and /snap/bin. Install uv with its official installer (or brew install uv on macOS), or link a custom install into ~/.local/bin (ln -s "$(command -v uv)" ~/.local/bin/uv), then restart ChatGPT.

  • Garmin Owl Local isn't listed: check codex plugin marketplace list, restart ChatGPT, and confirm your build and account support local marketplaces and stdio plugins.

  • Old behaviour after updating: reinstall the plugin as described in Updating the ChatGPT plugin.

What it can tell you

Your assistant chooses among 19 read-only tools. None of them can change anything in your Garmin account.

One day at a time

Tool

Answers

get_daily_summary

Steps, activity/sedentary time, goals, calories, HR, stress, respiration, SpO2, Body Battery

get_sleep

Sleep score/need, stages, timing, sleeping HR/stress, respiration, SpO2, Body Battery change, skin-temperature deviation

get_hrv

HRV status, nightly and weekly averages

get_body_battery

Charged, drained, and start/end/highest/lowest levels

get_stress

Average and max stress, plus durations by intensity band

get_training_readiness

Garmin's readiness score, components, and factor feedback

get_cycle

Cycle phase, day, and Garmin predictions

Activities and training

Tool

Answers

get_activities

Activity summaries over up to 366 days (defaults to the last 14), at most 100 results

get_recent_activities

Activities from the last 1–90 days, optionally filtered by type (for example running)

get_activity

One activity's laps, training effect, HR/power zones, and your notes and ratings

compare_activities

Side-by-side metrics for 2–10 activities

get_training_week

Mon–Sun totals and zone time, with per-metric coverage

get_training_load

Acute/chronic load, ratio/status, load focus/targets, VO2 max, endurance, hill, acclimation

get_training_zones

Configured HR and cycling-power zone thresholds

get_running_tolerance

Running distance, impact load, tolerance, and feedback over 1–90 days

Body, combined, and trends

Tool

Answers

get_body_composition

Weight and related measurements over up to 366 days (defaults to the last 30)

get_recovery

Sleep, HRV, Body Battery, stress, RHR, and readiness for one day

get_recovery_trend

Sleep score, sleep HR, skin-temperature deviation, HRV, RHR, readiness, and Body Battery over the last 1-28 days

get_training_context

One day's recovery plus the 7 days of training before it

Dates and range limits

You can ask about any past date. The only limit on history is how much Garmin still returns for your account and device. Leave the date out and the tools use today. What is limited is how much one request covers:

Coverage per request

Tools

One day (any date)

The "one day at a time" tools, get_recovery, get_training_load

Up to 366 days

get_activities, get_body_composition

Up to 90 days

get_recent_activities (ending today), get_running_tolerance (ending on any date)

Fixed window

get_recovery_trend: last 1-28 days, ending todayget_training_context: the 7 days ending on the chosen dateget_training_week: the Mon–Sun week containing the chosen date

get_activity and compare_activities take activity IDs, not dates, and get_training_zones reads your current settings. Activity lists return at most 100 activities per request; their truncated flag says when more matched.

You don't need to know these limits: describe the period in plain language and Claude picks the dates. For longer periods, such as several years of activities, Claude can split the question into several requests. A request that is too long returns an error that states the limit.

Every timestamp (sleep start/end, readiness, activity and lap starts, weigh-ins, time-series readings) is ISO 8601 with an explicit UTC offset, such as 2026-10-09T23:18:16+02:00. It is built from Garmin's true GMT value. The offset is the one Garmin recorded for your device at that moment, or your computer's time zone when Garmin gives only UTC, so daylight-saving changes are handled per timestamp. Dates (YYYY-MM-DD) are Garmin calendar days.

How to read the answers

  • Garmin's numbers and garmin-owl's calculations are kept apart. Anything calculated (such as "12% above your recent average") states its baseline dates, how many days it used, and its formula.

  • Missing stays missing. Nothing is guessed, and an absent value is never counted as zero. Garmin's 0.0 for something an activity didn't measure (an indoor workout's distance, a ride without a power meter) is left out too.

  • Totals say how complete they are, for example "distance covers 3 of 4 activities".

  • Gaps are explained in an availability list: Garmin had no data, the metric is unsupported on your device, or the read failed or was rate-limited. This includes a day with no data at all for sleep, HRV, readiness, stress, or Body Battery.

  • Units are in the field name (_m, _seconds, _hours, _percent). Recovery time is in hours everywhere, and time series are always called timeseries.

  • get_cycle deliberately leaves out notes, symptoms, moods, sexual activity, and raw daily logs.

Your own training notes

Add notes to an activity's description in Garmin Connect, such as exercises, weights, or how it felt, and the assistant reads them alongside Garmin's numbers. get_activity returns them exactly as you typed them, together with any perceived effort and "How did you feel?" ratings you gave the activity.

Faster answers with the local cache (optional)

garmin-owl keeps what it reads in a small local database, so each day is fetched from Garmin only once. That happens automatically, but you can pre-load history so your first questions are quick:

uv run garmin-owl-sync                                       # last 7 days
uv run garmin-owl-sync --days 30                             # last 30 days (max 366)
uv run garmin-owl-sync --start 2025-01-01 --end 2025-12-31   # any past window
  • A single run covers at most 366 days. --days counts back from today. --start can be any past date, and --end defaults to today.

  • To load more than a year, run one window per year. Days already cached are skipped.

  • --refresh-today or --refresh-date YYYY-MM-DD re-fetches a day even if it's cached.

  • Sync pre-loads daily summaries, sleep, HRV, training readiness, and activity lists. Body Battery, stress, activity details, training load, body composition, and cycle data are fetched the first time you ask, then cached.

Inspect or clear the cache (clearing never touches your Garmin sign-in):

uv run garmin-owl-cache-info
uv run garmin-owl-cache-clear

The cache is stored at:

  • macOS: ~/Library/Application Support/garmin-owl/garmin.sqlite

  • Ubuntu/Linux: ~/.local/share/garmin-owl/garmin.sqlite, or under $XDG_DATA_HOME when that is set to an absolute path

The cache is bound to an account fingerprint checked against Garmin at startup. Use a separate GARMIN_OWL_DB for each Garmin account; opening another account’s cache is rejected. Existing caches without an account fingerprint must be explicitly cleared with garmin-owl-cache-clear before reuse, or preserved by choosing a new database file. Clearing data keeps an existing account binding. Account identifiers and credentials are not stored in the cache.

Successful activity and weigh-in range refreshes remove records deleted in Garmin from that range. Failed or malformed responses leave the cache unchanged.

Set GARMIN_OWL_DB to use a different file. If you used a version before 0.2.1 on Linux, your old cache is at the macOS-style path above. Point GARMIN_OWL_DB at it to keep it, or let the new cache fill up by itself.

Watches and scales upload late, so a day counts as final only from noon the next day. Data fetched after that point is kept for good. Data fetched earlier, while the day could still change, is reused for at most 20 minutes and then fetched again. Today's numbers therefore stay current, and a half-synced day never gets stuck in the cache.

Activity notes and ratings can be edited at any time, so if you change them on an older activity, ask the assistant to refresh that activity.

Updating

  1. Download the new .mcpb from Releases and drag it into Settings → Extensions again. It replaces the old version. For ChatGPT Desktop, follow Updating the ChatGPT plugin after step 2 instead.

  2. Update your terminal copy, which is used for garmin-owl-auth, sync, and the cache commands:

    cd garmin-owl
    git pull
    uv sync --locked

The cache upgrades itself when needed. Your saved sign-in carries over.

Troubleshooting

First, check that sign-in and the main reads work. The output shows only pass/fail per read, never your data:

uv run garmin-owl-smoke

garmin-owl never retries automatically and never shows raw Garmin responses, so error messages are short:

Message contains

Meaning

Fix

"No local Garmin tokens found"

Not signed in yet, or ~/.garminconnect was deleted

Run uv run garmin-owl-auth

"authentication expired or was rejected"

Garmin ended the session, for example after a password change

Run uv run garmin-owl-auth again

"rate limit reached (HTTP 429)"

Too many Garmin requests in a short time

Wait a few minutes. Sync smaller ranges.

"Could not reach Garmin Connect"

A network problem or timeout

Check the connection, then try again later

"server error (HTTP 5xx)"

Garmin Connect itself is failing

Try again later

"rejected this request as invalid or too large (HTTP 4xx)"

Garmin refused this exact request

Ask for a shorter period; retrying unchanged won't help

"unexpected response shape" / "unusable response"

Garmin changed a private endpoint

Open an issue naming the tool (never paste your Garmin data)

"no data for this request"

That metric isn't recorded for that date or device

Expected for unsupported metrics

"date range cannot exceed" / "days must be between"

The request was longer than the tool allows

Ask for a shorter period, or several periods

"Cache belongs to another Garmin account"

The cache was created while signed in to a different account

Use a separate GARMIN_OWL_DB for each account

"upgraded … by a newer garmin-owl"

A newer version changed the cache while this one was running

Restart the app

"local garmin-owl cache could not be read or written"

SQLite error, often another process holding the file

Close other garmin-owl processes; if it persists, run uv run garmin-owl-cache-clear

"unexpected internal error (…)"

A bug; details are withheld to protect your data

Retry once, then restart and report the tool name and error type

The cache repairs itself after updates. Rows stored in an older format are re-read from Garmin, rows cached before account binding existed are discarded and re-read, and a cache written by a newer version is renamed to garmin.sqlite.schema-N and replaced with a fresh one.

  • Extension doesn't appear: make sure you installed a .mcpb from Releases (or one built from the same version as your checkout), then restart Claude Desktop.

  • Tools time out the first time: run uv run garmin-owl-sync once to warm the cache.

  • Sign-in works in the terminal but not in Claude or ChatGPT: run garmin-owl-auth as the same OS user that runs the desktop app, and if you set GARMINTOKENS, make sure the app sees it too.

  • ChatGPT Desktop problems: see ChatGPT troubleshooting.

Privacy and safety

  • Everything runs locally and talks to your MCP client only over local stdio. There is no network listener, telemetry, or remote database.

  • Garmin access is read-only. garmin-owl has no tool that can change your account.

  • Tokens stay in ~/.garminconnect. Only normalized data, including your activity notes, is stored in the local cache, never raw Garmin responses.

  • Answers exclude credentials, account identifiers, raw GPS coordinates, and private cycle logs.

  • Health summaries are informational, not medical advice.

What you ask Claude, and the answers it gets from garmin-owl, are handled under your MCP client's privacy and data-retention settings, so review those before sharing health information with any model.

Limitations and removal

Garmin Connect's API is private, and which metrics exist depends on your device and account. When Garmin changes an endpoint, sign-in or individual reads can fail until garmin-owl is updated.

To remove garmin-owl:

  1. Uninstall the extension in Claude Desktop. For ChatGPT Desktop, uninstall Garmin Owl in the Plugins Directory, then run codex plugin marketplace remove garmin-owl-local.

  2. Delete your garmin-owl folder.

  3. Optionally delete the cache file listed above.

  4. Delete ~/.garminconnect only if no other Garmin tool uses those tokens.

Contributing

Bug reports and pull requests are welcome. CONTRIBUTING.md explains the project layout, design rules, tests, and release process.

Available Tools

19 tools
compare_activitiesA

Compare 2-10 activities; each metric range states how many reported a value.

ParametersJSON Schema
NameRequiredDescriptionDefault
activity_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It adds a useful output nuance ('each metric range states how many reported a value'), but it does not explicitly state that the operation is read-only or disclose any other behavioral traits. The comparison is implicitly safe but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is a single front-loaded sentence with no filler. It packs the core action, the resource bound, and a key output interpretation detail into minimal space.

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?

Given the low complexity (one array parameter) and the presence of an output schema, the description covers the essential scope and an important output nuance. The only notable absence is explicit sibling differentiation, which is not critical for this simple tool.

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

Parameters3/5

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

The schema provides zero description coverage for activity_ids, so the description must compensate. It implies the array-length constraint (2-10) but does not explain what the IDs refer to or any formatting expectations; the meaning relies heavily on the parameter name.

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?

The description states a concrete operation ('Compare') on a bounded resource (2-10 activities), which is specific enough to distinguish it from sibling get_activity/get_activities tools. The count range adds precision beyond a generic 'compare activities' phrasing.

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 context is only implied: the plural comparison semantics suggest choosing this over get_activity/get_activities, but there is no explicit when-to-use or when-not-to-use guidance. An agent must infer the selection criteria from the tool name and siblings.

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

get_activitiesB

List activities in an inclusive range of up to 366 days; defaults to the last 14 days.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
end_dateNo
start_dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It usefully discloses two real constraints: the range is inclusive and capped at 366 days, and the default window is 14 days. It omits pagination, ordering, and what 'limit' does, so it is only partially transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the core action and immediately followed by the two constraints that matter. No filler or redundancy.

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 need not be described. Still, for a zero-coverage 3-parameter tool the description leaves 'limit' and date format undocumented, which is a meaningful gap.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It explains the start/end date semantics (inclusive range, 366-day cap) and the default range, which covers two of three parameters, but says nothing about 'limit' or the date string format.

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 ('List') and resource ('activities'), so the operation is unambiguous. However, it does not differentiate itself from the near-identically-named siblings get_activity and get_recent_activities, leaving the agent to guess which one applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance and never mentions alternatives like get_activity or get_recent_activities. The stated default window (last 14 days) is a behavioral default, not routing guidance, so the agent gets no help choosing among siblings.

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

get_activityB

Get one activity summary, laps, training effect, and available HR/power zones.

ParametersJSON Schema
NameRequiredDescriptionDefault
activity_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly implies a read-only operation and notes that HR/power zones are 'available' rather than guaranteed, but it does not mention behaviors like how missing activity IDs are handled, auth requirements, or response edge cases.

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 description is a single compact sentence with no filler or redundant qualifiers. It front-loads the core action and then enumerates the specific returned data, making it easy to scan.

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 simple one-parameter getter with an output schema present, the description provides the key information needed to invoke it: the singular scope and the kinds of data returned. It omits usage guidance and edge-case behavior, but those are partially inferable from sibling names and the output schema.

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

Parameters3/5

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

The schema has 0% description coverage and only defines activity_id as a required integer. The description does not explicitly explain the parameter, but the property name and title 'Activity Id' are self-explanatory for a one-parameter getter, so the gap is minor.

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 description uses a specific verb and resource ('Get one activity') and lists concrete output categories (summary, laps, training effect, HR/power zones). The word 'one' distinguishes it from plural siblings like get_activities and get_recent_activities, though it does not explicitly contrast with compare_activities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance about when to use this tool versus sibling tools. The singular 'one activity' implies it is for a single activity's detail, but the description does not state to prefer it over get_activities or compare_activities, leaving the selection decision to inference.

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

get_body_batteryA

Get Garmin Body Battery charged/drained and start/end/high/low levels for one day.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo
include_timeseriesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the burden of disclosing behavior. It clearly states what data is returned, but it does not explain behavior around optional inputs like date nullability or include_timeseries, nor does it mention any side effects or access requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no filler. It front-loads the tool's purpose and includes useful output details without becoming verbose.

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?

The output schema covers return values, but the description lacks guidance on parameter behavior and usage when to use this tool versus siblings. It is adequate for a simple read operation but leaves optional-input semantics and selection context to the agent.

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?

The input schema has 0% description coverage, so the description must compensate. It vaguely maps to the date parameter through 'for one day', but it says nothing about include_timeseries, date format, or what a null date means. An agent would need to infer most parameter semantics.

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?

The description uses a specific verb ('Get'), names a clear resource ('Garmin Body Battery'), and specifies scope ('for one day'). It also enumerates the main outputs (charged/drained, start/end/high/low levels), which distinguishes it from sibling tools like get_sleep or get_daily_summary.

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?

The description implies this is the tool for day-level Body Battery data, but it gives no explicit guidance on when to choose it over alternatives like get_daily_summary. There are no stated conditions, exclusions, or references to sibling tools.

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

get_body_compositionA

Get weight and Garmin-provided body composition for at most 366 days.

ParametersJSON Schema
NameRequiredDescriptionDefault
end_dateNo
start_dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

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

Without annotations, the description carries the behavioral burden. It adds transparency about the maximum date range and data source, but it does not disclose default behavior when dates are omitted, date format expectations, or how the endpoint handles over-range requests.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the verb, resource, and key constraint all appear before any secondary details.

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?

With an output schema and only two optional simple parameters, the missing pieces are small, but the lack of default-date behavior and usage routing leaves an agent to infer how to call it without arguments.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It adds the meaningful constraint that start/end dates span at most 366 days, but it does not document date syntax or what null defaults mean for each parameter.

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?

States a specific verb ('Get'), resource ('weight and Garmin-provided body composition'), and a concrete boundary (at most 366 days). This clearly differentiates it from sibling health-data tools by naming the body-composition resource.

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?

The resource name implies use when body composition or weight data is needed, and the 366-day cap is a useful constraint. However, it does not explicitly state when to prefer this tool over siblings or give exclusions.

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

get_cycleB

Get normalized cycle phase/timing without notes, symptoms, or raw day logs.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior3/5

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

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context by noting the output is normalized and excludes notes, symptoms, and raw day logs, but it does not explain what 'normalized' means, how date selection affects results, or any data-availability caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word contributes to the core semantics of what is returned and what is excluded.

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?

The tool is simple with one optional parameter and an existing output schema, so return-value documentation is not required. However, the missing date semantics and lack of usage guidance leave some ambiguity about how to invoke it correctly, especially when a specific date is needed.

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?

The single optional 'date' parameter has 0% schema description coverage and the description does not mention date at all. The agent is given no guidance about accepted formats, default behavior, or what null means, so the description fails to compensate for the missing schema detail.

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 description uses the verb 'Get' with a specific resource, 'normalized cycle phase/timing', and explicitly states what is omitted ('without notes, symptoms, or raw day logs'). This identifies the tool's function clearly, though it does not directly differentiate from the listed siblings since none target cycle data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to use this tool versus alternatives. The exclusions imply a summary use case, but no sibling or alternative tool is named and no contextual conditions are provided.

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

get_daily_summaryC

Get activity time/goals, HR, stress, respiration, SpO2, Body Battery, steps/calories.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read operation, but the description does not clarify date behavior, defaults, authentication requirements, or any other operational constraints. It only lists returned fields rather than explaining how the tool behaves.

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 description is a single compact sentence with a front-loaded verb and a useful list of metrics. There is no filler or repetition, though it sacrifices necessary parameter information for brevity.

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

Completeness2/5

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 is too thin. It omits any mention of the date parameter and provides no usage or behavior context, leaving the agent to infer too much from the tool name and schema alone.

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

Parameters1/5

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

The only parameter, 'date', is completely absent from the description, while schema description coverage is 0%. The schema only provides a type and default, so the agent receives no guidance on date format, accepted values, or what omitting the date means.

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 description states a clear verb and resource: 'Get activity time/goals, HR, stress, respiration, SpO2, Body Battery, steps/calories.' It enumerates the data points returned, making the tool's purpose obvious. It does not explicitly contrast with sibling tools such as get_stress or get_body_battery, but the 'daily summary' framing implies an aggregate view.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the many sibling tools that cover individual metrics. It does not mention alternatives, exclusions, or scenarios where a different tool would be more appropriate.

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

get_hrvA

Get Garmin HRV status and nightly values; optional readings are capped at 48 points.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo
include_timeseriesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds a useful, non-obvious limitation: optional readings are capped at 48 points. The read-only nature is implied by 'Get', though not explicitly stated, so there is still some room for more transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with no filler. The main purpose is front-loaded, and the limiting behavior is appended clearly. Every word earns its place.

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?

The description is adequate for a simple getter, especially since an output schema exists to document return fields. However, it fails to explain the semantics of the date parameter and offers no usage guidance relative to siblings, leaving moderate gaps for an agent to resolve.

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?

Schema description coverage is 0%, so the description must compensate for the two parameters. It indirectly references timeseries readings, which maps to include_timeseries, but it never explains the date parameter, its default behavior, or what the returned values represent. This is insufficient for full parameter clarity.

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?

The description gives a specific verb and resource: retrieving Garmin HRV status and nightly values. This is immediately distinguishable from sibling tools focused on sleep, stress, recovery, or body composition, so an agent can tell what domain this tool belongs to.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to choose this tool over siblings, nor whether it should be used for current status versus historical HRV data. The 'optional readings' note hints at timeseries usage, but the description never states when to use it or what the date parameter should represent.

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

get_recent_activitiesB

List activities from the last 1-90 days, optionally filtered by type (case-insensitive).

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNo
limitNo
activity_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It does disclose the meaningful constraints that stay within a 1-90 day window and that type matching is case-insensitive, but it says nothing about result capping or truncation behavior despite a default limit of 20, nor about read-only safety. Useful context, but not complete for a zero-annotation tool.

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?

One compact sentence with no padding, front-loading the verb, resource, and time bound. It is arguably too terse for a three-parameter tool, but there is zero wasted language.

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-value details are not required. Still, an agent calling this needs to know the default day window and that 'limit' caps results; those gaps are not covered by schema descriptions or annotations, leaving the definition only minimally viable.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It does document the valid range for 'days' (1-90) and the case-insensitive behavior of 'activity_type', but omits the 'limit' parameter entirely and never states the default window of 14 days. Partial compensation for three undocumented parameters.

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 ('List') and resource ('activities') with a bounded scope ('last 1-90 days'), which is more precise than a bare name restatement. However, it never distinguishes itself from the closely named sibling get_activities, leaving the agent to guess which list endpoint is appropriate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of alternatives among the many sibling list tools (get_activities, get_activity, compare_activities), and no exclusions. The recency window is implied by the name but never framed as the selection criterion.

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

get_recoveryA

Combine Garmin sleep, HRV, Body Battery, stress, RHR, readiness; states why any is absent.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations provided, the description carries the disclosure burden, and it succeeds by revealing that the tool explicitly reports missing data with reasons. This is valuable behavioral context beyond a plain metric fetch. It does not mention authentication, rate limits, or data source freshness, but the presence of an output schema reduces the need to describe 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that names the resource, the operation, the involved metrics, and the absence-handling behavior. It has zero filler and front-loads the core aggregation purpose, making it highly scannable for an agent.

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?

Given the output schema exists to document return values, the description covers the essential selection context: what data is aggregated and how missing data is handled. The only minor gap is date format/semantics, but with a single optional parameter and default null, the tool remains fully invocable. This is slightly better than the minimum viable definition.

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 description coverage is 0%, so the description must compensate for the single 'date' parameter. While the description doesn't explicitly mention the parameter, the tool's name and action make it clear that an optional date selects the recovery window. With only one optional parameter and a clear default of null, the semantics are reasonably inferable.

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 description states a specific verb ('Combine') and resource ('Garmin sleep, HRV, Body Battery, stress, RHR, readiness'), making the tool's purpose clear. It does not explicitly differentiate it from sibling tools like get_daily_summary or get_training_readiness, but the aggregation framing sets it apart from the individual metric tools.

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?

The phrase 'states why any is absent' implies this tool is a comprehensive recovery aggregator, useful when a consolidated view is wanted instead of querying each metric separately. It doesn't explicitly list exclusions or alternatives, but the 'combine' wording gives enough context for an agent to select it over getting single-metric siblings.

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

get_recovery_trendC

Trend sleep HR/temp, HRV, RHR, readiness, Body Battery over the last 7/14/28 days.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that output is aggregated over a 7/14/28-day window, which is useful, but says nothing about permissions, whether values are smoothed/baselined, rate limits, or how the trend is computed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the metrics list and the time window are both immediately visible. Nothing is wasted.

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 need not be explained, and the trend window is covered. However, for a tool surrounded by many similar recovery/health siblings, the absence of any routing or scoping guidance leaves the definition only minimally complete.

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?

Schema description coverage is 0% and the single 'days' parameter is undocumented in the schema. The description hints at acceptable values ('7/14/28 days') but never names the parameter, states its default of 7, or clarifies whether other integer values are honored.

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 ('Trend') and enumerates the concrete resources trended (sleep HR/temp, HRV, RHR, readiness, Body Battery) plus the window. The multi-metric trend framing does implicitly separate it from single-metric siblings like get_hrv or get_recovery, but it never explicitly names or contrasts those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance. With near-identical siblings such as get_recovery, get_hrv, get_sleep and get_daily_summary, the agent is left to infer that this tool is for multi-metric trend analysis over a window rather than point-in-time reads. No exclusions or alternatives are stated.

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

get_running_toleranceB

Get 1-90 days of Garmin running distance, impact load, tolerance, and feedback.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNo
end_dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden of revealing behavior. It clearly indicates a read operation and describes the retrieved data, which is useful. However, it doesn't disclose what happens if days is outside the 1-90 range, how end_date interacts with days, or any response-format caveats that the output schema may not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, repetition, or redundant phrasing. Every word adds meaningful detail and the key information is front-loaded.

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?

Given the tool's simplicity, an output schema exists, and the description covers core what-it-returns and the time range, the definition is serviceable. But it lacks usage guidance versus sibling tools and doesn't explain end_date interpretation, leaving a moderately informed agent to guess about edge cases.

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?

With 0% schema description coverage, the description must compensate for undocumented parameters. It does provide a range ('1-90 days') for the days parameter, which adds some meaning, but it says nothing about end_date beyond its name. The description leaves the relationship between days and end_date unclear, and doesn't cover format or validation details.

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 description uses a specific verb ('Get') and clearly identifies the resource (running tolerance) and the data fields returned (Garmin running distance, impact load, tolerance, feedback). It also specifies a time range (1-90 days), making the tool's scope unambiguous. It doesn't explicitly differentiate from siblings like get_training_status or get_daily_summary, but the metric list is distinctive enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives; it doesn't mention any sibling tools, prerequisites, or conditions that would select this tool over others. The '1-90 days' phrase is a parameter constraint, not usage guidance.

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

get_sleepC

Get sleep score/need, stages, HR/stress, respiration, SpO2, and skin-temp deviation.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

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

No annotations are present, so the description carries the full burden of behavioral disclosure. The verb 'Get' implies a read-only operation, but the description does not explain date semantics (e.g., what passing null means), timezone behavior, or how missing sleep data is handled. It only lists metric categories.

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 description is a single, front-loaded sentence that efficiently lists the tool's key outputs with no filler. It is appropriately compact, though the brevity contributes to the omission of parameter and usage context captured in other dimensions.

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

Completeness2/5

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

An output schema exists, so the return shape is covered, but the date parameter's format and behavior are undocumented, no sibling differentiation or usage conditions are given, and there are no annotations to fill gaps. These omissions make confident invocation harder than necessary for a tool with one critical parameter.

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

Parameters1/5

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

The description does not mention the sole 'date' parameter, which has 0% schema description coverage. The input schema only indicates a string/null with a default of null, leaving the expected date format and meaning of null undocumented; the description fails to compensate for this gap.

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 description uses a specific verb ('Get') and names the resource ('sleep') while enumerating the returned metrics: sleep score/need, stages, HR/stress, respiration, SpO2, and skin-temp deviation. This makes the tool's function clear, though it does not explicitly differentiate it from overlapping siblings like get_recovery, get_hrv, and get_stress.

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?

There is no explicit statement about when to use this tool versus alternatives. The name and metric list imply it is for sleep-related data, but no exclusions or alternate tool mentions are provided, leaving the selection to inference.

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

get_stressA

Get Garmin daily average/max stress and per-band durations; series capped at 48 points.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo
include_timeseriesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly notes the series is capped at 48 points, a meaningful limitation, and indicates daily aggregation. However, it does not address auth, permissions, or other side effects, though the cap is a key disclosed behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 12-word sentence that front-loads the primary action and result before stating the limitation. Every word earns its place with no redundancy.

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?

The description is adequate for a simple tool but leaves notable gaps: parameter semantics are thin, and 'per-band durations' is not defined. The presence of an output schema covers return types, but usage and parameter details would need to be inferred from parameter names and sibling context.

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

Parameters3/5

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

The input schema has 0% description coverage, so the description must compensate for the two parameters. It indirectly relates to `date` via 'daily' and to `include_timeseries` via 'series capped', but never explains accepted date formats or how the timeseries flag alters the response, leaving the agent to infer.

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?

The description begins with a specific verb and resource ('Get Garmin daily average/max stress') and clearly specifies output contents ('per-band durations'), making it distinct from sibling tools focused on other metrics like sleep, HRV, or body battery.

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?

The description implies usage context through the metric name 'stress' but does not explicitly state when to use this tool over siblings or mention any exclusions. No alternatives are named, leaving the agent to infer from the resource name.

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

get_training_contextA

Get recovery and preceding training anchored to date, with transparent comparisons.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It does disclose a behavioral trait beyond a plain fetch — 'transparent comparisons' signals that the tool performs analysis and surfaces the underlying values — and 'anchored to date' clarifies filtering behavior. However, it omits operational details such as what happens when the date parameter is null and how 'preceding training' is bounded (how far back, how many sessions).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 12-word sentence with the primary content ('recovery and preceding training') front-loaded before the qualifiers. Every word earns its place, there is no filler, and it is not a tautological restatement of the tool name.

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?

The output schema covers return shape and the tool is a simple one-parameter read operation, which lowers the bar. Yet with no annotations, the null-date behavior, the comparison baseline, and routing among a crowded sibling set remain unstated, so an agent would still need to make assumptions before invoking it.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate, and it does tie the only parameter 'date' to the core behavior via 'anchored to date.' It fails to state expected date format, timezone handling, or the semantics of null even though the schema defaults date to null, so an agent must infer what an omitted date yields.

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 description names a specific verb and resource: get 'recovery and preceding training anchored to date,' which is a composite scope that differentiates it from single-domain siblings like get_recovery or get_activities. However, 'with transparent comparisons' is vague about what is being compared against what, leaving some ambiguity about the tool's exact function.

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?

The composite scope ('recovery AND preceding training') implies a comparison-oriented use case, which offers situational context. But the description never states when not to use this tool or names alternatives such as get_recovery for recovery-only needs, leaving sibling routing to inference.

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

get_training_loadC

Get acute/chronic load, ratio/status, focus/targets, VO2 max, scores, acclimation.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

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

There are no annotations, so the description must bear the full behavioral disclosure burden. It only lists returned metric categories and gives a 'Get' verb; it does not explain date handling, what happens when date is omitted, units, or any other behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, so it is concise. However, the structure is a long slash-separated list of jargon ('acute/chronic', 'ratio/status', 'focus/targets') that is cryptic and harder to parse than necessary.

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

Completeness2/5

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

Although an output schema exists, the description lacks enough context for correct invocation. It does not explain the optional date's role or differentiate this tool from the sibling readiness, recovery, and activity tools, leaving important selection and call-time behavior unclear.

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?

The schema has one optional date parameter with 0% description coverage, and the tool description does not mention date at all. The parameter name 'date' and its default of null provide a minimal hint, but the description adds no meaning about format, default behavior, or how date filters the load metrics.

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

Purpose3/5

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

The description uses the verb 'Get' and names a resource ('training load') followed by a list of metric categories, so the general purpose is recognizable. However, it is an indiscriminate enumeration ('acute/chronic load, ratio/status, focus/targets, VO2 max, scores, acclimation') that does not distinguish this tool from closely related siblings like get_training_readiness or get_recovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not say when to use get_training_load versus alternatives, nor does it state any exclusions or conditions. An agent is left to guess which of the many overlapping health-metric tools is appropriate.

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

get_training_readinessC

Get Garmin training readiness, component percentages, and factor feedback.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.8/5.0
Behavior2/5

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It only states that the tool gets readiness data; it does not reveal whether the date is required, what happens when no date is given, whether it returns data for multiple days, or any side effects. 'Get' implies read-only, but the description does not explicitly confirm this.

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 description is a single, efficient sentence that names the resource and key output components with no fluff. It loses a point because the extreme brevity omits necessary context about the date parameter, but the existing text is well-structured and front-loaded.

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?

For a tool with one optional parameter and an output schema, the description provides a minimal but acceptable overview of the return value. However, it is incomplete for correct invocation: it does not explain the role of the date parameter or how this tool fits among the many similarly named readiness/recovery siblings.

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?

The schema has 0% description coverage for the only parameter, 'date'. The description does not mention the date parameter at all, so the agent must infer formatting, meaning, and default behavior from the schema's title and default value alone. The description fails to compensate for the low schema coverage.

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 description clearly states a specific verb and resource ('Get Garmin training readiness') and adds detail about the expected response contents ('component percentages, and factor feedback'). This distinguishes it from generic sibling tools like get_sleep or get_activities, though it does not explicitly contrast with get_recovery or get_body_battery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool instead of siblings like get_recovery, get_body_battery, or get_daily_summary. The description does not mention whether it supports a specific date, how it relates to other readiness metrics, or what inputs should be supplied.

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

get_training_weekA

Summarize a Mon-Sun week; every total discloses how many activities reported the metric.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior4/5

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

There are no annotations, so the description carries the full behavioral burden. It discloses a non-obvious reporting trait: each total states the count of activities that reported the metric, protecting against misinterpretation of incomplete aggregates. It also pins down the week boundary (Mon-Sun).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler; the purpose is front-loaded and the reliability caveat is appended in a second clause. Every word earns its place.

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 one-optional-parameter tool with an output schema, the description covers the aggregation window and a metric caveat. The main gap is the undocumented default/null-date behavior, which the schema leaves unresolved. That gap is minor given the low complexity.

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?

Schema coverage is 0%, and the description never mentions the single 'date' parameter, its format, or the meaning of null (default). The parameter name is self-explanatory, but the description does not compensate for the schema's lack of documentation. An agent must guess how to format the date and what a null value does.

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 ('Summarize') and resource ('a Mon-Sun week'), making the function's scope immediately clear. It contrasts implicitly with get_daily_summary by defining the weekly aggregation granularity, though it does not explicitly name any sibling.

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?

The 'Mon-Sun' qualifier conveys that a provided date is interpreted within its calendar week, which is useful routing context. It implies this tool is for weekly rather than daily or single-metric summaries, but gives no explicit exclusions and names no alternatives.

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

get_training_zonesA

Get configured Garmin HR-zone and cycling power-zone floor thresholds.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are present, so the description carries the disclosure burden. It signals a non-mutating retrieval operation ('Get') and clarifies that the data source is the user's configured thresholds. It does not mention output shape or edge cases, but the output schema covers return structure, making this a minimally sufficient disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single tight sentence with no filler, and the specific resource ('Garmin HR-zone and cycling power-zone floor thresholds') is front-loaded. Every word earns its place.

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 zero-parameter, read-only tool, the description covers what is returned and where the data comes from. The output schema covers return details, and sibling names help disambiguate intent. The only notable gap is usage guidance, which is minor given the tool's low complexity.

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 are no argument semantics to document. With no parameters, the baseline of 4 applies and the description does not need to compensate for schema gaps.

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?

The description states the verb 'Get' and a specific resource: 'configured Garmin HR-zone and cycling power-zone floor thresholds.' Unlike sibling tools, which return measured metrics like sleep or readiness, this targets stored configuration thresholds, making it readily distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus siblings such as get_training_context or get_training_load. The description neither states use cases nor exclusions, leaving the agent to infer intent from the tool name alone.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.2.0
    • Addedget_running_tolerance
    • Addedget_training_zones
  2. 17 tool updatesv0.1.0
    • First observedcompare_activities
    • First observedget_activities
    • First observedget_activity
    • First observedget_body_battery
    • First observedget_body_composition
    • First observedget_cycle
    • First observedget_daily_summary
    • First observedget_hrv
    • First observedget_recent_activities
    • First observedget_recovery
    • First observedget_recovery_trend
    • First observedget_sleep
    • First observedget_stress
    • First observedget_training_context
    • First observedget_training_load
    • First observedget_training_readiness
    • First observedget_training_week

TDQS

B3.2/5.0

Scored across 19 tools

Disambiguation3/5

The set contains several overlapping training-load/recovery tools: get_training_context, get_training_week, get_training_load, get_recovery_trend, get_recovery, and get_training_readiness all pull closely related fatigue/recovery data. While descriptions differentiate them somewhat, an agent could easily choose the wrong one. The activity listing tools (get_activities, get_recent_activities) are also somewhat redundant.

Naming Consistency5/5

Every tool follows a clean snake_case verb_noun pattern (get_*, compare_activities), with clear subjects like body_battery, training_load, recovery_trend. No camelCase or naming anomalies.

Tool Count4/5

19 tools is slightly heavy but reasonable for the breadth of Garmin health/training data covered. However, the overlap in recovery/training tools suggests some could be consolidated.

Completeness4/5

The surface covers a wide range of Garmin metrics: activities, sleep, stress, HRV, body composition, cycling, and training load. It is missing write operations (e.g., logging activities, setting goals) but for a read-only Garmin data server, coverage is strong.

Maintenance

ActivityActive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers