Provides a typed client for Garmin Connect, enabling authentication and access to health, fitness, and activity data, including wellness, activities, training metrics, workouts, gear, courses, devices, badges, body composition, women's health, golf, nutrition, and training plans. Supports reading and writing Garmin Connect data, workout building, exercise catalogue validation, MFA login, and automatic token refresh.
Unofficial. Not affiliated with, endorsed by, or supported by Garmin. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries.
A zero-dependency TypeScript client for Garmin Connect, for Node and Next.js server runtimes. It talks to the same undocumented endpoints the mobile app uses, with a fully typed, promise-based API.
It handles Garmin's undocumented SSO/OAuth flow, refreshes tokens for you, and gives you 200 typed methods over the endpoints the mobile app uses, plus two things that exist because Garmin's API is quietly hostile in specific places:
A fluent workout builder. Garmin's workout JSON has four traps that produce a silently wrong
workout rather than an error: global stepOrder numbering that runs through repeat children,
id/key triples that must agree, rests measured in a different field from times, and pace targets
expressed as descending metres per second. buildWorkout makes all four unreachable (see
WORKOUTS.md).
The exercise catalogue, type-checked. Garmin stores an unrecognised exercise name as an empty
string and returns success, so a typo costs you the exercise and tells you nothing.
garminconnect-js/exercises turns that into a compile error, with 1830 names verified one by one
against a live account.
Behind both: a verification habit. Every method carries a live-verification status in
AGENTS.md, and a write is only "verified" once the stored value has been read back:
a 2xx on its own has twice hidden a real defect here.
Want a running app first? garminconnect-nextjs-starter
is a Next.js template that signs in (MFA included) and charts your sleep and HRV. Click
Use this template, and you're a npm run dev away from your own data. Or try the
live demo first.
If you're an AI coding agent (or configuring one), read AGENTS.md first: it's a
terser, higher-signal briefing than this README and calls out what does not exist here.
garminconnect-js fetches your health, fitness, and activity data from
connect.garmin.com so you can use it in your own Node or Next.js
server code, without scraping HTML or reverse-engineering the mobile app yourself.
It covers wellness, activities, training metrics, workouts, gear, courses, devices, badges, body
composition, women's health, golf, nutrition and training plans (see API coverage
for the breakdown). For anything it doesn't wrap, client.connectapi() calls any Garmin Connect
endpoint with the same auth.
Compatibility: requires Node.js 18+. This library is server-only (see Node runtime only below for why). It has no runtime dependencies and does not run in a browser or on an Edge runtime.
Status: 0.x, so the public API may still change between minor versions; breaking changes are
listed in CHANGELOG.md. The endpoints underneath are undocumented and belong to
Garmin, who can change them at any time. That is why every method carries a verification date
rather than an assurance.
Garmin Connect has no public, documented API. Everything here talks to the same endpoints connect.garmin.com and the Garmin Connect mobile app use, so Garmin can change or break any of it without notice. Don't build anything safety-critical on it, and expect to update when login stops working.
Garmin returns 412 PreconditionFailedException: "The user is from EU location, but upload consent is not yet granted or revoked" for every write (addWeighIn, importActivity,
createManualActivity, workout uploads, gear writes: all of them) on an EU-region account that
has not clicked through Garmin Connect's upload-consent flow. This was hit live during this
project's own development. It is an account-state precondition, not a library bug: the request
shape and URL are correct, and Garmin's server is refusing the write until the account owner
grants consent in Garmin Connect's own settings UI. No method in this library wraps Garmin's
consent-status check, but you can read it directly:
// Response shape below is LIVE-OBSERVED, not assumed. There is no `enabled` field:
// the signal is `userOption`, which reads "opt-in" once consent has been granted.
const consent = await client.connectapi<{ userOption?: string }>(
"/gdprconsent-service/feature/UPLOAD",
);
const uploadConsentGranted = consent?.userOption === "opt-in";If your first write against an EU account 412s, check this before assuming your request is wrong.
Related MCP server: garmin-mcp
npm install garminconnect-jsimport { GarminClient, Garmin, FileTokenStore } from "garminconnect-js";
const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
const result = await client.login(process.env.GARMIN_EMAIL!, process.env.GARMIN_PASSWORD!);
if (result.state === "mfa_required") {
// login() does not throw or block on MFA; finish it with the code Garmin sent.
await client.resumeLogin(result.mfaState, await promptForCode());
}
const garmin = new Garmin(client);
console.log(await garmin.getUserProfile());(promptForCode is yours to supply: stdin in a script, a second HTTP request in a web app; see
MFA across two HTTP requests.) Tokens are now in ./tokens, so a
later process skips the password entirely:
const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
if (!(await client.loadTokens())) throw new Error("Not connected to Garmin: log in first");
const garmin = new Garmin(client);loadTokens() returns false rather than throwing when the store is empty.
new GarminClient(options?) accepts:
Option | Default | What it does |
|
| Where tokens are loaded from and saved to. See Authentication. |
|
|
|
|
| Per-request timeout for ordinary JSON calls. |
|
| Retries after the first attempt, on a network error or a 408/500/502/503/504. POST is never retried, so a write cannot be duplicated. |
|
| Base delay between retries, doubling each attempt (500, 1000, 2000 ms). |
|
| Swap in your own |
| random 3000â8000 | Pause before the SSO widget's credential POST, used only when the mobile login is rate limited (see Authentication). Set |
Login follows Garmin's SSO flow: GarminClient.login(email, password) exchanges credentials for an OAuth1 token, then exchanges
that for a short-lived OAuth2 access token. Both are handed to your TokenStore.
Rate-limited sign-in. Garmin rate limits the mobile sign-in route, per client id and
source IP, often after one or two sign-ins. When the mobile sign-in page or /mobile/api/login
answers HTTP 429, or /mobile/api/login reports a 429 inside a 200 JSON reply, login() signs
in once more through Garmin's SSO web widget (/sso/embed + /sso/signin), which sends no
client id, and returns the same tokens. If the widget is rate limited too,
GarminRateLimitError names the widget URL; other widget failures start with
Mobile login rate limited; , and a rejected password keeps its SSO error: prefix. Tokens
refresh for about 30 days without signing in, so keep them in a TokenStore rather than
signing in again.
Where tokens are stored: wherever your TokenStore puts them. FileTokenStore writes
oauth1_token.json and oauth2_token.json to a directory you choose (./tokens in the
examples above), using garth's on-disk format, so tokens produced by Python garth load here
unchanged. For serverless, implement the same three-method interface against your own
database or cache; see TokenStore example below.
Auto-refresh: the OAuth2 access token refreshes automatically, using the OAuth1 token (not
an OAuth2 refresh token; Garmin's flow doesn't have one), before it expires. You never call
refresh yourself; connectapi() calls do it transparently and persist the refreshed token back
to your store.
Observed lifetimes: OAuth2 access tokens have lasted roughly 27 hours, and the OAuth1 token
about 30 days. In practice a session keeps rolling forward as long as you use it (call any
method) at least once every 30 days. Beyond that window, GarminAuthError is thrown and you
need to log in again.
Cached tokens: once tokens exist in your store, client.loadTokens() reads them back and
no further password prompt is needed until the refresh window above lapses.
A third-party request at login. The OAuth consumer key and secret are not bundled; like
garth, the library fetches them from https://thegarth.s3.amazonaws.com/oauth_consumer.json,
a bucket run by garth's author. That happens once per process, on the first login or token
refresh, and the result is cached. If that URL is unreachable (an outage, or a server whose
egress is firewalled), login and refresh fail with a GarminConnectionError. Allow-list it if
you restrict outbound traffic.
login() returns { state: "mfa_required", mfaState } instead of throwing. mfaState is plain
JSON with no password in it, so it survives a round trip through a session store. That is
what makes MFA work on serverless, where the code arrives in a different request than the one
that started the login:
// app/api/garmin/login/route.ts
export const runtime = "nodejs";
export async function POST(req: Request) {
const { email, password } = await req.json();
const client = new GarminClient({ tokenStore: myStore });
const result = await client.login(email, password);
if (result.state === "mfa_required") {
await session.set("garminMfa", result.mfaState); // encrypted session
return Response.json({ mfaRequired: true, method: result.mfaState.mfaMethod });
}
return Response.json({ mfaRequired: false });
}
// app/api/garmin/mfa/route.ts
export const runtime = "nodejs";
export async function POST(req: Request) {
const { code } = await req.json();
const mfaState = await session.get("garminMfa");
const client = new GarminClient({ tokenStore: myStore });
await client.resumeLogin(mfaState, code);
await session.delete("garminMfa");
return Response.json({ ok: true });
}Treat mfaState as a short-lived secret: mfaState.cookies is a live, partially authenticated
SSO session, so anyone holding it can finish the login with the code. Encrypt it at rest, scope it
to the session that started the login, and delete it once used. The MFA path is exercised live by
npm run login (see See it run) as well as unit-tested.
mfaState.flow says which sign-in route produced it: "mobile" (the default; states saved by
0.1.0 or 0.2.0 have no flow and count as mobile) or "widget". A widget state also holds the
page's CSRF token and form parameters. Pass either kind straight back to resumeLogin; read
loginParams only after checking flow !== "widget".
This library uses node:crypto and Buffer. It does not run on the Edge runtime. In a Next.js
route handler:
export const runtime = "nodejs";Never import it into a Client Component: credentials and tokens must stay on the server.
// lib/garmin.ts
import { GarminClient, Garmin } from "garminconnect-js";
export async function getGarmin() {
const client = new GarminClient({ tokenStore: myStore });
if (!(await client.loadTokens())) throw new Error("Not connected to Garmin");
return new Garmin(client);
}
// app/api/sleep/route.ts
export const runtime = "nodejs";
export async function GET(req: Request) {
const date = new URL(req.url).searchParams.get("date")!;
const garmin = await getGarmin();
return Response.json(await garmin.getSleepData(date));
}Garmin caches the resolved user profile (and user settings) for the lifetime of the instance.
getGarmin() above builds a fresh Garmin per request, which is fine for a single call, but any
date-scoped method (getSleepData, getStepsData, ...) resolves displayName first, so a new
Garmin per request costs an extra socialProfile fetch on every call. If a request handler
makes several Garmin calls, or you're calling from a long-lived process (a cron job, a worker),
hoist and reuse one Garmin instance instead of building a new one per call.
Dates are interpreted as UTC calendar dates, not local ones. Passing a Date object (instead
of a "YYYY-MM-DD" string) is formatted with toISOString().slice(0, 10), so a caller in a
negative UTC-offset timezone (e.g. US Pacific) who calls new Date() late in their local day can
get tomorrow's date, because it's already tomorrow in UTC. Pass an explicit "YYYY-MM-DD" string
when you need the calendar date in the user's own timezone.
getSleepData returns SleepData | null (and so does getHrvData) rather than throwing when
Garmin has no data for the requested date. Check for null before using the result.
FileTokenStore suits scripts and a single long-lived server. On serverless, implement the
three-method interface against whatever you already run:
import type { TokenStore, Tokens } from "garminconnect-js";
// `Redis` here is illustrative; bring your own client's type
// (e.g. `import type { Redis } from "ioredis";`).
type Redis = { get(key: string): Promise<string | null>; set(key: string, value: string): Promise<unknown>; del(key: string): Promise<unknown> };
export class RedisTokenStore implements TokenStore {
constructor(private redis: Redis, private userId: string) {}
async load(): Promise<Tokens | null> {
const raw = await this.redis.get(`garmin:${this.userId}`);
return raw ? (JSON.parse(raw) as Tokens) : null;
}
async save(tokens: Tokens): Promise<void> {
await this.redis.set(`garmin:${this.userId}`, JSON.stringify(tokens));
}
async clear(): Promise<void> {
await this.redis.del(`garmin:${this.userId}`);
}
}Persist the whole Tokens object, and keep expires_at and refresh_token_expires_at
as numbers. Every refresh decision reads them. Storing the whole JSON blob, as above, keeps
them; a database schema or a field allowlist that drops them does not, and the client then treats
the token as expired (it fails closed) and refreshes on every call. Round-trip your store once in
a test and assert both numbers survive.
import { readFile } from "node:fs/promises";
const file = new Blob([await readFile("ride.fit")]);
// As an import (the extension picks the endpoint, and must be .fit, .gpx or .tcx):
const imported = await garmin.importActivity(file, "ride.fit");
// Or as an ordinary device-sync-shaped upload:
await garmin.uploadActivity(file, "ride.fit");Both are live-verified: a synthetic GPX was uploaded, found by polling getActivities once Garmin
finished processing it asynchronously (a few seconds to ~20s), then deleted. A duplicate file
makes importActivity throw a GarminConnectionError ("Activity already exists"). The two hit
different endpoints with different headers; see AGENTS.md section 6 before
swapping one for the other.
Both are built on client.upload(file, filename, path?, options?), which you can call directly
for an endpoint no method wraps. It posts multipart form data (field name file) to path
(default /upload-service/upload) with a 60s default timeout:
await client.upload(file, "ride.fit", "/upload-service/upload", { timeoutMs: 120_000 });A course is a saved route you can send to a device and follow. Creating one from a GPX file is two
steps inside Garmin (parse, then save), and createCourseFromGpx does both:
const course = await garmin.createCourseFromGpx(new Blob([gpxText]), "loop.gpx", {
name: "Sunday loop",
activityTypeId: 10, // a Garmin activity-type id; the default, 1, is running
privacy: "private",
});
await garmin.updateCourse(course!.courseId!, { name: "Sunday long loop", privacy: "public" });
const gpx = await garmin.downloadCourseGpx(course!.courseId!);Right after creation Garmin is still processing the course, and an update or delete can fail with
a 429 "not yet ready": a GarminRateLimitError, though it is not rate limiting. Retry after a few
seconds.
Error | Meaning |
| Base class for everything below; also thrown directly for malformed responses. |
| 401/403, failed SSO, or expired tokens. Log in again. |
| 429. Carries |
| Network failure or timeout (after retries), and a few semantic HTTP statuses that some services deliberately re-raise as this class: every HTTP error from |
| Any other non-2xx. Carries |
| The account has no Garmin Connect+, which this method needs (food logging). Carries |
Creating a Garmin workout by hand means writing deeply nested JSON with several non-obvious rules:
step numbering that runs across repeat blocks, enum references that must agree in three places, and
pace targets expressed as descending metres-per-second. buildWorkout handles all of that:
import { buildWorkout } from "garminconnect-js";
const workout = buildWorkout("4 x 1 km", { sport: "running" })
.warmup({ time: 600, target: { heartRateZone: 2 } })
.repeat(4, (set) =>
set
.interval({
distance: 1000,
target: { pace: { minPerKm: [4.5, 5] } },
secondaryTarget: { cadence: [176, 184] },
})
.recovery({ time: 120 }),
)
.cooldown({ lapButton: true })
.build();
await garmin.uploadWorkout(workout);It covers all twelve sports, every step and end-condition type, primary and secondary targets,
nested and time-boxed repeats, swim strokes/drills/equipment, strength exercises and weights, and
multi-sport bricks. uploadWorkout still accepts raw JSON, so the builder is optional.
For strength work, Garmin accepts an unknown exercise name and silently stores it as an empty
string: no error, just a step with no exercise. So the builder type-checks it: once you pick a
category, name autocompletes to that category's names, and anything else is a compile error.
All 1830 names were verified one by one against a live account:
.interval({ reps: 8, exercise: { category: "SQUAT", name: "BARBELL_BACK_SQUAT" }, weightKg: 60 })The catalogue itself is a separate entry point, garminconnect-js/exercises, so its data never
reaches the root bundle. Import it when you need the list or a runtime check:
import { EXERCISES, exercise, isExerciseName } from "garminconnect-js/exercises";
EXERCISES.SQUAT; // all 106 squat names, e.g. for a picker
exercise("SQUAT", "BARBELL_BACK_SQUAT"); // the same compile-time check, as a helper
isExerciseName("SQUAT", nameFromYourDatabase); // for names that are only strings at runtimeâ WORKOUTS.md is the full guide, with a worked example for every sport and a
reference for every option. Runnable versions of those examples live in
examples/workout-gallery.ts.
@dynamicsninja/garminconnect-mcp puts this library behind an MCP server, so you can ask Claude
Desktop to build a workout, schedule it and send it to your watch, or to read your sleep and
training data. It ships from this repo, in lockstep with the library.
Or use it without installing anything: add https://garmin.ficdev.xyz/mcp as a custom connector in claude.ai (see mcp/README.md).
201 typed methods across 13 categories. Each category links to a generated
docs/api/ page with every method's signature, a call you can paste, and
its live-verification status (confirmed against a real Garmin account, not merely unit-tested).
Category | Methods | Verified live | Covers |
35 | all | steps, heart rate, sleep, HRV, stress, SpO2, respiration, hydration, blood pressure, body battery, whole-day summaries | |
39 | all | list/filtered search/detail, splits, weather, workouts done, manual creation, import/upload, exercise sets, gear links, personal records, event type, RPE, feel and distance | |
18 | all | training status, race predictions, FTP, lactate threshold, HR/power zones (and setting HR zones), endurance and hill score | |
19 | all | CRUD, per-sport upload, scheduling, schedule summaries, training-plan and Garmin Coach workouts, device push | |
6 | all | CRUD, activity defaults, stats | |
8 | all | import a GPX, create, rename, privacy, export as GPX, delete | |
6 | all | races and other events: list, read, create, update, delete; races from Garmin's catalogue | |
6 | all | devices, settings, alarms, solar, last used | |
9 | all | earned/available badges, badge detail, challenges | |
9 | 8 of 9 | weigh-ins, weight goals, body composition (FIT upload) | |
11 | all | menstrual cycle, pregnancy | |
5 | 3 of 5 | summary, scorecards, shots, clubs, stats | |
30 | allš | profile, settings, goals, nutrition and food logging², training plans, GraphQL, logout |
š logout() makes no HTTP call, so there is nothing to verify against Garmin.
² Food logging (search, custom foods, logging, deleting) needs Garmin Connect+, which needs a paired Garmin device; verified on such an account. garmin.hasConnectPlus() tells you up front, CONNECT_PLUS_METHODS lists the methods, and without it they throw GarminConnectPlusRequiredError.
Still unverified: getGolfScorecard and getGolfShotData, because no available account has a
recorded round. getGolfShotData also returns an unexplained 410 against a made-up id, and one
real scorecard would show whether Garmin has retired that endpoint. getWeightGoals is partial:
it answers on both accounts, but neither has a weight goal, so only the empty response is confirmed.
Worth knowing before you call:
addHydrationData is permanent: Garmin has no delete for it.
The badge-challenge endpoints reject start=0 server-side; pass start >= 1.
Women's-health writes need cycle-tracking settings that only Garmin's own first-run wizard creates. Run it once in the web UI first.
getActivity(id) is not shaped like a list row: distance, duration and the rest are under
summaryDTO, the type under activityTypeDTO.
searchActivities returns an empty list, not an error, for an unknown sortBy or
requiredFields name (Garmin's names, not always the response's: averageHR is unknown).
Many response types are filled in from Garmin's official Personal API spec, also exported on
their own as the PersonalApi type namespace. Every field there is optional: Garmin leaves out
what does not apply.
The per-method gotchas and the evidence behind every verification are in AGENTS.md
section 3.
The standing rule behind all of this: a live write probe only runs when the value can be read back and the change undone, and a 2xx is never accepted as evidence on its own.
git clone https://github.com/DynamicsNinja/garminconnect-js.git
cd garminconnect-js
npm installCommand | What it does |
| Typecheck, lint, build and test, in that order: what CI and |
| Bundles |
|
|
| ESLint over |
| Prettier, writing in place. |
| Runs the unit/integration suite against mocked HTTP (see Testing). |
| Same, in watch mode. |
| Runs the live suite against the real Garmin API; requires |
| Regenerates |
| One-time interactive login; writes tokens to |
| Runs |
| Refreshes the scrubbed fixtures under |
| Live read probes against the test account, by category ( |
| Live write probes: create, read back, delete. |
| Builds, uploads, reads back and deletes a workout for each of the twelve sports. |
| The builder's full option cross-product for swim, bike and run, compared field by field on read-back. |
| Verifies candidate exercise names by upload and read-back, keeping only those Garmin echoes back. |
| Login to, and read-only probe of, a real personal account, on a transport that refuses any non-GET. Uses its own |
| Read-only, real account: calls every path in Garmin's Personal API spec on our host and diffs the field names against the spec. Fetches the spec from developer.garmin.com. |
| Regenerates |
The four write commands (smoke:write, smoke:gaps, smoke:builder, smoke:matrix) and
verify:exercises refuse to run unless the logged-in profile matches GARMIN_TEST_PROFILE_ID:
they are for a disposable test account, never a real one. smoke:real has the inverse gate: it
refuses if the profile DOES match.
Release: npm run bump -- X.Y.Z bumps the library and @dynamicsninja/garminconnect-mcp together; pushing tag
vX.Y.Z publishes both.
Credentials from a .env file: the dev scripts (npm run login, npm run demo,
npm run record) load GARMIN_EMAIL and GARMIN_PASSWORD from a .env file in the repo root,
if one exists, so credentials stay out of shell history. npm run login:real reads
GARMIN_REAL_EMAIL/GARMIN_REAL_PASSWORD instead, so both accounts can share one .env. Real
environment variables take precedence, and .env is gitignored.
npm run login and npm run demo talk to the real connectapi.garmin.com /
sso.garmin.com endpoints using your real Garmin credentials and your real account data.
Concretely:
npm run login sends your email and password to Garmin's SSO service over HTTPS, the same
request the mobile app makes, and writes real OAuth tokens to ./tokens (gitignored).
npm run demo and npm run record then use those tokens to fetch your own steps, heart
rate, sleep, HRV, activities, and body-composition history.
npm run demo's "Export all to JSON" option writes a file under ./export/ (gitignored) that
has been passed through the same scrub() helper the test fixtures use. But scrubbing
redacts by field name, not by content, so free-text fields (activity titles, notes) are not
scanned. Treat any export as containing real personal data.
None of your data leaves your machine except in requests to Garmin's own servers. The only other request is the OAuth consumer-key fetch described under Authentication, which carries no account data.
Two files show it working end to end:
scripts/login.ts: one-time interactive login. Prompts for an MFA code on
stdin if Garmin asks for one, then writes tokens to ./tokens.
examples/demo.ts: an interactive, numbered-menu demo (npm run demo)
that loads those tokens and walks through the categories this library implements: profile,
daily health, activities, body composition, and a JSON export.
$ npm run login
MFA code (sent via email):
Tokens written to ./tokens
$ npm run demo
garminconnect-js demo
=====================
1) User & Profile
2) Daily Health
3) Activities
4) Body Composition
5) Export all to JSON
0) Exit
> 1
--- User & Profile ---
Display name : jdoe-display
Full name : Jamie Doe
Profile ID : 1234567
Unit system : metric
garminconnect-js demo
=====================
1) User & Profile
2) Daily Health
3) Activities
4) Body Composition
5) Export all to JSON
0) Exit
> 2
--- Daily Health (2026-09-21) ---
Steps: 8742 Distance: 6.3 km Active kcal: 512
Resting HR: 58 bpm Min/Max: 54/142 bpm
Sleep data: available
HRV: available
Body Battery entries: 24
garminconnect-js demo
=====================
1) User & Profile
2) Daily Health
3) Activities
4) Body Composition
5) Export all to JSON
0) Exit
> 0
Goodbye.(Numbers above are synthetic: a demo fixture, not a real account.)
npm test874 tests across 60 files, all against mocked HTTP (via msw): no network access and no
credentials required. Covers auth/SSO/MFA, token storage and refresh, the HTTP fetcher's retry
and error handling, every service method, and the public build output.
npm run test:liveRuns a separate suite against the real Garmin API. Requires tokens from npm run login and is
not part of CI; run it locally when you want to confirm live behavior.
Testing your own code against this library: mock at the fetch layer rather than stubbing
Garmin methods. Pass a mock (or an msw handler) as GarminClientOptions.fetchImpl, and the
real request construction, auth headers, retries and response parsing all still run.
Before opening a PR:
npm run check passes: typecheck, lint, build and tests, in CI's exact order. CI runs this
same script, so a green local run cannot diverge from a green pipeline by omission.
npm run docs:api has been re-run if you changed a method or its AGENTS.md row, and the
regenerated docs/api/ files are committed. A test fails if they are stale.
New endpoints follow the existing services/* + Garmin method pattern, with a typed
response interface in types/.
Commits follow Conventional Commits.
No real credentials, tokens, personal names, emails, or GPS coordinates in anything
committed. Recorded fixtures must go through scrub() and be manually inspected before
staging, per the reminder npm run record prints.
If you're changing what's implemented, update the API coverage table above rather than leaving it stale.
Note anything user-visible in CHANGELOG.md.
Security issues go through SECURITY.md, privately, not a public issue: this
library holds live Garmin credentials on people's behalf.
If this library saves you time, you can support its development:
connect.garmin.com: the service this library talks to.
CHANGELOG.md: what changed in each release.
The SSO/OAuth flow was originally derived from garth and
python-garminconnect; attribution is in NOTICE.
MIT. See NOTICE for third-party attribution.
Records a weight (kg) with optional body-composition fields such as body fat and muscle mass, uploaded as a .fit weight-scale file built in memory. Builds a .fit binary in memory and uploads it via client.upload to /upload-service/upload; weight validated positive/finite, throws GarminError otherwise.
| Name | Required | Description | Default |
|---|---|---|---|
| extra | No | ||
| weight | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is covered. The description goes beyond that by disclosing the construction of a .fit binary in memory, the upload endpoint, and the validation/error contract ('weight validated positive/finite, throws GarminError otherwise') â genuinely useful behavioral context an agent couldn't infer from annotations.
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?
Front-loaded and information-dense, but the second sentence repeats the .fit-in-memory point already made in the first ('uploaded as a `.fit` weight-scale file built in memory' vs 'Builds a `.fit` binary in memory'), spending words on redundancy rather than the missing field documentation.
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 no-output-schema mutation tool with a nested 12-field object at 0% schema coverage, the definition covers the write mechanism and validation but leaves the bulk of the body-composition fields and the return behavior unspecified. Partially adequate but with real 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 description coverage is 0%, so the description carries the full burden. It clarifies that weight is in kilograms and must be positive/finite, but the nested 'extra' object has 12 subfields (bmi, basalMet, boneMass, muscleMass, percentFat, etc.) and the description names only two examples ('body fat and muscle mass'). Most parameters remain undocumented in both schema and 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 states a specific verb and resource ('Records a weight (kg) with optional body-composition fields') and adds the transport mechanism (.fit weight-scale file). However, it never differentiates itself from the very close siblings add_weigh_in and add_weigh_in_with_timestamps, so an agent can't tell from the description alone which weight-writing tool to pick.
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?
There is no when-to-use or when-not-to-use guidance. With three near-identical weight-writing siblings (add_weigh_in, add_weigh_in_with_timestamps, add_body_composition), the description should route the agent but instead offers only an implied purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Links a piece of gear to an activity. On 404 re-raises as GarminConnectionError ("gear not found (likely retired/removed)").
| Name | Required | Description | Default |
|---|---|---|---|
| gearUUID | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds a useful behavioral detail by mapping a 404 to GarminConnectionError with 'gear not found (likely retired/removed),' but it does not cover idempotency, permissions, side effects, or success behavior.
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, front-loaded with the purpose and then a compact error detail. No filler or redundancy; every sentence earns its place.
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 is a simple mutation with annotations covering its safety profile and no output schema. The description covers the purpose and one error case, but is missing usage context, complete parameter semantics, and side-effect details such as whether linking is additive or idempotent. It is minimally adequate but has clear 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 description coverage is only 50%: activityId is described as 'Numeric id' but gearUUID has no schema description. The tool description does not compensate by explaining UUID format, constraints, or how activityId accepts both integer and string. It only adds that a missing gear is likely retired/removed, which is partial semantic value.
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 verb and resource: 'Links a piece of gear to an activity.' This is clear enough to understand the action, but it does not differentiate the tool from siblings such as remove_gear_from_activity or get_activity_gear, so sibling routing is left to inference.
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?
There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The function is implied by the purpose statement, but no usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Logs water intake in milliliters (negative values subtract). There is no delete endpoint. Raw milliliters, magnitude capped at 10000, negative values allowed; no delete endpoint exists, so not safely round-trippable.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | A moment in time, ISO 8601, e.g. 2026-09-28T07:30:00 (local) or with Z/offset | |
| cdate | No | Calendar date, YYYY-MM-DD (UTC) | |
| valueInMl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false, destructive=false, openWorld=true; the description adds genuinely new behavior: a 10000 magnitude cap, acceptance of negative values, absence of a delete endpoint, and the resulting non-round-trippable state. That is real value beyond the annotations, though the same 'no delete endpoint' fact is stated twice.
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?
Only three sentences, but 'There is no delete endpoint' is repeated verbatim and the bolded 'not safely round-trippable' is jargon that adds little for an agent. The unit/negation semantics are front-loaded, so the waste is at the tail.
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-value mutation with no output schema, the description covers mutation semantics, the cap, and the irreversibility of entries, which is what an agent needs to call it safely. Missing only explicit defaulting behavior for the optional when/cdate fields.
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 67% and the one undocumented parameter, valueInMl, is precisely the one the description explains (raw milliliters, cap 10000, negatives allowed). It does not address the when vs cdate distinction, but the schema already documents both of those.
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?
States a specific verb and resource ('Logs water intake') plus the unit (milliliters), which an agent can distinguish from the read-side sibling get_hydration_data without opening a schema.
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?
Gives actionable guidance on how to correct an entry ('negative values subtract') and warns that no delete endpoint exists, which effectively tells the agent when this tool is the only option. It stops short of naming a sibling or stating an explicit when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records a weigh-in in "kg" (the default) or "lbs". when defaults to now. Defaults unitKey="kg", when=new Date().
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | A moment in time, ISO 8601, e.g. 2026-09-28T07:30:00 (local) or with Z/offset | |
| unitKey | No | ||
| weightValue | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the write/open-world nature is covered. The description adds real value by disclosing defaults (unitKey='kg', when=now), but says nothing about auth needs, whether it overwrites an existing entry for the same timestamp, or what happens on failure.
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 short, front-loaded sentences with the unit default stated first. The final sentence largely restates the previous two ('when defaults to now' / 'when=new Date()'), which is mild redundancy rather than bloat.
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 simple three-parameter logging tool with no output schema, the description covers the defaults but omits the remaining things an agent needs: the unit context of weightValue, whether a same-timestamp entry is replaced, and the shape of the success response.
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 only 33%: `when` is documented in the schema and both `unitKey` and `when` defaults are stated in the description, so the description does compensate for the missing enum/date-format detail. However, the required `weightValue` receives no explanation of range, precision, or which unit it is interpreted in, leaving a gap on the one mandatory field.
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?
States a specific verb+resource ('Records a weigh-in'), which an agent can distinguish from get_weigh_ins and delete_weigh_in. It does not, however, differentiate itself from the close sibling add_weigh_in_with_timestamps, so the name/description pair leaves one ambiguity unresolved.
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?
No when-to-use guidance is given and no alternatives are named, despite the sibling add_weigh_in_with_timestamps existing right next to it. The only usable signal is the implicit 'if you want to log a weigh-in, call this', with no conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
addWeighIn with explicit local and GMT timestamps. Same raw-value, no-conversion rule as addWeighIn; the two timestamps are COUPLED: the local instant resolves from dateTimestamp if given (naive strings read as LOCAL time) else from when (defaults new Date()), and gmtTimestamp, when omitted, is derived from THAT resolved instant, never independently from when. Both supplied strings are re-formatted rather than forwarded verbatim (a naive gmtTimestamp is read as UTC).
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | A moment in time, ISO 8601, e.g. 2026-09-28T07:30:00 (local) or with Z/offset | |
| unitKey | No | ||
| weightValue | Yes | ||
| gmtTimestamp | No | ||
| dateTimestamp | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (not read-only, open-world, non-destructive). The description adds real behavioral context the annotations cannot: the two timestamps are coupled, local resolution precedence, derivation of gmtTimestamp from the resolved instant, and that supplied strings are re-formatted rather than forwarded verbatim with naive strings interpreted as LOCAL vs UTC.
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 core differentiator is front-loaded in the first clause, and every subsequent sentence addresses a distinct timing edge case rather than restating the schema. It is dense with jargon and one long paragraph, but no sentence is 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 mutation tool with no output schema and 5 params, the description covers the genuinely hard part (timestamp coupling and interpretation) thoroughly. It omits what the call returns and any unit-conversion note, which are minor gaps given the raw-value rule is stated.
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 only 20% (only 'when' is documented), so the description must compensate, and it does: it explains the precedence of dateTimestamp over when, the new Date() default, and the coupling to gmtTimestamp. It leaves weightValue and unitKey (the required value and its enum unit) unexplained, so it is not fully compensating.
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 the specific operation ('addWeighIn with explicit local and GMT timestamps'), identifying both verb and resource, and implicitly contrasts it with the sibling add_weigh_in by noting the extra timestamp handling. An agent can tell which of the two weigh-in adders to pick without opening either schema.
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 states the distinguishing condition (you supply explicit local and GMT timestamps) and ties behavior back to the base addWeighIn ('same raw-value, no-conversion rule'), which routes the agent correctly. It never spells out an explicit when-not or a named alternative to avoid, 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.
Confirms that a period started on a date, with its period and cycle lengths. There is no undo. Needs cycle tracking set up in Garmin Connect first. POSTs /periodichealth-service/menstrualcycle/{periodStartDate} directly, NOT the dayview/calendar/lastconfirmed/summary sub-paths.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| cycleLength | Yes | ||
| periodLength | Yes | ||
| periodStartDate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new context â irreversibility ('There is no undo') and the setup prerequisite. No permission/auth details, but the write nature and irreversibility are covered.
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?
Front-loads the core action, then adds the critical caveats and endpoint detail in order of importance. The endpoint-path sentence is dense but earns its place by preventing calls to the wrong sub-paths.
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 write tool with no output schema and terse annotations, the description covers the key facts an agent needs: prerequisite, irreversibility, and target endpoint. It falls short only on parameter-level detail (units/meaning) for the low-coverage 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 coverage is only 25% and three params are required, so the description must compensate. It loosely maps 'period and cycle lengths' to periodLength/cycleLength but adds no units, ranges, or meaning for options.predictedCycle. Marginal compensation for a low-coverage 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?
States a specific verb (confirms) and resource (menstrual period start) with the payload it carries (period and cycle lengths). It is clearly distinguishable from siblings like init_menstrual_cycle_setup, update_menstrual_calendar, and get_menstrual_last_confirmed.
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?
Gives an explicit prerequisite (cycle tracking must be set up in Garmin Connect first) and a strong caution (no undo). It doesn't name specific alternative tools to call instead, but the endpoint sentence routes the agent away from the wrong sub-paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The total number of activities on the account. Returns the envelope's totalCount, not the whole response; throws GarminError if Garmin returns nothing or a non-numeric totalCount.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, it discloses that only the envelope's totalCount is returned and that GarminError is thrown when Garmin returns nothing or a non-numeric totalCount. This is genuine behavioral context an agent cannot get from the annotations or the empty schema.
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, front-loaded with the purpose and followed by the return/error contract. No 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?
There is no output schema, so the description must carry return-value disclosure, and it does explain that totalCount is returned and when an error is thrown. It is complete for a trivial zero-parameter count tool, with only minor room to note the exact return type.
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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify about inputs, and the schema coverage is 100%.
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?
States a specific verb and resource ('the total number of activities on the account') and the clause 'Returns the envelope's totalCount, not the whole response' clearly separates it from siblings like get_activities that return full activity records.
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?
Usage is only implied: an agent can infer you call this when you need a count rather than the records themselves, but the description never states when to prefer this over get_activities or get_activities_by_date, nor any preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds a race or other event to the calendar. Always stored PRIVATE. POSTs /calendar-service/event. CalendarEventInput = {name, date, startTime?: "HH:MM", timeZoneId?, eventType?, race?, primary?, distance?: {value, unit: meter|kilometer|yard|mile}, goalTimeSeconds?, location?, url?, note?}; only name/date are required by Garmin ('addEvent.arg3.eventName' must not be blank otherwise). Garmin forces every user-created event PRIVATE and unshareable whatever is sent, sets isTrainingEvent whenever isPrimaryEvent is, and answers an unknown eventType with a 500. It also rewrote âĻ
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing server-side quirks: events are force-set PRIVATE and unshareable regardless of input, isTrainingEvent is auto-set when isPrimaryEvent is, unknown eventType returns a 500, and blank name/date triggers a specific validation error. This is exactly the kind of hidden behavior an agent needs before invoking.
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?
Front-loaded with purpose and the key PRIVATE constraint, then dense param detail; almost every clause earns its place. It is somewhat over-packed into long lines and the trailing sentence is truncated ('It also rewrote âĻ'), which slightly hurts readability.
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 mutation tool with no output schema and a nested object param, it covers the input contract, required fields, and server-side side effects thoroughly. It omits nothing critical, though it does not address response shape or auth/permission expectations.
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?
Reported schema coverage is 0% at the top level, and the description compensates by inlining the full CalendarEventInput shape with formats ('HH:MM', IANA zone, enum meter|kilometer|yard|mile) and the critical rule that only name/date are required. It stops short of explaining every field's semantics (e.g. url, note), leaving some room, but adds substantial meaning over the raw 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?
Opens with a specific verb+resource ('Adds a race or other event to the calendar') and immediately scopes behavior ('Always stored PRIVATE'). An agent can distinguish this creation tool from siblings like update_calendar_event, list_calendar_events, and get_calendar_event without opening any schema.
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?
Usage is implied by the create semantics but the description never states when to choose this over update_calendar_event or schedule_workout, nor any prerequisites. The inclusion of the raw endpoint hints at integration context but does not guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves a course from a name and at least two geo points. Garmin computes the distance. POSTs /course-service/course with the template Garmin's web client sends. CourseInput = { name, geoPoints, coursePoints?, activityTypeId? = 1 (running), privacy? = "private" }; privacy maps to rulePK public 1 / private 2. Garmin computes distanceMeter and elevation. Throws GarminError before any request on an empty name or fewer than two geoPoints.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing the exact endpoint, that it mirrors Garmin's own web client payload, the server-side computation of distanceMeter and elevation, the privacy-to-rulePK mapping, and that a GarminError is thrown before any request on empty name or fewer than two points.
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?
Front-loads the action and its minimum requirements, then layers in endpoint, payload template, defaults, and error behavior. Dense but every sentence adds operational value; no 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 creation tool with no output schema, the description covers inputs, defaults, server-side effects, and failure conditions. The only gap is what the call returns (a course id/object), which the agent has to infer from the mention of computed distanceMeter and elevation.
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 0%, but the description carries the burden by spelling out CourseInput (name, geoPoints, coursePoints?, activityTypeId?=1 running, privacy?="private") and the privacy/rulePK mapping. It says nothing about the per-point shape (latitude/longitude/elevation/distance/timestamp) or coursePoints contents, so it does not fully compensate.
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?
States a specific verb and resource plus the minimum input needed ('Saves a course from a name and at least two geo points'). This implicitly separates it from create_course_from_gpx, which builds a course from a GPX file, but does not name that sibling outright.
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?
Usage is implied by the input contract (name + geo points) and the validation rule (at least two geo points), but there is no explicit when-to-use/when-not guidance nor a pointer to create_course_from_gpx, update_course, or import_course_gpx as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
importCourseGpx then createCourse, in one call. Name defaults to the GPX <name>, then the filename without .gpx.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| filePath | Yes | Absolute path to a local .fit, .gpx or .tcx file (~ is expanded) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context by explaining the name-resolution fallback order, but says nothing about what gets created, permissions, or failure modes.
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 with no filler, and the core operation is front-loaded ahead of the naming detail. It is efficient, though the terse phrasing borders on cryptic.
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 mutating, open-world tool with a nested options object and no output schema, the description covers the naming fallback but leaves the other option fields and the result unaddressed. Adequate but with clear 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 only 50%, so the description must compensate. It usefully documents the name-defaulting fallback (GPX `<name>`, then filename without `.gpx`), which the schema omits, but stays silent on the options object fields (privacy, activityTypeId) that the agent must pass.
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 tool name and description together convey that a course is created from a GPX file by combining import and create steps. However, the description leans on internal camelCase function names (`importCourseGpx`, `createCourse`) that do not match the actual sibling tool names (import_course_gpx, create_course), so the purpose is inferable but not stated as a clean verb+resource.
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?
'In one call' implicitly positions this as the shortcut over calling import and create separately, which hints at when to prefer it. But there is no explicit when-to-use, when-not-to-use, or routing to the sibling tools â the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Creates a custom food (per serving). Needs Connect+. A PUT, not a POST, to /nutrition-service/customFood; CustomFoodInput = {name, calories, servingUnit? = "G", servingSize? = 100, brand?, carbs?, protein?, fat?, fiber?, sugar?, saturatedFat?, transFat?, sodium?, cholesterol?, potassium?, calcium?, iron?, vitaminD?} per ONE serving, absolute amounts (not %DV); numbers are sent as strings, as Garmin's own client does. Returns the stored food with the foodId/servingId logFood takes.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds substantive behavior beyond them: the Connect+ auth gate, the non-obvious PUT-vs-POST transport quirk, that numbers are serialized as strings, that values are absolute (not %DV), and what the call returns (foodId/servingId).
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?
Front-loads the hard prerequisite, then the field contract, then the return value â a sensible order. Minor waste: "Needs Connect+" repeats the opening subscription requirement, and the raw endpoint path is borderline verbose, but overall it packs high-value detail without padding.
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 a 19-field nested input, no output schema, and no per-field schema descriptions, the description supplies the shape, defaults, per-serving/absolute-value semantics, serialization quirk, and return contract. Units per nutrient are the only thing an agent might still need, but the essentials for correct invocation are present.
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 ~0%, so the description must carry the load, and it does: it enumerates the CustomFoodInput fields with defaults (servingUnit="G", servingSize=100), and clarifies the critical semantics that values are per ONE serving and absolute rather than %DV. It stops short of stating the expected unit per nutrient (mg vs g), which is the remaining gap for a 19-field nested object.
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?
States a specific verb+resource ("Creates a custom food") and adds the scoping detail "per serving." It also names related siblings implicitly (has_connect_plus for the prerequisite, logFood for the returned IDs), so an agent can place it in the nutrition workflow without opening a schema.
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?
Gives a concrete prerequisite and how to verify it: "Requires a Garmin Connect+ subscription (check with has_connect_plus)." It also explains where the returned IDs go (logFood). It does not, however, name the modify path (update_custom_food) or when to prefer quick_add_food/search_foods, so an explicit alternative/exclusion statement is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a piece of gear (shoes, bike and so on). Usage limits are given in km and minutes. POSTs /gear-service/gear/v2; defaults usageType="DISTANCE", notes=""; gearType/usageType upper-cased via validateSportKey; converts maxUsageDistanceKm -> maxUsageDistanceMeters (round(km*1000), floor 1) and maxUsageDurationMin -> maxUsageDurationSeconds (round(min*60), floor 1), the opposite direction from addWeighIn's "send raw" rule; returns the response unchecked.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| brand | Yes | ||
| model | Yes | ||
| notes | No | ||
| gearType | Yes | ||
| usageType | No | ||
| firstUseDate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| activityTypeKeys | No | ||
| maxUsageDistanceKm | No | ||
| maxUsageDurationMin | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a non-read-only, non-destructive, open-world write. The description adds substantial beyond-schema behavior: the POST endpoint, server-applied defaults (usageType=DISTANCE, notes=""), upper-casing of gearType/usageType, unit conversion with rounding and a floor of 1, and that the response is returned unchecked. It omits auth/rate-limit details, but the disclosure is well above the annotation baseline.
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?
Dense but front-loaded: the core purpose leads, followed by endpoint, defaults, and conversion rules in a compact sequence. The comparison to addWeighIn's 'send raw' rule is arguably tangential but does reinforce the direction of the conversion, so little is truly wasted.
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 10-parameter mutation tool with no output schema and 10% schema coverage, the description covers the non-obvious parameters and normalization but leaves five required/optional fields unexplained and only vaguely states the return behavior ('returns the response unchecked'). It is workable but not complete enough to call the tool confidently without reading 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 only 10%, so the description must carry the load and it does for the tricky fields: defaults for usageType and notes, case normalization for gearType/usageType, and the km->meters / minutes->seconds conversion with rounding rules. It still says nothing about the meaning of brand, model, name, or activityTypeKeys, so it compensates only partially.
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?
States a specific verb and resource ('Creates a piece of gear') and gives concrete examples (shoes, bike), so an agent knows exactly what entity is produced. It does not explicitly differentiate from nearby siblings like add_gear_to_activity or set_gear_activity_defaults, but create-vs-assign is inferable from the verb.
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?
There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as add_gear_to_activity for attaching gear to a workout. The only contextual hints (units in km/minutes) describe the payload rather than when to call the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a manual activity from a distance in km and a duration in minutes. startDatetime is a local timestamp with milliseconds, e.g. "2026-09-22T10:00:00.000". converts units: distanceKm * 1000 â meters, durationMin * 60 â seconds, before building the request body; startDatetime is NOT routed through formatDate (it's a full local timestamp, not a bare calendar date) and must include milliseconds, e.g. "2026-09-22T10:00:00.000"; omitting them produced a live HTTP 500 ValueInstantiationException from Garmin during verification.
| Name | Required | Description | Default |
|---|---|---|---|
| typeKey | Yes | ||
| timeZone | Yes | ||
| distanceKm | Yes | ||
| durationMin | Yes | ||
| activityName | Yes | ||
| startDatetime | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose write semantics (readOnlyHint=false), non-destructiveness, and open-world behavior, so the bar is lower. The description adds genuinely useful traits beyond that: the internal unit conversion (kmâm, minâs) applied before building the request body, and a documented live failure mode (HTTP 500 ValueInstantiationException when milliseconds are omitted) â non-obvious operational context an agent cannot get from structured fields.
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 critical constraint (startDatetime format) is front-loaded, which is good, but the same timestamp example is stated twice in near-identical form, and the final clause mixes instruction with a debugging anecdote in a run-on sentence. The content is dense and mostly earns its place; the duplication is real waste.
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 six-parameter, fully-required write tool with no output schema and no schema descriptions, the definition covers the risky fields but leaves half the surface undocumented â typeKey validity, timeZone format, and activityName constraints. An agent could call it correctly for the timestamp but would be guessing on three required inputs.
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 0%, so the description carries the full burden for six required parameters. It compensates well for three of them (distanceKm, durationMin, startDatetime, including exact format and conversion semantics), but timeZone, typeKey, and activityName are never explained â notably which type keys are valid and what timezone string format is expected.
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?
States a specific verb+resource ('Creates a manual activity') and names the primary inputs (distance in km, duration in minutes), so the agent knows exactly what the tool produces. It does not explicitly differentiate itself from the sibling 'create_manual_activity_from_json', which is the nearest alternative and is left unaddressed.
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?
There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative 'create_manual_activity_from_json' or when the JSON-based variant is preferable. The description explains mechanics only, leaving tool selection entirely to inference from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a manual activity from a payload sent to Garmin verbatim. Sends payload to Garmin verbatim, no shape validation.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (write, open-world, non-destructive). The description adds genuinely useful behavior beyond them: the payload is passed through with no shape validation, implying the server performs no transformation and that malformed payloads surface as Garmin-side errors.
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?
Short and front-loaded, but sentence two largely restates sentence one ('from a payload sent to Garmin verbatim' / 'Sends `payload` to Garmin verbatim'), a small redundancy in an otherwise tight definition.
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 write tool with no output schema and an open-world hint, the core passthrough semantics are present, but the description omits what the call returns, failure behavior when Garmin rejects the payload, and any pointer to the sibling structured tool or payload reference.
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?
One required parameter with 0% schema coverage, so the description must compensate. It explains how the value is handled ('sent verbatim, no shape validation') but gives no hint at the expected object shape, keys, or where to source them, leaving the agent to guess the structure.
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?
Specific verb+resource: 'Creates a manual activity from a payload.' The 'from_json / verbatim' framing communicates the distinguishing trait versus the sibling create_manual_activity (structured fields), but the description never names that sibling, so the agent must infer the split.
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?
Usage is only implied: the 'verbatim, no shape validation' phrasing suggests this is the raw-passthrough escape hatch used when you already have a complete Garmin-shaped payload. It never states when to prefer this over create_manual_activity, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a workout to the user's Garmin Connect workout library. Only after the user has confirmed a preview_workout of the same spec. Look exercise names up with search_exercises first; an unknown name is rejected. Afterwards, schedule_workout (if available) puts it on the calendar and push_workout_to_device (if available) sends it to the watch. Paces are minutes as decimals (4:30 = 4.5), distances metres, times seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | A Garmin workout. Give `steps` for one sport, or `legs` (each with its own sport) for a multi-sport workout, not both. Distances are metres, times seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real behavioral context beyond them: the mandatory preview-then-confirm workflow, rejection of unknown exercise names, and the downstream scheduling/push chain. It does not address what happens on duplicate saves or auth/permission requirements, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, none wasted. Purpose is front-loaded, then prerequisites, then downstream workflow, then units. Each sentence earns its place and nothing is padded.
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 complex nested-spec tool with no output schema, the description covers the essential workflow, prerequisites, and units, while the rich JSON schema handles the spec structure. It could go further on failure/repeat-call behavior given idempotentHint=false, but nothing critical for a correct call 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?
Schema description coverage is already 100%, so the baseline is 3. The description adds a compact unit-convention summary (paces as decimal minutes with the 4:30 = 4.5 example, distances in metres, times in seconds) that reinforces and consolidates conventions an agent must get right, adding genuine value over 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?
States a specific verb and resource: 'Save a workout to the user's Garmin Connect workout library.' It clearly distinguishes itself from siblings like update_workout, delete_workout, and preview_workout, and an agent can tell it apart without opening any schema.
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?
Explicitly names prerequisites (only after a confirmed preview_workout of the same spec, look up exercise names with search_exercises), a failure condition (unknown name rejected), and the follow-up alternatives (schedule_workout, push_workout_to_device). This is textbook when-to-use guidance with named siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes an activity. IRREVERSIBLE. Resolves to null on success. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so irreversibility is partly covered, but the description reinforces it and adds genuinely new context: the operation returns null on success (valuable since there is no output schema) and a required user-confirmation step. It stops short of saying whether the activity is recoverable or what happens to dependent data like gear links.
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?
Short and front-loaded, but repeats 'IRREVERSIBLE' twice, once as a bare fragment and again mid-sentence. The duplication wastes space and reads as boilerplate rather than deliberate emphasis, so it falls short of a clean, waste-free statement.
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 no output schema, the description correctly supplies the return behavior (null on success) and the destructive/confirmation requirement. For a single-parameter delete tool this is nearly complete; it would be fully complete with a note on recoverability or cascading effects.
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 parameter (activityId) and schema description coverage is 100% ('Numeric id'), so the schema already carries the parameter documentation. The description adds nothing about the id format, yet accepts both integer and string per the schema, so an agent gets no extra clarification. Baseline 3 when the schema does the heavy lifting.
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?
States a specific verb (Deletes) and resource (an activity) in the opening sentence, clearly separating it from the many sibling delete_* tools (delete_workout, delete_course, delete_weigh_in) and from the set_/update_ activity tools. An agent can identify the correct tool without opening the schema.
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 one actionable usage rule: confirm with the user before calling. However, it never states when to prefer this over alternatives (e.g., deleting an activity vs. clearing a description via set_activity_description) or what preconditions exist. Usage guidance is present but thin.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes one blood-pressure reading by its version, taken from getBloodPressure. Deletes one reading by its version, taken from getBloodPressure. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuine value beyond that by flagging the operation as IRREVERSIBLE and mandating user confirmation, which is a behavioral workflow constraint not expressible in annotations. It does not, however, describe failure modes (e.g., stale version) or permission requirements.
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 core content is short and the IRREVERSIBLE warning is appropriately emphasized. But the first sentence is repeated verbatim, which is pure redundancy and pushes the actionable warning later than necessary.
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 destructive mutation with no output schema, the description covers the essential safety story (irreversible, confirm first) and identifier provenance. It leaves gaps around the role of the required `cdate` parameter and any post-condition or return behavior, which an agent calling a delete would benefit from knowing.
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 50%: `cdate` is documented in-schema, but `version` has no schema description. The description partially compensates by explaining where `version` comes from (`get_blood_pressure`), but it never explains what `cdate` contributes to a delete or how the two fields interact to identify a reading.
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?
States a specific verb (deletes) and resource (one blood-pressure reading) qualified by the identifier (`version`). It is clearly distinguishable from sibling deletes like delete_weigh_in or delete_custom_food. It stops short of a 5 because the duplicated sentence and the mismatched reference `getBloodPressure` (vs. sibling `get_blood_pressure`) introduce noise rather than sharper scoping.
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?
Gives real usage context: the `version` value must be sourced from a prior read (`get_blood_pressure`), and the user must confirm before the call. However, there is no explicit when-not guidance and no mention of the alternative path (e.g., updating instead of deleting, or batch-deletion siblings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
IRREVERSIBLE. DELETE /calendar-service/event/{id}, resolves null (204). IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description goes further by stating the operation is IRREVERSIBLE and that it resolves `null` with a 204, i.e. no body is returned and there is no undo. That is genuine added context beyond the structured hints, though it says nothing about auth requirements or side effects on recurring events.
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?
Very short and front-loads the most important fact (irreversibility) before the technical detail. The word IRREVERSIBLE appears twice, which is mild redundancy, but the second instance is attached to an actionable instruction rather than pure repetition.
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 destructive tool with no output schema, the description covers the essentials: it destroys data permanently, returns nothing (204), and requires user confirmation. Nothing critical to correct invocation 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?
Schema coverage is 100% and the single `eventId` parameter is documented as 'Numeric id'. The description mirrors this with the `{id}` path placeholder but adds no extra meaning such as accepted id sources or behavior for invalid ids, so baseline 3 applies.
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 the exact operation via the HTTP route `DELETE /calendar-service/event/{id}`, so the verb (delete) and resource (calendar event) are unambiguous even though the prose never spells out 'calendar event'. It does not distinguish itself from the many other `delete_*` siblings, but the operation itself is clear.
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 adds one real usage rule: 'confirm with the user before calling', which is a meaningful precondition for a destructive op. It gives no guidance on when to prefer deletion over `update_calendar_event`, nor any note about scope or dependencies, so usage is only implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
IRREVERSIBLE. A course created seconds ago may 429 "not yet ready"; retry shortly. DELETE /course-service/course/{courseId}, resolves null (204). May 429 "not yet ready" for a few seconds after creation. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| courseId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `destructiveHint: true` and `readOnlyHint: false`, but the description adds substantial behavioral context: irreversibility, a transient 429 'not yet ready' state for newly created courses, the exact HTTP endpoint, and a 204/null success response. This goes well beyond what annotations provide and helps the agent handle edge cases correctly.
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 repeats key facts: 'IRREVERSIBLE' appears twice, and the 429 'not yet ready' rate-limit behavior is stated twice in slightly different words. This redundancy wastes space and dilutes the front-loaded warning, failing the 'every sentence should earn its place' test.
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 a single-parameter destructive delete with rich annotations and no output schema, the description covers the crucial behavioral details: irreversibility, rate-limit retry guidance, endpoint, and response code. It lacks explicit guidance on alternatives or permissions, but is otherwise complete for correct invocation.
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% with a single `courseId` parameter documented as 'Numeric id'. The description embeds `{courseId}` in the endpoint path but adds no further meaning, format, or constraints beyond the schema. A baseline 3 is appropriate when the schema already carries the parameter semantics.
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 operation via `DELETE /course-service/course/{courseId}`, making it clear this deletes a course. It does not explicitly differentiate itself from sibling tools like `update_course` or `get_course`, but the HTTP method and resource are 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 includes a critical usage warning: 'IRREVERSIBLE: confirm with the user before calling.' It also notes a transient 429 condition after creation and advises retrying shortly. However, it offers no guidance on when to choose this tool over alternatives (e.g., `update_course`), so usage is implied rather than fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). IRREVERSIBLE. Needs Connect+. DELETE /nutrition-service/customFood/{foodId}, resolves null. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| foodId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context: the Connect+ subscription gate (with the has_connect_plus check), the need for user confirmation, and that the call resolves to null. It does not describe failure modes or whether the deletion cascades, so it is short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The prerequisite is front-loaded, which is good, but the text is redundant: the Connect+ requirement appears twice ('Requires a Garmin Connect+ subscription' / 'Needs Connect+') and 'IRREVERSIBLE' is stated twice. The duplicated sentences do not earn their place.
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 destructive one-parameter tool with no output schema, the description covers the key facts an agent needs: subscription requirement, irreversibility, confirmation, and the null return. Missing only edge-case behavior such as what happens when the food does not exist.
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 0% for the single foodId parameter, so the description must compensate. The `{foodId}` path template shows it identifies the food being deleted, but no format, source, or validity details are given, leaving the schema to carry the parameter alone.
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 `DELETE /nutrition-service/customFood/{foodId}` endpoint plus the tool name make the verb+resource unambiguous, and it clearly targets one custom food by id. It does not explicitly contrast with siblings like update_custom_food or delete_food_logs, so it stops short of a 5.
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 states a prerequisite ('Requires a Garmin Connect+ subscription (check with has_connect_plus)') and a usage directive ('confirm with the user before calling'), which tells the agent when the tool is usable and how to proceed. It does not name alternative tools for the non-subscription case, so it is not fully explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Deletes log entries from one day, any number at once. IRREVERSIBLE. DELETE /nutrition-service/food/logs/{date} with {logIds} as the body: any number in ONE call, regular and quick-add alike. logIds are on the entries of getNutritionDailyFoodLog. Needs Connect+. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| logIds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, so irreversibility is partly covered; the description still adds real value by spelling out the subscription gating, the batch semantics (any number in one call, regular and quick-add alike), and an explicit user-confirmation requirement that annotations cannot express.
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 critical warning is front-loaded and the endpoint/body shape is compact. It loses a point for repetition: the Connect+ requirement appears twice and irreversibility is asserted twice, which is redundant prose for an otherwise tight definition.
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 destructive, subscription-gated delete with a two-parameter schema and no output schema, the description covers everything the agent needs: prerequisites, batch behavior, ID provenance, irreversible consequence, and confirmation protocol.
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 only 50% and logIds carries no schema description, so the description must compensate â and it does, explaining that logIds accepts any number of IDs in one call, covers both regular and quick-add entries, and can be sourced from getNutritionDailyFoodLog. The date parameter is already documented in the schema, so nothing is duplicated.
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?
States a specific verb and resource ('Deletes log entries from one day'), plus scope ('any number at once') and the underlying endpoint. An agent can distinguish it from sibling deletes like delete_custom_food or delete_weigh_in without opening any schema.
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?
Gives prerequisites (Connect+ subscription, verified via has_connect_plus) and an explicit safeguard ('confirm with the user before calling'), and routes the agent to getNutritionDailyFoodLog for the logIds. It stops short of naming when a different tool would be preferred, but the when-to-use conditions are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a piece of gear and its activity history. IRREVERSIBLE. DELETE /gear-service/gear/v2/{gearUUID}, resolves null on success (204). The UUID must be HYPHENATED: getGear returns them WITHOUT hyphens and that form 404s, so this method re-inserts them for you when handed the bare 32-char form; only hand-rolled URLs hit the 404. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| gearUUID | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this destructive, but the description adds real behavioral context beyond them: the DELETE route, the 204/null-on-success return, and the non-obvious side effect that gear activity history is destroyed along with the record. The hyphenation quirk and its 404 consequence are pure added value.
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?
Purpose is front-loaded and the UUID caveat is well placed, but 'IRREVERSIBLE' is asserted twice and the endpoint/route detail is arguably internal trivia for an agent-facing description. Minor redundancy rather than bloat.
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?
No output schema exists, and the description supplies the success semantics (204/null), the destructive side effects, and the confirmation requirement. Nothing an agent needs in order to call this safely 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?
Schema coverage is 0%, so the description carries full burden for the sole parameter â and it does: it explains that the UUID must be hyphenated, that `getGear` returns the unhyphenated 32-char form, and that this method re-inserts hyphens so the caller need not. That is meaningfully more than the bare `{"gearUUID": string}` 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?
States a specific verb ('Deletes') and resource ('a piece of gear'), and crucially scopes the blast radius by noting it also removes the gear's activity history. This distinguishes it from sibling `remove_gear_from_activity`, which detaches but does not destroy the gear record.
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?
Gives clear preconditions: confirm with the user before calling, and the exact UUID form to supply. It never explicitly routes the agent away from alternatives such as `remove_gear_from_activity` or `delete_activity`, so the when-not guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a sport's own zone profile; it falls back to DEFAULT. PUTs the stored profile back with changeState: "DELETED", which removes it so the sport falls back to DEFAULT. Refuses DEFAULT; throws for a sport with no profile instead of doing nothing. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| sport | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint/readOnlyHint/openWorldHint; the description goes well beyond that by disclosing the fallback-to-DEFAULT semantics, the underlying PUT with changeState "DELETED", the two failure modes (refuses DEFAULT, throws on missing profile), and an explicit irreversibility warning with a confirmation requirement.
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?
Front-loads the core effect and ends with the most safety-critical sentence, which is good. However, the fallback-to-DEFAULT behavior is stated twice ('it falls back to DEFAULT' then 'which removes it so the sport falls back to DEFAULT'), wasting a clause.
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 destructive tool with no output schema, the description covers effect, side effects, error behavior, and irreversibility. The remaining gap is the expected input format for 'sport' and whether a caller must first verify a profile exists.
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 0% for the single 'sport' parameter, so the description must compensate. It adds meaningful semantics â 'sport' selects a sport-specific profile and the reserved value DEFAULT is rejected â but does not clarify the accepted format (name vs. numeric sport ID), leaving an ambiguity for the caller.
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?
States a specific verb (removes/deletes), a precise resource (a sport's own heart-rate zone profile), and the consequence (falls back to DEFAULT). This clearly distinguishes it from get_heart_rate_zones and set_heart_rate_zones among the numerous sibling tools.
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?
Gives explicit when-not conditions: it refuses the DEFAULT sport and throws when the sport has no profile rather than silently no-op'ing, plus a 'confirm with the user before calling' instruction. It does not name the sibling alternatives (get/set_heart_rate_zones) an agent might use instead, 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.
Quits an enrolled plan ("Quit Plan"); its workouts leave the calendar. IRREVERSIBLE. DELETE /trainingplan-service/trainingplan/trainingplan/{planId} (the trainingplan segment really is doubled): the request Garmin Connect's "Quit Plan" sends, observed in the web client on 2026-10-06. Resolves null (204); the plan's scheduled workouts leave the calendar, completed activities stay. A second call is a 404 "Training plan not found with ID: âĻ". IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| planId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the destructiveHint=true annotation: it specifies the exact endpoint (including the doubled path segment), the HTTP outcome (204/null), the second-call 404 behavior with the error text, and, most importantly, the blast radius â scheduled workouts are removed but completed activities remain. That side-effect specificity is exactly what an agent needs before a destructive call.
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 purpose and the IRREVERSIBLE warning are both front-loaded, and most sentences carry operational weight. It loses a point for incidental detail â the observed-date provenance and the aside that the path segment 'really is doubled' â which is useful trivia but dilutes the core message.
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 no output schema, the description fully compensates by describing the return (null, 204), the failure mode (404 with message), and the data consequences. Nothing needed to call this destructive tool safely 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?
Schema description coverage is 100%, so planId's meaning is already documented as a numeric id. The description's mention of planId only shows its position in the URL template and does not add type, format, or sourcing guidance beyond the schema. Baseline 3 applies.
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?
States a specific verb+resource pair ('Quits an enrolled plan') and immediately describes the effect on the calendar. An agent can distinguish it from siblings like delete_workout, unschedule_workout, or get_training_plan_by_id without opening any schema.
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?
Gives a clear directive on the required procedure ('confirm with the user before calling') and signals the irreversible nature, which strongly shapes when to invoke it. However, it never names an alternative such as unschedule_workout for removing a single workout instead of quitting the whole plan, so the routing guidance is contextual rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes one weigh-in, by date and its weightPk. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| weightPk | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true. The description goes beyond them by asserting the operation is IRREVERSIBLE (stronger than 'destructive') and imposing a confirm-first workflow, which is useful added context. It still omits whether the delete cascades or what the response looks like.
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, front-loaded with verb and resource, then the risk warning. Every clause earns its place with no padding.
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 destructive, no-output-schema tool, the critical risk (irreversibility) and the confirmation requirement are surfaced, and the annotations carry the safety profile. The remaining gaps are how to source weightPk and the sibling boundary.
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 only 50%: cdate is documented with format guidance but weightPk is bare. The description merely restates the two field names as the identifier without explaining what weightPk is or how an agent obtains it, so it fails to compensate for the uncovered parameter.
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?
States a specific verb (deletes) and resource (one weigh-in) plus the identifying fields (date, weightPk). The word "one" implicitly separates it from the plural sibling delete_weigh_ins, but it never names that alternative, so the differentiation is inferential rather than explicit.
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?
Provides a calling precondition ("confirm with the user before calling"), which is a genuine usage instruction. However it gives no guidance on when to pick this versus delete_weigh_ins for bulk removal or versus the get_weigh_ins tools to find a weightPk, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes the weigh-ins recorded on one date and returns how many went. IRREVERSIBLE. No HTTP path of its own: calls getDailyWeighIns, then loops deleteWeighIn per entry; returns null (deletes nothing) if there are zero entries, or more than one entry and deleteAll is not true; otherwise deletes every entry that day and returns the count. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| deleteAll | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds substantial behavior beyond them: the internal two-step mechanism (getDailyWeighIns then looped deleteWeighIn), the exact conditions that yield null (zero entries, or multiple entries without deleteAll), and the count return. This tells the agent precisely what gets destroyed and when nothing happens.
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?
Purpose is front-loaded and the content is valuable, but 'IRREVERSIBLE' is stated twice and the return value is described redundantly ('returns how many went' then 'returns the count'). Trimming that duplication would tighten the definition without losing 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?
No output schema exists, and the description correctly covers return values (count or null). For a destructive mutation tool it explains irreversibility, confirmation, and the deleteAll gate. The only missing piece is its relationship to the delete_weigh_in sibling.
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 50%: cdate is documented in the schema, but deleteAll has no schema description. The description compensates by explaining deleteAll's effect â without it, more than one entry deletes nothing; with it, every entry that day is removed.
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?
States a specific verb (deletes) and resource (weigh-ins) with the scope constraint (recorded on one date) plus the return value. It is distinguishable from the singular delete_weigh_in by the date-based bulk semantics, but it never names that sibling to make the distinction explicit.
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?
Provides a clear procedural rule ('IRREVERSIBLE: confirm with the user before calling') and describes the deleteAll gating behavior. However, it gives no guidance on when to prefer this tool over delete_weigh_in or the alternatives in the sibling set, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a workout from the library. IRREVERSIBLE. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| workoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's remaining job is to add context beyond that. It does: it states the change is IRREVERSIBLE and imposes a user-confirmation workflow, which is genuine operational guidance the annotations cannot express.
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 purpose is correctly front-loaded and the whole definition is short, but the literal duplication 'IRREVERSIBLE. IRREVERSIBLE:' is wasted space in an already terse description. Emphasising the risk once would have been equally effective.
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 deletion with no output schema, the description covers what an agent needs: what is removed, that it cannot be undone, and that the user must confirm first. Only the absence of alternative routing keeps it from being fully 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?
Schema description coverage is 100% (workoutId is documented as 'Numeric id'), so the schema already carries parameter meaning. The description adds nothing about what ids are valid or whether string ids are accepted, which is the correct baseline-3 outcome when the schema does the heavy lifting.
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?
States a specific verb+resource ('Deletes a workout from the library') that is unambiguous against the large sibling set, including the nearby delete_activity, delete_course and delete_training_plan. It does not explicitly contrast itself with those siblings, but the resource noun alone is enough to disambiguate.
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?
Gives an explicit precondition: confirm with the user before calling. That is actionable guidance rather than an implication. It stops short of naming alternatives (e.g. update_workout or unschedule_workout for non-destructive needs), so it is not a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's display name, which date-scoped endpoints put in their URLs. Cached.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact â the value is cached â but says nothing about staleness, refresh, or that it returns a plain string. Modest added value against an already-covered annotation set.
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?
Very short and front-loaded: the resource is named first, then the URL context, then the cached flag. The trailing 'Cached.' fragment is terse but informative; nothing is padded, though it reads as clipped rather than crafted prose.
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 zero-param read with annotations covering safety and no output schema, the description is close to sufficient, but it never says what the return value looks like (a string) or resolves the ambiguity against full_name/user_name. That overlap gap is the main missing piece.
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 takes zero parameters, so the schema carries no semantic load and the description cannot add parameter detail. Baseline 4 applies for a zero-param tool.
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 specific resource it returns: the account's display name. It is distinguishable from the similar-looking siblings full_name and user_name by naming the exact attribute. It is a noun phrase rather than a verb+resource statement, but the resource is 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?
It adds oblique context that the value feeds into URL construction for date-scoped endpoints, implying a reason to fetch it, but it never states when to call this versus full_name or user_name, nor any prerequisites. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads an activity file: "ORIGINAL" (the default), TCX, GPX, KML or CSV. ActivityDownloadFormat is "ORIGINAL" | "TCX" | "GPX" | "KML" | "CSV", default "ORIGINAL".
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and no contradiction exists. The description adds the default format value, but says nothing about the returned payload (binary stream, URL, or base64), file-size/rate-limit considerations, or whether ORIGINAL returns the raw uploaded file.
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 format list is stated twice â once as prose and again as a verbatim enum transcription with the type name `ActivityDownloadFormat` â which is pure repetition. The key fact (default) is present but buried in the duplicate.
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 no output schema, the description carries the burden of explaining the return value, yet it never says whether the response is a file stream, a URL, or encoded content. Format options and the default are covered, so it is minimally viable for a 2-parameter download tool but not 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?
Schema description coverage is 50% (activityId documented as 'Numeric id'; format has an enum but no default). The description compensates by supplying the missing default ('"ORIGINAL" (the default)') and naming what the format controls, which is genuine value beyond the schema â though it never explains what 'ORIGINAL' actually yields.
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?
States a specific verb and resource ('Downloads an activity file') and enumerates the exact output formats, so the agent knows precisely what the tool produces. It does not, however, differentiate itself from the similar-sounding siblings download_workout, download_course_gpx, and download_health_snapshot.
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?
There is no when-to-use guidance: nothing says to prefer this over download_workout or download_course_gpx, nor whether this streams a file versus returning metadata (get_activity). Usage is only inferable from the verb 'downloads'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads a saved course as GPX bytes. GETs /course-service/course/gpx/{courseId} through client.download.
| Name | Required | Description | Default |
|---|---|---|---|
| courseId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds two useful facts beyond them: the payload is GPX bytes (not JSON), and it is fetched via client.download from the course-service gpx endpoint. It does not say how bytes are encoded or what happens if the course id is invalid.
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, zero waste, with what-it-does front-loaded and the endpoint/mechanism as supporting detail.
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 no output schema, the description usefully discloses the return type ('GPX bytes'). The remaining gap is minor but real: byte payloads must be encoded somehow (e.g. base64) for an MCP text response, and that is not stated.
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% (the single courseId parameter), so the schema already carries the load. The description only echoes the placeholder {courseId} and adds no format or id-source detail, so baseline 3 is correct.
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 verb+resource+output format: 'Downloads a saved course as GPX bytes.' That distinguishes it from the richer get_course (structured course data) and from the unrelated download_activity/download_workout siblings, though it never names those alternatives explicitly.
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?
No when-to-use or when-not-to-use guidance. An agent must infer that this is for retrieving a course as a GPX file rather than as structured JSON (get_course) or as an import (import_course_gpx); nothing routes it between those options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads the Health Snapshot recorded on a date, as raw bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| requestedDate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description does add one genuinely useful behavioral fact â output is raw bytes, not JSON â which tells the agent not to parse it. It says nothing about size, content type, or whether the snapshot requires special entitlements.
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, zero padding, and the two load-bearing facts (what is fetched, and that the payload is bytes) are front-loaded. Nothing could be trimmed without losing 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?
There is no output schema, so the description carries the burden of describing the return value; 'raw bytes' is a helpful start but leaves the actual format (JSON, ZIP, binary container) unknown. For a single-parameter read tool with annotations covering safety, this is adequate but leaves an agent guessing about the payload.
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% and the single parameter is fully documented in the schema as a YYYY-MM-DD UTC calendar date. The description restates the date concept without adding format, timezone, or range constraints, so baseline 3 applies.
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?
States a specific verb and resource ('Downloads the Health Snapshot') plus the scoping input ('recorded on a date') and the return type ('raw bytes'). It is clearly distinguishable from neighboring get_* stats tools, though it never explicitly contrasts itself with them.
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?
No when-to-use guidance, no prerequisites (e.g. subscription/permission tier), and no mention of alternatives such as get_user_summary or get_stats for agents that want parseable daily data. The only implied context is the date parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads a workout as FIT-file bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| workoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the one non-obvious behavior: the return payload is raw FIT bytes rather than JSON, which matters because there is no output schema. It says nothing about error behavior, whether workouts must be scheduled/owned, or size limits.
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, zero filler, and the most decision-relevant fact (FIT-file bytes) is placed at the end of a short clause where it is still immediately visible.
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 download with no output schema, the description supplies the crucial return-format information and annotations cover safety. The remaining gap is routing: it never says how this differs from get_workout_by_id or preview_workout.
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% for the single required workoutId (typed integer|string, 'Numeric id'), so the schema does the work. The description adds no clarification on the identifier's source or format, which is the baseline expectation when schema coverage is high.
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?
States a specific verb (downloads) and resource (workout) plus the payload form (FIT-file bytes), which separates it from read-shaped siblings like get_workout_by_id and preview_workout. It does not name those siblings explicitly, so the differentiation is inferred from the output format rather than stated.
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?
There is no guidance on when to use this versus get_workout_by_id, preview_workout, or download_activity. The agent is left to infer that this is the export path for a workout object.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account holder's full name, from the cached user profile.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral fact beyond that: the value comes from a cached profile, implying it may be stale and that no network fetch is involved. It stops there, giving no detail on null/empty behavior.
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?
A single front-loaded clause, no filler, no repetition of the tool name. Every element ('account holder's', 'full name', 'cached user profile') earns its place.
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 no-argument read with an explicit safety annotation, the description plus annotations cover nearly everything needed to invoke it. The remaining gap is disambiguation from 'display_name' and 'user_name', which live in the usage-guidelines dimension but also affect a complete picture of this tool's role.
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 takes zero parameters, so the baseline of 4 applies; there is no parameter surface the description needs to compensate for. It correctly avoids inventing argument behaviour it does not have.
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 resource and provenance for a zero-param getter: the account holder's full name from the cached profile. That is unambiguous about what it returns. It does not, however, distinguish itself from sibling tools like 'display_name', 'user_name', or 'get_user_profile', which an agent would need to choose between.
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?
There is no when-to-use guidance, no condition under which this is preferable to 'display_name' or 'user_name', and no mention of what it returns if the profile is empty. The agent must infer selection purely from the near-identical sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A page of activities, newest first (start defaults to 0, limit to 20). Defaults start=0, limit=20.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description does add genuine behavioral context beyond the annotations: results are ordered newest-first and the call is paginated with defaults. It stops short of explaining page size limits or how to detect the end of the result set.
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 ordering and pagination fact is correctly front-loaded, but the second sentence ('Defaults `start=0, limit=20`.') is a verbatim restatement of the parenthetical in the first sentence. Roughly half the description is duplicated content that does not earn its place.
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 two-parameter list endpoint with no output schema, the description should at least hint at the page envelope (total count, whether more pages exist). It says 'a page' but never explains how an agent knows pagination is finished, leaving the caller to infer termination from an empty or short page.
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 0%, so the description must carry the parameter burden. It supplies the defaults for both parameters (start=0, limit=20), which the schema does not, but gives no semantics for what start offsets from (an index? a timestamp?) or whether limit is capped.
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 resource (a page of activities) and an ordering trait (newest first), which tells an agent roughly what comes back. But it uses no verb and never distinguishes itself from the many siblings that also return activities (get_activities_by_date, get_activities_for_date, get_last_activity, get_activity, count_activities, get_gear_activities). An agent must guess which activity-listing tool is the unfiltered one.
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?
There is no when-to-use guidance at all: nothing says this is the unfiltered/paginated listing versus the date-scoped siblings. With ~140 sibling tools including several activity listers, the absence of any routing hint is a real gap, though the description is not actively misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every activity between two dates, optionally filtered by activity type. Pages through the results internally. Paginates internally: fetches fixed pages of 20, incrementing start by 20, until an empty page (normal end) or 2000 pages without one (throws GarminError).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| sortorder | No | ||
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| activitytype | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, so safety is covered, yet the description adds real behavioral context the agent could not otherwise know: fixed 20-item pages incremented via `start`, termination on an empty page, and a hard cap of 2000 pages before throwing GarminError. That failure mode is genuinely useful for a client.
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 core scope is front-loaded and the pagination mechanics are useful. The two opening pagination sentences ('Pages through the results internally. Paginates internally: ...') restate the same fact, a small redundancy in an otherwise tight description.
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 no output schema, the description should say more about what each activity record contains and how the result set is shaped, and it leaves sortorder and enddate semantics unexplained. It does cover the risky part (internal pagination and its error condition) well.
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 description conveys that startdate/enddate form the range and that activitytype is an optional filter, but sortorder is never explained and enddate's optionality/default is not stated. With 50% schema coverage, the schema documents only the two date formats, so the description partially compensates but leaves gaps.
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 gives a specific verb and resource ('Every activity between two dates') plus an optional filter by activity type, so the operation is clear. It does not, however, distinguish itself from close siblings such as get_activities, get_activities_for_date, or get_last_activity, which an agent must disambiguate by name alone.
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?
There is no when-to-use guidance or mention of alternatives, despite many overlapping activity-retrieval siblings in the toolset. The only routing signal is the implied date-range scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The activities recorded on one date. Despite the name, the path is /mobile-gateway/heartRate/..., not an activities-service path.
| Name | Required | Description | Default |
|---|---|---|---|
| fordate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful operational warning that the endpoint is `/mobile-gateway/heartRate/...` rather than an activities-service path, implying the payload may not match activity-service shapes. It still says nothing about pagination or 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-loaded with the purpose. The second sentence is unconventional but earns its place as a routing warning; nothing is padded.
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?
No output schema exists, so the description carries the burden of explaining what comes back (activity IDs? summaries? full details?) and it does not. Combined with the unresolved overlap against `get_activities_by_date`, the definition is too thin for an agent to call confidently.
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 single `fordate` parameter (YYYY-MM-DD, UTC) is fully documented in the schema. The description only echoes 'one date' and adds no format, timezone, or boundary detail beyond the schema â the baseline 3 applies.
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 first sentence states a specific resource and scope ('the activities recorded on one date'), which is clearer than a bare restatement of the name. However, it makes no attempt to distinguish this tool from the near-identical sibling `get_activities_by_date`, leaving the agent to guess which one to call.
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?
There is no explicit when-to-use guidance and no mention of alternatives, despite several siblings (`get_activities`, `get_activities_by_date`, `get_last_activity`) covering overlapping ground. The path note hints at a routing quirk but gives no selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One activity by id; measurements are under summaryDTO. Throws GarminError if Garmin returns nothing. ActivitySummary extends PersonalApi.ActivitySummaryDTO, typed from Garmin's Personal API spec (AGENTS.md section 3).
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a read-only, open-world operation. The description adds useful behavioral context beyond the annotations, specifically that it throws GarminError when Garmin returns nothing and that measurements are located under summaryDTO.
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 short and front-loads the core behavior in the first clause. The remaining details are compact, though the AGENTS.md/spec reference is developer-oriented and slightly less useful for an agent.
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 no output schema, the description partially compensates by naming summaryDTO and the underlying type. However, it does not explain the return structure in enough detail and provides no sibling-routing guidance, leaving meaningful gaps for an agent.
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%, and the schema already documents activityId as a numeric id. The description says "by id" but does not add format, validation, or lookup semantics beyond the schema, so 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 phrase "One activity by id" clearly identifies the resource and scope, and an agent can understand it retrieves a single activity. It does not explicitly distinguish itself from close siblings such as get_activity_details, get_last_activity, or get_activities, so it falls short of a 5.
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 no when-to-use guidance, prerequisites, or alternatives. It does not explain when an agent should choose get_activity over get_activity_details, get_last_activity, or list/search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An activity's time series and GPS track, capped at maxchart/maxpoly points. Defaults maxchart=2000, maxpoly=4000, sent as maxChartSize/maxPolylineSize.
| Name | Required | Description | Default |
|---|---|---|---|
| maxpoly | No | ||
| maxchart | No | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the result is truncated, capped at maxchart/maxpoly points, with explicit defaults of 2000 and 4000, which tells the agent data may be downsampled. It stops short of stating auth needs or what happens on invalid ids.
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 with no filler, and the payload description leads. Structure is efficient but slightly note-like, opening with a bare noun phrase rather than an action, which mildly hurts scanability.
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 no output schema, the description must sketch the return shape; it does say time series plus GPS track and warns about capping, which is the minimum an agent needs. It omits response format details (point units, ordering, what a capped result looks like) and any routing versus sibling activity tools.
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 only 33% (just activityId as 'Numeric id'), so the description carries the two undocumented params and does so well: it defines maxchart/maxpoly as point caps, gives their default values, and even maps the camelCase wire names maxChartSize/maxPolylineSize. It does not specify units or valid ranges, keeping it out of 5 territory.
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 phrase 'An activity's time series and GPS track' names a specific resource and payload, but supplies no verb, so the operation (retrieve) is only inferred. It also does not distinguish itself from close siblings like get_activity, get_activity_splits, or get_activity_hr_in_timezones, leaving the agent to guess which activity-data view it returns.
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?
There is no when-to-use statement, no prerequisite (e.g. that activityId must come from get_activities), and no mention of alternatives among the many get_activity_* siblings. Usage is only implied by the resource being described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The event types setActivityEventType accepts. GETs /activity-service/activity/eventTypes: nine {typeId, typeKey, sortOrder} entries (race, recreation, specialEvent, training, transportation, touring, geocaching, fitness, uncategorized).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description goes further by naming the underlying endpoint, the exact count of entries (nine), the record shape {typeId, typeKey, sortOrder}, and the full value set â all of which matter because no output schema exists. It does not note whether the list is static or auth-gated, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler: the consumer relationship and the endpoint lead, then the payload is enumerated. Nothing is wasted 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description carries the full return-value burden and does so â it specifies the payload shape, count, and every value. Nothing an agent needs to call and use this tool correctly 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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming no input is needed.
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?
States a specific resource (the event type enum) and ties it directly to the consumer tool `setActivityEventType`, distinguishing it from the many other `get_*types` siblings such as get_activity_types. An agent knows exactly what it gets without opening the schema.
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 framing 'the event types `setActivityEventType` accepts' strongly implies this is the lookup to call before set_activity_event_type, which is effective routing. It stops short of an explicit when/when-not statement or naming alternatives, so it is clear context rather than full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A strength activity's exercise sets.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered, but the description adds nothing behavioral beyond them: no indication of what happens for a non-strength activity, whether an empty result is possible, or whether data is paginated. For a read against user data, that is a meaningful gap even with the lower annotation-adjusted bar.
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?
It is a single short phrase with zero filler and the resource is front-loaded, so nothing wastes the agent's attention. Its brevity, however, is closer to under-specification than to disciplined concision.
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 no output schema, the description is the only place to explain what comes back (set count, reps, weights, ordering) and it does not. It also omits the strength-activity precondition that governs whether the call is meaningful, leaving the definition short of what an agent needs to call 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?
Schema description coverage is 100%, so the schema already documents activityId ('Numeric id'), which sets the baseline at 3. The description adds only the implicit constraint that the id refers to a strength activity; it gives no format, range, or lookup guidance beyond that.
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 fragment 'A strength activity's exercise sets' names the resource and its domain (strength activities) but supplies no verb, so the agent must infer that this is a read that returns the sets recorded for a given activity. It is distinguishable from the sibling set_activity_exercise_sets only by the set_/get_ prefix, not by the text itself.
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?
There is no when-to-use guidance, no statement of prerequisites (e.g. that the activityId must belong to a strength activity), and no mention of alternatives such as get_activity_details or set_activity_exercise_sets. The agent must infer the usage context entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The gear linked to an activity. Returns an ARRAY, verified live.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful piece of behavior beyond annotations: it returns an ARRAY (compensating for the absent output schema). 'Verified live' is testing provenance rather than agent-relevant behavior, and nothing is said about empty results when no gear is linked.
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-loaded with the purpose and the return shape. The trailing 'verified live' phrase is meta-commentary that consumes space without informing an agent's invocation decision.
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 no output schema, the description carries the burden of describing returns and does only the minimum: it says an ARRAY comes back but never what each element contains or how empty results appear. For a simple single-parameter read this is adequate but leaves a real gap on the return contract.
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%, with activityId documented as 'Numeric id' and constrained to the single required parameter. The description adds no format details, id source, or the fact that the field also accepts a string despite the 'Numeric' label. Baseline 3 is appropriate when the schema carries parameter documentation.
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 the exact resource and its relationship: gear linked to a specific activity, which is distinct from get_gear (gear inventory) and get_gear_activities (activities for gear). It is clear, but it never names or contrasts those siblings, so the agent must infer the distinction from the name alone.
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?
No when-to-use guidance and no mention of the closely related get_gear, get_gear_activities, or add_gear_to_activity tools. The agent gets no signal about when this lookup is preferable to the other gear endpoints in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time spent in each heart-rate zone during an activity.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the result is a per-zone time breakdown, with nothing about whether an activity lacking HR zones returns empty, errors, or a default zone set. That is modest added value against an already-covered read operation.
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 short sentence with zero filler, and the payload (per-zone time) is front-loaded. It is a noun fragment rather than a complete statement, which slightly reduces its structural clarity.
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 simple read with one documented parameter and no output schema, the description is close to complete about what comes back. It is still missing selection guidance against the several sibling heart-rate and zone tools, which is the main gap.
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?
With a single parameter and 100% schema description coverage, the schema fully documents activityId, so the baseline is 3. The description neither names the parameter nor adds accepted id forms or per-activity constraints beyond what the schema states.
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 specific resource (time spent per heart-rate zone) and is distinguishable from neighbors like get_activity_power_in_timezones or get_heart_rate_zones. It stops short of a verb+scope framing and never contrasts itself with the closest siblings, so it lands just under a 5.
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?
There is no when-to-use guidance at all: no mention that this is per-activity and requires an activityId, and no pointer to get_heart_rate_zones or get_activity_power_in_timezones as alternatives. The agent must infer the use case from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Time spent in each power zone during an activity.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the notion that output is per-zone time, which is a modest restatement of the tool name; no auth needs, scope limits, or behavior on activities without power data are disclosed.
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?
A single short sentence with no filler and the key concept (time in each power zone) front-loaded. It is efficient, though the odd 'in_timezones' naming is not unpacked anywhere.
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?
There is no output schema, and the description gives only the conceptual shape of the return value. It never clarifies the confusing 'timezones' element of the name (it means power-zone buckets, not time zones), which is the main thing an agent would misread.
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% and there is exactly one parameter (activityId), so the schema carries the burden. The description adds nothing about the identifier's form (numeric id vs string), leaving parameter semantics entirely to the schema â baseline 3.
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?
States a specific resource and scope: time spent in each power zone during a single activity. It is distinguishable from the near-named sibling get_activity_hr_in_timezones by the word 'power', though it never explicitly contrasts itself with tools like get_power_zones or get_power_zones_for_sport.
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 no when-to-use guidance, no prerequisites, and no alternatives. An agent cannot tell from this text whether it should call get_power_zones (zone definitions) or this tool (time attribution), nor that an activityId is mandatory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An activity's laps.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that â no note on return shape, pagination, or what a 'split' contains relative to sibling endpoints.
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?
It is extremely short and wastes no words, but it is under-specified rather than well-structured â a bare noun phrase rather than a front-loaded statement of action and scope.
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 simple read tool with annotations and full schema coverage this could be adequate, but in a suite containing get_activity_splits, get_activity_split_summaries, and get_activity_typed_splits the description must explain the distinction and does not. An agent cannot confidently select this endpoint.
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?
Only one parameter (activityId) with 100% schema description coverage, so the schema carries the burden and the baseline of 3 applies. The description adds no meaning about the id format (integer or string) or any filtering behavior.
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 is the fragment 'An activity's laps.' â essentially a restatement of the tool name ('splits' â 'laps') with no verb and no scope. It does not distinguish this tool from close siblings such as get_activity_split_summaries or get_activity_typed_splits, leaving the agent unable to tell which split-related endpoint to choose.
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?
There is no when-to-use guidance, no prerequisites, and no mention of the three look-alike siblings (get_activity_split_summaries, get_activity_typed_splits, get_activity_details) that an agent must disambiguate against. Nothing misleading, but nothing helpful either.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summaries of an activity's splits.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so safety is covered, but the description adds nothing beyond that: it does not say what a 'summary' aggregates, how the summary differs from raw splits, or whether results are grouped by lap/segment.
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?
It is a single front-loaded phrase with zero filler, but at the cost of under-specification rather than genuine concision. There is no wasted text, but also not enough text to be useful.
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 output schema, so the description should carry at least some sense of what is returned and how it relates to get_activity_splits, yet it does neither. For a read tool whose only purpose is its return shape, the definition is incomplete.
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% for the single activityId parameter, so the schema carries the parameter documentation. The description adds no additional meaning (e.g., whether an invalid or missing activity id errors or returns empty), so the baseline of 3 applies.
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 is essentially a restatement of the tool name: 'get_activity_split_summaries' becomes 'Summaries of an activity's splits.' It names the resource but gives no verb and no way to distinguish it from close siblings like get_activity_splits or get_activity_typed_splits, leaving 'summaries' undefined.
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?
There is no when-to-use guidance at all. With three closely related split tools in the sibling list (get_activity_splits, get_activity_typed_splits, get_activity_split_summaries), the absence of any routing rule forces the agent to guess among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An activity's typed splits, richer than getActivitySplits for some sports. Richer detail than getActivitySplits for some activity types (e.g. Bouldering).
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that â nothing about the shape of typed splits, whether all activity types return data, or what happens for unsupported sports.
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 two sentences say essentially the same thing â 'richer than getActivitySplits for some sports' is immediately restated as 'richer detail than getActivitySplits for some activity types (e.g. Bouldering)'. The duplication means one sentence does not earn its place.
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 read tool with no output schema, the description should convey what the agent gets back and for which sport types; instead it repeats itself. Nothing an agent needs beyond the sibling name is provided, and the 'some sports' qualifier is never made actionable.
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?
Only one parameter (activityId) and schema description coverage is 100%, so the schema carries the burden. The description adds no meaning about the id (e.g. that it must be an activity of a supporting sport type), leaving the baseline 3.
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?
Names a specific resource ('an activity's typed splits') and explicitly contrasts it with the sibling getActivitySplits, so an agent can tell the two apart. It lacks a verb like 'fetch'/'list', but the resource is concrete enough to identify the operation.
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 names the alternative (getActivitySplits) and hints at when this one wins ('richer for some activity types, e.g. Bouldering'), but never states an explicit rule such as 'use this for Bouldering/climbing, otherwise use getActivitySplits'. Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every activity type Garmin knows: { typeId, typeKey, parentTypeId, ... }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network reach are covered. The description's only added behavioral value is the expected record shape (`typeId, typeKey, parentTypeId`), which partially compensates for the absent output schema. It says nothing about whether the list is cached, stable, or large.
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?
A single short fragment with the scope statement front-loaded and zero filler. It is terse to the point of being a sentence fragment, but nothing is wasted.
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 zero-parameter reference lookup with annotations covering read-only status, the description is close to adequate, and the inline return-shape hint substitutes for the missing output schema. It still omits sibling differentiation and any statement about list completeness or filtering.
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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema itself is complete (empty object, no additional properties).
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 fragment names the resource ('Every activity type Garmin knows') and its return shape, so an agent can tell it enumerates activity types rather than, say, event types. But it is a noun phrase with no verb and no explicit differentiation from close siblings like get_activity_event_types or set_activity_type. Purpose is inferable but not crisply stated.
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?
There is no when-to-use guidance, no mention of prerequisites, and no pointer to alternatives such as get_activity_event_types. The 'every ... Garmin knows' phrasing implies an unfiltered lookup, but the agent receives no routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The weather recorded for an activity.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds only the word 'recorded', implying retrieval of pre-existing data, but does not describe return format, error behavior (e.g., missing weather), authentication needs, or rate limits. It adds minimal value beyond annotations.
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 a single, concise sentence with no wasted words. However, it is under-specified and not front-loaded with a clear action, which limits its usefulness. Conciseness is fine, but the structure prioritizes brevity over necessary detail.
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 simple read tool with one parameter and full schema coverage, the description is too minimal. It does not explain what weather data is returned (e.g., temperature, conditions) or what happens if no weather is recorded, and there is no output schema to fill that gap. It fails to differentiate from siblings that may also return activity weather.
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%, with the single activityId parameter documented as 'Numeric id'. The description does not add any meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema fully documents the parameter.
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 identifies the resource (weather for an activity) but lacks a specific action verb like 'get' or 'retrieve'. It is a noun phrase that roughly restates the tool name, leaving the exact operation somewhat implied rather than stated. It does not distinguish from siblings like get_activity_details, which may also include weather.
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?
There is no guidance on when to use this tool versus alternatives. No prerequisites, no conditions, no mention of related tools. The description offers no context for selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The workouts done during an activity, with the steps the device ran. GETs /activity-service/activity/{id}/workouts: the workouts done during the activity, {index, workoutName, timeCreated, sport, manufacturer, multisportSet, steps, workoutPhrase} with the steps the device ran (PersonalApi.ActivityWorkoutDTO, matched key for key, steps included). [] for an activity done without one.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint) and open-world reach, so the bar is lower. The description still adds real behavior: it discloses the underlying GET path and, importantly, that an activity done without a workout returns `[]` rather than erroring. It does not cover failure modes for a bad/unknown activityId.
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?
Front-loaded with the core meaning, but it is noticeably repetitive: 'the workouts done during an activity' and 'with the steps the device ran' each appear twice, plus an internal DTO name and 'matched key for key, steps included' which restates earlier text.
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 with annotations and no output schema, listing the returned field set and the empty-array case makes it largely self-sufficient. Missing only error behavior and any note on whether steps can be nested/large.
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 is already documented as 'Numeric id', so the schema carries the load. The description only echoes the id as `{id}` in the path template and adds no format, range, or accepted-string nuance beyond 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?
States a specific verb+resource: returns the workouts performed during one activity, including the device-executed steps. That is clearly distinct from library tools like get_workouts and from get_activity_details. It never names a sibling explicitly, so it stops short of full 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?
There is no when-to-use or when-not-to-use guidance and no named alternative. The reader must infer from the id-based schema that this is the per-activity drill-down versus get_activity_details or get_activity_exercise_sets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One adaptive (Garmin Coach) training plan by id. GETs /trainingplan-service/trainingplan/fbt-adaptive/{planId}, a distinct sub-path from getTrainingPlanById's phased path.
| Name | Required | Description | Default |
|---|---|---|---|
| planId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the backing service path (`/trainingplan-service/trainingplan/fbt-adaptive/...`), which is useful provenance but says nothing about auth requirements, error behavior when the id is invalid, or what the returned plan contains.
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, front-loaded sentences with no filler; the resource and scope come first and the disambiguation follows. The raw REST path is arguably implementation detail an agent caller never uses, which slightly dilutes an otherwise efficient definition.
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 read-only lookup with no output schema, the definition covers identity and the sibling boundary adequately. It leaves implicit what shape the returned plan takes (workouts, phases, status), a minor gap given no output schema exists to carry that.
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% (the single `planId` param is documented as a numeric id), so the schema carries the parameter semantics. The description's 'by id' restates rather than extends that, which is the expected baseline when the schema does the work.
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?
States a specific resource (one adaptive/Garmin Coach training plan), the lookup key (by id), and explicitly separates itself from the sibling `get_training_plan_by_id` by naming its distinct API sub-path. An agent can distinguish the two tools without opening either schema.
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 comparison to `getTrainingPlanById`'s `phased` path tells the agent this is the correct tool for adaptive plans specifically, which is genuine alternative-aware guidance. However, it stops short of an explicit when-to-use/when-not statement (e.g. 'use this when the plan is a Garmin Coach adaptive plan').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A Garmin Coach workout by its workoutUuid (getWorkoutById cannot). GETs /workout-service/fbt-adaptive/{uuid}: a Garmin Coach workout with segments, steps and estimatedTrainingEffect. Coach workouts have no workoutId, and getWorkoutById cannot fetch them: /workout-service/workout/{uuid} is a 404. Take the uuid from getTrainingPlanWorkouts or getScheduledWorkoutSummaries.
| Name | Required | Description | Default |
|---|---|---|---|
| workoutUuid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds valuable context: it notes the 404 pitfall of the sibling endpoint and describes the returned content (segments, steps, estimatedTrainingEffect). It does not cover error behavior for this endpoint itself or rate limits, but the disclosure is strong for a read-only fetch.
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 tightly packed sentences, front-loaded with the core purpose and followed by the endpoint and the UUID sourcing. Every clause earns its place, and there is no 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?
Given no output schema, the description adequately covers what is returned (segments, steps, estimatedTrainingEffect), why the tool exists (sibling cannot fetch coach workouts), and where the UUID comes from. This is complete for a single-parameter read-only fetch.
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?
With 0% schema description coverage, the description must compensate. It explains that the workoutUuid comes from getTrainingPlanWorkouts or getScheduledWorkoutSummaries, which adds meaning beyond the bare parameter name. It does not specify the UUID format, but the source guidance is substantial.
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?
States a specific verb (GET) and resource (Garmin Coach workout by workoutUuid), and explicitly distinguishes it from the sibling getWorkoutById, which cannot fetch these workouts. An agent can immediately tell this apart from get_workout_by_id without opening either schema.
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?
Explicitly states when to use this tool (for Garmin Coach workouts that getWorkoutById returns 404 for) and where to obtain the required workoutUuid (from getTrainingPlanWorkouts or getScheduledWorkoutSummaries). No ambiguity remains about the alternative or the prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ad-hoc challenges the account took part in. GETs /adhocchallenge-service/adHocChallenge/historical; start validated non-negative, limit validated positive (throws GarminError otherwise); returns an ARRAY, verified live.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered, but the description adds genuinely useful behavior the annotations do not: input validation rules (start must be non-negative, limit must be positive, otherwise garminError is thrown) and the fact that the return value is an array. It stops short of describing pagination semantics or rate limits.
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?
A single compact sentence front-loads the purpose, then appends endpoint, validation, and return-type details. Every clause carries information; it is dense but not padded.
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 no output schema, the description usefully states that an array is returned and documents the required parameters' validation. Still missing for a complete picture: pagination behavior, default/maximum limit values, and what an element of the returned array contains, all of which an agent needs to call this confidently.
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 0%, so the description must compensate, and it does partially by stating the validation constraint on each of the two parameters. However, it never explains what the numbers mean semantically (offset vs. index for 'start', max record count for 'limit'), which is the key ambiguity for a paged list call.
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 the specific resource ('Ad-hoc challenges the account took part in') and even pins the backing endpoint, so the agent knows exactly what data this returns. It does not explicitly differentiate itself from near-name siblings such as get_badge_challenges or get_inprogress_virtual_challenges, so it falls short of a 5.
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?
There is no when-to-use guidance, no statement of prerequisites, and no mention of any alternative sibling tool. The agent must infer the usage context entirely from the name and the resource phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily events for one date (Garmin's dailyEvents feed).
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a small amount of context by tying the tool to Garmin's underlying `dailyEvents` feed, which helps an agent reason about the payload shape, but says nothing about auth, rate limits, or how far the feed reaches.
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?
A single short sentence with no filler, and the scope constraint ('one date') is front-loaded. Nothing in the text is redundant with the title or annotations.
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?
There is no output schema, so the description is the only place a reader could learn what a 'daily event' actually contains, and it does not say. For a minimal single-parameter read tool the rest is adequate, but the return semantics remain opaque.
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?
Only one parameter (cdate), and schema description coverage is 100% with a clear YYYY-MM-DD (UTC) note, so the schema already carries the full burden. The description adds nothing about the date parameter beyond what the schema states, which is the baseline 3.
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 the resource ('daily events') and narrows it to a single date, which is more specific than a bare tautology. However it contains no verb at all and does nothing to separate it from siblings like get_calendar_event, list_calendar_events, or get_body_battery_events, so an agent must infer that this returns a read feed.
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?
No when-to-use guidance, no prerequisites, and no named alternatives are given. The reader cannot tell from the text whether this overlaps with get_calendar_event or get_daily_stats, or under what circumstances the raw 'dailyEvents' feed is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All-day stress levels for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond those annotations and the schema's date scope: no mention of data granularity, return shape, units, or whether sparse/no-data days are handled.
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?
A single short sentence with zero padding and the key scope term front-loaded. It is efficient, though the terseness contributes to the missing sibling differentiation rather than resolving it.
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 simple read-only tool with annotations covering safety and no output schema to explain, the description is minimally adequate. It falls short of complete because a swarm of similarly named stress/stats siblings exists and this definition gives the agent no basis for choosing among them.
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?
With one parameter at 100% schema description coverage (including the YYYY-MM-DD UTC format), the schema fully documents the input. The description's 'for one date' merely echoes the parameter, so 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?
States a specific verb/resource pair ('all-day stress levels') with a scope qualifier ('for one date'), which is more precise than a bare name restatement. However, it does not distinguish itself from close siblings such as get_stress_data or get_weekly_stress, leaving the agent to guess which stress endpoint applies.
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?
'For one date' implies the single-day scope, which is a weak usage signal, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., get_weekly_stress for ranges, get_stress_data for other granularity). Guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Badge challenges the account can join. Garmin rejects start=0; start at 1. GETs /badgechallenge-service/badgeChallenge/available; same start/limit validation; same array-not-dict correction and same live start=0 -> 400 discovery as getBadgeChallenges.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds meaningful non-obvious behavior: Garmin rejects `start=0`, the endpoint path, the array-not-dict correction, and the live 400 discovery. These are real behavioral traits an agent can't infer from structured fields.
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?
Purpose is front-loaded in the first clause, followed by dense implementation notes. Very compact for the amount of quirk detail conveyed, though the backward references to `getBadgeChallenges` assume the reader has already seen that definition.
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 read-only list endpoint with no output schema, the description covers the pagination traps well but says nothing about the shape or fields of returned challenges, leaving a gap for an agent that needs to interpret results.
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 0%, so the description must carry the burden. It does add one key constraint â `start` must begin at 1, not 0 â but defers the rest to 'same `start`/`limit` validation' without stating the limit range or defaults, leaving meaning partially implied.
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?
States the resource and scope precisely: 'Badge challenges the account can join,' which distinguishes the joinable set from earned/in-progress siblings. It references `getBadgeChallenges` for parity rather than explicitly differentiating from other badge siblings like `get_available_badges`, but the verb+resource is clear.
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?
No explicit guidance on when to use this tool versus alternatives such as `get_badge_challenges`, `get_available_badges`, or `get_non_completed_badge_challenges`. Comparisons to `getBadgeChallenges` are about implementation quirks, not selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Badges the account can still earn, each with badgeImageUrls added. GETs /badge-service/badge/available?showExclusiveBadge=true; same badgeImageUrls as getEarnedBadges; stays nullable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds real value beyond them: the exact endpoint and hardcoded showExclusiveBadge=true query, plus the fact the response 'stays nullable'. It stops short of describing pagination or filtering behavior.
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 dense sentence that front-loads the outcome and follows with implementation detail. The endpoint path is arguably noise for an agent, but everything else earns its place.
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 no output schema, the description carries the return-value burden and does so adequately by identifying badgeImageUrls and flagging nullability. It does not enumerate other badge fields the agent will receive.
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?
Zero input parameters, so the baseline is 4. The description usefully notes the server-side showExclusiveBadge=true default that the caller cannot override, which is meaningful context about what the call actually returns.
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?
States a specific resource and scope: badges the account can still earn, explicitly excluding earned badges. This contrasts cleanly with siblings getEarnedBadges, get_in_progress_badges, and get_badge_challenges.
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?
Usage is implied by the 'can still earn' framing, and it references getEarnedBadges for the shared badgeImageUrls shape, but it never states when to pick this over get_in_progress_badges or get_available_badge_challenges.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Completed badge challenges. Garmin rejects start=0; start at 1. GETs /badgechallenge-service/badgeChallenge/completed; same start/limit validation as getAdhocChallenges; returns an ARRAY, verified live. Live discovery: Garmin's server rejects start=0 with a 400 ("start should > 0.") on this endpoint even though the client-side check allows it (non-negative); the 400 is Garmin's server, not a wrong URL; call with start>=1 in practice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds real behavioral context beyond them: Garmin's server rejects start=0 with a 400 'start should > 0.' despite a permissive client-side check, the URL is correct, and the response is an ARRAY verified live. This is exactly the kind of operational quirk that saves an agent failed calls, though auth needs and pagination/return details remain unstated.
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 purpose is front-loaded, but the start=0 rejection is stated twice (once tersely, once in the 'Live discovery' paragraph), which is redundant. The second statement adds the actual error message and reasoning, so it is not pure duplication, but the content could be compressed considerably.
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 simple two-parameter read tool with annotations and no output schema, the description is close to complete: it covers purpose, endpoint, return shape, and the critical start constraint. The only meaningful gap is limit semantics and any when-not-to-use guidance relative to the other badge endpoints.
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 0%, so the description carries the full burden. It explains the start constraint in depth (must be >=1, start=0 causes a 400), which is valuable, but it says nothing about limit (range, default, max) and never clarifies that both are required numbers.
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 opening fragment 'Completed badge challenges' names the resource and the completed subset, which lets an agent distinguish it from get_non_completed_badge_challenges and get_available_badge_challenges. The endpoint path is also stated, but the purpose is never phrased as a proper verb+object statement and no sibling is named explicitly.
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 practical invocation guidance ('start at 1', start>=1 in practice) and cross-references getAdhocChallenges for validation behavior, which is genuinely useful. However, it never states when to choose this tool over the closely related badge tools (non-completed, available, earned, in-progress), so routing is left to inference from the word 'Completed'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One badge with its related series and what earned it. Works for unearned badges. GETs /badge-service/badge/detail/v3/{badgeId}, the request Garmin Connect's web app makes when a badge is opened; badgeId validated as a positive integer. Returns an OBJECT: the getEarnedBadges fields plus relatedBadges (the rest of the series, each with earnedByMe), badgeAssocType/badgeAssocDataId/badgeAssocDataName (for "activityId", the activity that earned it) and followings. An unknown id is a 400 GarminHttpError, not a 404. The badge and each relatedBadges entry gain `badgeImageUâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| badgeId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond them: badgeId is validated as a positive integer and an unknown id yields a 400 GarminHttpError rather than a 404. This error-shape disclosure is genuinely useful for an agent. It stops short of describing rate limits or auth requirements, so not quite top marks.
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?
Front-loads the core meaning in the first two short sentences, then layers technical detail (endpoint, validation, return shape, error code). Every sentence carries information, though the density borders on a spec dump. Appropriate size for a detail-fetch tool, with the trailing truncation being an artifact of the excerpt.
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 no output schema, the description correctly carries the return-value burden, enumerating the object fields (getEarnedBadges fields, relatedBadges, badgeAssocType/DataId/DataName, followings) and the error case. An agent has enough to call it and interpret the result. Only pagination/volume or auth specifics are absent.
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?
With only one parameter and 0% schema description coverage, the schema says nothing beyond 'number'. The description compensates by stating badgeId is validated as a positive integer, adding real meaning not present in the structured field. A single well-documented param lands at 4.
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?
States a specific verb+resource: retrieves one badge with its related series and cause of earning. The clause 'Works for unearned badges' implicitly distinguishes it from siblings like get_earned_badges and get_available_badges, though it never names them. Clear purpose, but the differentiation from the many badge siblings is inferential rather than explicit.
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?
Implies usage by noting it works for unearned badges and mirrors what the web app does when a badge is opened, giving context for when it applies. However, it never names an alternative (get_earned_badges, get_in_progress_badges) or states a condition that should route the agent elsewhere. Usage is implied, not directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Blood-pressure readings for a date or a date range (enddate defaults to startdate).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the enddate-falls-back-to-startdate behavior, which is genuine extra context, but says nothing about return format, data sources, or pagination.
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?
A single sentence with the resource front-loaded and the range semantics in a parenthetical. No filler, nothing redundant with the schema.
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 simple two-parameter read tool with readOnly/openWorld annotations and no output schema, the description covers what to pass and the one non-obvious default. Only the returned data shape is unaddressed, which is minor here.
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, but the description adds a real semantic not present in the schema: enddate silently defaults to startdate. That default-resolution rule materially affects how an agent should call the tool.
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 specific resource (blood-pressure readings) and scope (a date or date range), so an agent immediately knows it is a read tool. It does not explicitly differentiate from siblings set_blood_pressure and delete_blood_pressure, which is why it stops short of 5.
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 scope phrase 'for a date or a date range' implies the intended usage, and the enddate-default note hints at a single-day lookup. There is no explicit when-to-use/when-not guidance or mention of the write/delete siblings, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily Body Battery reports for a date or a date range (enddate defaults to startdate).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the default behavior for enddate, which is useful context, but does not disclose return format, auth, or rate limits.
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?
A single, front-loaded sentence with no filler. The parenthetical default is compact and earns its place.
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 simple two-parameter read-only getter with annotations covering safety, the description is nearly complete. It states purpose and parameter default, but omits any indication of what a 'report' contains, which could matter without an output 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 coverage is 100% and both parameters are documented with format and UTC note. The description adds the default value relationship (enddate defaults to startdate), which is not in the schema, providing meaningful semantic value.
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?
Names the resource (Body Battery) and the operation (daily reports) clearly, but does not differentiate from the sibling get_body_battery_events or state the scope beyond date filtering.
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?
Only states that it accepts a date or date range; no guidance on when to choose this tool over get_body_battery_events or other body battery retrieval tools, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Body Battery events for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds nothing beyond the date scope: it does not say what an 'event' is, whether results can be empty, or how they are ordered or paginated. For a read tool with zero supplementary context, this is a gap.
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 short front-loaded sentence with no filler, appropriate in length for a single-parameter read tool. It is efficient, though the terseness edges toward under-specification rather than crispness.
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-only tool with full schema coverage and annotations, little is strictly required, and no output schema exists so return values need not be documented. Still, the key ambiguity â what constitutes a Body Battery 'event' versus the sibling get_body_battery â is unresolved.
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?
With a single parameter at 100% schema coverage (cdate with format and UTC note), the schema carries the burden, so baseline 3 applies. 'For one date' is consistent with cdate but adds no format or timezone detail beyond what the schema already states.
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 the resource (Body Battery events) and the scope (one date), so the agent knows roughly what comes back. But it never states a verb and gives no differentiation from the closely-named sibling get_body_battery, so an agent cannot tell whether 'events' means discrete charge/drain transitions or the same data as the summary 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?
There is no when-to-use guidance, no prerequisites, and no reference to the obvious alternative (get_body_battery or get_body_battery for a range). The agent must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Body-composition data for a date or a date range (enddate defaults to startdate). GETs /weight-service/weight/dateRange; throws GarminError if startdate > enddate getStatsAndBody (wellness service) now delegates to this instead of inlining its own copy of the same call.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds real behavioral context beyond them: the enddate default, the GarminError thrown when startdate > enddate, the underlying endpoint, and the delegation relationship. It stops short of describing return shape or pagination.
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?
Front-loaded with the core scope before the endpoint and delegation detail. The trailing clause about getStatsAndBody delegating is internal implementation trivia that adds little for an agent deciding how to call the tool.
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 two-parameter read tool with no output schema, the description covers scope, defaulting, and the one failure mode. The main remaining gap is that 'body-composition data' is not elaborated into what fields come back, which would matter since no output schema exists.
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 baseline is 3, but the description adds the default behavior of enddate ('defaults to startdate'), which is not expressed anywhere in the schema. That is genuine semantic value beyond the structured fields.
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?
States a specific verb+resource ('Body-composition data') and its scope (a date or a date range), and the delegation note about getStatsAndBody hints at how it relates to the sibling get_stats_and_body. It does not, however, explicitly contrast itself with the other weight-adjacent readers like get_weigh_ins or get_daily_weigh_ins.
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?
Usage is implied by the scope ('for a date or a date range') and the note that getStatsAndBody delegates here suggests this is the canonical call. There is no explicit when-to-use / when-not-to-use statement or named alternative for the agent to route between.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One calendar event by id. GETs /calendar-service/event/{id}; a missing id is a 404 GarminHttpError.
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), yet the description adds real context: the underlying GET path and the concrete failure mode (a missing id yields a 404 GarminHttpError). That error contract is information the annotations do not supply.
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, both front-loaded and load-bearing: the first states what it returns, the second gives the endpoint and error behavior. No 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?
With no output schema, the description could have sketched the returned event fields, which is the main remaining gap. For a one-parameter read tool it otherwise covers identity, endpoint, and error semantics adequately.
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% with a single parameter documented as 'Numeric id'. The description adds only 'by id', which restates the schema rather than clarifying the accepted integer-or-string union or id provenance. Baseline 3 applies.
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?
States a specific verb and resource with a scoping qualifier ('One calendar event by id'), which implicitly distinguishes it from list_calendar_events and get_all_day_events. It stops short of naming the near-identical sibling get_shared_calendar_event, so an agent must still infer the split.
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?
No explicit when-to-use guidance. The description never says when to prefer this over list_calendar_events, get_all_day_events, or especially get_shared_calendar_event, which shares the same single-event shape. Usage is only weakly implied by 'by id'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Active, resting and total calories per day over a date range. Merges active (metricId 22) and resting/BMR (metricId 23) series into [{calendarDate, active, resting, total}].
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description then adds genuine behavioral value by disclosing the return shape and, importantly, that the result is a merge of two distinct series (metricId 22 active and metricId 23 resting/BMR) â something the annotations and schema do not convey.
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 purpose front-loaded and the return contract second. No filler, and every clause carries information the caller needs.
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 no output schema present, the description compensates by specifying the exact returned structure `[{calendarDate, active, resting, total}]`. For a simple two-parameter read tool, an agent has everything needed to call and interpret it.
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% and both date parameters are fully documented in the schema (format and UTC semantics). The description only restates 'over a date range' without adding format, timezone, or boundary-inclusion detail, so 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?
States a specific resource (calories per day) with precise scope (active, resting, and total, over a date range), so an agent knows exactly what it retrieves. It does not explicitly differentiate itself from overlapping siblings like get_daily_stats or get_stats_and_body, which also surface daily calorie-adjacent data, so it stops short of a 5.
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?
There is no explicit when-to-use, when-not-to-use, or named alternative. Usage is only implied by the tool name and the 'over a date range' phrase; with many daily-stats siblings available, the agent gets no help routing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One saved course by id. GETs /course-service/course/{courseId}; a missing id is a 404 GarminHttpError ("Course not found : {id}").
| Name | Required | Description | Default |
|---|---|---|---|
| courseId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context beyond the structured fields: the underlying endpoint and, more usefully, the failure mode (a missing id yields a 404 GarminHttpError with a specific message).
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-loaded with the core purpose before the endpoint and error detail. Nothing is redundant and nothing needs trimming.
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 annotations covering safety, the description supplies purpose, endpoint, and error semantics. With no output schema, it could say a bit more about what a returned course contains, but nothing essential to correct invocation 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?
Schema description coverage is 100% ('Numeric id'), so the schema already documents the single parameter; baseline 3 applies. The description reinforces that the id targets one specific course and that an unmatched id errors rather than returning empty, but adds no format or type nuance.
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?
States a specific verb and resource with scope: 'One saved course by id', which implicitly contrasts with the plural list_courses sibling. It does not name list_courses or any other sibling explicitly, so differentiation is left to inference rather than stated.
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?
Usage is implied by the 'by id' scope â an agent needing a single known course rather than an enumeration would pick this over list_courses. However, there is no explicit when-to-use statement, no mention of the alternative, and no prerequisite or auth guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Your custom foods, optionally filtered by name (limit <= 20). Needs Connect+. GETs /nutrition-service/customFood with includeContent=true: {customFoods, moreDataAvailable}. limit is capped at 20 (Garmin 400s above it). There is NO get-by-id: GET /customFood/{id} is a 405, so search by name to read one back.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No | ||
| search | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld, but the description adds real behavioral context: a Garmin Connect+ subscription prerequisite, the limit cap of 20 that triggers a 400 above it, the 405 on GET /customFood/{id}, and the actual response shape {customFoods, moreDataAvailable}. These are non-obvious constraints that materially change invocation.
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?
Front-loads the precondition and scope, then the hard constraints, with the limit cap bolded for emphasis. It repeats the Connect+ requirement twice ('check with has_connect_plus' and 'Needs Connect+'), a minor redundancy that costs a point.
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 3-param, no-output-schema tool, the description covers auth preconditions, parameter constraints, error behaviors, the single-item read workaround, and the return shape. An agent has everything needed to call it correctly; only 'start' is left implicit.
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 0%, so the description carries the burden. It explains that search filters by name and that limit is hard-capped at 20, adding real meaning over the bare schema. The 'start' parameter (pagination offset) is never explained, leaving one gap.
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?
Names a specific verb+resource ('Your custom foods') and clearly distinguishes from the create_custom_food/update_custom_food/delete_custom_food siblings. An agent immediately knows this is a retrieval tool for the user's own custom food library.
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?
Gives explicit when-to-use context: check has_connect_plus first, and crucially the workaround 'There is NO get-by-id ... so search by name to read one back', which tells the agent exactly how to fetch a single item. This is actionable routing information beyond mere description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Serving units a custom food can use. Needs Connect+. GETs /nutrition-service/metadata/customFoodServingUnits (13 units).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower; the description still adds the subscription gating requirement and discloses the fixed result count (13 units) and endpoint. That is meaningful context beyond the annotations.
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 content is short but redundant: 'Requires a Garmin Connect+ subscription' and the trailing 'Needs Connect+' restate the same fact, and the raw endpoint adds little for an agent. Front-loading is acceptable but the repetition wastes the limited space.
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 parameterless metadata read with no output schema, the description supplies the essential gating (subscription check) and the nature of the return (a set of ~13 serving units). Nothing critical is missing for correct invocation.
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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No misleading parameter guidance is present.
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 the specific resource ('serving units a custom food can use') and the underlying endpoint, distinguishing it from siblings like get_custom_foods and create_custom_food. It is clear what is retrieved, though the phrasing is slightly clipped rather than a crisp verb+resource statement.
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 states a prerequisite (Garmin Connect+ required) and points to the has_connect_plus sibling to verify it, which is useful routing. However, it never explains when an agent should call this versus other nutrition metadata lookups, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The latest cycling functional threshold power (FTP). Latest value only; use getFunctionalThresholdPowerRange for history.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 'latest value only' scoping behavior, which is useful, but says nothing about what happens when no FTP exists or how the value is presented. Comparable to the calibration HIGH case, a 3 fits.
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, no waste, with the scoping constraint front-loaded before the sibling redirect. Every clause earns its place.
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 zero-param, read-only scalar lookup with annotations covering safety, the description captures both the resource and the correct alternative. The return is implicitly described ('the latest cycling FTP') though no output schema exists, leaving only minor room for error/none-recorded semantics.
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 takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface that the description needs to explain.
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?
States a specific verb (retrieve) and resource (latest cycling FTP), and explicitly distinguishes itself from the history sibling by declaring 'Latest value only'. An agent can tell it apart from get_functional_threshold_power_range without opening either schema.
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?
Explicitly names the alternative and the condition that selects it: 'use getFunctionalThresholdPowerRange for history.' Nothing is left to inference about when this tool is the right one versus the range variant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily hydration in milliliters, with the goal, over a date range; ranges over 31 days are chunked. GETs /usersummary-service/stats/hydration/daily/{start}/{end}: {calendarDate, valueInML, goalInML} per day that has an entry (the spec's sweatLossInML/activityIntakeInML were not seen). Garmin 400s end - start > 30 ("cannot be more than 31 days"), so longer ranges go in 31-day windows.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint/openWorldHint; the description adds real behavior: the versioned endpoint path, that results are sparse ('per day that has an entry'), and that Garmin returns 400 when end - start > 30, driving the chunking strategy. That error and sparsity disclosure materially exceeds what the annotations provide.
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?
Front-loaded with the core purpose, then supporting detail; nothing is padding. The parenthetical about sweatLossInML/activityIntakeInML is useful given no output schema, though the single dense run-on sentence is harder to scan than it needs to be.
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 no output schema, the description supplies the return shape ({calendarDate, valueInML, goalInML}), notes omitted spec fields, and documents the failure/chunking behavior. An agent can call this and interpret the response without further sources.
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 both dates are already documented, so the baseline is 3. The description earns a bump by defining the relationship constraint between start and end (max span of 31 days, chunk beyond that), which the schema itself does not express.
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?
States a specific resource and verb ('Daily hydration in milliliters, with the goal, over a date range') plus the underlying endpoint, so the agent knows exactly what data comes back. It does not explicitly contrast with the close sibling get_hydration_data, leaving that differentiation to inference.
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?
Gives operational guidance for the 31-day window constraint ('longer ranges go in 31-day windows') and the 400 failure mode, which tells the agent how to call it correctly. It never says when to prefer this over get_hydration_data or add_hydration_data, so usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-day calorie or step totals; ranges over 28 days are chunked. GETs /usersummary-service/stats/daily/{start}/{end}?statsType=CALORIES|STEPS; statsType is exactly "CALORIES" or "STEPS" (any other value, lower-case included, is a Garmin 404). Garmin 400s when end - start > 27, so longer ranges are fetched in 28-day windows and the rows concatenated; Garmin's per-request aggregations (averages) are DROPPED rather than returned wrong for a chunked range. A range with no data returns [] (Garmin answers null). Overlaps getDailySteps/getCaloriesDaily; this one returns total/actâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| statsType | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint, so the description carries the rest and does so richly: case-sensitive statsType causing a 404, Garmin 400s when end-start>27, automatic 28-day chunking with concatenated rows, dropped aggregations for chunked ranges, and [] for empty ranges. This is far beyond what annotations provide.
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?
Front-loads the purpose then packs dense, high-value API quirks (chunking, error codes, empty-range behavior) into tight sentences. Slightly dense, but nearly every clause earns its place given the tool's non-obvious behavior.
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?
No output schema exists, and the description covers return values ([] for no data vs Garmin's null) and the dropped aggregations, plus error behavior. For a quirky, open-world read tool this is complete enough for correct invocation.
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 documents start/end but leaves statsType with only an enum and no description. The description compensates by specifying statsType is exactly "CALORIES" or "STEPS" and that lowercase or other values yield a 404, adding real meaning beyond the enum.
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?
States a specific verb+resource: per-day calorie or step totals, with the statsType distinction. It also names the overlapping siblings (getDailySteps/getCaloriesDaily), but the differentiating clause is truncated ("this one returns total/actâĻ"), so the split from siblings is incomplete.
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?
Provides clear context: ranges over 28 days are auto-chunked and it names the alternatives it overlaps with. However the stated distinction from getDailySteps/getCaloriesDaily is cut off, so the agent can't fully resolve when to pick this one over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily step totals over a date range; ranges over 28 days are fetched in chunks. Auto-chunks ranges over Garmin's 28-day-per-request limit into â¤28-day windows and concatenates; a single request within the limit.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description does add genuinely useful operational context about 28-day chunking and concatenation, which the annotations cannot convey, but it says nothing about granularity, return shape, or empty ranges.
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?
Front-loaded with the core purpose, but the second sentence largely restates the first: 'ranges over 28 days are fetched in chunks' and 'Auto-chunks ranges over Garmin's 28-day-per-request limit into â¤28-day windows and concatenates' convey the same fact twice.
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 two-parameter read-only tool with no output schema and full schema coverage, the description is nearly sufficient, and the chunking disclosure is a meaningful addition. It only falls short on describing what a daily total record contains or how missing days are handled.
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%, with both parameters documented as YYYY-MM-DD UTC dates, so the schema carries the parameter burden. The description adds no format or constraint detail beyond what the schema already provides, making the baseline 3 correct.
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?
States a specific verb and resource: daily step totals over a date range. However, it never distinguishes itself from close siblings like get_steps_data or get_weekly_steps, leaving the agent to infer which step-retrieval tool applies.
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?
No when-to-use or when-not-to-use guidance is given, and no alternative is named despite multiple step-related siblings. The date-range framing only weakly implies usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily stress level and time at each stress level over a date range; ranges over 28 days are chunked. GETs /usersummary-service/stats/stress/daily/{start}/{end}: {calendarDate, values: {overallStressLevel, restStressDuration, lowStressDuration, mediumStressDuration, highStressDuration}} per day, durations in seconds. Garmin 400s end - start > 27 ("cannot be more than 28 days"), so longer ranges go in 28-day windows; a reversed range throws GarminError before any request.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavioral traits beyond annotations: ranges over 28 days are automatically chunked, Garmin returns a 400 error when end - start > 27, and a reversed range throws GarminError before any request. Also details the exact response shape, which is valuable given no output schema.
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?
Front-loaded with purpose, then endpoint and response shape, then error/chunking behavior. Dense but every sentence adds value; could be slightly improved with bullet points, but no wasted words.
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?
Complete for a read-only tool with no output schema: it explains the response structure, error conditions, and chunking behavior. Annotations cover safety (readOnlyHint), and the description fills in operational details.
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 baseline is 3, but the description adds meaning: start must be before end (reversed range throws), and ranges longer than 28 days are chunked into 28-day windows. These are important parameter-order and range semantics not captured in 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?
States a specific verb (get) and resource (daily stress level and time at each stress level) over a date range, with clear per-day output fields. It implies daily granularity, distinguishing it from weekly or all-day siblings, but does not explicitly name those 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?
Provides implicit usage context (date range, 28-day chunking) but offers no explicit guidance on when to use this tool versus siblings like get_all_day_stress, get_stress_data, or get_weekly_stress. 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.
One whole-day summary per day: steps, calories, heart rate, stress, Body Battery, SpO2 and more. Ranges over a year are chunked. GETs /usersummary-service/v2/dailysummaries?startDate&endDate and unwraps data: one object per day grouped by topic (movement, calories, heartRate, intensityMinutes, stress, bodyBattery, hydration, respiration, pulseOx, jetLag), typed from PersonalApi.UserDailySummaryV2DTO. Garmin caps one request at a year ("must be P1Y or less": a 365-day span passes, 366 is a 400), so longer ranges go in 365-day windows. Days with no data are ABSENT, notâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the upstream endpoint, that long ranges are chunked into 365-day windows, the exact cap semantics ('must be P1Y or less': 365 passes, 366 is a 400), and that missing days are ABSENT rather than zero/null. That chunking and empty-vs-missing distinction is precisely the behavior an agent cannot derive from annotations.
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?
Front-loaded with the resource and metric list, then progressively technical detail. It is dense and every clause carries information, but the trailing sentence is truncated mid-thought ('Days with no data are ABSENT, notâĻ'), signaling missing or awkwardly packaged 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?
With no output schema, the description does the work of explaining returns: unwrapped `data`, one object per day, grouped by named topics, typed from UserDailySummaryV2DTO. That is unusually complete for a read tool, though the cut-off sentence leaves the empty-day semantics unfinished.
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 start/end semantics and the YYYY-MM-DD (UTC) format are already documented in the schema. The description adds the date-span constraint but nothing new about the parameters themselves, so the baseline 3 applies.
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?
States a specific verb+resource ('one whole-day summary per day') and enumerates exactly which metrics it bundles (steps, calories, heart rate, stress, Body Battery, SpO2), which distinguishes it from the many single-metric siblings like get_daily_steps or get_body_battery. An agent can tell this is the aggregate per-day read rather than a per-metric one.
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?
Usage context is implied through the year-cap and chunking behavior, which tells the agent how to invoke it for long ranges. However, it never explicitly contrasts itself with the many overlapping siblings (get_daily_stats, get_daily_steps, get_spo2_data), so the agent must infer when to pick this aggregate over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every weigh-in recorded on one date. GETs /weight-service/weight/dayview/{cdate}?includeAll=true.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavior beyond that: the `includeAll=true` query flag signals that no weigh-ins are filtered out, and the endpoint path confirms it is a pure read against the weigh-in day view. It stops short of covering return shape, ordering, or empty-result behavior.
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, front-loaded sentences with no filler; the scope statement comes first. The raw URL template is borderline noise the agent can't act on, which keeps it out of 5 territory.
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 whose annotations cover safety, the essentials are present, but there is no output schema and the description does not characterize what a weigh-in record contains or what happens when no weigh-ins exist on the date. That leaves the return contract unspecified.
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 cdate is fully documented as YYYY-MM-DD UTC in the schema, so the schema carries the load. The description's only contribution is restating the placeholder as `{cdate}` in the URL, adding no new semantics such as timezone handling or the meaning of the returned date bucket.
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?
States a specific verb+resource scope: all weigh-ins recorded on exactly one date, which implicitly distinguishes it from get_weigh_ins (range) and the add_/delete_ weigh-in siblings. It never names an alternative sibling, so the differentiation is only inferable from the singular-date scoping.
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?
No when-to-use or when-not-to-use guidance, and no prerequisite or alternative is named. The reader must infer from 'one date' that get_weigh_ins is the range counterpart; nothing in the text routes the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every alarm configured on every registered device. No HTTP path of its own: calls getDevices() once, then getDeviceSettings(device.deviceId) once per device (N+1 fan-out, sequential by design; do not parallelize), concatenating each device's alarms; a device with no alarms contributes nothing, never throws for that case.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations: discloses the N+1 fan-out pattern, that it is sequential by design and must not be parallelized, and that a device with no alarms contributes nothing and never throws. This is exactly the kind of performance and error-handling context annotations cannot carry.
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?
Single front-loaded sentence that leads with the outcome, then layers in the mechanism. Dense with semicolons but every clause (fan-out, sequential, empty-device handling) earns its place.
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?
No output schema exists, so the description carries the return-value burden; it explains the result is each device's `alarms` concatenated, though it does not describe the shape of an individual alarm object. For a zero-param aggregate tool the behavioral coverage is otherwise strong.
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?
Zero parameters, so there is nothing to document and the baseline is 4. The description correctly implies the tool takes no input and operates over all registered devices.
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?
States a specific resource and scope: 'Every alarm configured on every registered device.' An agent can tell this is an aggregate/roll-up tool distinct from get_devices (devices) and get_device_settings (one device's settings), even though it doesn't name those siblings as 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?
Usage is implied rather than stated. It explains it has no HTTP path of its own and aggregates across devices, from which an agent can infer 'use this when you want all alarms across devices,' but there is no explicit when-to-use vs get_devices/get_device_settings routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The device used most recently. Also used internally by pushWorkoutToDevice to resolve a missing deviceId.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context of its own â no indication of what the returned device object contains, whether it requires an authenticated user, or what happens when no device has ever been used.
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 very short sentences with the primary purpose front-loaded. The second sentence about internal use is borderline â it serves the agent somewhat by signaling this is an implementation helper, but it reads as leakage from another tool's code rather than agent-facing 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 zero parameters and no output schema, the description is the only place an agent could learn the shape of the return value (a device record with id/name/etc.), and it does not provide that. Annotations cover safety, but the missing return-value context leaves a real gap for a lookup tool.
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 takes zero parameters, so there is nothing for the description to clarify. The 4 baseline applies: no ambiguity is introduced and no parameter semantics are needed.
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 the exact resource returned ('the device used most recently'), which distinguishes it implicitly from the sibling get_primary_training_device (a different concept). It lacks an explicit verb (e.g., 'Returns/Retrieves'), making it a fragment rather than a full purpose statement, but an agent can still infer the tool's contract.
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?
There is no explicit guidance on when an agent should call this versus get_devices or get_primary_training_device. The note that it is 'used internally by pushWorkoutToDevice' describes another tool's implementation, not a decision rule the agent can apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every device registered to the account. Undocumented per-device shape, deviceId is the field the other device methods key off of.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious output context: the per-device shape is undocumented and `deviceId` is the keying field for downstream device methods. It does not mention result count, pagination, or whether empty accounts return an empty list, but the shape caveat is valuable.
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, no filler, with the resource identification front-loaded and the actionable `deviceId` tip immediately after. Every clause earns its place.
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?
No output schema exists, so the description carries the return-value burden, and it does flag that the per-device shape is undocumented while naming the one field that matters (`deviceId`). That is the right information for a zero-param read tool; a rough sense of the collection (array, count) would make it 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?
The tool takes zero parameters, so the baseline is 4 and there is no schema content for the description to duplicate or compensate for. Nothing about input is ambiguous or missing.
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?
States a clear verb-and-resource: it returns every device registered to the account. An agent can distinguish it from the many get_device_* siblings (alarms, settings, solar data, last used), which each target a single aspect. It lacks any explicit statement that it is the enumerating/lookup counterpart to those, but the resource is 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?
No explicit when-to-use or when-not-to-use guidance. The note that `deviceId` is 'the field the other device methods key off of' implicitly routes the agent here first to obtain IDs, which is useful but indirect. Alternatives such as get_primary_training_device or get_device_last_used are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One device's settings, by the deviceId from getDevices. deviceId coerced to an int, validated positive, re-stringified before being placed in the path Two-call sequence: get a deviceId from a getDevices() entry first, then pass it here.
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, yet the description adds genuine behavioral detail beyond them: deviceId is coerced to an int, validated positive, and re-stringified into the path. That input-processing behavior is non-obvious and useful.
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?
Front-loaded with the core purpose, but the sentence 're-stringified before being placed in the path Two-call sequence' has a run-on/missing-punctuation seam that mildly hurts readability. Content is dense with no real waste.
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 read tool whose safety profile is carried by annotations, the description covers the prerequisite sequencing and input handling adequately. It omits what the returned settings contain, but with no output schema this is a minor gap.
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 raw type is documented, but the description adds meaning beyond the schema's terse 'Numeric id': it tells the agent the value originates from a getDevices() entry and how it is transformed before being placed in the path.
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?
States a specific verb ('get') and resource ('one device's settings'), keyed by the `deviceId` read from `getDevices`. This distinguishes it from siblings like get_devices (listing) and get_device_alarms, though it doesn't explicitly name those siblings.
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?
Explicitly prescribes the calling sequence: 'get a `deviceId` from a `getDevices()` entry first, then pass it here,' naming the prerequisite tool. This is clear context, though it stops short of stating when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A solar device's charging input for a date or a date range (enddate defaults to startdate). The only raising method in this group: throws GarminConnectionError if the response is falsy or missing the deviceSolarInput key; returns resp.deviceSolarInput, NOT the envelope. enddate defaults to startdate, and singleDayView is sent "true" exactly when enddate was omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| deviceId | Yes | Numeric id | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a read-only, open-world operation, but the description adds substantial behavioral detail: it raises GarminConnectionError on falsy or missing key responses, returns the inner deviceSolarInput object rather than the full envelope, and explains the default and singleDayView flag behavior. This goes well beyond what annotations cover.
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 front-loaded with the purpose and packs useful behavioral details efficiently. However, it repeats the fact that enddate defaults to startdate twice, which is slightly redundant. Overall it remains compact and informative.
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 no output schema, the description adequately explains the return value (resp.deviceSolarInput) and error conditions. It does not detail the internal structure of deviceSolarInput, but for a read tool with full schema coverage and clear annotations, this is largely sufficient.
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 schema already documents parameter types and formats. The description adds value by specifying that enddate defaults to startdate and explaining the implicit singleDayView parameter, which is not in the schema. This clarifies behavior without duplicating schema details.
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 (a solar device's charging input) and its scope (a date or date range). It is a noun phrase rather than a verb-led statement, but the purpose is unambiguous. It does not explicitly differentiate from siblings, though the tool is unique in the group.
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 implies usage by stating it retrieves data for a date or date range, but gives no explicit when-to-use guidance or alternatives. No sibling tool overlaps in functionality, so the implied context is somewhat sufficient, but the lack of direct guidance keeps it at baseline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Badges the account has earned, each with badgeImageUrls added. GETs /badge-service/badge/earned; each badge gains badgeImageUrls: { small, large }, added by this library (Garmin sends no image URL): https://connect.garmin.com/images/badges/xxhdpi/badge_<badgeUuid ?? badgeId>_sml.png (_lrg.png for large), the URL Garmin Connect's web app builds; public, no session. Every other field passes through unchanged; stays nullable (does NOT coalesce to []).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the underlying endpoint, that the call is public with no session required, that the library injects a computed badgeImageUrls field (with the exact URL template), and that every other field passes through unchanged and stays nullable rather than coalescing to []. This is exactly the kind of behavioral context annotations cannot carry.
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?
Front-loaded with the resource and scope, then the behavior. Dense and mostly earns its words, though the full URL template is heavier than strictly necessary and slightly crowds the sentence flow.
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 no output schema, the description fully carries the return-value burden: it names the injected field, its shape, its provenance, and the nullability rule, and notes all other fields are untouched. Nothing an agent needs to interpret the result 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 takes zero parameters, so there is nothing to document and the baseline is 4. The description appropriately spends its words on return-shape semantics instead.
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?
States a specific resource with a scoping qualifier: 'Badges the account has earned.' The word 'earned' cleanly separates it from siblings like get_available_badges and get_in_progress_badges, so an agent can place it without opening any schema.
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?
Usage is implied by 'earned' versus the available/in-progress badge siblings, but the description never explicitly says when to use this over those alternatives or names any of them. Adequate but leaves the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Endurance score for a date, or weekly aggregates over a date range. TWO branches by presence of enddate: no enddate hits the single-day endpoint; with enddate hits .../stats with hard-coded aggregation="weekly".
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, open-world profile, but the description adds real behavioral detail: the range branch is hard-coded to aggregation="weekly", so the agent knows it cannot request daily values across a range. That is a genuinely useful constraint beyond the structured fields.
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, front-loaded with the output shape and then the branching rule, with zero filler. Every clause carries actionable 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 no output schema, the description does state what comes back (endurance score / weekly aggregates) and how the two modes differ, which is the core need. It omits whether the metric requires a subscription tier and what the returned fields/units look like, leaving a small gap.
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 baseline is 3, but the description goes further by explaining that merely the presence of `enddate` switches the underlying endpoint and forces weekly aggregation â semantics the schema (two plain date strings) does not convey.
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?
States the resource (endurance score) and the two granularities it can return (single day vs. weekly aggregates), which clearly separates it from sibling metrics like get_hill_score, get_running_tolerance, or get_fitness_age_data. It doesn't name a sibling to route against, but the verb+resource+scope is 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?
Explicitly tells the agent how to select between the two modes: omit `enddate` for a single day, include it for a range. That is concrete conditional guidance rather than implied usage. It stops short of naming alternatives when the agent wants raw daily data over a range.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fitness age for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context such as data freshness, whether the metric is computed or stored, or what the response contains. It does not contradict the annotations, but it adds essentially nothing beyond them.
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 extremely concise, with no wasted words, and the scope is front-loaded. It is a fragment rather than a structured sentence, but it is appropriately sized for a simple one-parameter getter.
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 simple read-only tool with one fully documented parameter, the description is minimally sufficient to invoke correctly. However, with no output schema and no explanation of what 'fitness age' represents or what fields are returned, it leaves a gap that a slightly fuller description could close.
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%: the single required parameter cdate is documented as 'Calendar date, YYYY-MM-DD (UTC)'. The description's phrase 'for one date' aligns with the schema but adds no syntax or format detail beyond it, so the baseline of 3 applies.
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 resource ('fitness age') and scope ('for one date'), which is enough to distinguish it from sibling tools like get_activities or get_sleep_data. It lacks an explicit verb, but the tool name supplies 'get', and the metric is 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?
There is no guidance on when to use this tool versus alternatives, nor any exclusions. It does not say whether a range-based sibling exists, whether this is suitable only for a single known date, or what to do for multi-date queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Floors climbed and descended for one date. Throws GarminError if Garmin returns nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that a GarminError is thrown when Garmin returns no data, which is real behavioral context beyond the annotations, but it says nothing about the shape or units of the returned floor count.
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-loaded with the metric and scope, with the error behavior appended. No filler or redundant restatement of the tool name.
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 read-only metric tool with full annotation coverage and full schema coverage, the description covers the essential what and an error case. The only minor gap is the absence of any hint about the return value's shape, though no output schema exists to carry that.
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 cdate parameter is fully documented as YYYY-MM-DD (UTC) in the schema itself. The description only implies a date scope without adding format or timezone detail, 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 names the specific metric (floors climbed and descended) and its scope (one date), so an agent can tell it apart from unrelated tools. It does not, however, differentiate itself from the many closely related daily-metric siblings such as get_daily_steps or get_calories_daily.
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?
There is no explicit when-to-use guidance, no prerequisites, and no mention of alternative tools for retrieving daily metrics. Usage must be inferred entirely from the tool name and the single required date parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Functional threshold power (FTP) history for a sport over a date range. Defaults sport="RUNNING", aggregation="daily"; sport upper-cased and validated (^[A-Z_]+$); aggregation restricted to {daily,weekly,monthly,yearly}.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| sport | No | ||
| start | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| aggregation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds real behavioral detail beyond them: default values for sport and aggregation, automatic upper-casing, regex validation (^[A-Z_]+$), and the closed set of aggregation values. It still says nothing about output shape (e.g. whether values are watts), but for an annotated read tool this is solid.
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 packed sentences: purpose and scope first, then defaults and constraints. No filler, no repetition of the tool name, and every clause carries information an agent needs to call the tool correctly.
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 read-only tool with no output schema and four simple parameters, the description covers purpose, scope, defaults, and validation. The remaining gaps are the relationship to the cycling-FTP and power-zone siblings and any note on unit or response shape, which are minor but would help selection.
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 only 50% (sport and aggregation have no schema descriptions), and the description compensates by supplying their defaults, the upper-casing rule, the validation regex, and the allowed aggregation values. Start/end semantics (YYYY-MM-DD UTC) live in the schema and are not duplicated, which 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 gives a specific verb+resource ('FTP history for a sport over a date range'), which is far more informative than the name alone and makes clear this is a read of a time-series metric. It does not, however, distinguish itself from siblings such as get_cycling_ftp or get_lactate_threshold, which an agent could plausibly pick instead.
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 states the required date range and the defaults for sport/aggregation, but never says when to prefer this tool over get_cycling_ftp, get_power_zones_for_sport, or get_lactate_threshold, nor what happens if the date range is unbounded. The agent must infer selection from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every piece of gear on the account. userProfileNumber is the profile's numeric id. Hits /gear-service/gear/filterGear?userProfilePk=...; returns an ARRAY of gear entries, verified live. This is the dedicated gear-CRUD service, distinct from getActivityGear (activities service, reuses the same base URL with activityId instead).
| Name | Required | Description | Default |
|---|---|---|---|
| userProfileNumber | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value beyond that: the concrete return shape ('returns an ARRAY of gear entries'), the underlying endpoint, and that the behavior is 'verified live'. It does not mention pagination or failure modes, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences, each carrying distinct information (scope, parameter meaning, return/endpoint, and sibling disambiguation). The raw endpoint URL is marginally indulgent but not wasteful; nothing is redundant.
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 read-only, single-parameter tool, the description supplies the return type in lieu of an absent output schema, the parameter meaning, and sibling routing. Complete enough to invoke correctly; only the provenance of the profile id is left implicit.
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 0% (the property is an undocumented integer|string), so the description must carry the meaning. It does: 'userProfileNumber is the profile's numeric id', and it maps that parameter to the query binding userProfilePk. It stops short of saying where to obtain the id or whether the string form is accepted, so not a 5.
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?
States a specific resource and scope ('Every piece of gear on the account') and explicitly differentiates itself from the sibling `get_activity_gear`. An agent can tell what it returns and how it differs from the activity-scoped gear lookup without opening either schema.
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?
Gives clear routing context by naming the alternative gear-fetch tool and the condition that selects it ('dedicated gear-CRUD service, distinct from getActivityGear ... with activityId instead'). However it does not address other gear siblings such as get_gear_stats, get_gear_defaults, or get_gear_activities, so the exclusion set is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activities that used a piece of gear (limit capped at 1000); [] if it is unknown. limit clamped to 1000; returns [] on a 404 instead of throwing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| gearUUID | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that: limit is clamped/capped at 1000, returns [] for unknown gear, and returns [] on a 404 instead of throwing. This error-handling and edge-case disclosure is exactly what annotations don't provide.
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?
Very short and front-loaded, leading with what is returned. The 1000 cap is stated three times ('capped at 1000', 'clamped to 1000'), which is minor redundancy but doesn't obscure the 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?
There is no output schema, so the description should ideally convey the return shape, which it does not beyond '[]'. Error handling is well covered, but pagination semantics (limit without offset) and returned fields are left unstated for a tool whose only output documentation is the empty-array case.
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 0%, so the description must carry the load. It meaningfully documents `limit` (clamped at 1000) but only implicitly identifies `gearUUID` via 'a piece of gear', adding no format or source detail. Partial compensation for the coverage gap, so a mid score.
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?
States a specific resource and relation: 'Activities that used a piece of gear'. An agent can tell this returns activities, not gear metadata. However it doesn't distinguish itself from close siblings like get_gear, get_gear_stats, or get_activity_gear, which could be confused for the same purpose.
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?
No guidance on when to call this versus get_gear_stats, get_gear, or get_activity_gear. The only usage-flavored hint is the 404 behavior, which describes runtime behavior rather than selection criteria. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which gear is the default for which activity types. GETs /gear-service/gear/user/{userProfileNumber}/activityTypes; returns an ARRAY of {uuid, activityTypePk, defaultGear} entries, verified live.
| Name | Required | Description | Default |
|---|---|---|---|
| userProfileNumber | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnlyHint and openWorldHint, and the description goes beyond them by naming the exact upstream endpoint and, importantly, disclosing the return shape (an array of {uuid, activityTypePk, defaultGear}) even though no output schema exists. It stops short of noting pagination, auth requirements, or error behavior.
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, purpose front-loaded, followed by the endpoint and return contract. The raw endpoint string is slightly noisy but it conveys method and path structure worth keeping.
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 no output schema, the description usefully documents the returned array entries, which is the key missing context. It leaves some gaps (what `defaultGear` contains, behavior when no default is set, pagination), but is complete enough for a single-parameter read tool.
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 0% for the single userProfileNumber parameter, so the description carries the burden. It partially compensates by embedding the parameter in the URL template `${userProfileNumber}`, clarifying it is the user's profile identifier, but it never states accepted formats or whether an ID vs. a string identifier is expected.
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?
States a specific verb+resource pair: reading which gear is the default for which activity types. An agent can distinguish it from get_gear, get_gear_activities, and get_gear_stats from the description alone, though it never explicitly names set_gear_activity_defaults as the write-side counterpart.
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?
Usage is implied by the purpose (fetch per-activity-type default gear), but there is no explicit when-to-use, when-not, or routing to alternatives such as get_gear_activities or set_gear_activity_defaults. Adequate for a simple getter but no real guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Usage totals for one piece of gear; {} if it is unknown. GETs /gear-service/gear/stats/{gearUUID}; gearUUID validated via validateUuid (hex, hyphens optional); returns {} on a 404 instead of throwing; other errors re-raised.
| Name | Required | Description | Default |
|---|---|---|---|
| gearUUID | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world behavior, and the description adds genuinely useful error semantics beyond that: `{}` returned on 404 rather than throwing, other errors re-raised, and the validation applied to the UUID. That is meaningful disclosure an agent cannot get from the annotations alone.
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?
Compact and front-loaded: the outcome (usage totals, `{}` when unknown) comes first, followed by the mechanism and error handling. No padding, though the backtick-heavy style is a bit dense to read.
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 no output schema, the description takes on the job of describing the return value, and it does so (`{}` on unknown/404, otherwise usage totals). The only real gap is the absence of any routing guidance among the many gear-related siblings.
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 0%, so the description carries the parameter burden, and it does: `gearUUID` is validated via `validateUuid` with hex characters and optional hyphens. The exact accepted format is specified, which the bare string-typed schema does not convey.
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?
States a specific resource and outcome: usage totals for one piece of gear. That clearly separates it from siblings like get_gear (gear records) and get_gear_activities (activities tied to gear), though it never explicitly names an alternative.
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?
There is no when-to-use or when-not-to-use guidance, and no mention of alternatives like get_gear or get_gear_activities. The reader can infer you call it with a known gearUUID, but nothing distinguishes the situations where this tool is the right pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's goals with a given status (active, future or past), every page fetched. Sends the Sec-Fetch-Site: same-origin header Garmin needs to return newer goal types. Defaults status="active", **start=1**, limit=30. start defaults to 1, NOT 0, because goal-service is 1-INDEXED and start=0 silently returns []; throws GarminError before any request for an invalid status. Paginated, multi-call: starting at start, fetches successive pages of limit entries (incrementing start by limit each call) until a page comes back empty/falsy, same fixed-page-size pattern as `geâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the readOnly/openWorld annotations: it discloses the Sec-Fetch-Site: same-origin header requirement, the paginated multi-call contract (increment start by limit until an empty page), the 1-indexed start quirk, and that GarminError is thrown before any request for an invalid status. This is exactly the kind of non-obvious behavior an agent needs.
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?
Information-dense and front-loaded, but there is redundancy ('Defaults start=1' restated as 'start defaults to 1, NOT 0...') and the text is truncated mid-sentence ('same fixed-page-size pattern as `geâĻ'), indicating it is over-length rather than tightly scoped.
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?
No output schema exists, and the description covers retrieval semantics, header handling, pagination, and error behavior thoroughly. The one gap is the truncated trailing comparison, which leaves the pagination explanation incomplete.
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 0%, so the description carries the full burden and does: it gives defaults for all three parameters (status, start, limit), explains that start is 1-indexed and that start=0 silently yields [], and ties the enum values to the status filter. All parameters gain meaning beyond the bare 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?
States a specific resource (the account's goals) and a specific filter dimension (status: active/future/past), plus the scope 'every page fetched'. An agent immediately understands what it retrieves. It does not need to differentiate from a sibling since no other goals tool exists, so 4 rather than 5.
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?
Explains the defaults (status='active', start=1, limit=30) and how the multi-call pagination loop should be driven, which is actionable guidance. It provides no explicit when-not-to-use, but with no competing sibling there is little to exclude.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-club golf stats. Defaults limit=1000; validated positive; GETs /gcs-golfcommunity/api/v2/club/player; hyphenated query params per-page and include-stats (literal "true"). An ARRAY, verified live: the test account returned a JSON ARRAY of 17 club entries ({id, clubTypeId, shaftLength, flexTypeId, averageDistance, adviceDistance, retired, deleted, lastModifiedTime}), not a single object.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnlyHint and openWorldHint, but the description adds substantial non-annotation context: the default limit=1000, that limit is validated positive, and critically that the response is a JSON ARRAY (verified live) with an explicit field list rather than a single object. The endpoint path and hyphenated query-param details are lower value for an agent but do not contradict the annotations.
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 purpose sentence is properly front-loaded, and the array-shape warning earns its place. But the middle clause packs low-level HTTP implementation detail (endpoint path, hyphenated query params, literal "true") that is not actionable for tool selection or invocation, adding noise to an otherwise tight definition.
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 no output schema, the description correctly compensates by disclosing the return shape (an array of club entries with named fields), and annotations already cover the read-only/open-world safety profile. For a 1-param read tool this is close to complete; only error/timeout behavior is left unaddressed.
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 0% for the single 'limit' parameter, so the description carries the burden â and it does: it gives the default (1000) and states the value is validated positive. That is meaningful semantics beyond the bare number type in the schema, though it omits units/upper bounds.
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?
States a specific resource with a scope qualifier ('Per-club golf stats'), which is enough to separate it from the sibling golf tools (get_golf_user_stats, get_golf_summary, get_golf_shot_data, get_golf_scorecard) since 'per-club' scopes it to club-level data. However, it never explicitly names those alternatives, so differentiation is left to inference.
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?
There is no when-to-use/when-not guidance and no mention of any alternative tool. The agent must infer from 'per-club' that this is the club-breakdown variant rather than the user- or shot-level stats. Nothing routes the agent between this and the other get_golf_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One golf scorecard in full. GETs /gcs-golfcommunity/api/v2/scorecard/detail; hyphenated query params scorecard-ids and include-longest-shot-distance (sent as the literal string "true").
| Name | Required | Description | Default |
|---|---|---|---|
| scorecardId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the description's job is lighter. It adds useful implementation detailâthe endpoint path and the quirky hyphenated query params with the literal "true" stringâbut says nothing about return shape, pagination, or error behavior.
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 with the core purpose front-loaded and implementation quirks relegated to the second. Terse and free of filler, though the API-path detail is only marginally useful to a caller.
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-param, read-only tool this is minimally adequate. With no output schema, the description could have said something about what a scorecard contains or how much data returns, leaving a small gap for the agent.
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 (scorecardId, "Numeric id") is already documented, so the schema carries the load. The description's mention of hyphenated query params does not correspond to any agent-facing input, adding little about how to supply scorecardId.
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?
States the resource (one golf scorecard) and its scope ("in full"), which distinguishes it from summary/stats siblings like get_golf_summary and get_golf_club_stats. The retrieval verb is only implied rather than stated, and no sibling is named explicitly.
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?
There is no when-to-use guidance, no exclusions, and no reference to alternatives such as get_golf_summary or get_golf_shot_data. An agent must infer that this is the tool for fetching a single known scorecard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shot data for a scorecard, optionally for some holes only (e.g. "1,2,3"). GETs /gcs-golfcommunity/api/v2/shot/scorecard/{scorecardId}/hole; holeNumbers accepts commas or hyphens as separators (spaces stripped), re-joined with - before sending as the hyphenated hole-numbers param; if any requested hole number is >9, the filter is silently dropped and all 18 holes are requested instead (Garmin's endpoint drops double-digit hole numbers from a filtered query); omitting holeNumbers also fetches all 18.
| Name | Required | Description | Default |
|---|---|---|---|
| holeNumbers | No | ||
| scorecardId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint and openWorldHint in annotations, the description goes well beyond the safety profile: it discloses the underlying GET path, the separator normalization (commas/hyphens accepted, spaces stripped, re-joined with '-'), and the critical quirk that any requested hole number >9 silently drops the filter and returns all 18 holes. That silent-failure disclosure is exactly the kind of hidden behavior an agent cannot infer from structured fields.
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?
Purpose and the holeNumbers example are front-loaded, and every clause carries real information â the endpoint path is the only near-decorative element. The back half is a dense run-on with parenthetical asides and bold, but the density is justified by the edge cases it encodes.
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?
There is no output schema, so the description ideally would say something about what 'shot data' contains (club, distance, accuracy, etc.); it only names the resource. Everything an agent needs to construct a correct request, including the silent filter-drop trap, is present, so the gap is limited to return-shape expectations.
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 50% and holeNumbers has no schema description at all, so the description carries the burden and does so thoroughly: accepted formats ('1,2,3'), separator flexibility, normalization behavior, and the >9 coercion rule. scorecardId is left as a plain numeric id, but it is trivial and already annotated 'Numeric id' in 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 specific resource and scope: 'Shot data for a scorecard, optionally for some holes only', which is a concrete verb+resource pair an agent can act on. It is clearly distinct from siblings like get_golf_scorecard or get_golf_club_stats, though it never names or contrasts those alternatives explicitly, which keeps it out of the top band.
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?
Usage context is implied rather than stated: passing holeNumbers narrows the fetch, omitting it fetches all 18. There is no explicit guidance on when to prefer this tool over get_golf_scorecard or the other golf siblings, nor any stated prerequisites (e.g. needing an existing scorecardId). Adequate but with a clear routing gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A page of golf scorecard summaries. Defaults start=0, limit=100; start validated non-negative, limit validated positive (throws GarminError otherwise); query params are literally hyphenated (per-page, start), matching Garmin's own naming. An OBJECT, not an array, verified live: the test account (0 rounds recorded) returned a single pagination-envelope OBJECT {pageNumber, rowsPerPage, totalRows}, not an array.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes further and discloses non-obvious behavior: default start/limit values, validation rules that throw GarminError, and the verified fact that the response is a pagination-envelope OBJECT rather than an array. This is genuinely useful disclosure beyond the annotations, though it mentions a `per-page` param that does not appear in the schema, which adds minor confusion.
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?
Purpose is front-loaded in the opening clause, and most of the material is information-dense rather than filler. The second half is a long run-on clause stack with parentheticals, so a minor deduction for readability, but little is truly expendable.
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 no output schema, the description correctly shoulders the return-value burden by describing the pagination envelope, and it covers both undocumented parameters. It stops short of saying what fields a scorecard summary row actually contains, so an agent knows the shape of the envelope but not its payload.
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 0%, so the description must carry parameter meaning, and it largely does: it gives defaults (start=0, limit=100) and validation semantics (start non-negative, limit positive, throws on violation). The only gap is that it never states what limit/start physically control beyond pagination offset/count, and the hyphenated `per-page` reference does not map to the schema's `limit`.
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 first clause names a concrete resource ("a page of golf scorecard summaries") and implies the paginated-list verb, so an agent knows it returns summary records. However, it never differentiates itself from close siblings like get_golf_scorecard, get_golf_user_stats, or get_golf_club_stats, leaving the agent to guess which golf resource this is.
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?
There is no when-to-use guidance, no prerequisite conditions, and no routing to alternative golf tools. The description explains implementation mechanics (defaults, validation) but never tells the agent under what circumstances this tool is the right choice versus its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Golf handicap and strokes-gained overview. GETs /gcs-golfcommunity/api/v2/player/stats; handicap and strokes-gained overview, no params.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that no params are needed and names the endpoint path, which is minor added context, but does not disclose return format, caching, or auth requirements.
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 clauses, but the opening sentence is essentially restated in the second clause ('handicap and strokes-gained overview' appears twice), making it redundant rather than fully 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 zero-param read tool with annotations covering safety, the description is minimally adequate. However, with no output schema present, the description could say more about what the overview returns (format, fields, pagination) to help an agent decide whether to call it.
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?
Zero parameters, so the baseline is 4. The description correctly notes 'no params', confirming the schema's empty object. No parameters exist whose semantics could be clarified further.
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?
States a specific resource and scope: 'Golf handicap and strokes-gained overview'. The verb is implied rather than explicit, but the resource and domain are clear enough. It is distinguishable from siblings like get_golf_club_stats or get_golf_summary, though it doesn't explicitly contrast with them.
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?
Implies usage by describing the content (handicap and strokes-gained) and noting 'no params', but offers no explicit when-to-use or when-to-prefer-an-alternative guidance despite multiple golf-related siblings like get_golf_club_stats, get_golf_shot_data, and get_golf_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Heart-rate samples plus resting, min and max heart rate for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful content about returned values (samples plus resting, min and max), but does not disclose pagination, rate limits, or response format beyond what annotations and schema imply.
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?
A single, front-loaded sentence with no wasted words. It efficiently communicates the main return content and scope.
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?
No output schema exists, so the description must characterize return values; it does so by naming sample-level data and resting/min/max summaries. Some detail about sample granularity or response shape is absent, but for a simple single-date read it is close to 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?
Schema description coverage is 100% and the single parameter is fully documented as a YYYY-MM-DD UTC date. The description adds no additional meaning beyond what the schema already provides, so 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?
States a specific resource (heart-rate samples plus resting, min and max heart rate) and scope (one date). It is clear what the tool returns, but it does not explicitly name or contrast with siblings such as get_heart_rate_zones or get_rhr_daily.
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 no when-to-use guidance or alternatives. It implies retrieval for a calendar date but does not explain when to choose this tool over other heart-rate or resting-heart-rate siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Heart-rate zone profiles: DEFAULT plus any per-sport ones.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds return-content context (DEFAULT plus per-sport profiles), but nothing about auth, whether an empty result is possible when zones are unconfigured, or how profiles are structured. Useful but thin addition over the annotations.
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?
A single short fragment with zero padding, and the most important fact (that multiple profiles are returned) is front-loaded. It is arguably too terse to serve as a full definition, but nothing in it is wasted.
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 no output schema and no parameters, the description is the only place an agent can learn what comes back, and it only sketches that (DEFAULT plus per-sport profiles) without describing zone boundaries or what a profile contains. Adequate to recognize the tool, but not complete for an output-bearing read.
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 takes zero parameters, so there is no parameter semantics for the description to carry; the baseline for a 0-param tool is 4. The schema simply enforces an empty object with additionalProperties=false.
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 specific resource (heart-rate zone profiles) and scopes its contents as DEFAULT plus per-sport profiles, which tells an agent what it will get without opening a schema. It lacks an explicit verb, but combined with the name the intent is unambiguous and distinguishable from sibling get_heart_rates (raw samples).
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?
There is no when-to-use guidance, no prerequisites, and no reference to the sibling tools that operate on the same resource (set_heart_rate_zones, delete_heart_rate_zones, get_heart_rates). The agent must infer that this is the read counterpart purely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hill score for a date, or daily values over a date range. TWO branches by presence of enddate, same shape as getEnduranceScore but the range branch hard-codes aggregation="daily" (NOT "weekly"; do not conflate the two).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the useful behavioral fact that the range branch forces daily granularity, but it frames this in terms of an `aggregation` parameter that does not exist in the schema, which is more confusing than clarifying. No return-format, pagination, or coverage caveats are given.
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?
Only two sentences and the primary behavior is front-loaded, which is good. The second sentence crams in a cross-reference to another tool's internals plus an all-caps warning about a nonexistent parameter, spending words on information an agent cannot act on.
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 two-parameter read-only tool with no output schema, the description covers the core branching behavior and the annotation covers safety, so the essentials are present. It omits what the returned daily values look like and, more importantly, leaves the phantom `aggregation` concept unexplained, which could mislead an agent about the tool's inputs.
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, but the description adds real semantic value by explaining that `enddate` is the switch between two distinct response modes rather than just another date bound. The stray reference to an `aggregation` value is not a parameter and slightly weakens the added meaning.
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?
States the resource (Hill score) and both retrieval modes (single date vs. daily range), and implicitly distinguishes itself from the sibling get_endurance_score by comparing shapes. It stops short of a crisp verb+resource+scope sentence, but an agent can identify the tool's job without opening the schema.
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 explains the branching rule (single value without `enddate`, daily series with it), which is genuine when-to-use guidance for the two modes. However, it gives no guidance on when to prefer get_hill_score over nearby siblings such as get_endurance_score, get_daily_stats, or get_training_status, and the 'do not conflate' warning addresses an internal concept rather than a tool-selection decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Heart-rate variability (HRV) readings and status for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, externally-sourced read. The description adds that the result covers both readings and a status for a single calendar day, but discloses nothing about data availability, empty days, or return shape. With annotations carrying the safety profile, this is adequate.
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?
A single front-loaded sentence with no waste; the resource is named first and the scope constraint follows. It is tight, though 'readings and status' remains slightly abstract about what is actually returned.
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 no output schema, the description covers what is fetched and for which day, which is the minimum viable. It does not describe the shape or contents of 'readings and status', and there is no output schema to compensate, so a gap remains.
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 a single required parameter documented at 100% schema coverage, with format and timezone ('YYYY-MM-DD (UTC)') spelled out in the schema itself. The description's 'one date' reinforces, but does not extend, what the schema already provides. Baseline 3 applies when the schema does the heavy lifting.
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?
States a specific resource (heart-rate variability readings and status) and narrows scope to 'one date', which implicitly distinguishes it from the sibling get_hrv_data_range. It never names that sibling explicitly, so the differentiation requires a small inference.
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 phrase 'for one date' implies this is the single-date tool as opposed to the range variant, but there is no explicit when-to-use rule, prerequisite, or named alternative. Usage is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily HRV summaries over a date range.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description contributes only the granularity signal ('Daily ... summaries'), and says nothing about whether long ranges are truncated, how results are ordered, or what a summary record contains. Modest added value over the annotations.
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?
A single short sentence with the resource and scope front-loaded and zero filler. It is efficient, though its brevity comes partly from omitting information the agent could use.
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 low-complexity two-parameter read, and annotations cover safety, so little is strictly required. But with no output schema the description is the only source for what a 'daily HRV summary' returns, and it gives none of that, nor any range-size or ordering caveats.
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% and both start/end carry format and timezone details (YYYY-MM-DD UTC), so the schema does the heavy lifting. The description only restates that the parameters define a range, adding no new semantics. Baseline 3 applies.
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?
States a specific verb and resource ('Daily HRV summaries') plus the scope ('over a date range'), so the agent knows it retrieves HRV data across a period. It does not, however, distinguish itself from the sibling get_hrv_data, which appears to cover a similar resource, leaving the agent to guess which one it needs.
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?
There is no guidance on when to choose this over get_hrv_data or other range tools, no exclusions, and no mention of prerequisites or limits on the range. Usage is only implied by the name and the 'date range' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The hydration log for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the purpose line: it does not say what happens when no hydration was logged for the date, what fields the log contains, or any rate/availability caveat.
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?
A single short sentence with no filler, and the key scoping constraint (one date) is front-loaded. It is efficient, though bordering on under-specified rather than truly concise.
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 annotations covering safety and no output schema, the definition is minimally viable. It omits any indication of what the log returns or how empty days are handled, which an agent would benefit from knowing.
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% and the single cdate parameter is documented with its format and UTC basis, so the baseline is 3. The description's 'one date' phrasing reinforces the single-parameter contract but adds no format or timezone detail beyond 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 identifies the resource (hydration log) and its scope (one date), which cleanly separates it from the write-side sibling add_hydration_data. It is a noun phrase rather than a verb+resource, so it falls short of the fully specific 5 tier, but an agent can still tell what it retrieves.
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?
There is no when-to-use guidance, no prerequisites, and no named alternative (e.g., a range or multi-day variant). 'For one date' hints at single-date scope but does not tell the agent when to pick this tool over anything else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Badges with progress towards them, from the earned and available lists. No HTTP path of its own: calls getEarnedBadges() and getAvailableBadges(), filters each with an in-progress predicate (progress truthy; if progress === target, only "in progress" when badgeLimitCount is set and badgeEarnedNumber < badgeLimitCount), then merges both filtered lists into a Map keyed by badgeId (available overwrites earned on collision, keeping the earned entry's position); never raises: a null from either call is treated as []. Badges carry badgeImageUrls (inherited from the two calls).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint and openWorldHint, so the description carries most of the behavioral burden and does so well: it discloses that the tool never raises (null from either call becomes []), how collisions resolve (available overwrites earned but keeps the earned position), and that badgeImageUrls is inherited. The remaining gap is that it describes internal mechanics more than agent-facing behavior such as result size or typical progress values.
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 purpose is front-loaded in the first clause, but the body is one very long compound sentence dense with implementation detail (progress truthy, progress === target, badgeLimitCount/badgeEarnedNumber comparison). Much of this reads as internal source-level logic rather than guidance the agent needs to select or call the tool.
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 no output schema, the description must explain the return shape and it does: a Map keyed by badgeId, plus the presence of badgeImageUrls. Combined with the never-raises guarantee and merge semantics, an agent has everything needed to call and interpret this tool.
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 takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The schema is empty and closed (additionalProperties: false), consistent with the no-argument contract implied by the 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 opening clause states a specific resource and scope: badges with progress towards them, drawn from the earned and available lists. This clearly distinguishes it from siblings get_earned_badges and get_available_badges, since it names both as its inputs and defines itself as the merged/derived view.
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?
Usage is implied rather than stated â an agent can infer this is the tool to call when it wants only in-progress badges rather than full earned/available lists, because the description spells out the filtering predicate. However, there is no explicit when-to-use vs. the two sibling calls it wraps, and no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Virtual challenges in progress. start must be at least 1. GETs /badgechallenge-service/virtualChallenge/inProgress; asymmetric validation: start validated POSITIVE here (rejects start=0), unlike the non-negative start on the four challenge methods above; limit validated positive; same array-not-dict correction.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint/openWorldHint, but the description adds real behavioral value: the asymmetric validation (start validated positive here, rejecting start=0, unlike the non-negative start elsewhere), positive limit validation, and the 'array-not-dict' correction. This is meaningful disclosure beyond the structured fields.
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?
Purpose is front-loaded, but the body is dense with cross-references ('the four challenge methods above', 'same array-not-dict correction') that point at context not present in this definition and can confuse an isolated reader. The critical start constraint is buried mid-sentence.
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 two-parameter read-only list tool with no output schema, the description covers the key behavioral quirks (validation asymmetry, response shape) but omits any sense of what the returned virtual challenges contain or pagination behavior. Adequate but with clear 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 0%, so the description carries the full burden and largely meets it: it documents that start must be at least 1 (rejecting 0) and that limit is validated positive. It does not explain the offset/limit pagination semantics of start itself, but the validation constraints are precisely specified.
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 specific resource ('Virtual challenges in progress') and implies the list/get verb, and it situates itself in the challenge family by referencing 'the four challenge methods above.' It stops short of naming the sibling that retrieves a different challenge state, so an agent must infer the distinction rather than being told it.
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 'in progress' scope implicitly indicates when this applies versus available/earned/completed challenges, and it references the other challenge methods. However, there is no explicit 'use this when / not when' routing or named alternative, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moderate and vigorous intensity minutes for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: no return format, no data availability caveats, no timezone handling for the UTC date.
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?
A single front-loaded sentence with zero waste. It is terse but conveys purpose, scope, and data type efficiently; only the lack of any sibling routing keeps it from a 5.
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 simple read-only tool with full schema coverage and annotations, the essentials are present. However, it omits the distinction from get_weekly_intensity_minutes and gives no hint about the returned data shape, which is the main gap given no output schema exists.
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% and the single cdate parameter is fully documented in the schema (YYYY-MM-DD, UTC), so the description need not compensate. The description adds no parameter detail beyond what the schema provides, making 3 the appropriate baseline.
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?
States a specific verb+resource ('intensity minutes') and scopes it to one date, and 'moderate and vigorous' clarifies what data is returned. It does not explicitly distinguish itself from the sibling get_weekly_intensity_minutes, though 'for one date' implies the daily-vs-weekly split.
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?
No explicit when-to-use statement, no prerequisites, and no named alternative. The daily/weekly distinction from get_weekly_intensity_minutes must be inferred entirely from the phrase 'for one date'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lactate threshold: the latest values (default), or history over a date range when latest is false. Defaults latest=true, aggregation="daily". TWO DIFFERENT branches: latest=true returns {speed_and_heart_rate, power} from two GETs; latest=false (requires startDate, throws otherwise) returns {speed, heart_rate, power} from three GETs.
| Name | Required | Description | Default |
|---|---|---|---|
| latest | No | ||
| endDate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startDate | No | Calendar date, YYYY-MM-DD (UTC) | |
| aggregation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld, so the description's value is in the extras it adds: the divergent return shapes, the underlying 2-GET vs 3-GET behavior, and the throw condition when startDate is missing. That is real behavioral context beyond the annotations.
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?
Front-loads the default behavior, then the two-branch distinction, then the return shapes. Dense but every clause (defaults, throw condition, GET counts) carries information. Slightly terse in phrasing but no wasted sentences.
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?
No output schema exists, yet the description details the exact return keys for both branches and the error case. Only minor gaps remain, such as endDate defaults and what aggregation actually changes in the output.
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 only 50% (latest and aggregation are undocumented in the schema), and the description compensates by giving the latest default, the aggregation='daily' default, and startDate's conditional requirement. This meaningfully fills the schema gap.
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?
States a specific verb+resource ('Lactate threshold: the latest values') and immediately distinguishes the two operating modes. An agent knows exactly what it fetches without opening the schema.
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?
Explicitly explains when each branch applies: latest=true is the default; latest=false returns history over a date range and requires startDate, otherwise it throws. No sibling alternatives are named, but the tool has no close sibling, so this is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The most recent activity, or null if there are none. Delegates to getActivities(0, 1), returns the last element or null.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds value by disclosing the null-on-empty result and the delegation to `getActivities(0, 1)`, but reveals nothing about ordering guarantees or payload content.
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-loaded with the returned value and its edge case. Every clause earns its place; no 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?
With no parameters and no output schema, the description's only obligations are to identify the result and the empty case, both of which it does. A brief note on what constitutes an 'activity' or the ordering basis would complete it.
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 takes zero parameters, so the schema baseline is 4. Nothing in the description is needed to clarify inputs, and nothing is misstated.
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?
States a specific verb+resource: retrieves the most recent activity, with the empty-case result (`null`) made explicit. It is distinguishable from the bulk `get_activities` family, though it never names a sibling or scope boundary directly.
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?
No when-to-use guidance or alternatives are given. It does not say whether this is preferred over `get_activities`/`get_activities_by_date` when an agent just wants the latest item, which is exactly the decision an agent faces in this large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lifestyle logging entries for one date. GETs /lifestylelogging-service/dailyLog/{cdate} Grouped under misc per the plan's explicit instruction, even though it superficially resembles a wellness-daily endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds the underlying endpoint path, but says nothing about what 'lifestyle logging' actually contains or the shape of the returned data, so it only marginally exceeds the annotations.
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 purpose is front-loaded and stated efficiently, but the second sentence about being 'Grouped under misc per the plan's explicit instruction' is leaked internal planning context that adds no value for an agent and dilutes the definition.
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 one fully documented parameter, read-only/open-world annotations, and no output schema, the basics are covered. But for a data-retrieval tool with no output schema, the description never characterizes the returned entries, leaving a real gap in what an agent should expect.
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% for the single cdate parameter, so the schema already documents format (YYYY-MM-DD UTC) and required status. The description's '{cdate}' reference in the URL adds no meaning beyond the schema, making the baseline 3 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 opening sentence states a clear verb+resource ('Lifestyle logging entries for one date'), which distinguishes it from the many other daily-log endpoints like get_menstrual_daily_log or get_nutrition_daily_food_log. However, the second sentence is internal meta-commentary about categorization and does not help an agent select the 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?
There is no when-to-use guidance, no prerequisites, and no named alternatives despite dozens of sibling daily-retrieval tools. The date-scoped usage is only implied by the phrase 'for one date'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Max metrics (VO2 max and related values) for one date. The date is repeated twice in the path (start=end=cdate).
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the URL-construction detail (start=end=cdate), which explains the unusual parameter naming, but says nothing about what values come back or whether data is missing for days without a measurement.
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 with the purpose front-loaded and no filler. The second sentence is arguably implementation detail, but it earns its place by explaining the odd 'cdate' path repetition.
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?
There is no output schema, so the description is the only place a caller could learn what is returned, and 'related values' is vague. For a read-only single-date fetch the definition is workable but leaves the return shape and empty-day behavior unspecified.
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 is fully documented in the schema (YYYY-MM-DD, UTC), so the description carries no additional burden. Its mention of 'cdate' merely restates the schema field. Baseline 3 is appropriate for a one-parameter tool with complete schema documentation.
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?
States a specific resource (max metrics / VO2 max and related values) and an explicit scope ('for one date'), so an agent can tell it is a single-day fetch. It does not name the sibling get_max_metrics_range, so the contrast is only implicit rather than explicit.
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?
'For one date' implies the single-date use case versus the sibling range tool, but the description never names get_max_metrics_range or states when to prefer one over the other. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Max metrics (VO2 max and related values) over a date range. Throws GarminError if start > end.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior beyond the annotations by disclosing the validation contract: it throws GarminError when start > end, telling the agent this is an error rather than an empty result. It still says nothing about pagination or return shape, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler. The resource and range are front-loaded and the failure condition follows immediately.
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 two-parameter read-only tool with a fully documented schema and no output schema, the description covers what is returned (max metrics such as VO2 max) and the one failure mode. Only the return structure/pagination is left unspecified, which is a minor gap for a read tool whose annotations already cover safety.
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% and both date parameters carry format and UTC guidance in the schema, so the baseline is 3. The description's only added parameter meaning is the start > end ordering constraint, which is useful but minimal.
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?
States a specific verb+resource (max metrics / VO2 max values) plus scope ('over a date range'), which implicitly distinguishes it from the sibling get_max_metrics for a single point in time. It never names that sibling explicitly, so the differentiation is inferable rather than stated.
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 date-range scope implies when to reach for this tool versus a single-day variant, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer the routing decision from the phrase 'over a date range' alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Menstrual-cycle calendar data between two dates (Garmin allows up to 91 days). Garmin rejects windows of 92+ inclusive days; not enforced here (caller's responsibility).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true/openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: Garmin's 91-day cap, the 92+ inclusive-day rejection rule, and the important fact that the limit is NOT enforced here, making it the caller's responsibility. It stops short of saying anything about the returned payload.
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, front-loaded with the resource and range, followed by the operational constraint. The parenthetical 'not enforced here (caller's responsibility)' is dense but earns its place by preventing a false assumption of validation.
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 read-only tool with full parameter coverage and no output schema, the description supplies the one non-obvious operational fact (the 91-day limit and its non-enforcement). It could say more about what the calendar data contains (entries vs. predictions), but nothing required to invoke it correctly 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?
Schema coverage is 100% and both parameters already document the YYYY-MM-DD (UTC) format. The description adds only the inclusive-window constraint tied to those two dates, which is relevant but does not go beyond what the schema already conveys about the arguments themselves.
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?
States a specific resource ('Menstrual-cycle calendar data') and a specific scope ('between two dates'), which an agent can distinguish from date-scoped siblings like get_menstrual_data_for_date or summary-style tools like get_menstrual_cycle_summary. It never names those siblings, so differentiation is inferred rather than stated.
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 two-date framing implies when the tool applies (range queries), but there is no explicit guidance on when to choose it over get_menstrual_data_for_date, get_menstrual_cycle_summary, or get_menstrual_reports, nor any stated prerequisite such as menstrual-cycle setup. Usage is only suggested.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A summary of the menstrual cycle containing a date.
| Name | Required | Description | Default |
|---|---|---|---|
| fordate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral on top: no indication of what the summary contains, whether it requires prior cycle initialization, or how a date with no tracked data behaves. It does not contradict the annotations.
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?
It is short, but that brevity comes from under-specification rather than economy. The trailing clause 'containing a date' is a fragment that restates the parameter and earns no place, and nothing useful 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?
With no output schema, the description carries the burden of explaining what the returned summary holds, and it fails to do so. For a read-only one-parameter tool the bar is low, but an agent still cannot tell what fields or time span it will receive.
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% â the single 'fordate' parameter is fully documented (YYYY-MM-DD UTC) in the schema. The description's phrase 'containing a date' merely echoes the parameter and adds no format, range, or default semantics. Baseline 3 applies.
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 is a noun fragment rather than a verb+resource statement: 'A summary of the menstrual cycle containing a date.' It gestures at the returned artifact but never says what it retrieves or on whose behalf, and it does nothing to separate this tool from close siblings such as get_menstrual_data_for_date, get_menstrual_reports, or get_menstrual_calendar_data.
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?
No when-to-use guidance, no prerequisites (e.g. whether cycle setup must exist first), and no mention of the many adjacent menstrual tools an agent could pick instead. The agent is left to guess between this and get_menstrual_data_for_date.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The menstrual-cycle day view for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| fordate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and there is no contradiction. The description adds the scoping fact that it returns a single day's view, but says nothing about what fields come back or the sensitivity/permission considerations of menstrual data.
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?
A single short sentence with the scope constraint front-loaded and no filler. It is terse to the point of being fragmentary, but nothing is wasted.
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 no output schema and full annotation coverage, the description is adequate but thin: it does not say what the 'day view' contains or how it relates to the sibling menstrual endpoints. Minimum viable, not 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?
Schema description coverage is 100% and the single parameter (fordate, YYYY-MM-DD UTC) is fully documented in the schema. The phrase 'for one date' merely restates that constraint, so the baseline of 3 applies.
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 specific resource (menstrual-cycle day view) and scopes it to a single date, so an agent knows this is a per-day read rather than an aggregate. However, it never distinguishes itself from close siblings like get_menstrual_calendar_data, get_menstrual_cycle_summary, or get_menstrual_reports, which an agent must disambiguate by schema inspection.
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?
There is no explicit when-to-use statement, no prerequisites, and no named alternative. In a crowded menstrual-data family (calendar, summary, reports, last_confirmed, daily log), the description gives no routing guidance for choosing this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The last confirmed period as of a date.
| Name | Required | Description | Default |
|---|---|---|---|
| fordate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds nothing beyond the schema, though it does not contradict the annotations. Useful context such as what is returned when no period has been confirmed, or the relationship to the confirm/update menstrual tools, is absent.
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?
A single short sentence with no wasted words, and the resource is front-loaded. It is efficient, though it errs toward under-specification rather than over-verbosity.
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-only tool with full schema coverage and annotations, the definition is minimally adequate: the agent knows what is fetched and for which date. It lacks any routing guidance among the numerous menstrual siblings and any note on behavior when no confirmed period exists.
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% with a single documented 'fordate' parameter (YYYY-MM-DD, UTC), so the schema carries the burden. The description's 'as of a date' only loosely echoes the parameter and adds no format or semantics beyond what is already documented.
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 phrase names a specific resource ('the last confirmed period') and scopes it to a date, so an agent can guess it retrieves a record rather than mutating one. However, it is a noun phrase with no verb and no differentiation from close siblings like get_menstrual_data_for_date or get_menstrual_cycle_summary, leaving the exact purpose ambiguous.
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?
There is no statement of when to use this tool versus the many other menstrual-data siblings (get_menstrual_calendar_data, get_menstrual_data_for_date, get_menstrual_cycle_summary, confirm_menstrual_period_start). The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Menstrual-cycle reports over the last 1, 6 (the default) or 12 cycles. Defaults numberOfCycles=6, nextReport=false, reportType="CYCLE", todayCalendarDate defaults to today; numberOfCycles restricted to {1,6,12} or throws GarminError.
| Name | Required | Description | Default |
|---|---|---|---|
| fordate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| options | No | ||
| numberOfCycles | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the bar is lower, and the description still adds real behavioral context: documented defaults (numberOfCycles=6, nextReport=false, reportType='CYCLE', todayCalendarDate=today) and the fact that an out-of-range numberOfCycles throws GarminError. This error behavior is genuinely useful and not present in the annotations or schema.
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?
A single dense sentence with the purpose front-loaded and no filler, though the backtick-heavy defaults clause reads as a run-on. Every clause carries information, but splitting defaults from the constraint would improve readability.
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 no output schema, the description would need to say what a 'report' contains, and it does not. It also omits sibling differentiation among several menstrual tools. Safety is covered by annotations and parameters are partially covered, so the definition is workable but leaves notable 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 description coverage is only 33%, so the description must compensate, and it does for the key gap: numberOfCycles has no schema description but the text specifies its allowed values {1,6,12} and its default, plus defaults for nextReport, reportType and todayCalendarDate. It stops short of explaining what nextReport means or the full domain of reportType, so it is strong but not complete.
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?
States a specific verb and resource ('menstrual-cycle reports') and the scope ('last 1, 6 or 12 cycles'), so the agent knows what it retrieves. However, it never distinguishes itself from close siblings such as get_menstrual_cycle_summary or get_menstrual_calendar_data, leaving the agent to guess which menstrual endpoint to call.
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?
There is no when-to-use or when-not-to-use guidance, and no mention of alternatives despite ~10 menstrual-related siblings. The default values and cycle-count restriction imply how to configure the call, but nothing tells the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The training readiness score computed after waking up on a date. Delegates to getTrainingReadiness, no HTTP call of its own; filters for inputContext === "AFTER_WAKEUP_RESET", falls back to the first entry; null for a falsy or empty result.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations: it discloses that there is no HTTP call of its own (delegation), the exact filter applied, the fallback to the first entry when the filter misses, and that null is returned for a falsy or empty result. These are exactly the behaviors an agent needs to interpret a null or unexpected response.
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, front-loaded with the purpose before the implementation detail, with no wasted words. The inline code-styled internals are slightly technical but each clause (delegation, filter, fallback, null) conveys distinct behavior.
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-param read-only tool with no output schema, it covers purpose, selection semantics, fallback, and the null case, so an agent can call and interpret it. It stops short of describing the score's shape or range, but the essential call-and-parse information is present.
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% (cdate documented as YYYY-MM-DD UTC), so the schema carries the parameter. The description adds no additional format, default, or range meaning beyond it, which matches the baseline 3 for a fully-documented single parameter.
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?
States a specific verb+resource ('training readiness score computed after waking up on a date') and pins down which variant is returned ('inputContext === "AFTER_WAKEUP_RESET"'). This distinguishes it in substance from the sibling get_training_readiness, though it never names that sibling as the alternative, so routing is inferred rather than explicit.
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 filter description implicitly signals this is the after-wakeup variant, but there is no explicit when-to-use/when-not statement and no naming of get_training_readiness as the general-purpose alternative. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The next scheduled workout from this month or next, or {} if there is none. Computed from two getScheduledWorkouts calls (this month + next, handling Dec->Jan rollover); returns {} if nothing matches, never throws.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavior beyond that: it returns an empty object when nothing matches, never throws, and handles Dec->Jan rollover â all useful for an agent's error handling.
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 front-loaded sentences with zero waste. The core return value and the empty-object fallback come first, and the implementation note follows.
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 no parameters and no output schema, the description carries the return-shape burden and does so ('{}' for none, never throws). The only minor gap is that it doesn't describe the shape of a matched workout, though the sibling tools presumably do.
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 takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies a no-argument call.
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?
States a specific verb+resource ('the next scheduled workout') and bounds it to 'this month or next,' which distinguishes it from the plural sibling get_scheduled_workouts that returns a list. An agent can identify the tool's purpose without opening any schema.
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?
Usage is implied by the name and description (fetch the single upcoming workout), but there is no explicit when-to-use-vs-alternatives guidance. It mentions getScheduledWorkouts only as an implementation detail, not as a routing alternative an agent should consider.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Badge challenges joined but not completed. Garmin rejects start=0. GETs /badgechallenge-service/badgeChallenge/non-completed; same start/limit validation; same array-not-dict correction and same live start=0 -> 400 discovery as getBadgeChallenges.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only declaring readOnlyHint and openWorldHint, the description adds substantial behavioral context: the exact endpoint, the Garmin-specific rejection of start=0, the start/limit validation pattern, the array-not-dict correction, and the live start=0 -> 400 discovery. These are API quirks an agent would not know from annotations alone.
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 front-loaded with the core purpose and then packs only operational caveats into a compact follow-up. Every clause conveys useful information about the resource, endpoint, validation, or response correction. There is no 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 paginated read tool with no output schema and read-only annotations, the description covers the endpoint, validation quirk, and response-shape correction. It relies on the sibling getBadgeChallenges to explain 'same validation' details rather than being fully self-contained, but it gives enough for an agent to call 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?
Schema coverage is 0%, so the description must compensate. It adds that start=0 is rejected and that start/limit use the same validation as getBadgeChallenges, but it does not define what limit controls or what valid start values mean beyond not being zero. This is partial compensation for two undocumented required 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 states a specific verb and resource: retrieving badge challenges that are joined but not completed. It distinguishes this filter from related siblings like get_badge_challenges and get_in_progress_badges by narrowing to the non-completed subset. The endpoint path reinforces exactly what is returned.
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 phrase 'joined but not completed' implies the appropriate use case, but there is no explicit when-to-use guidance. It does not name an alternative tool for selecting between this and get_badge_challenges, get_in_progress_badges, or get_available_badge_challenges. Usage is therefore only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The food log for one date. GETs /nutrition-service/food/logs/{cdate}.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path, which conveys little behavioral value â nothing about return contents, entry granularity, or auth/rate limitations.
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 with the resource front-loaded and no padding. The second sentence restating the HTTP endpoint is low-value repetition, keeping it short of a 5.
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 simple single-parameter read tool this is minimally viable: the parameter and safety profile are covered by schema and annotations. With no output schema, the description could have said what the log contains (entries, nutrients), but it does not.
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 single parameter cdate has 100% schema description coverage (type, date format, UTC convention), so the schema carries the semantics. The description adds nothing beyond it, which is the expected baseline when coverage is complete.
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?
States a specific resource (the food log) and scopes it precisely to a single date, which implicitly distinguishes it from the sibling get_nutrition_food_log_range. However, it never names a sibling or differentiates from get_nutrition_daily_meals, so it stays at a clear-but-undifferentiated 4.
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?
There is no explicit when-to-use statement and no mention of the obvious alternatives (get_nutrition_food_log_range for a span, get_nutrition_daily_meals for meal breakdowns). Usage is only faintly implied by the word 'one date', which is not enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Meals logged on one date. GETs /nutrition-service/meals/{cdate}.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description only restates that by quoting the GET endpoint path. It adds no behavioral context such as return shape, whether an empty day returns an empty list, or timezone handling beyond the schema's UTC note.
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 with the purpose front-loaded. The endpoint-path sentence is low-value implementation detail but does not bloat the definition.
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 read tool with annotations and full schema coverage, this is minimally viable. The missing piece is differentiation from get_nutrition_daily_food_log, which matters given how many nutrition siblings exist.
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 cdate parameter is fully documented (type, format, YYYY-MM-DD UTC). The description implies the date scoping but adds no meaning beyond the schema, so the baseline 3 applies.
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?
States a specific resource and scope: meals logged on one date. An agent knows it returns meal data for a single day. However, it does nothing to separate itself from the close sibling get_nutrition_daily_food_log, so the agent cannot tell which to pick from the description alone.
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?
No when-to-use guidance, no exclusions, and no mention of the adjacent nutrition siblings (get_nutrition_daily_food_log, get_nutrition_food_log_range, get_nutrition_daily_settings). The agent must infer selection from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nutrition settings and goals in effect on one date. GETs /nutrition-service/settings/{cdate}.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the point-in-time semantics ('in effect on one date') and discloses the underlying endpoint, but says nothing about auth requirements or what happens when no settings exist for the date.
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 with the purpose front-loaded and the endpoint detail trailing as supporting evidence. Nothing is padded or redundant.
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 read tool with no output schema, the description states the resource returned (settings and goals) and the temporal scoping, while annotations cover the safety profile. Nothing an agent needs to invoke it correctly 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?
Schema description coverage is 100% for the single cdate parameter (type, date format, UTC convention), so the schema carries the parameter burden. The description only echoes the concept of 'one date' without adding format or timezone detail beyond it, which is the baseline when the schema is complete.
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?
States a specific resource (nutrition settings and goals) with a clear temporal scope ('in effect on one date'), which separates it from the food-log and meal siblings. It does not explicitly name those siblings, but the settings-vs-log distinction is inferable from the noun.
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?
Usage is only implied: an agent can infer it retrieves the settings applicable to a given day. There is no statement of when to prefer this over get_goals, get_user_settings, or the other nutrition siblings, and no prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily food logs over a range; works without Connect+. GETs /nutrition-service/food/logs/range?startDate&endDate: {dailyNutritionSummaries}, one day-log per day that has anything logged.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only and open-world profile, so the bar is lower, and the description still adds real behavior: no Connect+ subscription required, plus the important detail that only days with logged data appear ('one day-log per day that has anything logged'), which prevents the agent from assuming a dense zero-filled series. It omits rate limits and pagination, but for a read-only tool this is solid added context.
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?
Front-loaded purpose sentence followed by a compact endpoint/value-shape note; no filler. The second clause is tersely punctuated, but every element (endpoint, required params, return shape) earns its place.
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?
There is no output schema, so the description compensates by naming the response key and its granularity. Combined with the Connect+ note and the conditional-inclusion behavior, an agent has enough to call this correctly with just two date parameters.
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% with both date parameters documented as YYYY-MM-DD UTC, so the schema carries the burden. The description echoes startDate/endDate in the endpoint path but adds no new semantics such as inclusivity of the boundaries or a maximum range span.
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?
States a specific verb+resource and scope: daily food logs across a date range, with the exact endpoint and the shape of the returned collection. The 'range' scope implicitly separates it from the sibling get_nutrition_daily_food_log (single day), so an agent can route between them without opening schemas.
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?
Adds one genuinely useful eligibility rule: 'works without Connect+', which tells the agent it can call this on free-tier accounts. However, it never states when to prefer this over the single-day get_nutrition_daily_food_log or get_nutrition_daily_meals sibling, leaving the range-vs-single-day choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's personal records, one row per record type. GETs /personalrecord-service/personalrecord/prs/{displayName}; no args PersonalRecords is PersonalRecord[], an ARRAY, verified live (the test account returned array[0]). Note the plural type name: the method name is singular but the payload is a list.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond annotations: the payload is an array (verified live, test account returned array[0]) and flags the singular-method/plural-payload trap. That is the kind of detail that prevents downstream parsing errors.
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?
Front-loaded with what the tool returns, then the endpoint and the array caveat. Three sentences, all contributing. The bolded emphasis on ARRAY is well-placed, though the endpoint path reference is arguably noise given there are no args.
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?
No output schema exists, so the description correctly carries the return-value burden, specifying PersonalRecords is a PersonalRecord[] with one row per record type. Combined with the array warning, an agent has enough to call and parse it, though the phantom {displayName} path leaves a small ambiguity.
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?
With zero parameters the baseline is 4, but the description references a `{displayName}` path segment while the schema declares no parameters and says "no args." This slight mismatch between the documented endpoint and the actual schema could confuse an agent about whether input is required, warranting a nudge down.
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?
States a specific verb and resource: retrieves "the account's personal records, one row per record type." This distinguishes it from siblings like get_activities or get_goals since personal records are a distinct resource. It does not explicitly name an alternative, so it falls short of a 5.
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 never states when to use or avoid this tool. No prerequisites, no alternatives, no context about why an agent would call it over a general stats tool. It is implied only by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power zone profiles.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds nothing beyond that: no indication of what the profile contains, whether it depends on user FTP settings, or whether it returns all sports or a default zone set.
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?
It is short and front-loaded, but it is a fragment rather than a usable sentence, and the brevity comes at the cost of specifiability rather than by eliminating filler. It is minimal, not efficient.
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 no output schema and no parameters, the description carries the full burden of explaining what the caller gets back. It does not say whether the response is a single default profile or a set keyed by sport, nor how it relates to get_power_zones_for_sport, leaving an agent unable to call it confidently.
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 takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to add on the parameter side, and schema coverage is 100%.
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 is a bare noun phrase that essentially restates the tool name: 'get_power_zones' â 'Power zone profiles.' There is no verb, no statement of what is retrieved or from which resource scope, and no differentiation from the obvious sibling get_power_zones_for_sport. It borders on 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?
There is no guidance on when to use this tool, and critically no mention of get_power_zones_for_sport, which is the natural alternative given the near-identical name. The agent must guess which of the two power-zone tools applies to its request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Power zones for one sport, e.g. "CYCLING". sport upper-cased and validated the same way as getFunctionalThresholdPowerRange.
| Name | Required | Description | Default |
|---|---|---|---|
| sport | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds that `sport` is upper-cased and validated, a real normalization behavior, but says nothing about return shape, empty results, or rate limits.
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-loaded with the resource and scope, with zero filler. The reference to `getFunctionalThresholdPowerRange` is slightly cryptic (and its camelCase form differs from the snake_case sibling name), costing a point.
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 whose annotations already cover safety, this is close to adequate. The main gap is the missing set of valid sport values, which the description defers to another tool rather than stating; no output schema exists, so return values are also unexplained.
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 0%, so the description carries the burden and partially meets it by specifying case normalization and validation behavior. It still does not enumerate the valid sport values, offering only a single example, so an agent cannot know the accepted domain without opening another tool.
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?
States a specific verb+resource (power zones) and narrows it to one sport, which distinguishes it from the sibling get_power_zones that presumably covers all sports. It does not explicitly name get_power_zones as the alternative, so the differentiation is implied rather than stated.
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?
Provides an example value ("CYCLING") and points to getFunctionalThresholdPowerRange for the validation rules, which gives a usable usage cue. However, it never says when to pick this over get_power_zones, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The pregnancy-tracking summary.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that â it does not say what period the summary covers, what data source or permissions it needs, or whether it returns nothing when tracking is uninitialized.
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?
It is a single short fragment with no filler, so nothing is wasted â but the fragment is so minimal that it barely earns its place, and there is no front-loaded scoping or content detail to structure.
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 zero-parameter read-only tool with no output schema, the description is the only place an agent could learn what the summary contains or over what window. It supplies none of that, leaving the agent unable to predict the response shape.
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 takes zero parameters, so per the rubric the baseline is 4. There is no parameter information the description could usefully supply, and the empty schema is self-explanatory.
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 is effectively a restatement of the tool name: 'get_pregnancy_summary' â 'The pregnancy-tracking summary.' It identifies the resource domain but adds no verb, scope, or distinguishing detail, and does nothing to separate it from the many sibling summaries (get_menstrual_cycle_summary, get_golf_summary, get_user_summary, get_progress_summary_between_dates).
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?
There is no when-to-use guidance, no prerequisites, and no named alternative among the numerous summary siblings. An agent has no signal about when this tool is the right choice versus get_menstrual_cycle_summary or the other pregnancy/menstrual tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's primary training device.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing behavioral beyond that â no indication of what is returned, whether a device must be configured, or what happens if no primary device 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?
A single short sentence with no filler and the key qualifier ('primary') front-loaded. It is efficient, though its brevity reflects under-specification rather than disciplined economy.
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 no output schema and no parameter schema, the description carries the full burden of conveying the result shape, yet it says nothing about what fields the returned device contains or how 'primary' is determined. For a zero-argument read tool this leaves the agent unable to predict the response.
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 takes zero parameters, so there is no parameter semantics for the description to explain. Baseline 4 applies since the description cannot add or omit parameter meaning.
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 the resource ('the account's primary training device'), which does distinguish it from the broad sibling get_devices by implying a single, default device. However, it is a noun fragment that largely restates the tool name rather than stating a verb+resource action, and it never clarifies what 'primary' means or what attributes are returned.
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?
There is no when-to-use guidance at all. With siblings like get_devices, get_device_last_used, and get_device_settings, an agent gets no signal about when this single-device lookup is preferred over the general device listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Totals of one metric (default distance) between two dates, grouped by activity type by default. Defaults metric="distance", groupbyactivities=true.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | ||
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| groupbyactivities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, openWorldHint=true). The description adds genuine behavioral value by disclosing default behavior when parameters are omitted (metric defaults to distance, groupby to true). It does not describe the output shape or limits, but with annotations covering safety, a 3 is appropriate.
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, front-loaded with the core operation. It is slightly redundant, restating the defaults ('default distance...' then 'Defaults metric=distance, groupbyactivities=true'), but overall efficient.
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 no output schema, the description conveys the aggregate shape (totals grouped by activity type) but not the returned fields, and it omits the set of valid metric values. Adequate for a 4-param read tool but leaves gaps an agent calling it might hit.
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 50% â metric and groupbyactivities lack schema descriptions. The description compensates for both by stating their defaults, which is useful. However, it never enumerates which metric values are valid (no enums exist), leaving a real gap for the metric parameter.
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 verb+resource: totals of one metric between two dates, grouped by activity type. An agent can grasp what it produces without opening the schema. It does not, however, name or distinguish itself from related aggregation siblings like get_stats or get_activities_by_date.
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?
There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. The aggregation-over-a-range purpose is only implied, leaving the agent to infer selection against sibling summary tools on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Predicted race times: the latest, or daily/monthly history when all three args are given. TWO branches, all-or-nothing params (throws on a partial combination): no params hits .../latest/{displayName}; all three hit .../{type}/{displayName}, capped at a 366-day span.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | No | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world behavior, yet the description adds real behavioral value: the all-or-nothing parameter contract throws on partial input, and the history branch is capped at a 366-day span. It stops short of describing return payload shape or pagination, so not a full 5.
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 dense sentences with no filler, and the two-branch structure is front-loaded. The backtick endpoint templates are compact but slightly cryptic for a caller who only needs argument behavior, which keeps it from a 5.
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 no output schema, the description only gestures at the return ('Predicted race times: the latest, or daily/monthly history'), leaving the prediction categories and response shape unexplained. It also references `{displayName}` path segments that are not among the three documented arguments, which may puzzle a caller. Adequate but with clear gaps for a read tool lacking an output 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 coverage is 67% and `type` has no description, but the description supplies the semantics the schema cannot express: the three parameters are an all-or-nothing group even though the schema marks zero required. That dependency is the single most important thing an agent needs and it is stated outright.
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?
Opens with a specific verb+resource ('Predicted race times') and immediately distinguishes the two retrieval modes (latest vs daily/monthly history). An agent can tell exactly what it gets and under which input shape without opening the schema.
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?
Explicitly states the trigger for each branch: no params hits `.../latest/{displayName}`, all three hits `.../{type}/{displayName}`. It also warns that a partial combination throws, which is effectively a when-not-to-use rule. No sibling alternative is named, but none of the sibling tools overlaps this capability, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Breathing-rate data for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the date scoping â no note on data granularity, sampling cadence, availability, or empty-response behavior for a health-metric read.
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?
A single short sentence with no filler and the scope front-loaded. It is efficient, though arguably at the edge of under-specification rather than maximal conciseness.
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 simple single-parameter read tool this is minimally adequate, but with no output schema the description should at least hint at what the returned breathing-rate data looks like (samples, timestamps, aggregation). As written, the agent knows what to pass but nothing about what comes back.
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 cdate is fully documented (YYYY-MM-DD, UTC). The description's 'one date' restates the schema rather than adding format or timezone nuance, so the baseline 3 applies.
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?
States the resource precisely (breathing-rate data) and the scope (one date), which an agent can map to the get_respiration_data verb. It does not differentiate itself from closely-patterned siblings such as get_hrv_data, get_spo2_data, or get_stress_data, but the resource is 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?
No statement of when to use this tool versus alternatives, no prerequisites, no exclusions. The agent must infer usage purely from the name and the date parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resting heart rate per day over a date range, as { calendarDate, value } rows. Reshapes allMetrics.metricsMap into [{calendarDate, value}], dropping null values.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond them: it discloses that null values are dropped, which tells the agent that no-data days are absent from the array rather than present as nulls.
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, zero waste, with the primary purpose front-loaded and the return shape following. Size is well matched to a simple two-parameter read tool.
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 no output schema, the description correctly compensates by specifying the row shape `{ calendarDate, value }` and the null-dropping behavior. Only minor gaps remain (e.g., no note on extremely long ranges or empty results), which are low-stakes for this tool.
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% and both parameters are documented with format and UTC semantics, so the baseline is 3. The description adds nothing about start/end beyond what the schema already provides.
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?
States a specific verb+resource+granularity: 'Resting heart rate per day over a date range'. The range-versus-single-day phrasing implicitly differentiates it from the sibling get_rhr_day, but it never names that sibling, so the routing is left to inference.
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?
No when-to-use, when-not-to-use, or alternative is stated. The most likely confusion, this tool vs. get_rhr_day (single day vs. range), is left unresolved for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resting heart rate for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond that â no note on missing data, timezone handling, or how a single day's value is derived.
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?
A single front-loaded sentence with zero waste, well sized for a one-parameter read tool. It is compact to the point of being terse, but nothing is padded.
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 simple read tool with annotations covering safety and a fully documented parameter, the description is minimally sufficient. The notable gap is the lack of any differentiation from the get_rhr_daily sibling, which an agent would need to select 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?
Schema coverage is 100%, with cdate fully documented as a YYYY-MM-DD UTC calendar date. The description's 'one date' phrasing adds nothing beyond the schema, 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 names a specific resource (resting heart rate) and a clear scope (one date), so an agent knows what it returns. However, it provides no differentiation from the near-identical sibling get_rhr_daily, so it fails the sibling-distinction bar for a 5.
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?
There is no when-to-use guidance and no mention of alternatives, despite the presence of the closely named get_rhr_daily sibling. The agent is left to guess which of the two to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Running tolerance over a date range, aggregated weekly (the default) or daily. Defaults aggregation="weekly"; restricted to {daily,weekly} (narrower than the FTP/lactate methods).
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| aggregation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description usefully adds the default aggregation behavior and the constrained enum values, but says nothing about what the returned series represents, its units, or behavior on empty/partial ranges.
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-loaded with the resource and scope, and no filler. Minor redundancy: the default is stated twice ("aggregated weekly (the default)" then "Defaults aggregation=\"weekly\"").
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 no output schema, the description carries the burden of explaining the result, yet it never defines what a running tolerance value is or its units. For a read-only metric tool with covered annotations and mostly documented params it is adequate, but the core output concept is left undefined.
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 67%, and the only undescribed parameter (aggregation) is precisely the one the description documents: its default of "weekly" and its restriction to {daily, weekly}. That is real added meaning beyond the schema enum, and it also clarifies the parameter is narrower than analogous methods.
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?
States a specific metric (running tolerance) and the retrieval scope (date range, aggregated weekly or daily). It also gestures at sibling differentiation by noting the aggregation set is narrower than the FTP/lactate methods, though it does not name those siblings directly.
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?
There is no statement of when to choose this tool over get_lactate_threshold or get_functional_threshold_power_range, nor any prerequisite or exclusion. The FTP/lactate reference only explains the enum restriction, not tool selection, so the agent must infer usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One scheduled workout by its scheduled-workout id. Uses a DIFFERENT base (/workout-service/schedule) than getScheduledWorkouts (/calendar-service).
| Name | Required | Description | Default |
|---|---|---|---|
| scheduledWorkoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds context about which service backs the id, but says nothing about not-found behavior, error handling, or what a 'scheduled workout' contains, which is the sort of detail that would earn a higher score.
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 with the purpose front-loaded and no filler. The second sentence is legitimately informative rather than padding, though the first sentence's fragment form costs it a perfect mark.
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 no output schema, the description should ideally hint at the shape of the returned scheduled workout and error cases. It only covers the id/endpoint distinction, which is helpful but leaves the agent without a return-value or failure picture.
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 single `scheduledWorkoutId` parameter is already documented as 'Numeric id'. The description adds only that the id belongs to the scheduled-workout namespace; it does not resolve the schema's integer|string type union or say where a valid id comes from.
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 the resource (a single scheduled workout) and the key (scheduled-workout id), and explicitly contrasts itself with `getScheduledWorkouts` by endpoint base. The opening is a fragment with no verb ('One scheduled workout by its scheduled-workout id'), and it does not distinguish itself from other nearby siblings such as `get_next_scheduled_workout` or `get_scheduled_workout_summaries`, so it falls short of a 5.
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 endpoint note implies that this tool takes ids from the `/workout-service/schedule` namespace rather than `/calendar-service`, which is a useful usage signal. However, it never states when an agent should choose this over `get_scheduled_workouts`, `get_scheduled_workout_summaries`, or `get_next_scheduled_workout` â the routing is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The calendar for one month (month is 1-12): scheduled workouts, events and more. month is 1-12 on the way in, converted to 0-indexed on the wire; validates year>=2000, month 1-12.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| month | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds genuine contract detail beyond them: month is 1-12 on input but converted to 0-indexed on the wire, and year>=2000 is validated. That input-normalization quirk is exactly the kind of thing an agent would otherwise get wrong. It does not describe the response shape beyond 'and more'.
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?
Short and front-loaded, but the 'month is 1-12' fact is stated twice within two sentences ('`month` is 1-12' and 'validates ... `month` 1-12'), which is visible waste in a description this size. The remaining content is dense and earns its place.
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 read-only tool with no output schema, the description covers inputs well but leaves the return shape vague ('and more') and says nothing about ordering, event types, or pagination. Since there is no output schema to fall back on, more return-side detail would have been warranted.
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 0%, so the description carries the burden for both parameters. It fully documents month (1-12, converted to 0-indexed internally) but leaves year only constrained to >=2000, with no format guidance (4-digit? string vs integer?). Partial compensation for a two-parameter, zero-coverage 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 names the resource and its scope precisely: 'The calendar for one month... scheduled workouts, events and more.' An agent can tell this is a month-scoped calendar reader rather than a single-workout lookup. It stops short of naming the adjacent siblings (get_next_scheduled_workout, get_scheduled_workout_summaries, list_calendar_events), so it does not fully differentiate on its own.
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?
Usage is implied by the month scoping â call this when you need a whole month's calendar rather than a specific workout. There is no explicit statement of when to prefer this over get_scheduled_workout_by_id, get_next_scheduled_workout, or get_scheduled_workout_summaries, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every scheduled workout between two dates, as compact summaries. POSTs the fixed GraphQL query workoutScheduleSummariesScalar(startDate, endDate): every scheduled workout in the range, plan or self-scheduled (tpType: null), as compact rows whose scheduledWorkoutId is what unscheduleWorkout takes, or null for a Garmin Coach workout, which also has tpType: null like a self-scheduled one (tell them apart by fbtAdaptivePlanId). Dates are validated before they are spliced into the query. A GraphQL error arrives as HTTP 200 with errors, turned into a GarminError. *It LAGS writesâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld; the description adds substantial behavioral context: it POSTs a fixed GraphQL query, dates are validated before splicing, GraphQL errors arrive as HTTP 200 with an errors payload turned into a GarminError, and it explicitly notes that it LAGS writes. The tpType/fbtAdaptivePlanId disambiguation is genuinely useful caveat detail.
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?
Purpose is front-loaded, but the body is dense and drifts into implementation minutiae (naming the internal GraphQL query `workoutScheduleSummariesScalar`) that an agent selecting the tool does not need, and the text runs long before reaching the practical write-lag caveat.
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?
There is no output schema, so the description usefully compensates by describing the returned rows, the scheduledWorkoutId field and its null case, and the fbtAdaptivePlanId discriminator, plus error handling. It is close to complete for a 2-param read tool, with only 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 description coverage is 100% and both parameters (startdate/enddate) are fully documented in the schema with format and UTC semantics, so the baseline of 3 applies. The description references the same startDate/endDate range but adds no syntax or format meaning beyond 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?
States a specific verb+resource+scope: 'Every scheduled workout between two dates, as compact summaries.' The word 'summaries' and 'compact rows' implicitly distinguishes it from the full-workout siblings like get_scheduled_workouts, but it never names them explicitly, so sibling differentiation is by inference rather than direct statement.
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?
Usage is implied by the range/compact-summary framing and the useful cross-reference that scheduledWorkoutId is what unscheduleWorkout consumes, but there is no explicit when-to-use-vs-alternatives guidance (e.g. versus get_scheduled_workouts or get_next_scheduled_workout).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-night sleep stats over a date range; ranges over 28 days are fetched in chunks. Garmin's endpoint has a documented 28-day-per-request limit; ranges beyond that are auto-chunked, de-duplicated by calendarDate, and sorted.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, openWorld), and the description adds genuinely useful operational behavior beyond them: the 28-day-per-request limit, automatic chunking, de-duplication by calendarDate, and sorting. It stops short of noting latency/rate implications of large ranges, but the disclosure is well above the annotation baseline.
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?
Front-loaded with the core purpose, then the operational caveat. The chunking behavior is stated twice ('ranges over 28 days are fetched in chunks' and '28-day-per-request limit... auto-chunked'), which is mild redundancy but the sentences otherwise earn their place.
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 read-only two-date-range tool with full schema coverage, complete annotations, and no output schema, the description is sufficient: an agent knows what it returns (per-night stats), what it accepts, and the range behavior. Only the relationship to get_sleep_data 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?
Schema coverage is 100% with both date parameters fully documented as YYYY-MM-DD UTC, so the schema carries parameter semantics. The description frames them as a date range but adds no format or edge-case detail beyond the schema, matching the baseline for high coverage.
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?
States a specific verb+resource+granularity: 'Per-night sleep stats over a date range.' The 'per-night' qualifier implies daily aggregation, which hints at differentiation from the sibling get_sleep_data, but that sibling is never named, so the distinction must be inferred.
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?
Usage is only implied through 'over a date range' plus the note that large ranges are chunked, which tells the agent it is safe to pass wide ranges. No when-to-use vs when-not, and the obvious alternative (get_sleep_data) is not mentioned, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sleep data for one date: the night's summary and its sleep levels.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the result contains a night summary and sleep levels; it says nothing about date bounds, missing-data behavior, or timezone handling beyond the schema's UTC note.
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?
A single compact sentence with the scope and payload front-loaded and zero filler. It is efficient, though it could have spent a few more words on disambiguation without bloat.
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 simple one-parameter read with no output schema, the description minimally covers the return content ('night's summary and its sleep levels'), but it omits the distinction from get_sleep_daily and any note on how missing or partial nights are returned. Adequate but with clear 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 cdate parameter is fully documented as a YYYY-MM-DD UTC date. The description's 'one date' phrasing merely echoes the schema, adding no format or edge-case detail, so the baseline 3 applies.
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?
States a specific resource (sleep data), scope (one date), and content (the night's summary and its sleep levels), which is concrete enough for an agent to know what it retrieves. However, it does not distinguish itself from the very similar sibling get_sleep_daily, leaving ambiguity about which one to pick.
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 phrase 'for one date' implies a per-day lookup, but there is no explicit when-to-use guidance, no prerequisites, and no mention of the get_sleep_daily alternative. The agent must infer selection from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One day's SpO2 readings with altitude acclimation. GETs /wellness-service/wellness/daily/spo2acclimation/{cdate} (Garmin's Personal API spec): the day's SpO2 averages, sleep and hourly series and the monitoring environment, typed from PersonalApi.DailySpO2AndAcclimationDTO. Distinct from getSpo2Data's path. A day with no data (even 2030-01-01) still returns the object, fields null.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world semantics, and the description adds genuinely non-obvious behavior: a day with no data still returns the object with null fields (illustrated with 2030-01-01), which prevents the agent from misreading an empty response as an error. It also identifies the backing endpoint and DTO type for traceability. It stops short of describing pagination or field-level error behavior, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then supporting detail; every sentence carries information. The endpoint path and DTO name are somewhat implementation-flavored but are defensible for an agent that must map to Garmin's spec.
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 read tool with no output schema, the description adequately covers the return payload by naming its constituent parts and the null-on-no-data case. Only minor gaps remain, such as whether partial data can occur or how units/typing are represented.
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 already 100% with a formatted date description, so the schema does the heavy lifting. The description still adds value by showing cdate as a path placeholder and demonstrating a concrete example value, reinforcing that this is a single-day lookup rather than a range query.
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?
States a specific resource and scope: one day's SpO2 readings with altitude acclimation, then enumerates what the payload contains (averages, sleep and hourly series, monitoring environment). It explicitly names the nearest sibling, getSpo2Data, so an agent can tell the two apart without opening either schema.
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 content-level context (acclimation, hourly series, environment) that lets an agent infer when this is the right call, and it flags that empty days still return an object. However, the sibling differentiation is phrased as an API path difference ("Distinct from getSpo2Data's path") rather than an explicit use-this-when/use-that-when rule, so selection still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pulse-oximeter (SpO2) readings for one date. Coerces a string lastSevenDaysAvgSpO2 to a number.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a useful, non-obvious note that the returned `lastSevenDaysAvgSpO2` string is coerced to a number, but says nothing about the overall 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-loaded with the resource and scope. Nothing wasteful, though the coercion clause is slightly tangential to selection and invocation.
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 trivial one-param read tool with annotations, this is close to sufficient, but with no output schema the description should describe the return shape; instead it only hints at one field's handling.
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?
Only one parameter exists and schema description coverage is 100% (date format YYYY-MM-DD UTC is documented). The description's 'one date' restates the schema rather than adding format or timezone detail, matching the baseline-3 rule for high-coverage schemas.
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?
States a specific resource (pulse-oximeter/SpO2 readings) and scope (one date), which is distinguishable from siblings like get_respiration_data or get_heart_rates. It lacks an explicit verb but the intent is 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 says 'for one date' but gives no guidance on when to use this versus adjacent health-metric tools, nor any prerequisites or exclusions. The agent must infer usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Alias of getUserSummary. Alias of getUserSummary.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true (and openWorldHint=true), so the safety profile is covered. The description adds nothing beyond that â it does not say what data the summary contains, whether it aggregates a full day, or any latency/permission characteristics.
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 one sentence is duplicated verbatim ('Alias of getUserSummary. Alias of `getUserSummary`.'), which is pure redundancy rather than concision. It is short, but the space is spent repeating itself instead of adding the routing information a reader needs.
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 read-only date-scoped stats tool sitting among a dozen near-identical stats/summary siblings, the description should at minimum clarify what it returns versus get_user_summary or get_daily_stats. With no output schema and only an alias pointer, the agent cannot tell what distinguishes this call.
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% and the single `cdate` parameter (YYYY-MM-DD UTC) is fully documented in the schema. The description adds no parameter meaning of its own, so the baseline 3 applies.
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 only asserts that the tool is an alias of `getUserSummary`, which does not state a verb+resource of its own and forces the agent to look up another tool's semantics. It also references a camelCase name that does not exactly match the sibling `get_user_summary`, so the mapping requires inference. This is close to restating the name rather than explaining purpose.
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?
There is no guidance on when to call get_stats instead of the many overlapping siblings (`get_user_summary`, `get_daily_stats`, `get_stats_and_body`, `get_user_profile`). The alias statement weakly implies interchangeability but never says which form is preferred or whether one is deprecated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUserSummary merged with the day's body-composition averages. Merges getUserSummary with the body-composition totalAverage block, delegating to getBodyComposition (bodyComposition service) for the latter.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. Beyond that the description only exposes implementation detail (delegation to the bodyComposition service) and adds nothing about return shape, permissions, or limits.
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 that restate the same merge idea, with the second simply expanding the first. It leads with internal function names instead of a front-loaded statement of what the tool returns, so the text is redundant rather than efficient.
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 read-only, single-parameter tool in a large family of near-identical `get_*` stats tools, the description omits the key routing information: how this differs from `get_stats`, `get_user_summary`, and `get_body_composition`. There is no output schema, so the description is the only place that distinction could be made, and it is not.
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 `cdate` parameter is fully documented in the schema (YYYY-MM-DD, UTC). The description never references the date parameter, so the baseline 3 applies with no added value.
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 conveys that the result is a merge of a user summary with body-composition averages, which hints at the resource, but it explains the tool in terms of internal functions (`getUserSummary`, `getBodyComposition`) rather than in terms of what the agent gets back. It does not distinguish this merged call from siblings like `get_stats`, `get_user_summary`, or `get_body_composition`.
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?
There is no guidance on when to use this combined call versus calling `get_stats`/`get_user_summary` and `get_body_composition` separately, nor any prerequisites or exclusions. Usage must be entirely inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step counts for one date, as a series of time intervals; [] if there are none.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds one genuinely useful behavior: the empty-result case returns `[]`. Beyond that it says nothing about units, granularity length, or data availability, which is a modest addition over the structured fields.
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?
A single front-loaded sentence that delivers resource, scope, return shape, and edge case with zero filler. Nothing to trim.
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 no output schema, the description carries the return-shape burden and does so (interval series, empty array case). For a one-parameter read tool with full schema coverage this is nearly complete; missing unit/granularity details keep it short of a 5.
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% and there is a single required `cdate` parameter documented as YYYY-MM-DD (UTC). The description adds no format or range detail beyond the schema, so the baseline 3 applies.
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?
Names a specific resource (step counts) with an explicit scope (one date) and return shape (series of time intervals). The 'series of time intervals' phrasing implicitly distinguishes it from aggregate siblings like get_daily_steps and get_weekly_steps, but it never names them, so the differentiation is inferred rather than stated.
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?
No explicit when-to-use or when-not-to-use guidance appears. The 'one date' scope and intraday interval return imply the use case (per-date granular step data) but the agent must infer the tradeoff against get_daily_steps or get_weekly_steps on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Alias of getAllDayStress. Identical URL to getAllDayStress; an alias.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and open-world behavior. The description adds that this is a duplicate alias with the same URL as `getAllDayStress`, which is useful behavioral context, but it does not describe rate limits, auth needs, or return shape.
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 appropriately short and front-loads the alias relationship. The second sentence partially restates the first, but the total length is minimal and not wasteful enough to harm usability.
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 simple alias tool with a fully described schema and read-only annotations, the description provides enough context to understand that it duplicates `getAllDayStress`. No output schema exists, so return values need not be explained.
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 single `cdate` parameter is already fully documented as a YYYY-MM-DD UTC date. The description adds no parameter-specific meaning beyond the schema, making the baseline 3 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 tool is an alias of `getAllDayStress` with an identical URL, which implies retrieving all-day stress data and distinguishes it as a duplicate endpoint. It is clear in context, though it does not independently state the verb and resource without relying on knowledge of the sibling.
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 says it is an alias but gives no guidance on when to use this tool versus `get_all_day_stress` or whether one should be preferred. The only implied usage is interchangeability, which is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One phased training plan by id. GETs /trainingplan-service/trainingplan/phased/{planId}.
| Name | Required | Description | Default |
|---|---|---|---|
| planId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's only behavioral addition is restating it as a GET plus the raw endpoint path. It discloses nothing about what a phased plan contains, error behavior for a missing planId, or auth requirements â the endpoint string is opaque metadata rather than useful context.
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-loaded with the purpose before the endpoint detail. Efficient, though the raw service path is arguably wasted tokens for an agent.
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 read with no output schema, the definition is minimally adequate but stops short: it does not explain what a phased training plan is, how it differs from adaptive plans or the plans list, or what the call returns. No output schema exists to 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 description coverage is 100% ('Numeric id' on planId), so the schema carries the parameter documentation. The description adds nothing beyond 'by id', which is the baseline 3 for a fully covered single parameter.
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?
States a specific verb and resource ('One phased training plan by id'), and the qualifier 'phased' hints at the distinction from the adaptive variant. However, it never names the sibling tools it must be distinguished from (get_training_plans, get_adaptive_training_plan_by_id), leaving that inference to the agent.
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?
There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_training_plans for listing or get_adaptive_training_plan_by_id for adaptive plans. Usage is only implied by 'by id'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's training plans. GETs /trainingplan-service/trainingplan/plans; no params.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the endpoint path and confirms it takes no parameters, which is minor added context, but says nothing about return shape, pagination, or what a 'training plan' contains.
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?
Very short and front-loaded, with no wasted sentences. It is a fragment rather than a well-formed sentence, which is a stylistic weakness but not verbosity.
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 no-param, read-only list tool this is close to adequate, but with no output schema the agent learns nothing about what a returned training plan looks like, and the absence of any usage guidance among many plan-related siblings leaves a gap.
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, so the baseline is 4. The description's 'no params' note is consistent with the empty schema but adds nothing beyond it.
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 fragment 'The account's training plans' plus the GET path conveys that this retrieves training plans for the account, and the plural 'plans' implicitly distinguishes it from the by_id sibling. But there is no explicit verb ('list'/'retrieve') and no scope detail (all plans vs. active), so it is only vaguely differentiated from get_training_plan_by_id and get_training_plan_workouts.
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?
No when-to-use guidance and no named alternatives, despite several sibling tools (get_training_plan_by_id, get_adaptive_training_plan_by_id, get_training_plan_workouts) that an agent must choose among. Usage is only inferable from the plural noun.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enrolled training plans' workouts around a date, grouped by plan. POSTs GraphQL trainingPlanScalar(calendarDate, lang, firstDayOfWeek) (all three arguments are REQUIRED by Garmin) and unwraps trainingPlanWorkoutScheduleDTOS: one entry per enrolled plan, {trainingPlanId, planName, trainingPlanClassification, trainingPlanDetailsDTO, workoutScheduleSummaries}. Garmin picks the window (18 workouts across several weeks for an ITP plan); [] with no plan.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| calendarDate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/openWorldHint already covering safety, the description adds real context: the underlying GraphQL call, that Garmin chooses the window (~18 workouts over several weeks), and that an unenrolled user gets `[]`. It stops short of rate limits or pagination, but discloses return shape and the empty-state edge case.
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?
Front-loaded with purpose, then behavior, then edge case â efficient ordering with no filler. The GraphQL signature and DTO field dump are heavier than most agents need, keeping it just short of ideal brevity.
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?
There is no output schema, and the description compensates by enumerating the returned entry keys (trainingPlanId, planName, classification, detailsDTO, workoutScheduleSummaries) and the empty case. For a 2-parameter nested-schema read tool this is nearly sufficient; only the `lang` value space is left undefined.
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 50% (only calendarDate is described). The description compensates by naming all three GraphQL arguments and asserting lang and firstDayOfWeek are REQUIRED by Garmin, which tells the agent to populate the otherwise-undocumented nested `options` object. It still omits valid `lang` values, so it doesn't fully close the gap.
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?
States a specific verb+resource with scope: 'Enrolled training plans' workouts around a date, grouped by plan.' The 'enrolled' + 'grouped by plan' qualifiers separate it from sibling readers such as get_scheduled_workouts, get_adaptive_workout, and get_training_plans without needing to open any schema.
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 never says when to choose this over the many adjacent tools (get_scheduled_workouts, get_training_plan_by_id, get_next_scheduled_workout). The only usage signal is implicit: it covers enrolled-plan workouts. No exclusions, prerequisites, or alternative-routing guidance are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Training readiness entries for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds a useful scope signal (one date) but does not disclose return format, freshness, or permission details. This matches the lower bar when annotations carry the safety context.
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 a single front-loaded sentence with no filler or repetition, making it appropriately sized for a simple one-parameter read tool.
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 simple read with full schema coverage and annotations, invocation is adequately covered. However, with no output schema, the description does not explain what a 'training readiness entry' contains, leaving return expectations implicit.
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% and the sole parameter cdate is fully documented with format and timezone. The description's 'for one date' merely echoes that schema and adds no syntax or constraints beyond it, so the baseline of 3 applies.
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 identifies a specific resource (training readiness entries) and a scope constraint (one date), which is enough to distinguish it from most CRUD siblings. It does not separate it from close siblings like get_morning_training_readiness or get_training_status, so it stops short of a 5.
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 implies the tool is called for a single calendar date but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer tool selection from the name and sibling list alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Training status for one date.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds only the constraint that the result is scoped to a single date; it says nothing about what data is returned, whether a date with no training yields empty data, or any other behavior beyond annotations.
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?
A four-word fragment with zero waste and the scope constraint front and center. It is appropriately sized, though the extreme terseness edges toward under-specification rather than tight structure.
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 no output schema, the description carries the burden of explaining what 'training status' actually returns, and it does not. An agent knows only that it gets something called a status for a date, which is insufficient to judge whether the call answers its question.
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% and the single cdate parameter is fully documented in the schema (format, YYYY-MM-DD, UTC). The description's 'for one date' reinforces the single-date semantics but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
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 identifies the resource (training status) and its scope (one date), and the name supplies the verb. However, it barely goes beyond restating the tool name and never defines what 'training status' contains, nor distinguishes it from close siblings like get_training_readiness, get_morning_training_readiness, or get_daily_stats.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives, despite several sibling tools (get_training_readiness, get_morning_training_readiness) that an agent could easily confuse with this one. The only implied usage is 'pass a date'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cached per instance; every date-scoped endpoint needs the display name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description does add one genuinely non-obvious behavioral fact not present in structured data: the result is cached per instance, warning the agent that the value may be stale. It does not cover return shape or staleness lifetime, so it is a modest add-on rather than rich disclosure.
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?
It is short with no filler, which is good, but it is a single semicolon-joined fragment that leads with an implementation detail (caching) rather than a front-loaded statement of what the tool returns. Brevity here shades into under-specification rather than efficiency.
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?
There is no output schema, so the description carries the full burden of explaining the return value, and it only obliquely implies the display name is returned without listing any other profile fields. For a read tool with numerous near-duplicate siblings and no structured output contract, the description is too thin for an agent to call it confidently.
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 takes zero parameters and the schema is fully closed (additionalProperties: false, 100% coverage), so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are missing.
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 never states what the tool does. 'Cached per instance; every date-scoped endpoint needs the display name' only hints that a display name is the payload and that the result is cached; it does not say 'returns the authenticated user's profile.' An agent must infer the verb and resource from the tool name alone, and the presence of siblings like display_name, full_name, user_name and get_userprofile_settings makes that inference riskier.
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?
There is a faint usage cue ('every date-scoped endpoint needs the display name'), which suggests when the value is consumed, but no explicit when-to-call guidance and no differentiation from the many overlapping siblings (display_name, full_name, user_name, get_user_settings, get_user_summary). The agent is left to guess whether this or a sibling is the right lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's profile settings record, from /userprofile-service/userprofile/settings. Distinct from getUserSettings() ("user-settings"): the two paths are one character apart. GETs /userprofile-service/userprofile/settings (SINGULAR "settings", distinct from getUserSettings's "user-settings"; the two paths are one character apart and easy to transpose) Three profile endpoints, three methods: getUserProfile() reads /userprofile-service/socialProfile (and backs displayName/fullName/userName), getUserSettings() reads /userprofile-service/userprofile/user-settings (and backâĻ
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds endpoint-path context that helps disambiguate the call, but says nothing about the returned settings shape, latency, or error behavior. With annotations doing the heavy lifting, this is a modest but real contribution.
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 restates the same path/sibling distinction three times ('Distinct from getUserSettingsâĻ', 'the two paths are one character apart', 'SINGULAR settingsâĻ one character apart and easy to transpose') and then terminates mid-sentence. It is not front-loaded and wastes a large fraction of its length on repetition.
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?
There is no output schema, so the description would ideally hint at what the settings record contains, but it does not. For a zero-parameter read tool with readOnlyHint annotations the essentials are present, yet the truncated ending leaves the sibling comparison unfinished.
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 takes zero parameters (empty schema, additionalProperties false), so there is nothing for the description to disambiguate. Per the zero-parameter baseline this sits at 4; the description adds no parameter detail because none exists to add.
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?
States a specific resource â the account's profile settings record â and explicitly distinguishes it from sibling tools getUserSettings and getUserProfile by path. The verb is implied via 'GETs', so the purpose is recoverable, though the repetition about paths being 'one character apart' muddies rather than sharpens the distinction.
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 enumerates three related endpoints and their backing fields, which gives implicit routing guidance, and names the alternatives (getUserProfile, getUserSettings). However, it never states a clean when-to-use-this rule, and the text is cut off mid-sentence ('and backâĻ'), so the guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cached per instance, same eviction-on-failure pattern as getUserProfile().
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuine behavioral trait beyond them (per-instance caching with eviction-on-failure, meaning repeated calls may serve stale data and a failed call clears the cache), but it omits return shape and scope of the settings themselves.
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?
It is a single short sentence with no padding, but it is under-specified rather than concise and is front-loaded with an implementation detail instead of the tool's purpose.
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 no output schema and no parameters, the description carries the full burden of telling the agent what this returns and how it differs from get_user_profile, get_userprofile_settings, and get_device_settings. It does none of that, leaving the agent unable to distinguish it from sibling getters.
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 takes zero parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.
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 never states what the tool does or what settings it returns; it only describes an internal caching trait. It relies entirely on the name 'get_user_settings' plus the annotation title to convey purpose, which is a restatement rather than an explanation.
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?
No when-to-use, when-not-to-use, or alternative is given, despite close siblings like get_user_profile, get_userprofile_settings, and get_device_settings that an agent must choose between. The caching note does not help select the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The daily summary for one date: steps, distance, calories and the rest of the day's totals.
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and data-source profile are covered. The description adds only that the result is scoped to one date; it says nothing about pagination, timezone handling beyond the schema, or freshness. Adequate but not additive.
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?
A single front-loaded sentence that states the scope first and then the payload. Efficient overall, though the trailing 'and the rest of the day's totals' is vague filler that adds no 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?
For a simple one-param read with no output schema, the description gives a partial field list but leaves 'the rest of the day's totals' undefined, so an agent cannot anticipate the full response shape. With no output schema, a more concrete enumeration of returned metrics would be needed for a higher score.
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 cdate is documented as 'Calendar date, YYYY-MM-DD (UTC)'. The description's 'for one date' merely echoes the schema without adding format or constraint detail, so the baseline 3 applies.
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?
Clear verb+resource: returns the daily summary for a single date, and enumerates the key contents (steps, distance, calories). However, it does not differentiate itself from close siblings like get_daily_stats, get_daily_steps, or get_calories_daily, which an agent browsing 130+ tools would likely confuse with it.
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?
No when-to-use guidance, no exclusions, and no pointer to the overlapping siblings (get_daily_stats, get_daily_steps, get_calories_daily). The 'one date' scoping is implied by the schema's single required param but never framed as a selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weekly intensity-minute totals between two dates.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| start | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds only the date-range scope and does not disclose the return format, how weekly aggregation is defined, timezone handling, or whether results are grouped by week. This is minimal added behavioral context.
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 a single, front-loaded sentence with no wasted words. It efficiently communicates the scope and resource without unnecessary elaboration.
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 simple two-parameter read tool with full schema coverage and safety annotations, the description is minimally adequate. However, without an output schema, it should describe the return value (e.g., weekly totals grouped by week) or how weeks are defined, which it does not.
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%, fully documenting the start and end date parameters with format details. The description implies date-range filtering but adds no syntax or meaning beyond what the schema already provides, so the baseline of 3 applies.
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 verb implicitly ('totals') and resource ('weekly intensity-minute'), making the tool's purpose clear. However, it does not distinguish itself from the sibling tool get_intensity_minutes_data, leaving an agent to guess which one provides weekly aggregates versus other intensity data.
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 offers no guidance on when to use this tool versus alternatives, such as get_intensity_minutes_data or get_weekly_steps. There is no mention of prerequisites, exclusions, or typical use cases beyond the implied retrieval of weekly totals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weekly step totals for the weeks weeks (default 52) ending on end. weeks defaults to 52, must be a positive integer.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| weeks | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the default window (52 weeks) and the input constraint (positive integer), which is useful but thin; it says nothing about how the totals are bucketed or returned.
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-loaded with the scope. It repeats the weeks default twice, a small redundancy, but nothing else is wasted.
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 simple read tool with annotations covering safety, the description is nearly adequate, but with no output schema it never hints at the return shape (one total per week? which week boundaries?). An agent can call it, but its expectations of the result are unguided.
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 only 50% â `end` is documented but `weeks` is not. The description compensates by giving the default (52) and the validity constraint (positive integer), which the schema does not carry.
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?
States a specific verb+resource ('weekly step totals') plus the window it covers, so an agent can distinguish it from get_daily_steps or get_weekly_stress without opening the schema. It doesn't explicitly name those siblings, so it falls short of the top tier.
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?
There is no guidance on when to use this tool versus the many nearby alternatives (get_daily_steps, get_steps_data, get_weekly_intensity_minutes). The weekly granularity is implied by the name and description but never framed as a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weekly stress averages for the weeks weeks (default 52) ending on end. Same weeks default/validation as getWeeklySteps.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| weeks | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the default window size (52 weeks) and the anchoring semantics ('ending on end'), which is genuine behavioral context. It says nothing about auth requirements, rate limits, or whether partial weeks are included.
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-loaded with the return semantics and the window anchor. Every clause carries information and there is no 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 simple read tool with readOnly annotations and no output schema, the description covers the essential contract: what is returned, the window, and the default. The remaining gap is the unresolved 'weeks' validation, which is handed off to a sibling rather than explained.
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 50%: 'end' is documented in the schema, while 'weeks' has no schema description. The description compensates partially by disclosing the default (52) and pointing to getWeeklySteps for validation, but it defers the actual rules to another tool rather than stating units, bounds, or type, so the agent cannot fully resolve 'weeks' semantics from this definition alone.
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 specific verb+resource ('Weekly stress averages') and the aggregation window ('weeks weeks ending on end'), so an agent immediately knows it returns weekly-bucketed stress data. However, it does not differentiate from closely related siblings like get_stress_data, get_all_day_stress, or get_weekly_intensity_minutes, so the agent must infer the distinction.
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?
There is no explicit when-to-use or when-not-to-use guidance. The mention of getWeeklySteps is only a cross-reference for parameter validation, not a routing hint, and no alternative tool is named for related stress queries. The agent is left to infer that this is the weekly-aggregate counterpart to get_stress_data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Weigh-ins between two dates.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the date-range scoping, which is already implied by the required startdate/enddate params; it discloses nothing about result volume, ordering, or pagination.
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?
A single front-loaded sentence with zero waste. It is arguably too terse, but nothing in it is redundant or padded.
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 two-param read tool with full schema coverage and no output schema, this is minimally adequate. It leaves open what the return payload looks like and how many records come back for a wide date range, but the annotations and schema cover the essentials.
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% and both parameters are fully documented in the schema (YYYY-MM-DD UTC). The description adds no format or boundary detail beyond what the schema provides, so the baseline 3 applies.
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?
States the resource (weigh-ins) and scope (between two dates), which is a specific verb+resource. However, it does not differentiate from the close sibling get_daily_weigh_ins or get_body_composition, and the fragment lacks a verb to make the action 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?
No guidance on when to use this versus get_daily_weigh_ins, get_body_composition, or the range-based alternatives. The agent must infer the date-range condition from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The weight goals in effect between two dates, in grams. GETs /goal-service/goal/user/effective/weightgoal/{start}/{end}: {userGoals, userGoalRanges}, weights in GRAMS (PersonalApi.UserGoalsRangeDTO). No range limit found (1000 days answered); a reversed range throws before any request although Garmin itself accepts one.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, it discloses real behavioral traits: no observed range limit (1000 days answered), a reversed range throwing before any request even though Garmin accepts one, and the response envelope ({userGoals, userGoalRanges}) with units. This is exactly the kind of edge-case context annotations cannot convey, though error/permission behavior beyond the reversed-range case is not covered.
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?
It is compact and front-loads what the tool returns before the endpoint and caveats. Some density comes from internal identifiers ('PersonalApi.UserGoalsRangeDTO', the raw path), which are less useful to an agent than the behavioral facts, but no sentence is 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?
With no output schema and only two simple params, the description covers return shape, units, range behavior, and a failure mode â enough to call it correctly. The main remaining gap is not distinguishing it from get_goals, which shares the 'goals' concept and could cause misselection.
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 date formatting is already documented. The description still adds meaning the schema cannot: the ordering constraint on start/end (reversed range throws) and that the returned weights are in grams, not user units.
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 first sentence gives a specific verb and resource ('The weight goals in effect between two dates, in grams') and pins the time window, so an agent knows exactly what it retrieves. It never references the nearby sibling get_goals, which also covers goals, so the boundary between the two is left for the agent to guess.
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?
Usage is only implied by the date-range framing; there is no explicit statement of when to call this versus get_goals, get_weigh_ins, or get_body_composition. The reversed-range note is a calling constraint rather than guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One workout from the library by id.
| Name | Required | Description | Default |
|---|---|---|---|
| workoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds essentially nothing beyond that: no note that a missing/unknown id behaves one way or another, no auth or rate-limit context, and no indication of the returned record's shape beyond the word "one".
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?
A single short sentence with zero filler, front-loading the resource before the lookup key. It is arguably clipped to the point of being a fragment, which keeps it just short of ideal.
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 simple single-parameter read with no output schema and annotations covering the safety profile, this is the minimum viable amount of text. It leaves the return shape and unknown-id behavior unaddressed, which is tolerable but not thorough.
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 a single parameter fully documented in the schema (100% coverage), so the baseline is 3. The description's "by id" restates the schema rather than clarifying the integer-or-string union or what happens when the id does not resolve.
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?
States a specific resource and scope ("one workout from the library") and the lookup key ("by id"). It implicitly distinguishes a single-library-workout fetch from the list tool get_workouts and from get_scheduled_workout_by_id, though it never names those siblings outright.
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?
There is no when-to-use or when-not-to-use guidance, and no alternative is named. The agent must infer from "by id" that an id must already be known and from "library" that this is not the scheduled-workout path; neither point is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A page of the workout library (start defaults to 0, limit to 100). Defaults start=0, limit=100, stays nullable (does NOT coalesce to []).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: default paging values and the notable 'stays nullable (does NOT coalesce to [])' return semantic. It stops short of describing ordering or what a workout entry contains.
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 states the same fact twice â 'start defaults to 0, limit to 100' and then 'Defaults start=0, limit=100' â which is pure redundancy. The content is short but poorly front-loaded, leading with a fragment rather than a clear statement of purpose.
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 two-parameter paginated read tool with annotations covering the safety profile and no output schema, the description covers defaults and the null-vs-empty-array behavior. It is minimum viable but omits result ordering and how the 'library' relates to scheduled or user workouts.
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 0%, so the schema documents nothing. The description compensates partially by giving defaults for both parameters (start=0, limit=100), but it never explains offset/limit semantics or the effect of large limit values. Adequate but incomplete given the zero-coverage 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 phrase 'a page of the workout library' names the resource and implies a paginated list, but the verb is only implicit and the description is dominated by pagination mechanics rather than stating its purpose. It does not distinguish itself from siblings like get_workout_by_id, get_scheduled_workouts, or get_training_plan_workouts.
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?
There is no statement of when to use this tool versus the many workout-related siblings, nor any prerequisites or exclusions. The only content is pagination defaults, which is invocation detail, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether the account has a Garmin Connect+ subscription, from the cached user profile. The methods in CONNECT_PLUS_METHODS need it and throw GarminConnectPlusRequiredError without. Whether the account has a Garmin Connect+ subscription, read from the cached user profile (/userprofile-service/socialProfile, so usually no extra request): true when hasPremiumSocialIcon is true or userRoles holds any ROLE_SP_FEATURE_n entry. The methods in CONNECT_PLUS_METHODS (searchFoods, getCustomFoods, getCustomFoodServingUnits, createCustomFood, updateCustomFood, deleteCustomFoodâĻ
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the value comes from the cached user profile at /userprofile-service/socialProfile, so it usually costs no extra request, and the true condition is defined via hasPremiumSocialIcon or a ROLE_SP_FEATURE_n role.
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 lead sentence is repeated verbatim before the description continues, which is pure duplication, and the text ends mid-list in an ellipsis. The front-loaded opening is fine, but a third of the text earns nothing.
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 no output schema, the description carries the return semantics and does so: a boolean derived from hasPremiumSocialIcon or userRoles, read from cache. It also ties the result to the error other methods raise. Only the truncated method list leaves a small gap.
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 are zero parameters, so the baseline of 4 applies. Nothing in the description misrepresents the (empty) input surface.
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 resource and predicate: whether the account holds a Garmin Connect+ subscription. No sibling tool covers subscription status, so it is distinguishable, but the duplicated opening sentence and the truncated method list ('deleteCustomFoodâĻ') keep it short of a clean 5.
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 explicitly names the condition that makes this relevant: the methods in CONNECT_PLUS_METHODS need it and throw GarminConnectPlusRequiredError without it, and it enumerates several of those methods. It does not advise when to call it proactively as a preflight check, but the when-to-use signal is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Imports a .fit, .gpx or .tcx file as an activity. A duplicate raises GarminConnectionError. Multipart upload to /upload-service/upload/{ext} (extension from filename, must be fit/gpx/tcx) with the load-bearing NK/origin/custom User-Agent headers that make Garmin treat it as an import rather than a device sync; a 409 is re-raised as GarminConnectionError ("Activity already exists (duplicate):...").
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to a local .fit, .gpx or .tcx file (~ is expanded) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and openWorldHint=true, but the description goes further by disclosing failure semantics: a duplicate raises GarminConnectionError and a 409 is re-raised as 'Activity already exists (duplicate)'. This is valuable error-handling context beyond the annotations.
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 purpose is front-loaded, but the second sentence is bloated with implementation detail (endpoint path, NK/origin/User-Agent headers) that does not help an agent decide or invoke correctly.
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-param mutation with no output schema, the definition still omits what a successful import returns (an activity id? the created object?), leaving the agent unable to chain follow-up calls. Auth/account prerequisites are also only hinted at via header jargon.
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 filePath param is already documented as an absolute path with ~ expansion. The description adds only that the extension is derived from filename and must be fit/gpx/tcx, which duplicates the schema's format list rather than extending it.
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?
States a specific verb+resource ('Imports a .fit/.gpx/.tcx file as an activity') and names the accepted input formats. It does not, however, distinguish itself from the sibling 'upload_activity', which an agent will likely confuse it with.
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?
There is no explicit when-to-use guidance, no prerequisites, and no mention of the near-identical sibling 'upload_activity' or 'create_manual_activity'. The agent must infer when to prefer this over those alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parses a GPX file into a course WITHOUT saving it (courseId: null). Multipart POST (field file) to /course-service/course/import. Parses only, saves NOTHING: the result has courseId: null and a RESAMPLED track (13 GPX points came back as 37) with null elevations/timestamps; courseName is the GPX <name>. Only .gpx accepted (only .gpx verified); throws GarminError on an empty response.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to a local .fit, .gpx or .tcx file (~ is expanded) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses the transport (multipart POST, field `file`), the endpoint, that nothing is persisted, the resampling behavior (13 GPX points return as 37) with null elevations/timestamps, and the empty-response error. One tension worth noting: readOnlyHint=false implies possible state modification while the description insists nothing is saved; the description is the more accurate account, but the mismatch is not spelled out.
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?
Front-loaded with the key fact (parse, do not save) and wastes little. It is densely packed with bold, parentheticals and a concrete numeric example (13 -> 37) that borders on over-detailed, but every sentence still carries actionable 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?
There is no output schema, so the description carries the return-shape burden and does so: courseId stays null, the track is resampled, elevations/timestamps are null, and courseName comes from the GPX `<name>`. Error behavior and accepted file type are also covered, so nothing an agent needs to call it correctly 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?
Schema coverage is 100%, so baseline is 3, but the description adds a constraint the schema does not carry: only `.gpx` is accepted/verified, while the schema's own description advertises `.fit`, `.gpx` or `.tcx` for this field. That narrowing meaningfully reduces the chance of a rejected call.
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?
States a specific verb+resource (parse a GPX into a course) and immediately qualifies scope with 'WITHOUT saving it' and 'courseId: null', which separates it from the sibling create_course_from_gpx. An agent can pick between preview-parse and persist-create without opening either schema.
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 'Parses only, saves NOTHING' framing makes the use case clear (parse/preview when you do not want persistence) and the failure mode ('throws GarminError on an empty response') is stated. It never names create_course_from_gpx as the alternative when persistence is desired, so the routing guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets up cycle tracking from a first period start date and average period and cycle lengths. Account-level and not undoable; not meant for an account that is already set up. Does NOT also update tracking-preference settings (call updateMenstrualSettings separately for that); not intended for an already-configured account.
| Name | Required | Description | Default |
|---|---|---|---|
| cycleLength | Yes | ||
| periodLength | Yes | ||
| periodStartDate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds value the annotations don't: this is account-level scoped and irreversible ('not undoable'), which is critical context for a mutation. It does not disclose auth requirements or what is returned, but with annotation coverage the bar is lower.
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?
Front-loaded with the core action, which is good, but the closing clause ('not meant for an account that is already set up' / 'not intended for an already-configured account') restates the same exclusion twice, wasting space in an otherwise short description.
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 3-param, no-output-schema, one-shot account initializer, the description covers the essentials an agent needs: irreversibility, account-level scope, the not-already-set-up precondition, and the companion settings call. Missing only parameter units and any error/conflict behavior on return.
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 only 33% (only periodStartDate is documented), so the description must compensate. It does add real meaning â periodStartDate is the *first* period start and the two lengths are *averages* â but it never states units (days?) or plausible ranges for periodLength/cycleLength, leaving the two undocumented numeric params ambiguous.
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?
States a specific verb and resource ('Sets up cycle tracking') plus the exact inputs it seeds the setup from (first period start date, average period/cycle lengths). An agent can distinguish it from siblings like confirm_menstrual_period_start and update_menstrual_settings without opening any schema.
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?
Gives an explicit when-not ('not meant for an account that is already set up') and names the alternative for the adjacent task ('call updateMenstrualSettings separately' for tracking preferences). The agent is told both the exclusion condition and the correct sibling to route to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every event between two dates, inclusive, or every event on the account with no dates. Events also appear in getScheduledWorkouts' month feed as itemType event; this GETs /calendar-service/events, with startDate/endDate when both dates are given (inclusive) or no params for every event on the account; one date alone throws.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | No | Calendar date, YYYY-MM-DD (UTC) | |
| startdate | No | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and openWorldHint, so the safety profile is set. The description adds non-obvious behavior: date bounds are inclusive and supplying exactly one date is an error, plus the underlying endpoint path. That is meaningful context beyond the annotations.
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 purpose is front-loaded, but the second sentence crams the endpoint path, parameter behavior, and a sibling cross-reference into one run-on clause. The raw '/calendar-service/events' detail adds implementation noise without helping an agent invoke the tool.
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 two-optional-param list tool with no output schema, it covers both invocation modes, the inclusivity rule, the single-date failure case, and where the same data appears elsewhere. Return format is left unstated, but no output schema exists and the annotations plus description are otherwise sufficient.
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% (baseline 3), but the description adds real meaning: startDate/endDate must be supplied together, are interpreted inclusively, and a lone date throws rather than being ignored. This coordinates the two optional params beyond their individual schema docs.
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?
States a specific resource and scope: every calendar event between two inclusive dates, or all events when no dates are given. It is clear what the tool returns, though it does not explicitly distinguish itself from the singular get_calendar_event or get_all_day_events siblings.
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?
Explains the two invocation modes (both dates given -> filtered; no params -> all events) and warns that a single date throws. It also names the related getScheduledWorkouts month feed where events also surface, giving context for choosing between sources, though it states no explicit when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every saved course, as { coursesForUser: CourseSummary[] }. GETs /web-gateway/course/owner/ (trailing slash included); returns an ENVELOPE { coursesForUser: CourseSummary[] }, not a bare array.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description still adds real behavioral value by disclosing the response is an envelope `{ coursesForUser: CourseSummary[] }` rather than a bare array, which matters because there is no output schema. It does not mention pagination or result limits, so it stops short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and front-loaded, but the return shape is stated twice in two sentences ('as `{ coursesForUser: CourseSummary[] }`' and again 'returns an ENVELOPE `{ coursesForUser: CourseSummary[] }`'), which is redundant. The endpoint path and trailing-slash note are useful, but the duplication costs it.
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 no input parameters and no output schema, the only thing an agent needs beyond the annotations is the return shape, and the description supplies it along with the underlying endpoint. Absent detail on pagination or whether results are capped keeps it from a 5.
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 takes zero parameters, so per the rubric the baseline is 4. Nothing about arguments needs explaining and the description does not invent any.
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?
States a specific verb and resource: it returns every saved course, which cleanly separates it from the single-course siblings get_course and get_course details. It never names a sibling explicitly, but the scope word 'Every' does the differentiation work on its own.
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?
Usage is implied rather than stated: 'Every saved course' makes clear this is the list-all option versus get_course for one course, but there is no explicit when/when-not guidance and no mention of alternatives such as filtering or searching. With no parameters there is little to mis-select, so this is adequate but not instructive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Logs a catalogue or custom food into a meal. Needs Connect+. PUTs /nutrition-service/food/logs with one REGULAR_LOG item and returns the whole day's log. FoodLogInput = {date, foodId, servingId, servings? = 1, time?, meal?, source? = "GARMIN", regionCode?, languageCode?}. Pass the catalogue food's source/regionCode/languageCode for a search result. Needs a mealId, which only exists after Garmin's nutrition setup in the app (400 mealId must not be null otherwise; this method throws a clearer error first). The meal is the named one, else the one whose window holds time, âĻ
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only cover non-readonly/openWorld/non-destructive), the description discloses the subscription/auth requirement, the underlying PUT endpoint and REGULAR_LOG payload shape, the precondition on mealId, the 400 error condition, and that it returns the whole day's log. That is substantial behavioral context an agent cannot infer from annotations.
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 key constraint (Connect+ requirement, then the mealId precondition) is front-loaded and every sentence carries information. It is dense with internal jargon and the trailing ellipsis shows it is truncated mid-sentence, which slightly hurts structure.
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 nested-object mutation tool with no output schema, it covers the return value (the whole day's log), the auth prerequisite, the precondition and the failure mode. The visible truncation means some explanatory content is cut off, so it is strong but not fully 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?
Schema coverage is reported at 0%, so the description carries the load: it restates the full FoodLogInput shape with defaults (servings=1, source=GARMIN) and adds cross-field guidance (pass the catalogue food's source/regionCode/languageCode for a search result). foodId and servingId still lack meaning anywhere, which keeps it below 5.
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 gives a specific verb (logs) and resource (a catalogue or custom food into a meal), and the added detail about source/regionCode/languageCode for a search result distinguishes it from create_custom_food and quick_add_food. An agent can tell exactly what this tool does without opening the schema.
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 clearly states prerequisites: a Garmin Connect+ subscription (with the sibling has_connect_plus named as the check) and a mealId that only exists after Garmin's in-app nutrition setup, plus the 400 failure otherwise. It stops short of explicitly contrasting when to use this versus quick_add_food, so it is clear context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a workout and show it in readable form WITHOUT saving anything. Always call this first, show the user the result, and wait for them to confirm before create_workout. Paces are minutes as decimals (4:30 = 4.5), distances metres, times seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | A Garmin workout. Give `steps` for one sport, or `legs` (each with its own sport) for a multi-sport workout, not both. Distances are metres, times seconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that ('WITHOUT saving anything'). It adds real behavioral context beyond the annotations: the mandatory human-in-the-loop step (show result, wait for confirmation) and the unit conventions for the input values. It does not describe error/validation behavior, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, zero filler, and the most important constraint (no saving) plus the mandatory ordering are front-loaded before the unit conventions.
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 deeply nested workout-spec input this covers the essential invocation workflow and units, but with no output schema the description only gestures at the return value ('show it in readable form') and never says whether validation errors are reported or what the preview output contains.
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% and the nested spec/step/target objects are richly annotated, so the schema already carries parameter meaning. The description's unit note (decimal-minute paces, metres, seconds) largely restates what the schema's own field descriptions say, so it adds little beyond the baseline.
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?
States a specific action (preview/show a workout in readable form) and a hard scope constraint (WITHOUT saving anything), which cleanly separates it from create_workout, named explicitly. An agent can tell exactly what this tool does and does not do.
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?
Gives an unambiguous workflow: 'Always call this first, show the user the result, and wait for them to confirm before create_workout.' It names the alternative tool and the condition (user confirmation) that gates it, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a workout to a device. Defaults to the newest workout and the most recently used device. Multi-call: resolves a missing deviceId via /device-service/deviceservice/mylastused's userDeviceId, a missing workoutId via getWorkouts(0,1)'s first result (throws if none), then reads getWorkoutById(workoutId).workoutName for the push message on the final POST.
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | No | Numeric id | |
| workoutId | No | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description goes further by disclosing the internal multi-call resolution chain, the specific endpoints used, and that it throws when no workouts exist. It stops short of describing the final POST's side effects or error surface, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and defaults, then a compact sentence describing the resolution sequence. Dense but every clause carries information; only the endpoint path detail is arguably more than an agent needs.
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 no output schema, the description still conveys the side-effecting nature of the call, the fallback resolutions, and the failure mode (throws when no workout exists). Annotations already cover the read/destructive/open-world profile, so the remaining gap is only in the response format, which is minor.
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 both parameters are trivially described as 'Numeric id', so the baseline would be 3. The description adds genuine meaning: it explains that a missing deviceId is resolved via mylastused's userDeviceId and a missing workoutId via getWorkouts(0,1), turning two opaque optional ids into self-resolving arguments.
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?
States a specific verb and resource ('Sends a workout to a device') and immediately specifies the default operand selection, which is the key behavioral fact for this tool. It does not name sibling tools like download_workout or get_workout_by_id, so the differentiation from related read/push tools is left to inference, keeping it below a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates that both parameters are optional and what happens when they are omitted (newest workout, most recently used device), which implies when the tool can be called bare. However, it never states prerequisites (e.g., that the user must have a paired device) nor contrasts the call with alternatives such as preview_workout or schedule_workout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Logs an entry by name and macros ("Quick Add"). Needs Connect+. PUTs /nutrition-service/food/logs/quickAdd: an entry by name + calories/carbs/protein/fat with no food behind it (QUICK_ADD). Same meal rules as logFood.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful behavior: a subscription gate, the PUT endpoint shape, the QUICK_ADD entry type, and that meal-selection rules are inherited from logFood. It does not say what happens on a duplicate entry or how the created entry is identified.
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?
Front-loaded with the blocking prerequisite, then the payload and endpoint. Every clause carries information, though 'Needs Connect+' repeats the opening subscription sentence almost verbatim and could be cut.
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 nested-object mutation with no output schema, the description supplies the prerequisite, endpoint, entry type, and a pointer to logFood's meal rules. The remaining gap is that macro units/scale are never stated, which matters for a nutrition-logging call.
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 reported at 0% and five of six required fields (name, calories, carbs, protein, fat) have no schema descriptions. The description partially compensates by enumerating exactly those macro fields and stating they carry no backing food, but it gives no units for the macros or semantics for the required `input` wrapper.
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?
States a specific verb and resource ('Logs an entry by name and macros') and explicitly names the differentiator from its closest sibling: the entry has 'no food behind it (QUICK_ADD)', unlike log_food. An agent can distinguish this from log_food and create_custom_food without opening a schema.
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?
Names the prerequisite (Connect+ subscription, with the concrete check via has_connect_plus) and points to the contrast case by describing the no-backing-food scenario. It never explicitly says 'use log_food when the food exists', so the alternative routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unlinks a piece of gear from an activity. PUT, not DELETE; same 404-handling pattern as addGearToActivity.
| Name | Required | Description | Default |
|---|---|---|---|
| gearUUID | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds genuinely new behavioral context beyond that: the HTTP method is PUT rather than DELETE, and it inherits a 404-handling pattern from the sibling â both useful for an agent anticipating error behavior.
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 with zero filler; the core action is front-loaded and the method/error nuance follows. Every clause earns its place.
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?
No output schema, but annotations cover the safety profile, and the description adds the method and error-handling pattern. What remains thin is per-parameter meaning, which leaves the definition slightly incomplete for a 2-required-param mutation tool.
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 only 50% (activityId is documented as "Numeric id", gearUUID has nothing), and the description never mentions either parameter, so it does not compensate for the gap. Names are self-explanatory, keeping this at the minimum-viable baseline rather than below it.
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 ("Unlinks") plus the exact resource boundary ("a piece of gear from an activity"), which is unambiguous and clearly the inverse of the sibling `add_gear_to_activity`. An agent can distinguish it from delete_gear or set_gear_activity_defaults without opening the schema.
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?
Usage is implied by naming the counterpart operation (`addGearToActivity`), so the agent can infer this is the removal path. However, there is no explicit statement of when to use this versus alternatives like `delete_gear`, nor any prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Asks Garmin to reload a day's wellness data that it has offloaded. POSTs /wellness-service/wellness/epoch/request/{cdate} with no JSON body; asks Garmin to reload/recompute a day's data (Garmin offloads older data, so this forces it back).
| Name | Required | Description | Default |
|---|---|---|---|
| cdate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description goes beyond them by disclosing the mechanism (POST with no JSON body) and the reason Garmin needs it (older data is offloaded, this forces it back), which is real context an agent could not infer. It stops short of saying whether the reload is async or what the response indicates.
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 core action is front-loaded, but the description restates itself: 'reload a day's wellness data that it has offloaded' is repeated as 'reload/recompute a day's data (Garmin offloads older data, so this forces it back).' The redundancy costs space without adding new 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?
For a single-parameter, no-output-schema tool this covers what the agent needs: the action, the endpoint, the body format, and the rationale. Missing only the outcome semantics (does it block, does it return confirmation, how long before data is available), which keeps it from being fully 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?
Schema description coverage is 100%, so the baseline is 3, but the description adds value the schema does not: the path template `/wellness-service/wellness/epoch/request/{cdate}` shows the date is a path segment rather than a query or body field. It does not add format constraints beyond the schema's YYYY-MM-DD (UTC).
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 gives a specific verb (reload/recompute) and resource (a day's offloaded wellness data), and even names the exact endpoint. No sibling tool does anything similar, so an agent can identify this unambiguously from the list.
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?
Usage is only implied: 'reload a day's wellness data that it has offloaded' suggests calling it when data appears missing or stale. There is no explicit when-to-use statement, no when-not-to-use, and no named alternative or prerequisite (e.g., call after a sync gap).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedules a library workout on a date.
| Name | Required | Description | Default |
|---|---|---|---|
| dateStr | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| workoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds no further behavioral context: it doesn't say whether the workout is pushed to a device, whether duplicate scheduling is rejected, or what happens on conflict. It does not contradict the annotations, but it contributes nothing beyond them.
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?
A single front-loaded sentence with zero padding; the action and its two inputs are stated immediately. It is arguably too terse, but nothing is wasted.
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 two-parameter mutation with no output schema, the essentials (verb, resource, date target) are present and the schema covers parameter detail. Gaps remain around return value, conflict behavior, and whether scheduling has downstream effects on the device/calendar.
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 phrase 'library workout' does clarify that workoutId refers to a workout from the exercise library rather than an activity, adding marginal value over the schema's bare 'Numeric 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?
States a specific verb and resource: scheduling a library workout on a given date. It distinguishes itself from create_workout and unschedule_workout by implication ('schedules', 'library workout'), though it never names those siblings explicitly.
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?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as unschedule_workout, push_workout_to_device, or create_workout. The agent must infer that this attaches an existing library workout to the calendar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One page of activities filtered by text, type, dates, distance, duration, power, location and more. One page from /activitylist-service/activities/search/activities (the getActivities endpoint) with the filters Garmin's Personal API spec documents: search, activityType (a PARENT key, includes its subtypes; a subtype there is a 400), activitySubType, excludedActivitySubTypes, eventType, startDate/endDate, min/max distance (m), duration and elapsed duration (s), elevation gain (m), minAvgPower (W), favorite, excludeChildren, sortBy/sortOrder, requiredFields, `boundâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world safety, yet the description adds real behavioral value: it returns exactly one page, a subtype in activityType yields a 400, an unknown sortBy or requiredFields name silently returns NO activities rather than an error, and Garmin rejects a bounding box wider than 50 km. These silent-empty-result traps are the sort of thing an agent cannot infer from annotations or schema.
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 opening sentence is well front-loaded, but the rest is a sprawling run-on enumeration of every filter that repeats the schema, and the text is truncated mid-word ('boundâĻ'), signaling an incomplete definition that was not curated to fit its purpose.
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 search tool with no output schema, nothing is said about what a returned activity record looks like or whether paging metadata (total counts, next offset) comes back. Combined with the truncation and the missing sibling differentiation, an agent cannot fully predict the response or confirm this is the right list tool.
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 single top-level `filters` parameter is undocumented, but the nested schema already describes every sub-filter in detail (units, inclusive bounds, parent/subtype rules, enum values), so the schema carries most of the burden. The description's parameter contentâa list of filter names with unitsâlargely duplicates rather than extends 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?
States a concrete verb+resource (search activities) and a precise scope: one page of results filtered by text/type/date/metrics. However, it never distinguishes itself from the many sibling list tools (get_activities, get_activities_by_date, get_activities_for_date, count_activities), and calling itself 'the `getActivities` endpoint' actively blurs the line with the `get_activities` sibling.
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?
Usage is implied by the enumerated filters, and useful operational rules are given (activityType must be a PARENT key, subtype â 400, use activitySubType; boundingBox must be â¤50 km). But there is no explicit when-to-use/when-not statement and no routing to alternatives such as get_activities_by_date or count_activities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Garmin exercise names for strength, HIIT, cardio, yoga, pilates and mobility steps. Returns CATEGORY / NAME lines; use them as exercise: { category, name }.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Words to look for, e.g. "back squat" or "push up" | |
| category | No | Only search this category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value by disclosing the return format ('CATEGORY / NAME lines') that would otherwise be unknown, since no output schema exists. It stops short of describing matching semantics or empty-result behavior.
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, zero filler, with the purpose front-loaded and the output contract immediately following. Every clause earns its place.
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 two-parameter read-only lookup with no output schema, the description supplies the missing piece â the shape of the returned lines and how to reuse them. It leaves match semantics and no-result behavior unstated, but nothing critical is absent.
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%: both 'query' (with examples) and 'category' (with the full enum) are fully documented in the schema. The description adds no format or matching detail beyond that, so the baseline 3 applies.
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?
Specific verb ('Find') plus a specific resource ('Garmin exercise names') and an explicit scope covering the exercise-type families (strength, HIIT, cardio, yoga, pilates, mobility). No sibling tool in the list performs exercise-catalog lookup, so an agent can route here unambiguously.
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 tells the agent what to do with the results ('use them as exercise: { category, name }'), which is genuinely useful downstream guidance. It does not say when to prefer this over alternatives, whether query is fuzzy/substring matching, or how category narrows the search â usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). Food catalogue search. Needs Garmin Connect+. GETs /nutrition-service/food/search?searchExpression&start&limit (defaults 0/20): {results: Food[], moreDataAvailable}; catalogue foods carry source: "FATSECRET" and several servings each.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say read-only/open-world, but the description adds the subscription gate, the underlying GET path, pagination defaults (0/20), the response envelope {results, moreDataAvailable}, and the fact that catalogue foods carry source: FATSECRET with multiple servings. That is substantive behavior beyond the annotations.
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 subscription requirement is stated twice in the first two sentences ("Requires a Garmin Connect+ subscription... Needs Garmin Connect+."), which is pure redundancy, and the purpose sentence is buried behind the prerequisite rather than front-loaded. The endpoint/response detail is dense but earns its place.
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 no output schema, the description correctly supplies the return shape and the moreDataAvailable pagination flag, plus the auth prerequisite. The main gap is that the three parameters remain semantically thin (no query format or limit bounds) for a 0%-coverage 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 coverage is 0%, so the description must compensate, and it does partially: it maps the parameters onto searchExpression/start/limit and supplies default values (0 and 20). It still doesn't define the query string format or any cap on limit, so it doesn't fully close the gap.
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?
States a clear verb+resource ("Food catalogue search") and pins the scope to the FATSECRET-sourced catalogue, which implicitly separates it from the sibling get_custom_foods. It never names a sibling directly, so differentiation requires the agent to infer catalogue-vs-custom.
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?
Gives a concrete prerequisite (Garmin Connect+ subscription) and a specific tool to verify it with (has_connect_plus), which is actionable context an agent can act on before calling. It does not, however, say when to prefer this over get_custom_foods, quick_add_food, or log_food.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets an activity's description. Resolves to null on success.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id | |
| description | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is already covered. The description adds one genuinely useful behavioral fact not in the annotations â 'Resolves to null on success' â which matters because there is no output schema, but it omits whether an existing description is overwritten and what happens on failure.
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, action first, return-value behavior second. Nothing is padded and both clauses carry 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?
For a simple two-parameter mutation with no output schema, the 'null on success' note and the annotations cover the essentials. But with the description parameter undocumented in both schema and prose, and no error/prerequisite behavior stated, it is only minimally 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?
Schema coverage is only 50%: the 'description' parameter has no schema description at all, and the 'activityId' doc ('Numeric id') is slightly at odds with a type union of integer|string. The description text adds no parameter guidance to compensate for the gap.
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?
States a specific verb and resource ('Sets an activity's description'), so the operation is unambiguous. However, it does nothing to distinguish itself from near-identical siblings like set_activity_name, set_activity_feel, set_activity_type, or set_activity_perceived_effort.
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 no when-to-use context, no prerequisites (e.g. the activity must exist), and no mention of alternative tools. An agent must infer that this is the write-side counterpart to get_activity_details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Files an activity under an event type, e.g. "race" or "training". Partial PUT /activity-service/activity/{id} with {activityId, eventTypeDTO: {typeKey}}. The typeKey alone is enough; Garmin fills in typeId/sortOrder. Throws GarminError before any request for a key outside the nine.
| Name | Required | Description | Default |
|---|---|---|---|
| eventType | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing that this is a partial PUT, that Garmin backfills typeId/sortOrder, and that an out-of-range key throws GarminError before any request is sent â a useful pre-flight failure mode. It says nothing about auth requirements or reversibility, keeping it out of 5 territory.
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?
Front-loaded with the purpose, then mechanics, then error behavior â three sentences that each carry information. The raw PUT path and DTO shape are implementation detail that could be trimmed, but they are not padding.
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 two-parameter mutation tool with no output schema, the description covers the write semantics, the acceptable inputs, and the failure case. Missing only peripheral details like permission requirements and whether the activity must already exist.
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 only 50% (activityId documented, eventType enum undocumented), so the description must carry weight â and it does, explaining that typeKey is the only field the caller needs and that the enum's nine values are the complete valid set. It does not clarify the integer-vs-string flexibility of activityId.
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?
States a specific verb and resource ('Files an activity under an event type') and makes the scope concrete with examples ('race', 'training'). It does not, however, disambiguate from the adjacent sibling set_activity_type, which is a genuinely confusable operation, so it stops short of a 5.
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?
Usage is implied by the mechanics rather than stated: the agent learns typeKey alone suffices and that invalid keys fail, which effectively tells it how to call the tool. But there is no explicit when-to-use vs set_activity_type or when-not guidance, so it is minimum viable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces ALL of a strength activity's exercise sets with payload. replace-all semantics, payload sent verbatim. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the danger signal is partly redundant, but the description adds real value: replace-all semantics (all existing sets are discarded, not merged) and that payload is sent verbatim. These specifics go beyond what the structured annotations convey.
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-loaded with the core operation and immediately followed by the risk warning. No filler; every clause carries signal.
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 destructive mutation tool with annotations already covering the safety profile and no output schema, the description discloses the critical risk and the replace-all behavior. The main residual gap is the opaque payload shape, which is left unaddressed.
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 50%: activityId is documented ('Numeric id') but payload has no top-level description and its exerciseSets items are opaque ('Any JSON value'). The description clarifies how payload is applied ('sent verbatim', replace-all) but never explains its expected structure, so it only partially compensates for the coverage gap.
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?
States a specific verb ('Replaces') and resource ('a strength activity's exercise sets'), with scope made explicit ('ALL'). This clearly distinguishes it from the read sibling get_activity_exercise_sets, so an agent can tell it is the write counterpart without opening the schema.
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?
Gives one concrete usage rule ('IRREVERSIBLE: confirm with the user before calling'), which is genuinely actionable. However, it offers no guidance on when to use this tool versus alternatives and no prerequisites beyond the confirmation step, so usage is only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
"How did you feel?": 0, 25, 50, 75 or 100, or null to clear it. Partial PUT of summaryDTO.directWorkoutFeel, one of 0/25/50/75/100 ("How did you feel?", very weak to very strong); null clears it. Garmin stores any number (30 read back as 30) that its apps cannot display, so the method refuses anything else.
| Name | Required | Description | Default |
|---|---|---|---|
| feel | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real behavioral context beyond them: it is a *partial* PUT, `null` clears the field, and the method actively refuses values outside the allowed set rather than silently passing them. It does not mention auth requirements or failure modes when the activity is missing.
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 opening quote and the middle clause restate the same fact (the 0/25/50/75/100 domain is given twice, and `null` clearing is stated twice). The information is front-loaded, but roughly a third of the text is duplication.
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 two-parameter mutation with no output schema, the description covers the value domain, the clearing path, and validation behavior. It leaves the schema/description mismatch on `null` and any result/response expectations unaddressed.
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 50% and the `feel` enum carries no description, so the description compensates by naming the five admissible values, their meaning scale (very weak to very strong), and the clearing semantics. Note the description's `null`-clears behavior is at odds with the schema, which requires `feel` and offers no null branch â helpful for the agent to know, but unexplained.
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?
States a specific verb and target field: a partial PUT of `summaryDTO.directWorkoutFeel` on an activity, with the value domain spelled out. An agent can distinguish it from siblings like set_activity_perceived_effort or set_activity_description by the named field, though the description never explicitly says so.
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?
There is no when-to-use guidance, no mention of prerequisites (e.g. the activity must already exist / be a workout), and no routing away from the close sibling set_activity_perceived_effort. Usage is only implied by the parameter set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renames an activity. Resolves to null on success.
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id | |
| activityName | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuinely non-obvious behavioral fact â that success resolves to null rather than returning the updated activity â but says nothing about permissions, failure modes, or what happens if the activity does not exist.
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-loaded with the action and followed by the return contract. No filler whatsoever.
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 mutation tool with two required parameters, no output schema, and only 50% parameter documentation, the description omits failure behavior, permission requirements, and any indication of whether the rename is reversible. The return-value note is the only substantive content.
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 50%: activityId has 'Numeric id' while activityName is undocumented. The description only loosely implies that activityName is the new name and activityId the target, adding essentially nothing beyond the schema and leaving the undocumented parameter unexplained.
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?
States a specific verb and resource ('Renames an activity'), which is unambiguous about the mutation target. It does not explicitly distinguish itself from nearby setters like set_activity_description or set_activity_type, so it falls short of a 5.
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?
No when-to-use guidance, no prerequisites, and no mention of alternatives among the many set_activity_* siblings. The agent must infer everything about when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perceived effort (RPE) 1-10, or null to clear it. Partial PUT of summaryDTO.directWorkoutRpe, which Garmin stores TIMES TEN: pass RPE 1-10 (integer), it sends 10-100; null clears it. Garmin itself rejects 150 with a 400 MEASUREMENT_NOT_VALID. Never read-modify-write the whole summaryDTO instead: PUTting its stored start-coordinate pair back is a 400.
| Name | Required | Description | Default |
|---|---|---|---|
| rpe | Yes | ||
| activityId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/destructive/openWorld; the description adds substantial non-obvious behavior: Garmin stores the value times ten, the 10-100 wire range, the server-side 400 `MEASUREMENT_NOT_VALID` rejection at 150, the partial-PUT semantics, and the read-modify-write pitfall that yields a 400. This is exactly the kind of context annotations cannot express.
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?
Front-loads the essential constraint (RPE 1-10 or null) and every sentence carries real signal, but 'null clears it' is stated twice, a small redundancy in an otherwise dense, well-ordered description.
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?
No output schema, yet the description covers the error behavior (400 responses) and the mutation semantics an agent needs; with annotations covering the safety profile and the only ambiguous parameter fully explained, nothing needed to call this correctly is absent.
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 only 50% (`rpe` has no schema description), and the description fully compensates: integer 1-10, `null` to clear, and the internal Ã10 transformation. `activityId` is covered by the schema as a numeric id, so nothing material is missing.
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?
States a specific verb (set) and resource (perceived effort / RPE on an activity), and names the exact underlying field `summaryDTO.directWorkoutRpe`, which cleanly separates it from the many other `set_activity_*` siblings that target different fields (feel, name, description, type).
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?
Clearly states the two modes of use (pass RPE 1-10, or `null` to clear) and explicitly warns against the wrong approach (read-modify-write of the whole `summaryDTO`). It does not route to a sibling alternative, but no obvious sibling competes for this operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes an activity's type. Resolves to null on success.
| Name | Required | Description | Default |
|---|---|---|---|
| typeId | Yes | ||
| typeKey | Yes | ||
| activityId | Yes | Numeric id | |
| parentTypeId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safe profile is covered. The description adds a useful non-schema detail ('Resolves to null on success'), but omits what happens on failure, and says nothing about the openWorldHint=true external lookup implied by typeId/typeKey.
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, front-loaded sentences with no filler; the mutation is stated first. Nothing is wasted, though the second sentence is the only content-bearing addition.
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 4-required-param mutation with no output schema and thin schema documentation, the description is too sparse. It never explains the required type identifiers or the fact that all four arguments must be supplied, leaving the agent to infer the whole call shape.
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?
Four required parameters at only 25% schema coverage, and the description mentions none of them. It does not explain the relationship or precedence between typeId, typeKey, and parentTypeId, which is the most ambiguous part of this call and the thing the description should compensate for.
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?
States a specific verb and resource ('Changes an activity's type'), so the agent knows it mutates an activity's classification. However, it does not distinguish itself from the closely-named sibling set_activity_event_type, nor clarify how 'type' differs from 'event type'.
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?
No when-to-use, prerequisites, or alternative is given. Given siblings like set_activity_event_type and the get_activity_types lookup tool, the description should state which tool to pick and whether a type lookup is expected first, but it offers nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records a blood-pressure reading (systolic 70-260, diastolic 40-150, pulse 20-250). when defaults to now. Validates systolic 70-260, diastolic 40-150, pulse (if given) 20-250, all integers; when defaults to new Date().
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | A moment in time, ISO 8601, e.g. 2026-09-28T07:30:00 (local) or with Z/offset | |
| notes | No | ||
| pulse | No | ||
| systolic | Yes | ||
| diastolic | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about validation or defaults; the description adds the accepted value ranges, the integer requirement, and the `when` default of now. It stops short of saying what happens on out-of-range input or what the response contains.
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 value ranges and the `when` default are stated twice in nearly identical wording ('systolic 70-260, diastolic 40-150, pulse 20-250' then again with 'Validates ... all integers'), wasting roughly half the text. The purpose is correctly front-loaded, but the duplication is pure bloat.
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 simple 5-parameter write tool with no output schema, the description covers the constraints an agent needs to produce a valid call, including the timestamp default. The gaps are `notes` and the lack of any statement about the return value or failure behavior.
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?
With schema description coverage at only 20%, the description carries most of the burden and does so well for systolic, diastolic, pulse and `when`. The `notes` parameter remains undocumented in both schema and description, and no measurement units (mmHg, bpm) are stated.
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?
States a specific verb and resource ('Records a blood-pressure reading'), which cleanly disambiguates it from get_blood_pressure and delete_blood_pressure. It even names the validated fields, so an agent knows exactly what this tool writes.
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?
There is no when-to-use guidance, no mention of the alternative blood-pressure tools (get_blood_pressure, delete_blood_pressure), and no statement about prerequisites such as existing data or overwrite behavior. Usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets which activity types default to this gear. Uses the v2 full-record PUT Garmin's own web client uses (the older dedicated default-gear endpoint is dead). The working way to set gear defaults (the old dedicated default-gear endpoint is dead; there is no setGearDefault). Read-modify-writes the v2 record: GETs /gear-service/gear/v2/{uuid}, replaces associatedActivityTypes with [{activityTypeKey, defaultGear: true, preferredGear: false}] per key, PUTs the whole record back. Keys are lowercase ("running"), matching createGear, NOT setGearDefault's upper-cased form. [] clearâĻ IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| gearUUID | Yes | ||
| activityTypeKeys | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive behavior beyond them: it is a read-modify-write of the whole v2 record, existing associatedActivityTypes are replaced, and the operation is irreversible. The GET/replace/PUT sequence is exactly the kind of context annotations cannot convey.
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?
Purpose is front-loaded, but the text is repetitive: the 'old dedicated default-gear endpoint is dead' claim appears twice and there is tangential API lore. Sentences are dense with useful content but could be tightened by roughly a third without losing meaning.
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 destructive, zero-schema-coverage mutation with no output schema, the description supplies the essential context: irreversibility, the read-modify-write nature, key casing, and the clear semantics. The only real gap is what gearUUID refers to and any permission requirements.
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 0%, so the description must carry the parameters, and it does: it specifies activityTypeKeys must be lowercase ('running'), matching createGear and not the upper-cased setGearDefault form, and that '[]' clears the defaults. gearUUID is only implied by the GET path, so it is not a full 5.
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?
States a specific verb and resource: 'Sets which activity types default to this gear.' It goes further by naming the mechanism and contrasting with related operations (createGear, the dead setGearDefault), which helps the agent place it among gear tools. Not a 5 because the purpose statement is muddied by repetitive endpoint lore rather than a crisp one-line summary.
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?
Provides a real usage cue: 'IRREVERSIBLE: confirm with the user before calling.' That is genuine when-to-act guidance. However it gives no explicit routing against alternatives (e.g. add_gear_to_activity vs this), only a safety precondition, so it lands at minimum-viable-plus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes one heart-rate zone profile and returns it as stored. READ-MODIFY-WRITE of one profile: GETs /biometric-service/heartRateZones, overlays {sport? = "DEFAULT", trainingMethod?, maxHeartRate?, restingHeartRate?, lactateThresholdHeartRate?, zoneFloors?: [5 bpm]} with changeState: "CHANGED", PUTs [profile] (204), then returns the profile READ BACK. A sport with no profile starts from DEFAULT's. Setting restingHeartRate also turns off restingHrAutoUpdateUsed. Garmin does NOT recompute floors when the method or a heart rate changes. Send zoneFloors too. Floors must be stricâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| update | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description goes well beyond that: it discloses the exact endpoint sequence, the 204 response, the read-back verification, the side effect that setting restingHeartRate disables restingHrAutoUpdateUsed, and the non-obvious domain rule that floors are not recomputed server-side.
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?
Front-loads the one-line purpose, then the mechanics in a compact, information-dense form with no filler. It is long, but nearly every clause carries behavior an agent must know; the truncation is the only real structural flaw.
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 mutating tool with a nested object payload, no output schema and no explicit annotation coverage, the description supplies the return behavior ('returns the profile READ BACK'), the side effect, and the server-side non-recomputation caveat. Only the truncated zone-floor validation rule keeps it from being fully self-sufficient.
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 nominally low, so the description carries the load: it enumerates the accepted payload fields, pins zoneFloors to '[5 bpm]', and explains the sport-default fallback. It adds real meaning over the bare nested object, though the final constraint sentence is truncated mid-word ('Floors must be stricâĻ'), leaving part of the validation rule unstated.
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?
States a specific verb and resource ('Changes one heart-rate zone profile') and adds scope ('one profile', not all). The GET/PUT flow makes it clearly distinguishable from the read-only sibling get_heart_rate_zones and from delete_heart_rate_zones without opening any schema.
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?
Gives procedural guidance an agent needs: it describes the read-modify-write sequence, notes that a sport without a profile starts from DEFAULT's, and instructs 'Send `zoneFloors` too' with the warning that Garmin does not recompute floors. It never explicitly names when to prefer this over delete_heart_rate_zones or the read tools, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign in to Garmin Connect. Call this when another Garmin tool says you are not logged in or the session expired. It opens a sign-in page in the user's browser; the password and MFA code are entered there, never in the chat. Afterwards, ask the user to tell you when they have finished, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond them by disclosing that a sign-in page opens in the user's browser, that credentials and MFA are entered there and never in chat, and that the agent must pause and wait for user confirmation before retrying. That is exactly the behavioral context an agent needs for a browser-based auth flow.
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?
Four sentences, each front-loaded and purposeful: purpose, trigger, mechanism, follow-up. Nothing is redundant and the most important routing condition appears early.
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 an auth tool with no parameters and no output schema, the description covers the trigger, the browser-based mechanism, the security constraint (no credentials in chat), and the required wait-and-retry loop. Nothing an agent needs to call and recover from this tool 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 takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could add on parameter semantics, and it correctly avoids inventing inputs.
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 verb+resource ('Sign in to Garmin Connect') and immediately distinguishes itself from the many data-retrieval siblings by being the authentication tool. An agent can tell at a glance this is the login entry point, not a data query.
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 an explicit trigger ('when another Garmin tool says you are not logged in or the session expired') and a complete post-action protocol ('ask the user to tell you when they have finished, then retry'). No inference is required about when to call it or what to do afterward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
measurementSystem lives on /userprofile-service/userprofile/user-settings (under userData), not on the social profile. A convenience accessor, not a data endpoint: returns undefined rather than throwing if the payload shape is missing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavior beyond that: it returns `undefined` rather than throwing when the payload shape is missing, which is exactly the kind of error-behavior detail an agent needs to write defensive code. It does not describe caching or network-failure behavior, but the key failure mode is disclosed.
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, no filler, and the payload-location caveat is front-loaded. The service path is a bit dense but it is the evidence that justifies the tool's existence, so it earns its place.
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 no output schema and no parameters, the description carries the burden of explaining the return value, and it only partially does so: it says what happens on a missing payload but never states what is returned on success (presumably the measurement-system identifier). The location and failure-mode context is good, but the success shape is left to inference.
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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description spends its space on scope and return behavior instead of inventing parameter detail, which 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 identifies the resource (`measurementSystem`) and its location on `/userprofile-service/userprofile/user-settings`, and explicitly distinguishes it from the social profile, which differentiates it from siblings like get_user_profile. It frames itself as 'a convenience accessor, not a data endpoint', which tells an agent it is a shortcut rather than a full fetch. It never directly states the return value (e.g., the metric/imperial preference), so it is clear but slightly indirect.
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 'not on the social profile' note implicitly steers an agent away from profile tools toward this one, and 'convenience accessor, not a data endpoint' hints at when it is preferable to a full settings fetch. However, no sibling tool is named as an alternative and there is no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a workout from the calendar; the workout stays in the library. Removes the calendar entry without deleting the workout template; irreversible. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| scheduledWorkoutId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds what the annotations cannot: the blast radius (calendar entry only, template preserved) and that the effect is irreversible, plus a required user-confirmation step. That is meaningful behavioral context beyond the structured fields.
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 core constraint is front-loaded and easy to scan, but the content is stated twice: 'the workout stays in the library' is restated as 'without deleting the workout template', and 'irreversible' is immediately echoed by 'IRREVERSIBLE:'. Two of the four clauses are redundant.
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 destructive tool with no output schema, the description covers the essential safety profile: scope of deletion, persistence of the template, irreversibility, and the confirmation requirement. Only the practical detail of how to source scheduledWorkoutId is left entirely to 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% for the single parameter (scheduledWorkoutId, described as 'Numeric id'), and the description adds nothing about id format, how to obtain it, or accepted integer/string forms. Baseline 3 is appropriate when the schema carries the parameter burden.
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?
States a specific verb and resource ('Removes a workout from the calendar') and immediately scopes it against the obvious sibling by clarifying 'the workout stays in the library', which separates it from delete_workout. An agent can pick this tool over the delete variant without opening either schema.
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?
Gives an explicit precondition for invocation ('confirm with the user before calling') tied to irreversibility, and the library-persistence clause implicitly routes the agent to delete_workout when the template itself should go. It stops short of naming that alternative outright, so it's clear context rather than a full when/when-not routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-modify-write of the stored event; resolves to null. READ-MODIFY-WRITE: GETs the event, overlays {name?, date?, location?, url?, note?, race?, goalTimeSeconds?} (null clears an optional one), PUTs the whole record back to /calendar-service/event/{id}; Concurrent callers can clobber each other.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | ||
| eventId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-read-only, non-destructive, open-world mutation, so the safety profile is largely covered. The description adds genuine behavioral value the annotations do not: the ordered GET-overlay-PUT sequence, the semantics of `null` as a field clear, and a lost-update race warning ('concurrent callers can clobber each other').
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?
Content is largely relevant, but the delivery is dense and awkward: a stray 'resolves to `null`', backticked type signatures, and semicolon-packed clauses make it read like an implementation note rather than a tool description. It is front-loaded with the core operation, which partly offsets the stuffing.
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 mutation tool with no output schema and a nested-object parameter, the description covers the mechanism, the null-clear semantics, and the concurrency hazard, and it states the return resolves to null. It omits error/auth conditions (e.g., behavior on an unknown eventId), which is a minor gap.
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 only 50% (nested `changes` fields are mostly undocumented beyond `date` and `eventId`). The description compensates by enumerating the overlayable fields and, crucially, defining the `null`-clears-an-optional-field semantics that the schema does not express. This is meaningful added value beyond the raw property list.
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 this is a read-modify-write update of a stored calendar event and names the resource (event). It is unambiguous as to verb+resource, though it does not explicitly contrast itself with siblings like create_calendar_event, get_calendar_event, or list_calendar_events.
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?
There is no explicit when-to-use or when-not-to-use guidance and no mention of alternative tools for the same resource (create/delete/get calendar event). The only usage hint is the parameter-level note that `null` clears an optional field, which is not routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename and/or change privacy. Read-modify-write of the whole record. READ-MODIFY-WRITE: GETs the record, overlays the changes, PUTs the whole record back to /course-service/course/{courseId}, the same request Garmin's own web editor sends on Save (observed 2026-09-24). Concurrent callers can clobber each other. Throws before any request if neither field is given or the name is blank. A just-created course may 429 "not yet ready".
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | ||
| courseId | Yes | Numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing the read-modify-write whole-record algorithm, the exact endpoint and that it mirrors Garmin's own web editor, concurrency clobbering between callers, fail-fast validation, and a possible 429 on freshly created courses. That is unusually rich operational context; the only gap is authentication/permission requirements.
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?
Front-loaded with the one-line summary before the mechanics, and every sentence carries operational information. Slightly penalized for the redundant restatement of 'Read-modify-write' twice in the first two sentences.
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 two-parameter mutation with no output schema and only partial annotations, the description supplies the algorithm, endpoint, concurrency risk, validation behavior and rate-limit caveat. It omits what the response contains and any permission requirements, but the essential calling information is present.
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 50% (only courseId is described, the nested changes object is bare), so the description must compensate. It does partly: it identifies the two permitted change fields and adds a constraint absent from the schema ('name is blank' causes a pre-request throw). It does not clarify formats or the privacy enum beyond what the schema already supplies.
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?
Opens with a specific verb pair and resource scope â 'Rename and/or change privacy' on a course â which is far more precise than the generic 'update_course' name and clearly separates it from create_course, delete_course, and list_courses. It also pins the exact mutation surface (name, privacy).
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?
Usage is implied by the scope statement (edit an existing course's name/privacy) but no sibling is named and no when-not guidance is given. The failure conditions ('throws if neither field is given or name is blank') are validation rules rather than routing guidance, so the agent must infer that create_course/delete_course are the alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requires a Garmin Connect+ subscription (check with has_connect_plus). FULL REPLACE of a custom food's definition. Needs Connect+. The same PUT carrying both ids. FULL REPLACE: a nutrient or brand left out is removed (verified: the brand was dropped).
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | ||
| foodId | Yes | ||
| servingId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses real behavior beyond the annotations (full-replace semantics, a verified case where the brand was dropped), but that disclosure directly conflicts with destructiveHint=false: the annotation declares only additive/non-destructive updates while the description states that omitted fields are removed. Per the rubric this is an annotation 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 text is short but redundant: Connect+ is mentioned twice ("Requires a Garmin Connect+ subscription..." and "Needs Connect+.") and FULL REPLACE is stated twice. The repetition means several sentences do not earn their place, though the critical warning 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 mutation tool with a nested 17-field input object, no output schema, and contradictory annotations, the description covers the two most important items (subscription prerequisite and full-replace data loss). It omits return format, error behavior, and what foodId/servingId must reference, leaving meaningful 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 description coverage is 0%, so the description must carry the load. "The same PUT carrying both ids" clarifies that foodId and servingId are both required, and the FULL REPLACE note explains a critical input semantic (omitted optional nutrients are deleted) that the schema does not state. It still says nothing about the 17 nested input fields, their units, or the servingSize/servingUnit defaults.
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 phrase "FULL REPLACE of a custom food's definition" gives a specific verb (replace) and resource (custom food), which distinguishes it from the create_custom_food and delete_custom_food siblings. However, the tool's actual purpose is buried behind a subscription-gating sentence that leads the description, and no sibling is named explicitly.
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 genuine usage gate ("Requires a Garmin Connect+ subscription (check with has_connect_plus)") and a caution about the destructive replace, which is useful operational context. But it never states when an agent should reach for this tool versus create_custom_food or delete_custom_food, so direction on alternatives is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrites the period days in a date range. Replaces what the range holds; there is no undo. Needs cycle tracking set up in Garmin Connect first. full replace, not a merge; each cycleDatesLists group must be non-empty, consecutive calendar dates, and fall within [startdate, enddate], else throws GarminError. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| enddate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| options | No | ||
| startdate | Yes | Calendar date, YYYY-MM-DD (UTC) | |
| cycleDatesLists | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it discloses that the operation is a full replace rather than a merge, that there is no undo, the input validation rules that trigger a GarminError, and a required user-confirmation step.
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?
Four dense sentences, no filler, with the core mutation semantics ('full replace') front-loaded ahead of the preconditions and validation rules. Every sentence carries actionable 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?
Covers the mutation semantics, irreversibility, prerequisites, and failure mode for a nested-object, no-output-schema tool. Minor gaps remain: the purpose of options.todayCalendarDate and the shape of a successful response are unstated.
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 only 50%, but the description compensates by explaining cycleDatesLists semantics in depth: each group must be non-empty, be consecutive calendar dates, and fall within [startdate, enddate]. It adds little about startdate/enddate or options.todayCalendarDate, which keeps it from a 5.
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?
States a precise verb and resource: 'Rewrites the period days in a date range.' The scoping to a date range plus the emphasis on 'full replace, not a merge' makes it clearly distinct from sibling mutators like update_menstrual_daily_log or confirm_menstrual_period_start.
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?
Gives a hard precondition ('Needs cycle tracking set up in Garmin Connect first') and an explicit call-time instruction ('IRREVERSIBLE: confirm with the user before calling'). It does not name alternative tools for the other menstrual-editing cases, 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.
Logs a day's cycle-tracking entry (symptoms, moods, flow, notes). Replaces whatever that day already holds; there is no undo. Needs cycle tracking set up in Garmin Connect first. full-day replace, not a merge; at least one optional field required or throws GarminError; notes: undefined preserves the existing note, notes: "" clears it (distinct, load-bearing); discharge rejects combining "NO_DISCHARGE" with any other value. IRREVERSIBLE: confirm with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| calendarDate | Yes | Calendar date, YYYY-MM-DD (UTC) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: full-day replace (not merge), no undo, throws GarminError when no optional field is supplied, and the load-bearing distinction between notes: undefined (preserve) and notes: "" (clear). These are exactly the behavioral facts an agent cannot derive from destructiveHint/openWorldHint alone.
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?
Front-loaded with the core action, then constraints, then the safety warning. Dense and every clause carries information, though the bolding/backtick styling is heavier than necessary for the amount of text.
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 an irreversible mutation with no output schema, the description supplies everything material: prerequisite, replacement semantics, error condition, field-level edge cases, and an explicit confirmation instruction. Nothing an agent needs to call it correctly 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?
Schema coverage is 50% and the nested options object is undocumented, but the description compensates for the highest-risk fields: notes semantics, the discharge combination constraint, and the at-least-one-field rule. Values for flow, moods, sexDrive, etc. remain unexplained.
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?
States a specific verb and resource ('Logs a day's cycle-tracking entry') plus the content domain (symptoms, moods, flow, notes) and the per-day scope. This cleanly separates it from siblings like update_menstrual_calendar, get_menstrual_data_for_date, and confirm_menstrual_period_start.
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?
Gives a clear prerequisite ('needs cycle tracking set up in Garmin Connect first') and an explicit pre-call directive ('IRREVERSIBLE: confirm with the user before calling'). It does not, however, name when to prefer this over update_menstrual_calendar or other menstrual siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes cycle-tracking preferences (merged into the current ones). Has no effect until cycle tracking is set up in Garmin Connect. settings must be non-empty or throws GarminError; multi-step: GETs /userprofile-service/userprofile/user-settings, overlays settings onto the current userMenstrualCycleSettings, then PUTs the same endpoint, including id if resolvable.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| settings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare it as a non-read-only, non-destructive, open-world write. The description adds substantial behavior beyond that: merge rather than replace semantics, the non-empty `settings` validation rule with the specific `GarminError`, and the multi-step GET-overlay-PUT flow including `id` resolution.
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?
Front-loaded with the core action and merge semantics, then the precondition, then validation and flow details. Dense but every clause carries information; the endpoint path detail is slightly more implementation-level than an agent needs.
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 nested-object mutation with no output schema and no schema descriptions, the description covers merge behavior, precondition, error case, and underlying request flow. It does not enumerate which setting keys are accepted, though `additionalProperties: true` makes that open-ended.
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 0%, so the description must compensate, and it largely does: it defines `settings` as a non-empty object overlaid onto the current `userMenstrualCycleSettings`, and hints at the `id`/`userSettingsId` role via 'including `id` if resolvable'. The `options` object itself is never named or explained.
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?
States a specific verb and resource ('Changes cycle-tracking preferences') with the added qualifier that changes are merged into existing settings. It does not name or contrast with close siblings such as init_menstrual_cycle_setup or update_menstrual_daily_log, so differentiation is left to the agent.
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?
'Has no effect until cycle tracking is set up in Garmin Connect' gives a clear precondition that implicitly routes the agent to init_menstrual_cycle_setup first. No explicit when-not or named alternative is given, but the operative context is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace an existing workout with a new spec. This OVERWRITES the whole workout; confirm with the user first, ideally after preview_workout. Paces are minutes as decimals (4:30 = 4.5), distances metres, times seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes | A Garmin workout. Give `steps` for one sport, or `legs` (each with its own sport) for a multi-sport workout, not both. Distances are metres, times seconds. | |
| workoutId | Yes | From get_workouts or create_workout |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so safety is partly covered. The description still adds real value by specifying what gets destroyed ('OVERWRITES the whole workout') and the human-confirmation expectation, which annotations cannot express.
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 short sentences, front-loaded with the destructive headline, then the confirmation workflow, then units. No filler; every sentence carries 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?
For a deeply nested, no-output-schema mutation tool, the description covers scope, risk, and prerequisite checking, and the schema carries the structural detail. It could say more about what state the workout is left in (e.g., schedule implications), which is the only real gap.
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 both top-level parameters and the nested spec units are already documented in the schema (including the pace 4:30 = 4.5 convention and metre/second units). The description's unit sentence largely restates that, so baseline 3 applies.
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?
States a specific verb and resource ('Replace an existing workout with a new spec') and clarifies scope: full replacement, not a partial edit. It also names preview_workout as the related sibling, so an agent can place it without opening the schema.
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?
Gives an explicit prerequisite workflow ('confirm with the user first, ideally after preview_workout'), which is actionable context for a destructive tool. It does not, however, contrast against create_workout or delete_workout, so the agent must infer why to update rather than recreate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Uploads an activity file through Garmin's plain device-sync upload path. Multipart upload to the PLAIN /upload-service/upload path, no extension suffix and none of importActivity's load-bearing import headers (ordinary device-sync-shaped upload, distinct from importActivity's spoofed-client import).
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to a local .fit, .gpx or .tcx file (~ is expanded) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a non-read-only, open-world write, so the safety profile is covered. The description usefully adds the plain upload path and that no import headers are used, but says nothing about success behavior (e.g., that it creates an activity), duplicate handling, or authentication needs beyond what annotations give.
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?
Front-loaded with the action in the first sentence and tightly scoped overall. The parenthetical '(ordinary device-sync-shaped upload, distinct from importActivity's spoofed-client import)' partly restates the preceding clause, so there is mild redundancy and dense jargon.
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 upload tool with annotations covering safety and no output schema, the description is nearly sufficient: it explains the mechanism and sibling distinction. It stops short of describing post-upload effects (whether it produces a new activity record), which would fully close the loop.
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?
Single parameter with 100% schema coverage and a self-documenting filePath (absolute path, .fit/.gpx/.tcx, ~ expansion), so the schema carries the semantics. The description adds no parameter-level detail, which is the correct baseline of 3 when coverage is high.
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?
States a specific verb+resource (uploads an activity file) and pins the exact mechanism and endpoint, explicitly distinguishing itself from the sibling import_activity/importActivity. An agent can tell what this does and how it differs from the nearest alternative without opening either schema.
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?
Names the alternative (importActivity) and its defining condition (device-sync-shaped upload vs spoofed-client import), giving a clear basis for selection. However, it frames the choice in implementation/path terms rather than stating explicit when-to-use/when-not scenarios or prerequisites (e.g., auth, supported file states).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's user name, from the cached user profile.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description does add one piece of genuine behavioral context â that the value comes from a cached profile, implying possible staleness and no live lookup â but it says nothing about nullability or freshness guarantees.
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?
A single short sentence that front-loads the returned value and its source. Nothing is padded or wasted.
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?
There is no output schema, so the description must carry the return-value burden; it names the value but not its format, nullability, or how it differs from full_name/display_name. For a trivial zero-param tool this is close to adequate, but the unresolved sibling ambiguity leaves a real gap.
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 takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly implies a no-argument retrieval.
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 resource and its origin: the account's user name read from a cached profile. It is clear what the tool returns, but it does nothing to distinguish itself from the closely-named siblings display_name and full_name, which an agent could easily confuse it with.
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?
There is no when-to-use guidance and no mention of alternatives. With display_name and full_name in the sibling list, the absence of any routing hint (e.g. which name field to prefer) is a meaningful gap.
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.10.0get_activity_workoutsget_daily_hydrationget_daily_stressget_daily_summariesget_spo2_acclimationget_weight_goalssearch_activitiesadd_body_compositionadd_gear_to_activityadd_hydration_dataadd_weigh_inadd_weigh_in_with_timestampsconfirm_menstrual_period_startcount_activitiescreate_calendar_eventcreate_coursecreate_course_from_gpxcreate_custom_foodcreate_gearcreate_manual_activitycreate_manual_activity_from_jsoncreate_workoutdelete_activitydelete_blood_pressuredelete_calendar_eventdelete_coursedelete_custom_fooddelete_food_logsdelete_geardelete_heart_rate_zonesdelete_training_plandelete_weigh_indelete_weigh_insdelete_workoutdisplay_namedownload_activitydownload_course_gpxdownload_health_snapshotdownload_workoutfull_nameget_activitiesget_activities_by_dateget_activities_for_dateget_activityget_activity_detailsget_activity_event_typesget_activity_exercise_setsget_activity_gearget_activity_hr_in_timezonesget_activity_power_in_timezonesget_activity_split_summariesget_activity_splitsget_activity_typed_splitsget_activity_typesget_activity_weatherget_adaptive_training_plan_by_idget_adaptive_workoutget_adhoc_challengesget_all_day_eventsget_all_day_stressget_available_badge_challengesget_available_badgesget_badge_challengesget_badge_detailget_blood_pressureget_body_batteryget_body_battery_eventsget_body_compositionget_calendar_eventget_calories_dailyget_courseget_custom_food_serving_unitsget_custom_foodsget_cycling_ftpget_daily_statsget_daily_stepsget_daily_weigh_insget_device_alarmsget_device_last_usedget_device_settingsget_device_solar_dataget_devicesget_earned_badgesget_endurance_scoreget_fitness_age_dataget_floorsget_functional_threshold_power_rangeget_gearget_gear_activitiesget_gear_defaultsget_gear_statsget_goalsget_golf_club_statsget_golf_scorecardget_golf_shot_dataget_golf_summaryget_golf_user_statsget_heart_rate_zonesget_heart_ratesget_hill_scoreget_hrv_dataget_hrv_data_rangeget_hydration_dataget_in_progress_badgesget_inprogress_virtual_challengesget_intensity_minutes_dataget_lactate_thresholdget_last_activityget_lifestyle_logging_dataget_max_metricsget_max_metrics_rangeget_menstrual_calendar_dataget_menstrual_cycle_summaryget_menstrual_data_for_dateget_menstrual_last_confirmedget_menstrual_reportsget_morning_training_readinessget_next_scheduled_workoutget_non_completed_badge_challengesget_nutrition_daily_food_logget_nutrition_daily_mealsget_nutrition_daily_settingsget_nutrition_food_log_rangeget_personal_recordget_power_zonesget_power_zones_for_sportget_pregnancy_summaryget_primary_training_deviceget_progress_summary_between_datesget_race_predictionsget_respiration_dataget_rhr_dailyget_rhr_dayget_running_toleranceget_scheduled_workout_by_idget_scheduled_workout_summariesget_scheduled_workoutsget_shared_calendar_eventget_sleep_dailyget_sleep_dataget_spo2_dataget_statsget_stats_and_bodyget_steps_dataget_stress_dataget_training_plan_by_idget_training_plan_workoutsget_training_plansget_training_readinessget_training_statusget_user_profileget_user_settingsget_user_summaryget_userprofile_settingsget_weekly_intensity_minutesget_weekly_stepsget_weekly_stressget_weigh_insget_workout_by_idget_workoutshas_connect_plusimport_activityimport_course_gpxinit_menstrual_cycle_setuplist_calendar_eventslist_courseslog_foodpreview_workoutpush_workout_to_devicequick_add_foodremove_gear_from_activityrequest_reloadschedule_workoutsearch_exercisessearch_foodsset_activity_descriptionset_activity_event_typeset_activity_exercise_setsset_activity_feelset_activity_nameset_activity_perceived_effortset_activity_typeset_blood_pressureset_gear_activity_defaultsset_heart_rate_zonessign_in_to_garminunit_systemunschedule_workoutupdate_calendar_eventupdate_courseupdate_custom_foodupdate_menstrual_calendarupdate_menstrual_daily_logupdate_menstrual_settingsupdate_workoutupload_activityuser_nameScored across 197 tools
Multiple tools have overlapping or identical purposes: get_stats is an alias of get_user_summary, get_stress_data aliases get_all_day_stress, get_user_profile/get_user_settings/get_userprofile_settings are one character apart, and get_daily_stats/get_daily_steps/get_steps_data/get_daily_summaries all return step/summary data. Aliases, delegating wrappers (get_morning_training_readiness, get_in_progress_badges), and near-duplicate date tools (get_activities vs get_activities_for_date vs get_activities_by_date) make misselection likely.
The bulk follows a snake_case verb_noun pattern (get_/add_/delete_/create_/update_), but bare noun accessors like display_name, full_name, user_name, unit_system, and preview_workout break it. Slight verb inconsistency (add_weigh_in vs create_gear vs set_activity_, get_stats vs get_user_summary) is readable but not uniform.
197 tools is an extreme surface far beyond any reasonable scope, with numerous aliases and thin accessor methods that could be consolidated. This is well past the 50+ mismatch threshold and hurts usability more than it helps.
Coverage is impressively broad, with CRUD across activities, workouts, courses, gear, events, badges, nutrition, menstrual tracking, and more. A few gaps exist (no update for weigh-ins or blood pressure, hydration has no delete/update, some features gated behind Connect+), but most lifecycles are covered.
Garmin data in Claude: 135 tools â activities, sleep, HRV, training, workouts. Free, open source.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
AI coach for Garmin: builds training plans and structured workouts, synced straight to your watch.