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 193 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).
193 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 |
31 | all | steps, heart rate, sleep, HRV, stress, SpO2, respiration, hydration, blood pressure, body battery | |
36 | all | list/search/detail, splits, weather, manual creation, import/upload, exercise sets, gear links, personal records, event type, RPE and feel | |
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 | |
8 | all | weigh-ins, 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.
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.
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 |
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 test853 tests across 59 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.
builds a .fit binary in memory (src/util/fit.ts, a hand-rolled FIT encoder) and uploads it via client.upload to /upload-service/upload; weight validated positive/finite, throws GarminError otherwise; passes client.upload's result through unchecked
| Name | Required | Description | Default |
|---|---|---|---|
| extra | No | ||
| weight | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, and openWorld=true, so the safety profile is set. The description adds meaningful behavioral detail: weight is validated positive/finite with a thrown GarminError, and the upload result is passed through unchecked. It does not cover auth, rate limits, or side effects beyond the upload.
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 front-loads low-value implementation trivia (file path `src/util/fit.ts`, internal endpoint `/upload-service/upload`) instead of purpose or usage. These internals do not help an agent select or invoke the tool, so they 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 mutation tool with a 12-field nested object and no output schema, the description is incomplete: it omits any explanation of the optional body-composition metrics. It covers the upload path but leaves an agent without the information needed to populate `extra` 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 0% and the bulk of parameters live in a nested `extra` object with 12 undocumented fields (bmi, muscleMass, percentFat, etc.). The description only clarifies validation on `weight` and says nothing about what the `extra` metrics are or how they map, so it fails to compensate 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?
The description describes the mechanism (builds a `.fit` binary and uploads it) rather than the user-facing outcome of adding body-composition data. An agent can infer the purpose from the tool name, but the text itself never states 'adds body composition/weight data' explicitly and gives no differentiation from siblings like add_weigh_in or add_weigh_in_with_timestamps.
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 many closely related siblings that also write body data. The description only covers implementation flow, leaving the agent to guess when this tool is preferred over add_weigh_in.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, so the safety profile is covered. The description adds genuine behavioral value by disclosing the 404 error semantics and the GarminConnectionError re-raise, which an agent cannot learn from the schema, though it says nothing about success behavior, permissions, or idempotency.
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. It is also a sentence fragment and is not front-loaded with purpose, so a reader gets error trivia before knowing what the tool does.
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 unambiguous 2-parameter signature, the description omits the core purpose, success behavior, and prerequisites. The single error-handling note is useful but leaves the definition largely 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 only 50%: activityId is documented as 'Numeric id' but gearUUID has no schema description, and the description provides no clarification of either parameter's format or constraints. With half the parameters undocumented, the description fails to 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?
The description never states what the tool does â it only documents a 404 failure mode. Only the tool name implies that gear gets attached to an activity; the text itself carries no verb+resource purpose 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?
There is no guidance on when to use this tool, no prerequisites (e.g., gear must exist and not be retired), and no mention of the obvious alternative remove_gear_from_activity or which activity/gear combos are valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered; the description adds genuinely new behavior: the 10000 magnitude cap, acceptance of negative values, and, most importantly, that the write is irreversible because no delete endpoint exists. It stops short of covering auth requirements, whether an existing same-timestamp entry is overwritten, or what a success 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?
Very short with no filler, and the most consequential fact (not round-trippable) is bolded for salience. The telegraphic fragment style with semicolons is somewhat clipped and reads as a note rather than a front-loaded sentence, which costs it a point but not much.
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 3-parameter write with no output schema, the description covers value semantics and irreversibility, which is the critical gap. It does not say what happens on a duplicate timestamp, whether a device/source is implied, or what the call returns, leaving the agent with partial context.
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%: 'when' and 'cdate' are documented in the schema, but the required 'valueInMl' has no description at all. The description fills exactly that hole by specifying units (raw milliliters), the accepted magnitude range, and that negatives are legal â meaning the agent does not need to guess the unit or bounds for the only required 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 never states what the tool does; it is a fragment of constraint notes ('raw milliliters, magnitude capped at 10000, negative values allowed') with no verb+resource sentence. The agent must infer the purpose ('log a hydration entry') entirely from the tool name and the sibling pair get_hydration_data/add_hydration_data. Adequate in combination with the name, but the description itself contributes no purpose 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?
There is no explicit when-to-use or when-not-to-use guidance versus siblings such as add_weigh_in or add_body_composition. The one operational caveat given â 'no delete endpoint exists, so not safely round-trippable' â implicitly warns the agent that this write cannot be undone, which is useful decision context, but it is not framed as usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 safety profile is covered. The description does add genuine behavioral facts beyond the annotations: the unit defaults to kg and the timestamp defaults to the current moment. It does not disclose what happens on a duplicate weigh-in for the same day, which matters for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and free of filler, so nothing is wasteful, but it is a sentence fragment with no front-loaded purpose statement. Brevity here comes from omission rather than from efficient editing.
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?
A mutation tool with no output schema, 33% schema coverage, and no usage guidance leaves real gaps: no statement of purpose, no sibling differentiation from `add_weigh_in_with_timestamps`, and no note on duplicate handling. The defaults alone are not enough to call 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?
Schema coverage is only 33% (only `when` is documented in the schema), so the description must compensate. It does so partially by giving the default `unitKey="kg"` and `when=new Date()`, which clarifies the enum default and the optionality. `weightValue` remains undocumented in both places, including the unit it is expressed in.
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; it only supplies default values for two optional parameters. The purpose must be inferred entirely from the name `add_weigh_in`, which is exactly the tautology-adjacent case the rubric penalizes.
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 obvious alternative, `add_weigh_in_with_timestamps`, which appears in the sibling list. The `when=new Date()` default faintly implies 'use this when you don't supply a timestamp', but that distinction is left for the agent to reconstruct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantive behavior beyond that: values are stored raw with no unit conversion, supplied timestamp strings are re-formatted rather than forwarded verbatim, and omitted `gmtTimestamp` is derived from the resolved instant. This is real disclosure for a mutation tool, though it says nothing about auth or failure 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?
It is compact and wastes no sentences, but it is not front-loaded: the purpose is deferred behind a reference to another tool, and the content is crammed into one dense paragraph with nested parentheticals. Efficient but not well-ordered for fast scanning.
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 five parameters, no output schema, and only 20% schema coverage, the hardest part (coupled timestamp resolution) is covered well. However, the unit/weight relationship and any notion of what the call returns or how success/failure manifests are absent, leaving gaps an agent would otherwise have to guess at.
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%, so the description must carry the burden, and it largely does: it clarifies `dateTimestamp` vs `when` precedence, naive-string interpretation (LOCAL for dateTimestamp, UTC for gmtTimestamp), the default of `new Date()`, and the derivation of `gmtTimestamp`. It leaves `weightValue` and `unitKey` unexplained beyond the passing 'raw-value, no-conversion' rule.
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 plainly that it records a weigh-in; it opens with an anaphoric reference ('same raw-value, no-conversion rule as `addWeighIn`') that assumes knowledge of a sibling. Combined with the name, an agent can infer the purpose, but the description is not self-contained and leans on comparison rather than stating verb+resource 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?
It references `addWeighIn` but gives no explicit guidance on when to choose this timestamped variant over the plain `add_weigh_in` sibling, which is the central routing decision for this tool. No prerequisites, no exclusions, no conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already declare readOnlyHint=false (a write), destructiveHint=false, and openWorldHint=true; the description's mention of POST merely corroborates the mutation hint without adding new information. It says nothing about auth requirements, idempotency, whether re-confirming overwrites an existing start date, or side effects on the cycle calendar.
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 no filler, and the positive path is front-loaded ahead of the exclusion clause. It is efficient, though the content is developer/endpoint-oriented rather than agent-oriented.
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 no output schema, 3 required params, a nested object, and low schema coverage, the description omits critical context: what the call changes, required prior state, units for cycle/period lengths, and what happens when the date is not a real period start. An agent cannot safely call this on the description alone.
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 25% â only periodStartDate carries a format note (YYYY-MM-DD UTC). cycleLength, periodLength, and the nested options.predictedCycle object are undocumented in both schema and description, and the description adds no units, ranges, or meaning for them despite the low coverage requiring compensation.
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 HTTP method and the exact endpoint path, and it names the sibling sub-paths it is NOT (dayview/calendar/lastconfirmed/summary), which helps disambiguate from the get_menstrual_* readers. However, it never states in human terms that this confirms/sets a menstrual period start date, so the actual purpose must be inferred from the tool name and URL.
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 the ... sub-paths' clause gives a when-not signal, implicitly steering the agent away from the read-only menstrual endpoints. But there is no positive when-to-use guidance, no prerequisites (e.g. must cycle be initialized via init_menstrual_cycle_setup), and no mention of consequences of calling it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations only cover readOnlyHint and openWorldHint, so the description adds real value by disclosing error behavior (throws `GarminError` on empty or non-numeric `totalCount`) and clarifying the narrowed return value. This is meaningful beyond the safety hints.
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, stating the return value first and the failure mode second. Dense but efficient; 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 tool with no output schema, the description adequately explains what is returned and how it fails. It leaves the scope of the count (all-time vs. filtered) unstated, 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?
The tool takes zero parameters, so there is nothing for the description to document; baseline 4 applies. No parameter guidance is needed or 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?
Combined with the name, the description states a specific behavior: it returns the envelope's `totalCount` rather than the whole payload, implicitly distinguishing it from `get_activities`. It never explicitly says 'counts activities' in prose, but the resource and result 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 phrase 'not the whole response' implies you should pick this over the full-response siblings when only a count is needed, but no explicit when-to-use or named alternative is given. 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.
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 Europe/Zagreb to Europe/Paris (same offset) while keeping `AmerâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial non-obvious behavior: Garmin forces every event PRIVATE and unshareable, sets isTrainingEvent whenever isPrimaryEvent is, returns a 500 on unknown eventType, and rewrites the supplied timezone â none of which the 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?
The description is dense and technical but front-loads the operation before the field shape and behavioral caveats, and each clause carries distinct information. It is information-rich rather than padded, though the single run-on block and apparent truncation reduce polish.
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 create tool with nested objects and no output schema, the description covers required fields, formats, side effects, and validation/error behavior well. The only shortfall is the visibly truncated trailing clause about timezone rewriting, leaving that behavior only partially 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?
Top-level schema description coverage is 0%, and the description compensates by inlining the full field shape with optionality markers (`startTime?`), format hints ("HH:MM"), and the distance unit enum. It also states only name/date are required, adding meaning 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?
The description opens with 'POSTs `/calendar-service/event`', giving a specific verb (create) and resource (calendar event), and the inline `CalendarEventInput` type clarifies scope precisely. It is clear what the tool does, but it never differentiates itself from siblings such as update_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 guidance or selection criteria relative to alternatives like update_calendar_event or create_manual_activity. The description states required fields and side effects but leaves the agent to infer that this is for creating (not modifying) a calendar event.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Beyond the annotations (which only declare write/non-destructive/open-world), the description discloses substantially more: validation occurs before any request (empty name or fewer than two geoPoints throws GarminError), Garmin computes distanceMeter and elevation server-side, and the privacy-to-rulePK mapping (public 1 / private 2). 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?
Dense but front-loaded, opening with the endpoint and immediately unpacking the input contract. Every clause carries information; the only cost is that the prose is terse enough to read as a spec note rather than flowing guidance.
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, the description covers input shape, defaults, validation, and server-side computation thoroughly. The notable omission is what the call returns (e.g. created course id), which would help an agent chain a follow-up get_course or download_course_gpx.
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 coverage reported at 0%, the description carries the burden and does so well: it lists the CourseInput fields, marks coursePoints/activityTypeId/privacy as optional, gives defaults (1 = running, 'private'), and explains the rulePK mapping the schema does not. It stops short of describing the inner geoPoint fields or the two-point minimum's relation to geoPoints, so not quite 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?
The description states a concrete action and resource: it POSTs to `/course-service/course` to create a course, and it names the exact `CourseInput` shape. That is clear and specific, but it never distinguishes itself from siblings like create_course_from_gpx or import_course_gpx, which are near-neighbors an agent could 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 or when-not-to-use guidance. Given the presence of create_course_from_gpx and import_course_gpx siblings, the absence of any routing hint for choosing between building a course from raw geoPoints versus importing a GPX is a real gap. Usage is only loosely implied by the required geoPoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
importCourseGpx then createCourse. 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, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description usefully adds the name-resolution fallback chain, but omits mutation details such as what happens if a course name collides, whether the GPX is validated, or auth prerequisites.
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 fragments with zero padding, and the most decision-relevant content (the underlying composition) leads. However the telegraphic style leans on the reader recognizing the API method names, so it is terse at some cost to 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?
No output schema exists, yet the return value (presumably the created course, or its id) is never mentioned, which matters for a composite write operation. The tool name says 'from_gpx' while the schema accepts .fit and .tcx as well, and that discrepancy is left 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?
The schema documents filePath (absolute .fit/.gpx/.tcx path, ~ expanded) and the key options at 50% coverage. The description adds genuine value beyond the schema by specifying the default name fallback (GPX <name>, then filename minus .gpx), which the options.name field does not state.
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 maps the tool to its two underlying API calls ('importCourseGpx then createCourse'), which implies course creation from a GPX file but never states the purpose in plain terms. An agent must know the underlying method semantics to be confident. Siblings (import_course_gpx, create_course) are not differentiated. The naming default is the only explicit behavior 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. With both import_course_gpx and create_course available as separate siblings, the agent is not told why it would choose this composite over calling those two steps itself, nor when it should not be used. The composition is implied but never framed as 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). 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. Needs Connect+
| 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, openWorldHint=true) by disclosing the subscription gate, the non-obvious PUT-instead-of-POST method, the string encoding quirk, per-serving absolute amounts, and the returned `foodId`/`servingId`. These are exactly the behaviors 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?
Dense but front-loaded, leading with the subscription requirement and payload shape. The one flaw is the redundant tail 'Needs Connect+' which restates the opening prerequisite, a sentence that doesn't 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 nested-object mutation tool with no output schema, the description supplies everything needed: prerequisite, method, complete payload contract, encoding, and the return identifiers for chaining. Nothing material 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?
With 0% schema description coverage, the description fully compensates by enumerating every `CustomFoodInput` field with defaults (`servingUnit = "G"`, `servingSize = 100`) and clarifying that values are per ONE serving, absolute (not %DV), and serialized as strings. This adds meaning the schema alone 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?
The name states a specific verb+resource (create a custom food) and the description reinforces it via the endpoint `/nutrition-service/customFood` and 'Returns the stored food'. It also differentiates from siblings by naming `logFood` as the consumer of the returned IDs. The prose itself never uses the word 'create', leaning on the name for the core 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?
It states a real prerequisite ('Requires a Garmin Connect+ subscription (check with has_connect_plus)') and points to `logFood` as the downstream tool. However, it never frames when to reach for this vs. `update_custom_food`, `get_custom_foods`, or `quick_add_food`. Usage is implied rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POSTs /gear-service/gear/v2; defaults usageType="DISTANCE", notes=""; firstUseDate routed through formatDate; 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?
This is the description's strength: it discloses defaults (`usageType="DISTANCE"`, `notes=""`), transformations (date formatting, upper-casing via `validateSportKey`), and exact unit-conversion formulas with floors for the two max-usage fields. It also states the response is returned unchecked, which warns the agent that no validation occurs.
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 free of filler, but delivered as a single semicolon-chained run-on rather than being front-loaded or structured. The most decision-relevant content (the unit conversions) 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 10-parameter write tool with no output schema, the description thoroughly covers behavioral quirks but incompletely covers the parameter set, leaving half the inputs unexplained. Annotations supply the safety profile, but an agent still lacks guidance on several required/optional 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?
With only 10% schema description coverage, the description carries heavy load and does add real meaning for the tricky params: the two `maxUsage*Km/Min` conversions, the `usageType` default, `firstUseDate` routing, and `gearType` upper-casing. But `name`, `brand`, `model`, `notes`, and `activityTypeKeys` are left entirely 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 pairs a specific verb/resource (POST to `/gear-service/gear/v2` for gear creation) with concrete behavioral detail, so an agent can identify it as the gear-creation tool. It does not, however, distinguish itself from siblings like `add_gear_to_activity`, `get_gear`, or `delete_gear`, and never states the purpose in plain language.
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 only cross-tool reference is a behavioral contrast with `addWeighIn`'s unit-handling rule, which is a note on consistency, not a routing signal to help pick between create_gear and its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Live-verified: the converted summaryDTO.distance/summaryDTO.duration were read back via getActivity and matched the expected meters/seconds exactly (5.5km/30min â 5500m/1800s)
| 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 mark this as a non-read-only, open-world write, and the description adds genuinely valuable context beyond them: the required millisecond precision on startDatetime, the live HTTP 500 failure mode it caused, and read-back verification of converted values. It does not cover auth requirements or rate limits, but the failure-mode disclosure is substantive.
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 run-on sentence built from semicolons, bold markers, and backticks. It is not front-loaded; the most important fact for an agent (that this creates a manual activity) is absent from the opening and only inferable indirectly.
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 mutation tool with no output schema and only hint-level annotations, the description omits purpose, sibling differentiation, typeKey semantics, and timeZone conventions. The format details it does include are helpful but insufficient to call the tool correctly on first attempt.
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 coverage the description must carry parameter meaning, and it partially does: it explains the kmâm and minâs conversion for distanceKm/durationMin and gives a concrete millisecond format for startDatetime. However, typeKey, timeZone, and activityName are left completely unexplained, so half the required parameters remain opaque.
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 in plain terms; it opens with unit-conversion implementation detail and only implies creation via 'before building the request body' and the name itself. It also fails to distinguish this tool from its obvious sibling create_manual_activity_from_json.
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. The sibling create_manual_activity_from_json is never referenced, so an agent gets no signal on which of the two creation tools applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds a genuinely useful behavioral trait beyond that: the payload is passed through with no shape validation, meaning malformed input surfaces as a Garmin-side error rather than a local one. It stops short of describing failure modes 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?
A single front-loaded sentence with zero filler, and the most decision-relevant fact (no validation) is stated immediately. It is arguably too terse for an opaque-payload tool, 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?
For a state-mutating, open-world tool with no output schema, no parameter documentation and an untyped nested object, the description does not say enough. It omits the payload's expected shape, what a successful call returns, and how this differs from create_manual_activity.
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% and the single parameter is an opaque additionalProperties object, so the description must carry the load. It usefully conveys that the object must match Garmin's own shape (verbatim, no validation), but it gives no pointer to where that shape is defined, leaving the agent to guess the payload 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?
The description states the mechanism (sending a raw payload to Garmin) but never says what it actually creates â the reader must infer from the tool name that it creates a manual activity. It also fails to differentiate from the close sibling create_manual_activity, which appears to be the structured variant. A specific verb is present, but the resource and sibling boundary are left implicit.
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 the obvious alternative, create_manual_activity. Only a faint implication exists that this is for callers who already hold a correctly shaped Garmin payload, which is not the same as stated guidance.
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.
resolves to null on success (204). Live-verified on synthetic fixtures created by the probe itself (never against pre-existing data): create â delete â poll-confirm gone via getActivities 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 the description's burden is lower, and it still adds real value: the 204/null return contract and, critically, that the effect is IRREVERSIBLE. The probe/fixture narrative adds a little assurance but is mostly meta-commentary about how the tool was tested rather than about the tool itself.
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 back-loaded: it opens with the return value ('resolves to null on success (204)') before stating purpose or the irreversible warning. The 'Live-verified on synthetic fixtures created by the probe itself' clause is internal process detail that does not help an agent decide or invoke, and it consumes a large share of an otherwise short 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-param destructive tool with annotations covering the safety profile and no output schema, the core needs â irreversibility and the success signal â are present. What is missing is a plain purpose statement and any hint of failure modes (e.g., what happens for a nonexistent or already-deleted activityId), leaving the definition just adequate.
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 parameter (activityId) at 100% schema coverage, so the schema already documents it ('Numeric id'). The description says nothing about the parameter's format, valid ranges, or whether string IDs are accepted, so it adds nothing beyond the schema â the baseline 3 for full 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?
The verb+resource are carried by the name and reinforced by 'delete' semantics ('resolves to null on success', 'IRREVERSIBLE'). It never states a clean purpose sentence, so an agent infers deletion from the name and behavioral cues rather than an explicit statement, and there is no sibling differentiation from delete_workout / delete_calendar_event / delete_gear.
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 one actionable directive â 'confirm with the user before calling' â which is genuine usage guidance for a destructive op. But there is no when-to-use framing, no prerequisites, and no routing between this and the many sibling delete_* tools; usage must be inferred from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 risk is structurally known; the description reinforces this with 'IRREVERSIBLE' and adds the confirmation workflow, which is genuinely actionable. It stops short of describing post-delete effects 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?
A single tight sentence that front-loads the action and appends the irreversible warning. The warning is run together with the parameter note rather than separated, 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 2-parameter destructive tool with no output schema, the description covers the critical concerns: what to delete, where the identifier comes from, and the irreversibility. The unexplained required cdate parameter is the only notable 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 50%: cdate is documented in the schema, version is not. The description compensates partially by explaining that version identifies a reading sourced from getBloodPressure, but it says nothing about cdate, which is also required.
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 one reading') plus the scoping unit ('by its version'), which cleanly separates it from the bulk delete siblings like delete_weigh_ins. The reference to getBloodPressure clearly identifies the domain object.
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?
Tells the agent where the required version comes from (getBloodPressure) and adds an explicit precondition to confirm with the user before calling. It doesn't name alternative tools, but the source-of-value guidance removes the main ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE /calendar-service/event/{id}, resolves null (204). IRREVERSIBLE 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 declare destructiveHint=true and readOnlyHint=false, but the description adds a human-confirmation requirement and the fact that the call resolves to null with a 204, which is useful return behavior with no output schema. The doubled 'IRREVERSIBLE IRREVERSIBLE' emphasizes the risk but reads as noise rather than new information.
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 the destructive warning placed where it will be read before the call. The duplicated 'IRREVERSIBLE IRREVERSIBLE' is wasted text, and the raw HTTP route/status details are somewhat implementation-flavored.
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 supplies the two things an agent most needs: irreversibility + user confirmation, and the null/204 return. Nothing critical is missing, though alternatives and error behavior (e.g., non-existent id) go unmentioned.
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% (eventId documented as 'Numeric id'), so the schema already carries the parameter burden. The description's '{id}' placeholder in the route adds no semantics beyond what the schema states, matching the baseline for fully-documented single-param tools.
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 (DELETE a calendar event by id), which is unambiguous and clearly separable from siblings like get_calendar_event, update_calendar_event, and delete_activity. It does not explicitly contrast itself with any sibling, so it falls short of the top mark.
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 instruction â confirm with the user before calling â which is real guidance for a destructive operation. However, it names no alternatives or conditions for choosing this tool over update/unschedule/delete variants, 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.
DELETE /course-service/course/{courseId}, resolves null (204). IRREVERSIBLE. 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, so safety is partly covered, but the description adds real value: the 204/null response shape, the irreversibility warning, and a rate-limit/readiness timing caveat (429 shortly after creation). These are non-obvious behaviors not present in 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 content is short but sloppy: 'IRREVERSIBLE' is repeated twice in close succession and the sentence about the 429 is awkwardly fused into the rest. The core warnings are front-loaded, but redundancy and phrasing cost 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 single-param destructive tool with an output schema absent, the description covers the key agent needs: what happens on success (204/null), that the action cannot be undone, and a timing hazard. Only the when-to-use-vs-alternatives dimension 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 a single required courseId documented as 'Numeric id', so the schema carries the parameter detail. The description only shows courseId interpolated in the path template and adds no format, range, or source guidance beyond that, matching 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 gives a specific verb (DELETE) and resource (course) via the HTTP endpoint, clearly identifying the tool as removing a course. It is distinguishable from sibling deletes (delete_activity, delete_workout, delete_gear) by the resource, though it leans on the raw endpoint rather than a plain-language 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 gives some usage context â confirm with the user before calling, and awareness of a possible 429 shortly after creation â but never states when to use this tool vs. alternatives (e.g., update_course, get_course) or why deletion is the correct choice in a given situation.
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). DELETE /nutrition-service/customFood/{foodId}, resolves null. IRREVERSIBLE. Needs Connect+ 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 genuinely new context: the deletion is irreversible, a Connect+ subscription gates it, and it resolves null. This goes meaningfully beyond what the structured fields 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?
The text is garbled and repetitive: 'IRREVERSIBLE' appears twice, and the second sentence ('IRREVERSIBLE. Needs Connect+ IRREVERSIBLE: confirm with the user before calling') reads as broken fragments. The important subscription note is front-loaded, but the redundancy wastes 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 an irreversible mutation with no output schema, the description covers the key facts an agent needs: the subscription gate, the irreversibility, the required user confirmation, and the null return. Only the foodId provenance and alternative-tool routing are 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 0%, so the description carries the burden of explaining foodId, but it only surfaces it as a path template without elaborating on format or source (e.g., obtained from get_custom_foods). It identifies the parameter's role but adds little beyond the schema's type declaration.
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 (DELETE) and resource (customFood/{foodId}), making the operation unambiguous. It does not explicitly differentiate from siblings like delete_food_logs or update_custom_food, but the resource is specific enough to identify the target.
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 concrete preconditions: a Connect+ subscription is required, the agent should verify via has_connect_plus, and the user must be asked to confirm before calling. It lacks explicit when-to-use-vs-alternative routing, but the prerequisite and confirmation protocol are strong context.
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). 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. IRREVERSIBLE. 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 flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavioral context: the Connect+ subscription requirement, the batch capability ('any number in ONE call'), the irreversibility, and the confirm-with-user protocol. The auth prerequisite and confirmation workflow go well beyond what 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?
Front-loads the subscription prerequisite and the irreversible warning, which is good. However, 'IRREVERSIBLE' appears twice and 'Needs Connect+' duplicates the opening requirement, so several clauses repeat information that already landed once.
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 mutation, the description covers the key agent needs: prerequisite subscription, ID source, batch capability, irreversibility, and confirmation. It does not describe what the response returns, though with no output schema that is a minor omission for a delete 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 only 50% (logIds is undocumented in the schema), so the description must compensate, and it does: it explains that logIds is a batch array and where the IDs come from (entries of getNutritionDailyFoodLog). The date parameter is covered by the schema's YYYY-MM-DD format and by the endpoint path notation.
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 (delete food logs) and even disambiguates scope by noting the tool handles both regular and quick-add entries in a batch. This clearly separates it from siblings like delete_custom_food or delete_activity, and the embedded REST endpoint anchors the exact 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?
Gives strong prerequisites and sourcing guidance: requires Connect+ (check with has_connect_plus) and logIds come from getNutritionDailyFoodLog. It also mandates user confirmation. What it lacks is any explicit when-not or comparison against a sibling, but for a delete operation with no true alternative this is close to complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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: removes the gear AND its activity history 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 only declare destructiveHint/readOnlyHint/openWorldHint generically; the description goes further by disclosing exactly what is destroyed (the gear AND its activity history), the return behavior (resolves null on 204), and the UUID hyphenation gotcha that causes 404s. This is substantial 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 endpoint method and the destructive warning are front-loaded well, but the duplicated 'IRREVERSIBLE:' fragment is a clear typo/formatting artifact that wastes space. Overall the passage is reasonably dense but not clean.
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 destructive tool with no output schema, the definition covers the return value (null/204), the destruction scope, and the UUID format trap. It is nearly complete; the only omission is any note about permissions/auth failure modes, 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 0%, so the description must carry the parameter burden, and it does: it explains the required hyphenated UUID form, that `getGear` returns the bare 32-char form, and that the method auto-re-inserts hyphens so either form works. That meaningfully exceeds the bare `gearUUID: string` schema, though it doesn't document the parameter name explicitly.
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 endpoint (`DELETE /gear-service/gear/v2/{gearUUID}`) and the resource it operates on, so the verb+resource are unambiguous. It does not explicitly contrast itself with the sibling `remove_gear_from_activity`, but the scope (deleting the gear itself) is clear enough to distinguish it from unlinking a gear from an activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a strong operational directive ('confirm with the user before calling') which is genuine when-to-invoke guidance for a destructive op. However, it offers no comparison to alternatives like `remove_gear_from_activity` or `create_gear`, and no prerequisites beyond the confirmation warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Goes well beyond the destructiveHint annotation by disclosing the wire mechanism (changeState: "DELETED"), the resulting state (fallback to DEFAULT), two refusal/error behaviors (DEFAULT refused, throws for a sport with no profile), and an explicit irreversibility warning. This is rich behavioral context an agent cannot get 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?
Terse and front-loaded, with the consequence stated first and the safety warning last. The final clause runs together without punctuation ('doing nothing IRREVERSIBLE'), a minor structure flaw, but no sentence 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 single-parameter destructive mutation with no output schema, the description covers behavior, error cases, and irreversibility well. The only gap is the lack of detail on valid sport values besides the refused DEFAULT.
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 usefully reveals that 'DEFAULT' is a special value that is refused, but says nothing about the expected name/format for other sports, leaving the parameter only partially characterized.
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 (delete) and resource (heart rate zones / stored profile) and explains the observable effect: the profile is removed and the sport falls back to DEFAULT. This distinguishes it cleanly from set_heart_rate_zones and get_heart_rate_zones.
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 instructs the agent to confirm with the user before calling and warns that sport=DEFAULT is refused. It gives clear context for when the tool applies, though it does not name sibling alternatives (set_/get_) as the fallback path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 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?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description still adds substantial value beyond them: the exact side effects (scheduled workouts leave the calendar, completed activities remain), the return shape (null/204), the 404 error string on repeat calls, and an explicit irreversibility warning. This is precisely the extra context the structured fields 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?
One dense paragraph with no filler sentences, and the operation itself is front-loaded. The doubled-path aside and the observation date are minor implementation trivia that slightly dilute the message, but the critical warning is clearly emphasized.
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 compensates by documenting the successful response (null/204), the failure mode (404 with message), and the second-order effects on calendar and completed activities. Nothing an agent needs to call this destructive operation 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% for the single planId parameter, so the schema already carries the semantics. The description only echoes planId inside the raw path template and quotes the 404 message containing the id, adding no format or lookup guidance (e.g. where to obtain a planId). 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 verb (DELETE) and resource (training plan), and even quotes the exact Garmin Connect UI action it corresponds to ("Quit Plan"), which disambiguates it from the many other delete_* siblings (delete_workout, delete_activity, delete_gear). An agent knows exactly what is being removed 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?
Provides clear usage context: it states the operation is irreversible and instructs the agent to confirm with the user before calling. It also warns that a second call returns 404, which implicitly tells the agent not to retry. It stops short of naming an alternative sibling tool or a when-not-to-use condition, so it is clear context rather than explicit routing.
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.
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: deletes ALL weigh-ins recorded on cdate when it proceeds 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?
Goes well beyond the destructiveHint annotation: it discloses the internal call chain (getDailyWeighIns then per-entry deleteWeighIn), the guard that can leave the operation a no-op, the return value (null vs. count), and flags IRREVERSIBLE with an instruction to confirm with the user. This is exactly the behavioral 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?
Content is front-loaded with the mechanism, but the IRREVERSIBLE warning is duplicated almost verbatim and the 'no HTTP path of its own' detail is implementation trivia. The formatting is rough and repetitive, costing 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?
With no output schema, the description does the work of explaining the return value (null or count) and the side effects, which is the key thing an agent needs. The conditional deleteAll behavior is functional but phrased densely, leaving a little ambiguity about the exact branch that deletes all entries.
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, but deleteAll has no schema description. The description compensates by explaining the conditional role deleteAll plays (it gates deletion when multiple entries exist), giving the undocumented parameter real 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 a specific verb+resource (deletes weigh-ins on a given date) and distinguishes itself from the singular sibling delete_weigh_in by being the day-wide/bulk variant. The guard logic (loops per entry, requires deleteAll when multiple exist) makes the scope 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?
Gives explicit conditions for when it proceeds versus deletes nothing (zero entries, or multiple entries without deleteAll), which tells the agent when the call is a no-op. It does not explicitly name delete_weigh_in as the alternative for single-entry deletion, so routing is left partly 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 template from the workout 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 safety profile is largely covered. The description adds the irreversible consequence and a mandatory human-confirmation step, which is real value beyond structured data. It does not describe what happens to workouts already scheduled from that template, which would have completed the picture.
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, front-loaded with the action and the destructive warning. The duplicated 'irreversible IRREVERSIBLE' is redundant emphasis and mildly wasteful, and the lowercase opening is sloppy, but there is 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 one-parameter destructive tool with no output schema and annotations covering the safety hints, the description supplies the key missing piece: irreversibility plus a confirm-first requirement. The only shortfall is the unaddressed effect on already-scheduled workouts derived from the template.
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 workoutId parameter, so the schema carries the burden and baseline 3 applies. The description adds nothing about the id's format or source (e.g., whether it accepts the id returned by get_workouts).
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 ('the template from the workout library'), which also implicitly distinguishes it from scheduled-workout siblings like unschedule_workout. It never uses the word 'workout' explicitly and calls the resource a 'template', so an agent must infer that this targets create_workout/update_workout artifacts. Clear, but sibling 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?
Gives an explicit precondition for invocation: confirm with the user before calling. That is genuinely actionable guidance beyond mere context. It does not name alternatives (e.g., unschedule_workout for scheduled instances vs. deleting a library template), which is the main remaining gap.
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.
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 declare readOnlyHint=true and openWorldHint=true, so safety is partly covered. The description adds the default value ('ORIGINAL') for format, which is minor. It omits anything about what the download returns (file bytes? URL?), auth constraints, or size limits â the critical behavior for a download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short, but it is not front-loaded with purpose â it opens with a raw type definition rather than telling the agent what the tool does. Brevity here reflects missing content, not 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?
With no output schema and a download/mutation-adjacent tool, the description should explain what is returned and when to use it. Instead it covers only one parameter's enum, leaving the tool's core behavior entirely undocumented.
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%. The description documents the `format` enum and default, which the schema's enum already implies, and says nothing about `activityId` (schema only notes 'Numeric id'). It adds the default, so slightly above baseline for the covered param but leaves activityId semantics to 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 never states what the tool does. It only documents the `format` enum values and default, giving no verb+resource like 'download an activity file'. An agent cannot tell from this text that this tool downloads activity data, nor how it differs from siblings like get_activity or download_course_gpx.
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 alternatives (e.g., get_activity_details returns data rather than a downloadable file), and no conditions for selecting a format beyond the enum list itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered. The description only restates the read nature ('GETs ... through client.download') and adds nothing about what is actually returned (a binary GPX file?), auth requirements, or any side effects. Minimal added context 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?
It is a single compact sentence with no waste, but it is not front-loaded around purpose or return behavior â it leads with an HTTP method and endpoint path rather than what the tool accomplishes for the caller. Concise but under-specified as a fragment.
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 explanation of the return value, the description leaves a key gap for a download tool: the agent cannot tell that it receives GPX file content rather than structured data. For a low-complexity one-param tool it covers the call mechanics but not the result 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?
Schema description coverage is 100% with a single required `courseId` (documented as 'Numeric id'), and the description merely echoes the parameter as the path placeholder. Baseline 3 applies since the schema fully documents the parameter and the description adds no syntax or format detail.
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 path (`/course-service/course/gpx/{courseId}`) and an operation, but it does so as a raw HTTP implementation detail ('GETs ... through client.download') rather than stating in plain language that it retrieves a course's GPX file. An agent can infer the effect from the endpoint and tool name, but it is not distinguished from siblings like `download_activity`, `download_workout`, or `import_course_gpx`.
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-to-use, or alternative-selection guidance. Nothing tells the agent how this differs from `get_course`, `import_course_gpx`, or the other `download_*` tools, leaving usage entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
routed through formatDate, routed through client.download
| 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 the safety profile is covered. The description adds no behavioral context beyond a vague hint of a download call, and it says nothing about the snapshot's contents, scope, or side effects. No contradiction with annotations, but no value added either.
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 that reflects under-specification rather than conciseness. Two comma-spliced fragments of implementation jargon carry no front-loaded purpose and every word fails to 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 one-parameter download tool with no output schema, the description is the only place to explain what a 'health snapshot' contains and what the returned artifact is. It explains none of this, leaving the agent unable to call the tool with confidence.
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 requestedDate parameter, which is fully documented as a UTC calendar date in YYYY-MM-DD format. The description adds nothing on top of the schema, 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 never states what the tool does. 'routed through `formatDate`, routed through `client.download`' is internal implementation detail, not a purpose statement, and gives no indication that this retrieves a health snapshot. An agent cannot distinguish it from download_activity, download_workout, or download_course_gpx.
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 download tools. The agent is left to infer everything from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered. The description does add one genuinely useful behavioral fact beyond annotations and beyond the schema: the return payload is binary FIT-file bytes, which matters for a tool with no output schema. It stops short of saying how those bytes are encoded or transferred.
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?
There is zero padding, which is good, but the content is a noun fragment rather than a sentence, so it reads as under-specification rather than disciplined brevity. The single assertion is at least 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 one-parameter read tool with no output schema, the description covers the single most important unknown: the return type is FIT bytes. It omits how those bytes are surfaced (base64 string, temp file, MIME type) and any size or error behavior, leaving the agent partially informed but not fully equipped.
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 (workoutId, 'Numeric id'), so the schema carries the parameter burden. The description adds nothing about the id, and accepts both integer and string forms without explaining that flexibility, 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?
'FIT-file bytes' identifies the payload type, which together with the name download_workout implies fetching a workout as a FIT file. But it is a sentence fragment with no verb, and it never distinguishes this from siblings like download_activity or download_course_gpx, so an agent must infer the resource 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?
The description gives no when-to-use context, no prerequisites (e.g. requires a valid workoutId already obtained via get_workouts), and no mention of alternatives such as download_activity for non-workout targets. Three words of fragments leave all routing 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 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.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that pagination defaults to start=0, limit=20, which is not present in the schema. It says nothing about maximum limits, ordering, or result shape, so it clears the lower annotated bar but adds little.
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, which is efficient, and the default values are front-loaded. But the brevity comes from under-specification rather than discipline, so it only reaches adequacy.
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 listing tool with no output schema and no annotation detail about returns, the description should explain what is listed, in what order, and how it relates to the date-filtered siblings. Only the default paging values are covered, leaving the agent unable to call this confidently versus its alternatives.
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 it does supply the only semantic content available: default values for both start and limit. However, it omits units, maximums, and whether limit is capped, so the compensation is partial.
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; it only supplies pagination defaults. The name get_activities implies a listing of activities, but the text itself contains no verb+resource statement and does nothing to distinguish it from get_activities_by_date, get_activities_for_date, or get_last_activity.
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, despite many near-identical siblings (get_activities_by_date, get_activities_for_date, count_activities, get_last_activity). Nothing tells the agent which of these to pick or under what conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already declare readOnlyHint=true and openWorldHint=true. The description does add genuine behavioral context beyond that â fixed 20-item pages, automatic pagination, and a GarminError thrown after 2000 pages â which is real error/pagination disclosure an agent cannot get from 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 a single compact sentence with no padding, so raw length is fine. However it front-loads implementation internals rather than the tool's purpose, so the most important information is absent rather than merely late.
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 and four parameters, the description omits the date-range semantics, filter behavior, and result shape. Pagination is covered, but that is one narrow aspect of what an agent needs to invoke this 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 50%, so the description would need to compensate for undocumented sortorder and activitytype, which it does not. Worse, it references a `start` offset incremented by 20 while the schema's date parameter is `startdate`, a naming mismatch that could mislead the agent about whether a pagination parameter exists.
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 retrieves â activities for a date range â and instead documents only internal pagination mechanics. The name alone conveys purpose, so the prose adds no distinguishing signal against siblings like get_activities, get_activities_for_date, or get_activity.
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 the several overlapping activity-retrieval siblings in the toolset. The agent is left to guess which of get_activities, get_activities_for_date, or this tool to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 must add behavioral context instead, and it does not. It discloses no return shape, no rate limits, no scoping behaviour â only an internal routing detail about the server path that has no bearing on how the agent should call or interpret the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is short, but brevity alone is not conciseness when the one sentence present does not serve the caller. The sentence begins with 'despite the name', which leads with a disclaimer rather than a purpose, and the implementation detail about the path does not earn its place in an agent-facing 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 single-parameter read tool with no output schema and 100% parameter coverage, the description still needs to convey what is returned for a date, and it fails to do so. The annotations cover safety, but the core question â activities or heart rates? â is left unresolved and is in fact muddied further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole parameter 'fordate' is fully documented as a YYYY-MM-DD UTC calendar date in the schema, so the baseline of 3 applies. The description adds nothing about the parameter, but per the scoring rule the schema carries this dimension.
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. Instead it tells the agent that the underlying path is '/mobile-gateway/heartRate/...' and not an activities-service path, which directly undermines the tool's name (get_activities_for_date) rather than clarifying it. An agent reading only this text cannot determine whether the tool returns activities or heart-rate data for the given 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 when-to-use guidance, no conditions, and no routing to alternatives such as get_activities_by_date or get_heart_rates, both of which appear in the sibling list and are obvious candidates. The single sentence offers no selection criteria at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One activity's summary by id. Throws GarminError if Garmin returns nothing.
| 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 and openWorldHint, lowering the bar. The description adds genuinely useful behavior beyond them: the failure mode ('Throws GarminError if Garmin returns nothing'), telling the agent to expect an exception rather than an empty summary.
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 compact sentences, front-loaded with the core purpose and immediately followed by the exceptional behavior. Nothing extraneous.
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-read tool with full annotation coverage and a fully documented parameter, this is nearly sufficient: purpose, scope, and error behavior are all present. Return-shape detail is only gestured at with 'summary', but there is no output schema requiring reconciliation.
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 activityId parameter is already documented as a numeric id; baseline 3 applies. The description reinforces 'by id' but adds no format or constraint detail beyond what the schema 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 and resource ('get one activity') plus scope ('summary by id'), which meaningfully distinguishes it from the many sibling get_* tools like get_activity_details and get_activities. It stops short of naming those siblings explicitly, so differentiation relies on the reader inferring 'summary' vs 'details'.
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 'by id' framing implies a single-record lookup versus the list/chart siblings, giving an implied use case. However, it never states when to reach for this over get_activity_details or get_last_activity, and gives no prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds no behavioral context of its own (no scope, no payload shape, no caveats). The single sentence is purely about parameter defaults, which belongs to the parameter layer, not 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?
It is short, but it is a dangling fragment with no subject or verb, so brevity is the result of under-specification rather than tight writing. Nothing about the tool's purpose is front-loaded because no purpose is stated at all.
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, three parameters, and no annotations beyond read-only/open-world, the description is the only place purpose and return content could be explained, and it omits both entirely. An agent cannot tell what this returns or why it differs from get_activity.
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% (only activityId is documented as 'Numeric id'), so the description must compensate. It does partially: it supplies the defaults maxchart=2000 and maxpoly=4000 and maps them to the wire names maxChartSize/maxPolylineSize. However it never explains what those sizes control (chart data resolution? polyline point count?) or the accepted units/ranges.
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 get_activity_details does. It opens with parameter defaults and reads like a fragment of schema documentation rather than a description of a tool. Against siblings such as get_activity, get_activity_splits, and get_activity_weather, an agent has no basis for telling this tool apart.
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 alternatives, and no indication of what kind of 'activity details' this returns versus the many other get_activity_* siblings. Nothing routes the agent to or away from this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 adds valuable context beyond annotations by specifying the exact endpoint path and the exact return shape and values (nine `{typeId, typeKey, sortOrder}` entries), though it omits auth or rate-limit notes.
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; the endpoint and return shape are packed efficiently into one line.
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 lookup with no output schema, the description fully covers what an agent needs: it describes the return format and all nine values. Annotations already cover the safety profile, so nothing critical 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?
There are zero parameters, so per the rubric the baseline is 4. The description appropriately does not discuss parameter syntax because none exists.
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 ('GETs') and resource (the eventTypes endpoint) and enumerates the nine returned entries, making it immediately distinguishable from sibling type-related tools like get_activity_types or set_activity_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?
Usage is implied: the tool is clearly a reference-data lookup for event type IDs/keys, but the description never states when to call it or which sibling consumes its output (e.g., set_activity_event_type). No explicit alternatives or exclusions are given.
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.
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's only additional claim is that it returns an array, which is mildly useful given there is no output schema, but "verified live" is opaque jargon that conveys no actionable 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?
It is short, but that brevity comes from under-specification rather than efficiency â the one sentence is filler with no informative content, and "verified live" is unearned.
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 is returned, and it provides only "an ARRAY" with no indication of element shape, gear fields, or the relationship between the activity and its gear. For a retrieval tool with many gear-related siblings, this is far from 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% for the single activityId parameter, so the schema already documents the input fully. The description adds no semantics beyond that, which is the baseline case 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?
The description never states what the tool does. "returns an ARRAY, verified live" describes an output shape and an unexplained quality claim, not a verb+resource; an agent only learns the purpose from the tool name itself. It is neither a specific purpose statement nor even a restatement of the title.
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-to-use, or alternative guidance at all, despite many siblings (get_gear, get_gear_activities, get_gear_stats, get_gear_defaults, add_gear_to_activity, remove_gear_from_activity) that an agent could easily confuse with this one.
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.
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 and openWorldHint, so safety is covered. The description adds one genuine behavioral fact â output richness varies by activity type â but says nothing about what happens for non-qualifying types, 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?
A single short, front-loaded sentence with no filler. It is efficient, though its brevity reflects under-specification as much as tight writing.
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 explain what "typed splits" contain and which activity types benefit, since the return value is otherwise opaque. As written, an agent knows it is a richer alternative but not what it will actually 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?
Only one parameter (activityId) with 100% schema description coverage, so the schema carries the burden. The description adds no meaning about the identifier beyond what the schema states; 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 defines the tool only by contrast ("richer detail than `getActivitySplits`") and never states what it actually returns or does on its own. The name implies typed splits, and it does successfully differentiate from the `get_activity_splits` sibling, but the core purpose statement is left implicit.
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 implies the alternative (`getActivitySplits`) and gives a usage condition ("for some activity types (e.g. Bouldering)"), but "some activity types" is not actionable â the agent cannot tell which types qualify beyond the single example, so when-to-use remains guesswork.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ActivityTypesResponse is ActivityType[] (154 entries observed live: {typeId, typeKey, parentTypeId, isHidden, restricted, trimmable}), an ARRAY, verified live
| 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 the fact most likely to trip an agent up: the payload is an ARRAY, not a wrapped object, plus the observed size (154) and the exact field names. Since no output schema exists, this return-shape disclosure is genuinely 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?
It is a single sentence with no padding, but the emphasis is inverted: the single most decision-relevant fact ('an ARRAY') is placed last and stated redundantly ('154 entries observed live' plus 'verified live'). The purpose should have led the 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 simple zero-argument getter the description does cover the return contract, which matters because there is no output schema. However, it omits how the returned typeIds relate to other tools (e.g. set_activity_type) and gives no signal about stability or caching of the 154-entry catalog.
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 compensate for. Baseline 4 applies for a no-argument 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 a verb or what the tool does; it only describes the response shape. A reader can infer that it returns the catalog of activity types, but that inference comes from the name, not the description. It is not a pure tautology, since the field list and array shape add real information, but the purpose itself is left implicit.
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 differentiation from near siblings such as get_activity_event_types or set_activity_type. Nothing tells the agent that this is a static reference catalog useful for resolving a typeId before calling set_activity_type.
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.
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, and the description does not contradict them. Beyond that it adds almost nothing behavioral: no note on what happens for an unknown or malformed planId, whether the plan must be active, or how large the response is.
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, and the differentiating information is front-loaded. But it is a sentence fragment built from an internal URL, so the brevity comes at the cost of readability rather than from disciplined editing.
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 telling an agent what comes back, and it does not: the shape of an adaptive training plan, whether it includes workouts or phases, and error behavior are all unspecified. For a read tool with one parameter the definition is technically callable but leaves the agent guessing about the result.
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 required parameter and 100% schema description coverage, the schema already documents planId (accepting integer or string). The description adds only the minor fact that planId is interpolated into the path rather than passed as a query parameter, which is the baseline-level value expected here.
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 (GETs) and resource (the fbt-adaptive training plan sub-path) and explicitly distinguishes it from the sibling get_training_plan_by_id's phased path, which satisfies sibling differentiation. However, it describes the tool through its API route rather than stating plainly what an adaptive training plan is or what the caller gets back, so it is clear but implementation-flavored rather than purpose-oriented.
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 contrast with getTrainingPlanById's phased path is a weak routing cue, but the description never says when an agent should prefer this tool over get_training_plan_by_id, get_training_plans, or get_training_plan_workouts, nor what preconditions (e.g., an existing adaptive plan, Connect+ entitlement) apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 cover safety (readOnlyHint=true, openWorldHint=true). The description adds non-obvious behavioral context beyond that: coach workouts lack a `workoutId` and a sibling endpoint 404s for them, which prevents a failed call. It stops short of describing return shape, pagination, or failure modes for bad uuids.
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 compact clauses, front-loaded with the endpoint and main payload description, then the disambiguation and uuid sourcing. Every sentence carries information, though the raw URL path is somewhat implementation-flavored and slightly denser than needed 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 helpfully names the returned content (segments, steps, estimatedTrainingEffect) and explains the uuid's origin and the sibling-tool limitation. Combined with readOnly/openWorld annotations, an agent has enough to call it correctly; only return format/error behavior 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 description coverage is 0% for the single required `workoutUuid` param, so the description must compensate, and it does: it tells the agent where to source the uuid (`getTrainingPlanWorkouts`/`getScheduledWorkoutSummaries`) and that it is a coach/adaptive workout identifier. It does not add format details, but the sourcing guidance is genuinely useful for a 1-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?
States a specific verb (GETs) and a precise resource: the `/workout-service/fbt-adaptive/{uuid}` Garmin Coach workout, and enumerates its contents (segments, steps, estimatedTrainingEffect). It explicitly distinguishes itself from `getWorkoutById`, 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?
Names the alternative tool (`getWorkoutById`) and explains why it cannot be used for these workouts (no `workoutId`; `/workout-service/workout/{uuid}` returns 404). It further tells the agent exactly where to obtain the required uuid: `getTrainingPlanWorkouts` or `getScheduledWorkoutSummaries`. This is explicit when-to-use and how-to-source guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral detail beyond that: specific validation rules (start non-negative, limit positive) and the fact that violating them throws GarminError, plus confirmation the call returns an ARRAY rather than an object. These are genuinely useful behavioral disclosures an agent can act on.
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 that front-loads the endpoint and follows with validation and return-type facts. It is compact with little waste, though the raw endpoint path is borderline noise for an agent that never sees URLs.
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 GET read with annotations covering safety and no output schema required, the description covers validation and return shape adequately. It still omits what the returned challenges represent and the meaning of the pagination-style parameters, so it is minimally viable rather than 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 0%, so both parameters rest entirely on the description. It supplies validation constraints (start non-negative, limit positive) which the schema lacks, but never explains what start/limit actually mean â offset vs. index vs. count â so the semantic meaning of the values remains 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?
The description names a verb (GETs) and the raw endpoint path for historical ad hoc challenges, so the basic resource is identifiable. However, it never explains what an 'adhoc challenge' is or how it relates to the many sibling challenge tools (get_badge_challenges, get_inprogress_virtual_challenges, get_earned_badges), leaving an agent unable to distinguish it semantically from its 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?
There is no when-to-use guidance and no mention of alternatives among the numerous challenge-related sibling tools. The agent is left to 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.
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.
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=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral details beyond annotations: the same start/limit validation as getBadgeChallenges, an array-not-dict correction, and a live start=0 returning 400. These are concrete quirks an agent would not otherwise know.
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 entire description is one dense sentence that front-loads the endpoint and then packs shared validation and behavioral quirks. It is efficient and not padded, though the shorthand references to getBadgeChallenges and internal correction behavior assume outside knowledge.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter read-only GET, no output schema, and annotations covering safety, the description provides endpoint and behavioral quirks. But it omits plain-language purpose, parameter meanings, and output shape, leaving an agent without enough context to confidently distinguish this from related badge-challenge 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 description coverage is 0% for both required parameters. The description only mentions that start/limit validation is shared and that start=0 causes a 400; it does not define what start or limit mean, their expected types beyond number, acceptable ranges, or pagination 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 HTTP verb and resource endpoint (`GETs /badgechallenge-service/badgeChallenge/available`), which tells an agent it retrieves available badge challenges. However, it never gives a plain-language user-facing purpose and only references getBadgeChallenges for shared behavior rather than clearly distinguishing the two 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?
There is no explicit guidance on when to use this tool versus siblings such as get_badge_challenges, get_available_badges, get_earned_badges, or get_non_completed_badge_challenges. The reference to getBadgeChallenges is only about shared implementation quirks, not an alternative-selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=true and openWorldHint=true, so safety and network behavior are covered. The description adds two non-obvious facts the annotations do not: the endpoint is always called with showExclusiveBadge=true, and the badgeImageUrls field is nullable. It omits auth requirements, pagination, and any notion of result size, which keeps it at a moderate level.
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 contains no filler, but the semicolon-separated fragment style is cryptic rather than front-loaded, and 'stays nullable' does not clearly identify what remains nullable. Compactness here reflects under-specification as much as 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, the description carries the burden of describing returns, and it only partially does so via the badgeImageUrls parity note and nullability remark. For a no-param read tool that is minimally acceptable, but the agent still cannot tell what the payload contains overall or how it differs from 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?
The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter discussion beyond noting the fixed query string baked into the 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 raw path `/badge-service/badge/available` implies retrieving available badges, and the hardcoded `showExclusiveBadge=true` hints at scope. However, it never states the purpose in plain language and does not distinguish itself from close siblings like `getEarnedBadges`, `get_in_progress_badges`, or `get_badge_detail`, so the agent must infer the difference from names 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 or when-not-to-use guidance. The only sibling reference, `getEarnedBadges`, is cited solely to explain a shared response field name, not to help the agent choose between the two tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: the endpoint returns an ARRAY and Garmin's server returns a 400 for start=0 despite permissive client-side validation, with a warning not to misread that as a wrong URL.
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 endpoint and method, followed by the return shape and the live-discovery caveat. It is dense but each clause carries signal; the parenthetical 400 message and "not a wrong URL" note earn their place by preventing misdiagnosis.
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 supplies the return type (array), a cross-reference for validation parity, and the start>=1 server constraint. The main residual gap is the absence of any explanation of what `limit` controls.
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. It adds a critical semantics detail (start must be >=1 in practice due to server-side rejection), which is valuable, but `limit` is only covered by a cross-reference to getAdhocChallenges rather than explained here.
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 (the completed badge-challenge endpoint) and even names the exact URL path. The word "completed" distinguishes it from siblings like get_non_completed_badge_challenges and get_available_badge_challenges, though it never explicitly names 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?
Usage context is only implied via the "completed" scope and a cross-reference to getAdhocChallenges for shared validation. The concrete "call with start>=1 in practice" is real operational guidance, but there is no explicit statement of when to prefer this tool over the many other badge/challenge siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Works for unearned badges. An unknown id is a 400 GarminHttpError, not a 404. The badge and each relatedBadges entry gain badgeImageUrls (see getEarnedBadges). Carries no description tâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| badgeId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial context beyond them: positive-integer validation on badgeId, and the non-obvious error contract that an unknown id returns a 400 GarminHttpError rather than a 404. It also enumerates what each relatedBadges entry carries, which is real behavioral 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?
The verb, endpoint and resource are front-loaded, and the sentence is dense but organized. It is long, but since there is no output schema the return-field detail is largely earning its place rather than 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?
With no output schema, the description carries the return-shape burden and does so (getEarnedBadges fields plus relatedBadges, assoc fields, followings, badgeImageUrls), and it documents validation and error behavior. Only the origin of a valid badgeId 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 single badgeId property is an undocumented number), so the description must compensate. It adds the meaningful constraint that badgeId is validated as a positive integer, which is not in the schema, though it does not indicate where a valid badgeId is sourced 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?
States a concrete verb (GETs) and resource (the badge detail v3 endpoint), and clarifies scope with 'Works for unearned badges', which an agent needs to distinguish it from get_earned_badges/get_available_badges. The purpose is unambiguous 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 rather than stated: the note that it 'works for unearned badges' and the reference to getEarnedBadges for field semantics hint at context, but there is no explicit when-to-use/when-not or naming of the retrieval siblings. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 supply readOnlyHint and openWorldHint, so the safety profile is covered. The description adds only the enddate-default behavior and says nothing about what data is returned (systolic/diastolic, per-reading vs aggregated), the granularity, or how ranges behave. 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 single sentence is short and has zero filler, but it is under-specified rather than effectively concise: a tool definition needs to earn its place by conveying purpose, and here the only sentence is a minor parameter note.
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 two date parameters, the description should at minimum say what is retrieved and over what period. Instead it omits the tool's purpose entirely, leaving the agent dependent on the name alone.
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 format (YYYY-MM-DD UTC) is already fully documented, giving a baseline of 3. The description does add one genuine piece of information not in the schema â that enddate defaults to startdate â but it addresses only one of the two parameters and no other 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 never states what the tool does. Its entire content is a parameter-default note ('enddate defaults to startdate'), which tells an agent nothing about retrieving blood pressure readings. The verb/resource is only inferable from the tool name, so the description itself is effectively missing.
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 such as get_heart_rates, get_daily_stats, or set_blood_pressure. No context, no exclusions, nothing to distinguish it from the many sibling 'get_*' data tools.
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.
GETs /weight-service/weight/dateRange; enddate defaults to startdate; 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 read-only/open-world safety, but the description adds real behavioral detail: enddate defaults to startdate and a GarminError is thrown when startdate > enddate. That error precondition is valuable, non-obvious information beyond what annotations or schema 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?
Front-loaded with the endpoint path, which is reasonable, but the trailing sentence about getStatsAndBody delegating reads as implementation trivia and the whole thing is a run-on string of semicolon clauses.
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 what the tool returns (weight/body-composition records over the range), but it only names the endpoint. It covers defaults and error behavior adequately, leaving the return shape 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 100%, so baseline is 3, but the description adds the default value for enddate (defaults to startdate) which the schema does not state. That is genuine semantic 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?
The description names the underlying endpoint (`/weight-service/weight/dateRange`) and implies a date-range weight/body-composition read, but never states plainly what the caller gets back. It is more specific than the bare name but frames the tool in implementation terms rather than user-facing 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 when-to-use guidance and no comparison against the many sibling read tools (get_weigh_ins, get_daily_weigh_ins, get_stats_and_body). The note that getStatsAndBody delegates here hints at a relationship but does not tell the agent when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safe read nature is covered. The description adds a concrete error behavior (missing id yields 404 GarminHttpError), which is useful context beyond annotations, but it does not mention auth, rate limits, or response 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 one compact sentence with the operation front-loaded and no filler. The semicolon-separated error clause is efficient, though the terse endpoint syntax is slightly opaque.
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 tool with annotations and full schema coverage, the description covers the endpoint and one error condition. Without an output schema, it should ideally describe the return shape or at least what the event object contains, which it omits.
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 eventId parameter is documented as 'Numeric id'. The description reinforces the id's role in the path and mentions a missing id error, but adds no format or type details beyond the schema, 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 HTTP method and exact endpoint path for retrieving a calendar event by id, which is clear and specific. However, it does not differentiate this tool from siblings like get_shared_calendar_event or list_calendar_events, leaving the agent to 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?
There is no guidance on when to use this tool versus alternatives such as list_calendar_events or get_shared_calendar_event. It only notes a failure mode, which is not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only cover readOnlyHint and openWorldHint; the description adds genuinely new information by disclosing the data sources (metricId 22 and 23) and the exact record shape returned, which matters since no output schema exists. It still omits calorie units (kcal vs kJ) and how days without data 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 dense fragment with no wasted words, and the output contract is front-loaded. It is arguably too compressed â an introductory verb phrase would help â 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 two-parameter read-only tool with no output schema, the description supplies the critical missing piece: the return structure. Units and behavior for days with partial data are the only notable gaps, which is minor for this tool's complexity.
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, so the baseline is 3. The description adds no extra meaning about the start/end semantics (range length limits, timezone handling) beyond implying a date range via 'daily'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete operation (merging active and resting/BMR series) and the exact output shape, so an agent can tell it produces daily calorie aggregates with active/resting/total fields. It does not, however, differentiate itself from the many other daily-metric readers in the sibling list (get_daily_stats, get_stats_and_body, get_nutrition_daily_food_log).
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, no mention of an alternative tool, and no stated preconditions. An agent must infer from the name alone that this is the calorie-specific daily reader rather than a broader stats endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is already covered. The description adds genuinely non-obvious behavior: a missing id yields a 404 GarminHttpError with the exact message format 'Course not found : {id}'. That error contract is useful for an agent to reason about failure 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?
A single compact clause with the endpoint and the failure mode, front-loaded and free of filler. The raw-path phrasing is terse rather than wasteful, though slightly opaque to a reader unfamiliar with the service.
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 says nothing about what a returned course contains, so an agent cannot anticipate the response payload. Combined with the absent usage guidance, the definition is adequate for invocation but not complete for a 1-param fetch tool with no declared 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 100% and the sole parameter is documented as 'Numeric id'. The description adds only the path-placement of that id and the error when it is missing, which the schema does not cover. With the schema doing the heavy lifting, 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 (GET) and resource (course by {courseId}), so an agent immediately knows it fetches a single course rather than a list. However, it leans on the raw endpoint path rather than naming its siblings (list_courses, download_course_gpx, get_workout_by_id), so the differentiation is implicit 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 when-to-use guidance at all. Nothing tells the agent to prefer this over list_courses for enumeration or download_course_gpx for GPX export, and no precondition beyond the required id is given.
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). 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. Needs Connect+
| 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 carry readOnlyHint/openWorldHint; the description adds substantial non-obvious behavior: the Connect+ gate, a hard `limit` cap of 20 that triggers HTTP 400 above it, and the 405 on get-by-id. These are exactly the operational traits an agent needs and 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?
Front-loaded with the subscription gate and packed with high-value gotchas in a small space. The one waste is restating the Connect+ requirement at the very end ('Needs Connect+'), which duplicates the opening 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?
With no output schema, the description supplies the return shape and the key failure modes (400 on large limit, 405 on by-id). Missing is any explanation of `start` pagination semantics, which an agent listing many custom foods would need.
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. It documents `limit` (capped at 20) and implies `search` (search by name), but leaves `start` and its pagination relationship to `moreDataAvailable` unexplained, 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?
The description names the exact endpoint and return payload (`GET /nutrition-service/customFood` returning `{customFoods, moreDataAvailable}`), so the read-list purpose is unambiguous. It also distinguishes itself from the absent get-by-id variant by noting `/customFood/{id}` is a 405. It is slightly endpoint-flavored rather than plain-language, but an agent can still identify it immediately.
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 hard prerequisite (Connect+ subscription, verifiable via has_connect_plus) and a concrete workflow rule: since there is no get-by-id, read a single food back by searching on name. No explicit exclusions against sibling listing tools like search_foods, but the when-to-use context is clear.
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). GETs /nutrition-service/metadata/customFoodServingUnits (13 units). Needs Connect+
| 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 the safety profile is covered. The description usefully adds that a Garmin Connect+ subscription is required and names has_connect_plus as the way to verify it, but it states this requirement twice ('Requires ... subscription' and 'Needs Connect+') without adding anything on result shape beyond the bare '(13 units)'.
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 the Connect+ requirement is repeated redundantly ('Requires a Garmin Connect+ subscription' / 'Needs Connect+'), and the front-loaded sentence is a prerequisite rather than the tool's purpose. The parenthetical '(13 units)' is left unexplained, costing a sentence's worth of 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 zero-parameter metadata fetch with annotations covering the read-only profile, the essentials (endpoint and subscription requirement) are present. It is still thin on why an agent would need the serving units and what each unit entry contains, and there is no output schema to compensate, so it lands at minimum-viable rather than 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 and the schema is an empty object with additionalProperties=false, so there is nothing for the description to disambiguate. The baseline of 4 applies for a parameterless 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 the concrete endpoint (`/nutrition-service/metadata/customFoodServingUnits`) and hints at the result size (13 units), so the agent can infer it returns serving-unit metadata for custom foods. However, it largely restates what the tool name already conveys and gives no differentiation from the surrounding custom-food siblings (get_custom_foods, create_custom_food, update_custom_food), nor what the units are used for.
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 this versus alternatives. The only usable signals are the Connect+ prerequisite and the pointer to has_connect_plus, which are environment/auth conditions rather than routing guidance about 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.
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 safety and external-dependency profile is covered structurally. The description adds one genuinely useful behavioral fact â that only the latest value is returned, not a series â but says nothing about return format, units, or behavior when no FTP is recorded.
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 clause, front-loaded with the scope constraint and immediately followed by the routing instruction. No filler, no repetition of the tool name 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?
With no output schema present, the description carries the burden of conveying the return, and 'latest value only' is only a partial answer â it does not specify the unit (watts), the shape of the payload, or the behavior when no FTP exists. For a zero-parameter read tool this is adequate but leaves 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?
The tool takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to explain or compensate for. Nothing in the text misrepresents the (empty) input contract.
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 what the call returns â the latest FTP value only â which is a specific scope for a zero-arg getter, and it implicitly distinguishes itself from the historical range sibling. It never spells out the resource explicitly (cycling functional threshold power), relying on the tool name to carry that, so it falls just 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?
It names the alternative (getFunctionalThresholdPowerRange) and the exact condition that selects it ('for history'), which is precisely the when-to-use/when-not pairing the dimension asks for. An agent needs no further inference to route between the two.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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/active/resting calories together, and steps with totalDistance andâĻ
| 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 readOnly/openWorld, but the description discloses deep behavior: statsType case-sensitivity causing 404, a 400 on ranges over 27 days, 28-day windowed chunking with concatenated rows, and aggregations being dropped rather than returned wrong. It also clarifies [] vs Garmin's null for 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?
Dense but front-loaded, with the core GET/param semantics first and edge cases after. Most sentences earn their place; the raw HTTP path is mildly redundant for an agent, and the trailing ellipsis truncates an otherwise well-structured 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 carries the return-value burden and does so (calorie composition, steps fields, [] for empty ranges, dropped aggregations). Completeness is only undercut by the truncated final clause.
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% (dates documented, statsType only via enum). The description compensates by pinning statsType to exactly 'CALORIES' or 'STEPS' (case- and value-sensitive) and explaining the range constraints that govern start/end, adding real 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 (GET) and resource (daily stats), and explicitly distinguishes itself from siblings getDailySteps/getCaloriesDaily by noting it returns total/active/resting calories together. The truncation of the return-value list leaves the purpose slightly incomplete, but an agent can still identify 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?
Explicitly names the overlapping alternatives (getDailySteps/getCaloriesDaily) and gives the selection criterion â this one returns calories broken into total/active/resting plus steps with totalDistance. No explicit 'when-not' for other daily-stat tools, and the sentence trails off.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
auto-chunks ranges over Garmin's 28-day-per-request limit into â¤28-day windows and concatenates; a single request within the limit passes its (possibly null) result through unchecked
| 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 (readOnlyHint, openWorldHint), but the description adds genuinely useful behavior the annotations do not: automatic chunking around Garmin's 28-day-per-request cap, concatenation of windows, and an unchecked pass-through that can yield `null` for a single in-limit request. That null-handling disclosure is exactly the kind of trait an agent needs before assuming a result is present.
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 â a single dense sentence with no filler â but it is front-loaded with implementation internals rather than the user-facing outcome, and the semicolon-clause about `null` results reads as jargon. Concise, but not optimally ordered.
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 the return, and it only hints at shape via the `null` pass-through remark. For a simple two-parameter read tool this is adequate but leaves the agent guessing at the response structure (per-day entries, ordering, units).
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 fully documented (YYYY-MM-DD, UTC), so the schema does the heavy lifting. The description adds only that these two values bound the chunked range; it gives no extra format or boundary 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 never actually states that this returns daily step counts â that meaning comes only from the tool name and title. Instead it leads with request-chunking mechanics, so the purpose is only implied. It also does nothing to distinguish itself from close siblings like get_weekly_steps or get_steps_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?
There is no guidance on when to choose this over get_weekly_steps, get_steps_data, or get_daily_stats. The only selection-relevant signal is the implied date-range input, which the schema already conveys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=true and openWorldHint=true, so the safety profile is covered. The URL does implicitly reveal a fixed `includeAll=true` query behavior not present in the schema, but it is never explained (what 'all' includes, timezone handling, whether it aggregates multiple weigh-ins). Little behavioral value 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?
It is short, but brevity here reflects under-specification rather than concision. A single URL slug is not a useful structure for an agent deciding whether to 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 single-parameter read tool the schema and annotations carry most of the load, but the description omits anything that would distinguish it from `get_weigh_ins` or explain what the day-view result contains. An agent has almost no basis for choosing between the two weigh-in readers.
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` (YYYY-MM-DD, UTC) is fully documented by the schema; baseline 3 applies. The description adds no syntax or semantic detail about the date, and the hidden `includeAll` flag it exposes is left unexplained rather than clarified.
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 REST path (`GET /weight-service/weight/dayview/{cdate}`) rather than a statement of purpose. An agent can infer that it reads weigh-ins for a date, but only by parsing a URL, and it gives no indication of how this differs from the sibling `get_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?
There is no guidance whatsoever about when to use this tool versus alternatives such as `get_weigh_ins`. The raw endpoint string carries no context, no prerequisites, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations already cover the safety profile (readOnlyHint, openWorldHint), yet the description adds genuine behavioral detail: an N+1 fan-out via getDevices plus per-device getDeviceSettings, sequential invocation, empty-device handling, and the never-throws guarantee. The empty-case behavior in particular is useful disclosure 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?
It is a single sentence with no padding, but it is a dense run-on packed with backticked internals, and it front-loads the least informative clause. The fan-out/parallelization detail is arguably server-side noise rather than 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?
For a zero-parameter read tool with annotations covering safety and no output schema, the description is arguably complete on behavior. However, it never describes the shape of the returned alarms or when this tool is the right choice, leaving gaps relative to the breadth of the sibling set.
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 covered, so there is nothing for the description to disambiguate. Baseline of 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 conveys that alarms are gathered from all devices ('concatenating each device's alarms'), so the resource is inferable, but the opening sentence leads with an implementation note ('no HTTP path of its own') rather than stating the purpose. It reads as internal mechanics rather than a crisp 'returns alarms across all devices' 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?
There is no guidance on when to use this versus siblings like get_devices, get_device_settings, or get_device_last_used. The only directive ('do not parallelize') is an implementation constraint for the server, not a selection guideline for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 contributes one piece of real context â that this resolves a missing deviceId for pushWorkoutToDevice â but says nothing about what 'last used' means, what is returned, or any failure 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?
It is short, but it is a sentence fragment with no front-loaded verb or resource, and it spends its only clause on internal plumbing rather than on orienting the 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?
Zero params and no output schema keep the bar low, but with only one clarifying clause the definition leaves an agent unable to predict what this returns or how it differs from the many get_device* siblings. It is inadequate for correct tool 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?
The tool takes zero parameters, so the schema baseline of 4 applies. The description correctly implies no arguments (the deviceId is resolved internally), which is consistent with the empty 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 text is not a purpose statement at all; it is an aside noting that the tool is used internally by pushWorkoutToDevice. An agent learns nothing explicit about what get_device_last_used itself retrieves (a device object? an id? a timestamp?), so purpose must be guessed 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?
There is no direct when-to-use guidance. The mention of pushWorkoutToDevice hints at an internal consumer, but it neither tells the agent when to call this tool directly nor when to prefer the sibling get_devices or get_primary_training_device.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered. The description adds one genuinely useful behavioral note â that the per-device shape is undocumented â which warns the agent not to assume a known return contract, but it says nothing about pagination, auth, or what the response includes.
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 it is a sentence fragment rather than a front-loaded statement of purpose, so the brevity reflects under-specification rather than economy. The deviceId detail appears with no framing sentence explaining what the tool returns first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a zero-parameter list tool with no output schema, so the description carries the burden of explaining what comes back. It hints that the shape is undocumented and names deviceId, but never describes the list itself, making it inadequate for an agent that must 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?
The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level meaning 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?
The description never states what the tool does in verb+resource terms; it is a fragment that assumes the reader infers 'list devices' from the name. It only notes that the per-device shape is undocumented and that deviceId is the key field, which is metadata about the return value rather than a statement of 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 explicit when-to-use, when-not, or alternative named among the many get_device_* siblings (get_device_settings, get_device_last_used, get_device_alarms). The remark that other device methods key off deviceId weakly implies this tool is where deviceId comes from, but that routing is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=true and openWorldHint=true, so the safety profile is covered. The description adds that the id is coerced to an int, validated positive, and re-stringified into the path, which is useful input-handling behavior, but it says nothing about what settings are returned or any auth/rate considerations.
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, but the first is a fragment of unstated purpose and internal processing detail rather than being front-loaded with what the tool does. The second sentence carries the useful routing information; the rest is verbose for the value delivered.
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 statement of what the tool returns, an agent cannot tell what a device's settings include versus sibling endpoints. The purpose is missing entirely, and the description only covers how to supply the id.
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%, but the description adds real meaning beyond it: that an integer or string is accepted, coerced to int, validated positive, and re-stringified into the path. That tells the agent the parameter is tolerant and path-bound, which the schema alone 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?
The description never states what the tool retrieves. It describes input coercion and a call sequence, but the actual resource (device settings) is only inferable from the tool name, making this effectively a restatement rather than a definition of 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?
It gives one concrete usage rule: obtain a `deviceId` from a `getDevices()` entry before calling. That prerequisite is genuinely useful, but there is no guidance on when to use this versus sibling tools like `get_devices` or `get_device_last_used`, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Despite annotations only covering readOnlyHint/openWorldHint, the description discloses rich behavior: it throws GarminConnectionError on a falsy response or a missing deviceSolarInput key, it returns resp.deviceSolarInput rather than the envelope, and it reveals the enddate-to-singleDayView coupling. These are exactly the operational details an agent needs and cannot get from 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?
The content is dense with no filler, but structure is poor: it begins mid-thought with a lowercase fragment ('the only raising method in this group') instead of front-loading the purpose, and crams four distinct behaviors into one long sentence with embedded backticks.
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 read tool with annotations, the error and return semantics are well covered, but with no output schema the description still never says what solar data fields deviceSolarInput actually contains, leaving the agent unable to anticipate 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: enddate defaults to startdate, and singleDayView is sent 'true' precisely when enddate was omitted. This interaction between two parameters is not derivable from the schema 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 never states what the tool does. It opens with 'the only raising method in this group' and jumps straight into error and return-value semantics, assuming the agent already knows from the name that this fetches solar data for a device. There is no explicit verb+resource statement and no differentiation from the many other get_* device 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?
No when-to-use guidance and no named alternative. 'The only raising method in this group' hints at a behavioral difference from siblings but gives no selection criteria, so an agent has no help deciding when to call this versus get_device_settings or get_devices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real behavior: the endpoint is public with no session/auth, each badge is augmented with library-synthesized badgeImageUrls, all other fields pass through unchanged, and the result stays nullable rather than coalescing to []. That is meaningful context beyond structured 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 a single dense paragraph that front-loads the endpoint and then the return-value augmentation. Every clause earns its place (image URL template, pass-through behavior, nullability), though the long URL template makes it harder to scan than an ideal short summary.
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 shape and does so by describing the added badgeImageUrls object and the pass-through/nullable behavior of other fields. It stops short of enumerating the badge fields themselves, but for a zero-param read tool this is reasonably 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. Schema coverage is 100% (empty object) and there are no parameters whose semantics need explaining.
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 endpoint (`GET /badge-service/badge/earned`) and the name implies retrieval of the user's earned badges, so the verb+resource is clear. However, it never explicitly states the purpose in plain language nor distinguishes itself from badge siblings like get_available_badges or get_in_progress_badges; the 'earned' scope 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?
There is no statement of when to use this tool versus the many badge-related siblings (get_available_badges, get_badge_detail, get_in_progress_badges, get_badge_challenges). The description is purely structural about the response, giving an agent no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond annotations: the request silently switches endpoints based on `enddate` and the range mode hard-codes `aggregation="weekly"`, which materially affects what data comes back.
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 sentence with no filler, but the cryptic path fragment (`.../stats`) and implementation jargon reduce its utility for an agent. Terse to the point of being hard to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining the return value, yet it says nothing about what the endurance score looks like or how single-day vs. weekly results differ. For a data-retrieval tool it leaves the 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 coverage is 100% (both dates documented as YYYY-MM-DD UTC), so the baseline is 3. The description adds real semantic value by explaining that the presence of `enddate` is a behavioral switch, not just another filter.
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 clarifies the tool's two operating modes (single-day vs. range/weekly) but never states what an endurance score is or what the tool actually returns. The purpose must be inferred from the tool name, and the text reads as HTTP routing detail rather than a purpose 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 implies usage via the branch condition: omit `enddate` for the single-day endpoint, include it for the `.../stats` weekly endpoint. This is actionable but framed as endpoint mechanics rather than user intent, and it names no alternatives or exclusions among the many sibling score/stats tools.
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.
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 does add one genuinely useful behavioral fact beyond the annotations: it raises GarminError when Garmin returns no data. However, it omits return shape, units, and whether absence of data is normal (e.g. no floors recorded) versus exceptional.
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 it is under-specified rather than concise: the single sentence occupies the entire description while omitting purpose. Nothing is front-loaded because there is no main statement to lead with.
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 should at minimum identify the resource being fetched and what the date means. Annotations cover the safety profile, but the agent is left guessing what 'floors' returns and whether the error is expected for days with no stair activity.
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 required parameter cdate is documented in the schema as 'Calendar date, YYYY-MM-DD (UTC)'. The description adds nothing about the parameter, so the 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?
The description never states what the tool does. 'throws `GarminError` if Garmin returns nothing' is an error-handling footnote, not a purpose statement; an agent cannot tell from the text that this retrieves floors-climbed data for a date, nor distinguish it from siblings like 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?
No when-to-use guidance, no alternatives named, no conditions for selecting this over the many other daily-metric getters. The only clause present describes a failure mode, not usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral detail the schema lacks (default values, upper-casing and regex validation), but says nothing about return shape, range 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?
Extremely terse with no filler and information front-loaded across semicolon-separated clauses. It is under-informative rather than verbose, but every clause present carries real content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a data-retrieval tool with no output schema, the description should explain what is returned (FTP values across a date range) and how start/end bound the result. Instead it covers only two of four parameters and omits any return or range semantics, leaving the agent to infer the tool's output entirely.
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%, so the description must compensate, and it does add the two defaults (sport=RUNNING, aggregation=daily) and a validation regex not present in the schema. However it leaves start/end semantics undocumented and gives no valid vocabulary for sport beyond the regex pattern.
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, names no verb or resource, and is entirely a dump of parameter defaults and validation rules. The tool name is informative, but the description text itself adds nothing to purpose and would be a tautology at best.
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 alternatives are named, despite very close siblings such as get_cycling_ftp, get_lactate_threshold, and get_power_zones_for_sport that an agent could easily confuse with this one. The reader gets no signal on which FTP/threshold tool to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hits /gear-service/gear/filterGear?userProfilePk=...; returns an ARRAY of gear entries, verified live. This is the dedicated gear-CRUD service (src/services/gear.ts), 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 and openWorldHint, so safety is covered. The description adds the return shape ("ARRAY of gear entries") and a reliability note ("verified live"), but says nothing about auth requirements for userProfilePk, rate limits, 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?
It is a single sentence and front-loads the endpoint, but it spends words on internal implementation details (`src/services/gear.ts`) that don't help an agent select or invoke the tool. The sibling contrast is the only high-value 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?
Return shape is described, which is good given there is no output schema, and the sibling distinction is covered. But with 0% parameter description coverage and no output schema, the lack of guidance on obtaining userProfileNumber is a real gap for a tool that cannot be called without 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 0% for the single required parameter, so the description carries the full burden. It only surfaces the parameter obliquely via `userProfilePk=...` in the URL, never explains what the profile number is or where to obtain it, and even uses a different name than the schema's `userProfileNumber`.
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 and outcome ("returns an ARRAY of gear entries") and explicitly distinguishes itself from getActivityGear, which is the key sibling. However, it never states the verb plainly (list/fetch gear for a user) and leans on the endpoint path to imply it, so it falls short of a crisp purpose 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 names the alternative getActivityGear and the condition that selects it (activities service with activityId), which is genuinely useful routing. It does not address the other gear siblings (get_gear_stats, get_gear_defaults, get_gear_activities), so the guidance is clear but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 description earns credit for adding two concrete behavioral details beyond them: `limit` is clamped to 1000, and a 404 returns an empty array instead of throwing. It still omits normal return shape and any auth/rate-limit context, so it is not fully exhaustive.
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 very short and contains no filler, and both clauses are useful behavioral notes. However, it is not front-loaded with purpose or usage information, and the extreme brevity reflects under-specification rather than effective 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 read tool with a required `gearUUID`, no output schema, and no parameter descriptions, the description should explain the tool's purpose, the required identifier, and what is returned. It only covers limit clamping and 404 handling, leaving core context 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 0% for both parameters. The description adds meaning for `limit` by stating it is clamped to 1000, but it says nothing about the required `gearUUID` parameter, so it only partially compensates for 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?
The description never states what the tool does or that it returns activities associated with a gear UUID. It only documents limit clamping and 404 behavior, leaving the tool's purpose to be inferred entirely from the name.
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 instead of siblings such as get_gear, get_gear_stats, get_activity_gear, or get_activities. No alternatives, prerequisites, or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the return-array structure (valuable since there is no output schema) and the 'verified live' note, but discloses nothing about auth requirements, rate limits, 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?
A single dense sentence with no filler, and the endpoint (the primary identifying information) is front-loaded. It is compact though slightly cryptic in its raw-API phrasing.
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 parameter, no output schema, and a read-only annotation already provided, the description gives the return shape but omits the origin/meaning of userProfileNumber and any permission context. It is minimally viable but leaves real gaps for a 1-param 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%, so the description must carry the burden. It partially compensates by embedding {userProfileNumber} in the path template, signaling it is the user profile path parameter, but it never explains the integer/string flexibility or where to obtain the 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 names the underlying resource (gear user activity types) and specifies the return shape (an array of {uuid, activityTypePk, defaultGear}), so an agent can infer it retrieves default gear settings per activity type. However, it does nothing to distinguish itself from close siblings like get_gear, get_gear_activities, and set_gear_activity_defaults, and it is framed as a raw HTTP endpoint rather than a task-oriented 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?
There is no guidance on when to use this tool, no prerequisites, and no mention of alternatives. An agent has to infer from the name and endpoint whether this is the right call versus get_gear or set_gear_activity_defaults.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, but the description adds non-obvious error-handling behavior: a 404 yields an empty object rather than throwing, while other errors propagate. That is exactly the kind of trait an agent needs and cannot get from 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 dense sentence with no filler, though it is front-loaded with the raw HTTP endpoint path, which is less useful to an agent than the semantic purpose would be. 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?
With no output schema, the description should convey what 'stats' contains, and it does not â it only covers the 404 case. It is adequate for invocation (validation rules, error behavior) but leaves the return shape 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?
With only one parameter and 0% schema description coverage, the description must carry the burden, and it does: gearUUID is validated with validateUuid and accepts hex with optional hyphens. That adds real syntactic meaning beyond the bare 'string' 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 names a specific verb ('GETs') and resource (gear stats for a given gearUUID), so an agent can tell this fetches aggregate stats rather than the gear item itself. However it never differentiates from siblings like get_gear, get_gear_activities, or get_gear_defaults, so the boundary with those tools 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?
There is no guidance on when to call this versus get_gear (gear metadata) or get_gear_activities (per-activity gear usage). The agent is left to infer that 'stats' is a distinct payload from the sibling tools'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 getActivitiesByDate; throws GarminError if MAX_PAGINATED_REQUESTS (2000) pages are fetched without ever seeing an empty one. **Sends the load-bearing `Sec-Fetch-Site: sameâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| start | No | ||
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the annotation baseline (readOnlyHint/openWorldHint): it warns that start is 1-indexed and that start=0 silently returns [], that an invalid status throws GarminError before any request, that fetching is paginated until an empty page, and that 2000 pages without an empty page raise an error. These are exactly the non-obvious runtime traits an agent must know to call the tool 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?
Defaults are front-loaded and each clause carries a real constraint, but the sentences are long run-ons that pack multiple facts (pagination pattern, request cap, header injection) into one block, which slightly hurts scannability.
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 read tool with no output schema, the description covers defaults, error conditions, pagination termination, and the request cap thoroughly; only an explicit statement of what the returned goal records contain (or a one-line purpose statement) 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 must carry the load, and it does: it documents defaults for all three parameters (status='active', start=1, limit=30) and explains the 1-indexed start semantics. The meaning of the status enum values (future/past) is left to the schema, 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?
The description is entirely about mechanics (defaults, pagination, error behavior) and never states in plain terms that it retrieves the user's goals from goal-service. The resource is inferable from the name and the mention of 'goal-service', but an agent gets no explicit 'this returns your goals' statement, and there is no differentiation from siblings like get_training_plans.
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 discloses that status defaults to 'active', which implicitly tells the agent to pass a different status to see future/past goals, but it never says when to use this tool versus the many other retrieval tools, nor does it mention 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.
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 only supply readOnlyHint/openWorldHint, and the description adds genuinely useful behavior: the default limit of 1000, positive-value validation, and the verified fact that the response is a JSON array of 17 club objects with named fields rather than a single object. That live-verified array disclosure is exactly the kind of trait annotations cannot convey. It loses a point for implementation trivia (raw URL path) and for referencing per-page/include-stats query params that are not exposed in the 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 array-shape warning is bolded and front-loadable, which is good, but the sentence is a semicolon-chained block mixing relevant caller-facing facts (default, return type) with low-value implementation detail (the raw endpoint path). The endpoint URL in particular does not help an agent decide 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 does the right thing by documenting the returned array's field set, and it covers the lone parameter. What is missing is any framing of what these club stats represent, when the data is meaningful, or how this differs from get_golf_user_stats/get_golf_summary, so the agent has return structure but no context for selecting or interpreting the 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?
The single parameter has zero schema description coverage, so the description carries the burden, and it does state the default (limit=1000) and that it is validated positive. It is docked for also describing per-page and include-stats query parameters that do not exist in the input schema, which muddies rather than clarifies what can actually be passed.
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 implies the tool fetches golf club entries by documenting the endpoint path and the array of club objects returned, but it never states a plain verb+resource purpose like 'retrieve golf club statistics'. It also does nothing to distinguish itself from close siblings get_golf_user_stats, get_golf_summary, and get_golf_scorecard, leaving the agent to guess 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?
There is no when-to-use guidance, no prerequisites, and no named alternatives. The agent learns the wire format but not the circumstances that should make it pick this tool over the other four golf tools 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.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious implementation behavior: hyphenated query parameter names and the quirk that `include-longest-shot-distance` must be sent as the literal string "true" rather than a boolean. It still says nothing about error behavior or response shape, so it is 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?
It is a single short sentence with no padding, so it is concise and front-loaded. However, the space is spent on transport details instead of the functional purpose, so the sentence does not fully earn its place as the primary 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 one-parameter read-only GET with no output schema, the description gives enough to construct the request, including the boolean-as-string quirk. It is incomplete in that it never explains what a scorecard contains, how it relates to sibling golf tools, or how to obtain the required scorecard id.
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% for the single `scorecardId` parameter, so the 3 baseline applies. The description goes beyond the schema by exposing additional query parameters (`scorecard-ids`, `include-longest-shot-distance`) that appear nowhere in the input schema, including the string-vs-boolean encoding quirk. It does not reconcile the plural `scorecard-ids` naming with the singular `scorecardId` schema field, which is a minor ambiguity.
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 names the underlying REST path (`/gcs-golfcommunity/api/v2/scorecard/detail`) rather than stating in functional terms that it retrieves a single golf scorecard by id. It restates the tool name through a URL, and gives no clue how a 'scorecard detail' differs from get_golf_summary, get_golf_shot_data, or get_golf_club_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 and no mention of any alternative golf tool. An agent cannot tell from this text whether to call this or get_golf_summary/get_golf_shot_data for the same data, nor what prerequisites (e.g., needing a scorecard id from another call) exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations already declare readOnlyHint and openWorldHint, yet the description adds a genuinely important caveat: requesting any hole >9 causes the filter to be silently dropped and all 18 holes returned. That silent-failure behavior directly changes how an agent should call the tool and cannot be derived 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?
It is a single dense sentence with heavy backticks and an internal re-join implementation detail, and it leads with the URL rather than the user-facing purpose. The critical >9 caveat is buried mid-sentence rather than front-loaded, though little is outright 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 read-only tool with no output schema, the description covers the parameter behavior and the one surprising failure mode thoroughly. It omits what the returned shot data actually contains and how to obtain a valid scorecardId, which are minor gaps given the annotations carry the safety profile.
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% (holeNumbers has no schema description), and the description compensates well: comma/hyphen separators, whitespace stripping, the `-` re-join, the >9 drop, and the omit-to-get-all-18 default. Only scorecardId's provenance (where to obtain a valid id) is left 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?
The raw endpoint path (`/gcs-golfcommunity/api/v2/shot/scorecard/{scorecardId}/hole`) plus the verb 'GETs' makes it inferable that this fetches shot data for the holes of a golf scorecard, which is a specific resource. It never states the purpose in plain language and gives no differentiation from siblings like get_golf_scorecard, get_golf_summary, or get_golf_club_stats, so an agent must infer the boundary from the URL 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?
The description explains what happens when `holeNumbers` is omitted or contains values >9, but that is behavior, not guidance on when to choose this tool over get_golf_scorecard or get_golf_summary. There is no stated prerequisite (e.g. needing a scorecardId from another call) and no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, but the description adds substantial behavioral context beyond them: the start=0/limit=100 defaults, validation rules that throw GarminError, the hyphenated query-param naming (per-page, start), and most importantly the live-verified claim that the payload is a pagination-envelope OBJECT rather than an array. That return-shape disclosure is genuinely useful given no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The body is a single dense semicolon-chained sentence that leads with defaults rather than purpose, followed by a bolded return-shape note. There is no padding, but the structure is a wall of detail with no front-loaded statement of what the tool is, so it reads as unordered facts rather than a guided 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 shoulders the return-value burden by disclosing the pagination envelope shape, and it covers defaults and validation. But for a read-only open-world tool it omits purpose, sibling differentiation, and pagination traversal guidance, so an agent can call it but cannot confidently decide it is the right 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%, so the description must compensate, and it does add real meaning: defaults, non-negative start validation, positive limit validation, and the mapping to Garmin's hyphenated query names. However it still leaves the core semantics ambiguous (is start a row offset or a page number?) and never explains limit's relationship to per-page. Useful but incomplete against a total 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?
The description never states what the tool does. It opens with defaults and validation and reveals the return shape, but there is no explicit verb+resource statement of purpose, and no differentiation from golf siblings like get_golf_user_stats, get_golf_club_stats, or get_golf_scorecard. The agent must infer intent entirely from the name.
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 the alternative golf tools. The text covers defaults and validation but leaves scenario selection completely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, so the safety profile is covered. The description adds only the raw endpoint path and repeats the zero-param fact from the schema; it discloses nothing new about auth, response shape, or scope.
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-loaded with the endpoint and immediately followed by the content summary. No wasted filler, though the raw API path is arguably noise 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 zero-parameter read tool with no output schema, the description is minimally adequate: it names the data returned. It does not clarify the return structure (e.g., summary vs. per-round detail) or how it relates to sibling golf endpoints, leaving some 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?
There are zero parameters, so the baseline is 4. The description's 'no params' note is consistent with the empty schema and adds no conflicting information.
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 (GETs) and resource (golf player stats), and names the returned content (handicap and strokes-gained overview). It partially differentiates from golf siblings like get_golf_club_stats and get_golf_scorecard by describing the aggregate stat content, but does not 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?
No indication of when to use this versus the other golf endpoints, nor any prerequisites or conditions. The 'no params' note tells the agent it can call it directly but gives no selection guidance.
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.
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 and openWorldHint, lowering the bar. The description adds one genuine behavioral fact beyond them: the range branch hard-codes aggregation="daily". That is a useful disclosure, but it is expressed as a reference to an undescribed sibling rather than self-containedly.
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 no filler, so it is compact and front-loads the branching rule. But the density comes partly from cryptic references to unstated tools and an unexplained `aggregation` field, which reduces rather than improves information value.
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 is returned, and it does not. It relies on the agent already knowing `getEnduranceScore`'s shape and the `aggregation` concept, leaving an agent unable to predict the response for either branch.
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. The description does add meaning by explaining that the presence of `enddate` changes behavior into two branches, which the schema alone does not convey, but it omits the semantic consequence of that branch beyond the aggregation constant.
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 produces: it only describes the branching behavior of `enddate` and points to `getEnduranceScore` for shape. An agent must infer the purpose (returning a hill score) purely from the name, so it fails to state a 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?
It implies when each branch applies ('TWO branches by presence of enddate') and warns against conflating this with the weekly aggregation used elsewhere. However it names no alternative tool or condition for choosing between this and `get_endurance_score`, so the guidance is only implicit.
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.
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 already declare readOnlyHint and openWorldHint, and the description goes beyond them usefully: it states the tool never raises (null from either underlying call treated as []), documents collision behavior (available overwrites earned but keeps the earned entry's position), and notes badges carry badgeImageUrls. That is genuine behavioral context 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?
The single dense sentence opens with implementation trivia ('no HTTP path of its own', internal function names, Map keying) rather than the user-facing purpose, so the most selection-relevant fact is buried. Much of the length serves implementation curiosity rather than helping an agent decide to call it or not.
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 supplies the essentials: what the returned set contains, its keying, and the badgeImageUrls payload. The main gap is the absence of any routing guidance relative to the many badge-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?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is reported at 100% and the input schema is an empty closed object, consistent with the no-argument framing.
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 makes the result set concrete: it filters the earned and available badge lists by an 'in-progress' predicate (progress truthy; progress === target only counts when badgeLimitCount is set and badgeEarnedNumber < badgeLimitCount) and merges them into a badgeId-keyed Map. That effectively tells the agent this returns badges currently being progressed. It does not, however, contrast itself against the visible siblings get_earned_badges / get_available_badges in user-facing terms, 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 statement of when to call this versus get_earned_badges, get_available_badges, get_inprogress_virtual_challenges, or get_badge_challenges. The only relational information is the internal call names, which are implementation references rather than selection guidance. An agent gets no explicit use/when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description does add genuinely useful behavioral detail beyond that: `start` is validated as strictly positive (rejecting 0) and `limit` must be positive. However, opaque phrases like 'the four challenge methods above' and 'same array-not-dict correction' assume context a fresh agent does not have.
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 compact sentence front-loaded with the endpoint, which is efficient. But it is packed with back-references ('the four challenge methods above', 'same array-not-dict correction') that act as noise for an agent lacking that conversational context, so density partly comes at the cost of 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 two-parameter read-only tool with no output schema, the description covers both parameter constraints and hints at the return shape ('array-not-dict'). That is largely adequate, but the reliance on undefined external context and the absence of any pagination or response-size guidance leave 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 0%, so the description carries the burden and does provide real constraints: `start` must be positive (nonzero) and `limit` must be positive. That meaningfully constrains both required params, but omits type expectations (integer vs float), allowable maximums, and default behavior, 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?
The description leads with the raw endpoint path `virtualChallenge/inProgress` rather than a plain statement of purpose, so the agent must infer that it returns in-progress virtual challenges from the URL and tool name. The name plus path does convey a verb+resource, but there is no clear differentiation from siblings like get_badge_challenges, get_non_completed_badge_challenges, or get_in_progress_badges other than the oblique reference to 'the four challenge methods above'.
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 contrasts its validation behavior with 'the four challenge methods above,' which is a weak positional back-reference rather than explicit when-to-use guidance. It never states when an agent should pick this tool over the other in-progress/challenge siblings, and offers no exclusions or prerequisites.
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.
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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior: two distinct execution paths, the number of underlying GETs, the differing return shapes, and a thrown error when startDate is missing. That is beyond what annotations provide, though there is no mention of auth scopes 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?
It is short but front-loads parameter defaults before stating the tool's function, and it is written in a dense pseudo-code register (`{speed_and_heart_rate, power}`) with backtick syntax that reads more like implementation notes than agent-facing guidance.
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 it does specify the two response shapes â a real contribution. But it omits what the fields actually mean, units, and which branch is appropriate when, so an agent can call the tool but not confidenty 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 coverage is 50%; startDate and endDate carry format descriptions but `latest` and `aggregation` have none. The description compensates partially by documenting that latest switches branches and requires startDate when false, but it never explains aggregation's enum values or how endDate interacts with the range mode. 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 never says what the tool retrieves in plain terms â it only specifies default parameters and the JSON shapes returned by two branches. An agent must infer from the name that this fetches lactate threshold data. It does describe the two response modes, but the core verb+resource statement is absent.
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 does state the key branch condition: `latest=false` requires `startDate` and throws otherwise. That is useful invocation guidance. However, it never says when an agent should choose this tool over date-range alternatives like get_max_metrics_range or get_cycling_ftp, and no when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered. The description adds that it returns `null` when no element exists, which is useful behavioral context, but it does not disclose return shape, pagination, or any other traits 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 description is very short, but the single sentence spends space on internal delegation rather than front-loading the user-facing purpose. It is concise but not well structured for an agent deciding whether to call 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 no output schema, the description should at least clarify what "last element" means (e.g., the most recent activity) and the return value shape. It only says it returns an element or null, leaving ambiguity about what object is returned and how "last" is determined.
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 covered (100%), so there are no parameter semantics to explain. The description does not need to add parameter information; baseline for zero parameters is 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?
The description is essentially an implementation note ("delegates to `getActivities(0, 1)`") rather than a clear statement of purpose. It implies returning the last activity but never explicitly names the resource or distinguishes itself from sibling `get_activities`. An agent can infer the purpose from the tool name, but the description itself is vague.
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 is given on when to use this tool versus alternatives like `get_activities` or `get_activity`. The delegation detail is an implementation fact, not usage guidance. The agent is left to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 safety profile is covered. Beyond that the description adds only the raw endpoint path â no auth requirements, no pagination, no return shape, no note on what happens for dates with no log. The 'superficially resembles a wellness-daily endpoint' remark raises ambiguity without resolving it.
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 second clause â 'Grouped under `misc` per the plan's explicit instruction, even though it superficially resembles a wellness-daily endpoint' â is internal categorization chatter that does not help an agent invoke the tool and consumes roughly half the text. Only the first 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?
This is a one-parameter read tool with no output schema, so the description is the only place an agent can learn what comes back. It says nothing about the returned fields or the domain meaning of 'lifestyle logging', leaving the agent unable to judge whether this tool 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 schema fully documents the single `cdate` parameter (type, date format, YYYY-MM-DD UTC). The description only echoes that the date slots into the path template, adding no format or range detail beyond the schema. 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 gives a verb and resource in HTTP form ('GETs `/lifestylelogging-service/dailyLog/{cdate}`'), which at least reveals the tool fetches a single day's log. But it never says what 'lifestyle logging data' actually contains, and the second clause is meta-commentary about taxonomy rather than function. It does nothing to distinguish this tool from the many other date-scoped `get_*` 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?
There is no statement of when to use this tool, when not to, or which sibling to prefer. The only contextual remark is about how it was grouped in a plan file, which is irrelevant to an agent choosing a tool. The date parameter implies a daily-fetch use case but nothing is stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, but the description adds no behavioral context whatsoever â no return shape, no coverage window, no data freshness. The path note conveys nothing about how the tool behaves when invoked.
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 stems from under-specification rather than efficiency. Nothing about the tool's function is front-loaded because nothing about its function is stated at all.
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 annotations describing returned data, the description carries the full burden of explaining what this call produces â and it delivers none of it. An agent has no basis to select this tool over the many other metric 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?
Schema description coverage is 100% and there is a single parameter, so the baseline is 3. The description only restates that the date is used twice in the path (start=end=cdate), which adds no semantic meaning beyond the schema's 'Calendar date, 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 never states what the tool does. 'the date is repeated twice in the path (start=end=cdate)' is an implementation note about URL construction, not a statement of purpose. An agent cannot tell what metrics are returned or how this differs from the sibling get_max_metrics_range.
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 get_max_metrics_range or other metric endpoints, and no mention of prerequisites or scope. The single sentence is entirely about path formatting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 state readOnlyHint=true and openWorldHint=true. The description adds a concrete runtime behavior, GarminError when start > end, which is useful, but it does not cover return shape or auth/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?
It is an extremely short one-sentence fragment with no wasted words, but it is not front-loaded with purpose and reads as an addendum rather than a usable 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 read tool with no output schema, the description fails to explain what a max metrics range contains or what a successful call returns. Annotations only cover safety; the core data contract 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% and documents both date parameters. The description adds a cross-parameter constraint (start must not exceed end), which is meaningful but limited; baseline 3 applies for high schema 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?
The description never states what the tool retrieves; it only documents a validation error. The name implies a range getter, but the text gives no verb+resource 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 is given on when to use this tool versus get_max_metrics or other range-based siblings, and no prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 establish readOnlyHint and openWorldHint, so the bar is lower, and the description adds genuinely useful behavioral context: Garmin's API rejects 92+ inclusive-day windows and this wrapper does not enforce that, making it the caller's responsibility. This is a non-obvious, actionable pitfall worth flagging. It stops short of 5 because it says nothing about return shape, pagination, or partial-window 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?
It is short and waste-free, but the single sentence is spent on an edge-case caveat rather than front-loading what the tool returns. Concision here reads as under-specification rather than discipline.
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 range query with no output schema, the description should at least say what data comes back (cycle/day entries across the range) and how this differs from its menstrual siblings. Annotations cover the safety profile and the schema covers inputs, but the core purpose gap leaves the definition 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?
Both parameters (startdate, enddate) are fully documented in the schema with YYYY-MM-DD (UTC) format at 100% coverage, so the baseline is 3. The description adds no format, boundary, or semantics beyond the schema, though the 92-day rule implicitly bounds the range.
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 â no verb, no resource, no scope. The only content is a constraint caveat, so an agent must infer the purpose entirely from the name and from sibling names like get_menstrual_data_for_date. That is closer to missing purpose than to a clear 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?
There is no when-to-use guidance and no routing to alternatives such as get_menstrual_cycle_summary, get_menstrual_reports, or get_menstrual_data_for_date, all of which cover overlapping menstrual data. The window-size caveat is a constraint, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
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=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the exact default values applied when options are omitted, that todayCalendarDate silently defaults to today, and â most valuably â that numberOfCycles outside {1,6,12} throws GarminError. It stops short of describing the returned report structure, 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?
The text is terse with no wasted words, but it is a single telegraphic fragment that front-loads parameter trivia rather than the tool's purpose. Appropriately sized for the schema detail it adds, but structured backwards for an agent scanning for intent.
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 sitting among five or six menstrual-data siblings, the description leaves too much out: no statement of what the report contains, no when-to-use guidance, and no differentiation from get_menstrual_calendar_data or get_menstrual_cycle_summary. Only the parameter-level gaps are filled.
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%, so the description must compensate, and it largely does: it documents defaults for nextReport, reportType, and todayCalendarDate (all undocumented in the nested schema) and supplies the enum-like restriction {1,6,12} plus default 6 for numberOfCycles. The required fordate is left to the schema, which describes it fully.
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 â it opens with a list of default parameter values and a validation constraint. The resource and verb are only recoverable from the tool name 'get_menstrual_reports'. No sibling differentiation (vs. get_menstrual_cycle_summary, get_menstrual_calendar_data, get_menstrual_data_for_date) is offered.
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 this tool, what fordate means in context, or how it differs from the several other menstrual-report retrieval tools in the sibling list. The description is purely mechanical (defaults and limits), leaving usage entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations only cover readOnlyHint and openWorldHint; the description goes further by disclosing that there is no HTTP call of its own, that it delegates to getTrainingReadiness, that it filters on inputContext and falls back to the first entry, and that it returns null for a falsy/empty result. That edge-case behavior (fallback and null) is exactly the kind of trait 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?
A single dense sentence with no filler, front-loaded on the delegation behavior. It is efficient, though the semicolon-chained internal details read more like implementation notes than a crisp summary.
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 present, the description covers delegation, filtering, fallback, and the null case. It stops short of describing what the returned readiness object contains, which matters somewhat since there is no output schema to carry that burden.
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 as YYYY-MM-DD UTC, so the description is not required to compensate. It adds nothing about cdate, which is fine given 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?
The description reveals that it wraps getTrainingReadiness and applies an AFTER_WAKEUP_RESET filter, which implicitly conveys the purpose (morning readiness snapshot). However, it is framed as implementation notes rather than a user-facing statement of what is returned, and it never explicitly contrasts itself with the sibling get_training_readiness.
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 or routing to alternatives. The filter condition (AFTER_WAKEUP_RESET) hints at when this differs from get_training_readiness, but the agent is left to infer that this is the 'morning' variant rather than being told to prefer it in that scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
With readOnlyHint and openWorldHint already provided, the description adds real behavioral context: it never throws, returns an empty object instead of failing when nothing matches, and handles Dec-to-Jan rollover. It still does not describe the successful return shape, but the error/fallback behavior is unusually well 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?
The description is very short and contains no filler. It is slightly front-loaded with implementation detail rather than the tool's direct purpose, but every clause adds relevant 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 zero-parameter tool with no output schema, the description should clarify what is returned when a match exists. It only describes the empty-object fallback and never states the successful return value, leaving a meaningful gap for an agent that must know what to 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?
The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter semantics because there are none to clarify.
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 explicitly says it returns the next scheduled workout; it only explains that the result is computed from two getScheduledWorkouts calls and that an empty object is returned when nothing matches. The tool name carries most of the purpose, but the description itself is indirect and implementation-focused.
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 instead of get_scheduled_workouts, get_scheduled_workout_by_id, or get_scheduled_workout_summaries. The mention of computation from two calls implies a use case but does not state when the agent should prefer this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavioral traits: the response comes back as an array (not a dict) requiring correction, and there is a live failure mode where `start=0` returns a 400. That is genuine context annotations do not carry. It loses a point only because these traits are conveyed by reference ('same ... as getBadgeChallenges') rather than stated outright.
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 dense sentence with the endpoint front-loaded, so it is compact. However, it is a run-on semicolon chain crammed with internal jargon ('array-not-dict correction', 'live start=0 -> 400 discovery') that reads more like a developer note than an agent-facing 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 two-required-parameter read tool whose annotations already cover safety, the description supplies the response-shape and error-mode quirks. But with no output schema and 0% parameter coverage, the meaning of start/limit and the exact return contents remain unstated, leaving gaps an agent must fill by opening the sibling 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% and both `start` and `limit` are required, so the description carries the burden. It only says the validation is 'the same' as another tool and never explains that these are pagination offset/count parameters, nor their ranges or defaults. It does not compensate 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?
The description gives the literal endpoint path (`/badgeChallenge/non-completed`) and the verb 'GETs', so a careful reader can infer the resource is non-completed badge challenges. But it never states the purpose in plain language, relying on the reader to parse a URL path, and it does not explicitly contrast itself with siblings like get_badge_challenges or get_available_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?
It cross-references `getBadgeChallenges` for shared validation behavior but never says when this tool should be chosen over that sibling or over get_in_progress_badges / get_available_badge_challenges. There is no when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, but the description adds nothing beyond the raw endpoint â no indication of what the response contains (meals, macros, servings) or how it is shaped. It is a bare route string with zero 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?
One short line with no filler, so it is efficient and front-loaded, but the brevity is under-specification rather than true conciseness â nothing an agent actually needs is expressed.
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 annotations explaining the return payload, the description carries the burden of telling the agent what comes back, and it does not. For a retrieval tool whose whole value is the returned log data, this is a clear 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% and the single `cdate` parameter is fully documented in the schema (calendar date, YYYY-MM-DD, UTC), so the baseline of 3 applies. The description contributes nothing the schema does not already say.
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 underlying HTTP route ("GETs `/nutrition-service/food/logs/{cdate}`") rather than a statement of what the tool does for an agent. It never says it returns the day's logged food entries, nor does it distinguish itself from siblings like get_nutrition_daily_meals or get_nutrition_food_log_range.
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 of when to prefer this single-day log over get_nutrition_food_log_range for multi-day queries, and no prerequisites. The path itself hints at per-date scope, but nothing explicit is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, so the safety profile is covered. The description adds nothing beyond the endpoint path: no return shape, no pagination, no auth or rate-limit notes, no indication of what a 'meal' record 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?
It is a single short line with no filler, so it is not bloated. However, the brevity comes from under-specification rather than efficient communication, and there is no structure to front-load.
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 required param and no output schema, the description still omits what the call yields and how it differs from adjacent nutrition endpoints. With annotations covering safety, more of the burden falls on describing the returned meal data, which is entirely 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 100% for the single cdate parameter, including format and UTC semantics, so the schema carries the meaning. The description's `{cdate}` placeholder merely echoes the parameter name and adds no interpretation 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 only restates the tool name as an HTTP route ('GETs `/nutrition-service/meals/{cdate}`'), which is essentially a tautology rather than a statement of what the tool returns. It does not distinguish this from close siblings such as get_nutrition_daily_food_log, get_nutrition_daily_settings, or get_nutrition_food_log_range.
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 routing to alternatives. An agent cannot tell from the text why it would pick this meals endpoint over the food-log or settings endpoints that share the same daily-nutrition space.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 safety is covered. The description adds nothing about what the endpoint returns, whether settings are user-level or per-day, or any auth/rate-limit behavior â no value 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?
It is a single short fragment with no waste, but the brevity is achieved by omitting substance rather than by efficient phrasing. Front-loading is irrelevant when there is only a path string.
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 gives no indication of the response shape, so an agent has no way to know what it will receive from an opaque 'settings' endpoint. It is inadequate for selecting or interpreting this call among ~150 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 coverage is 100% for the single cdate parameter, so the description need not compensate. It offers no additional semantic detail, warranting 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 only restates the tool name as a raw REST path ('GETs `/nutrition-service/settings/{cdate}`'). It conveys the HTTP verb and a resource path but never says what 'nutrition daily settings' actually are or what data is returned, so an agent cannot distinguish it conceptually from get_nutrition_daily_food_log, get_nutrition_daily_meals, or get_user_settings.
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 this versus the many sibling nutrition and settings tools. No prerequisites, no time-frame context, no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GETs /nutrition-service/food/logs/range?startDate&endDate: {dailyNutritionSummaries}, one day-log per day that has anything logged. The ONLY food-logging call that works without Connect+ (returns no days then)
| 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 safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower, and the description adds genuinely useful behavior: the Connect+ dependency and the fact it silently yields zero days for non-subscribers. It does not describe missing-day gaps or pagination, 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?
One dense, front-loaded sentence that names the endpoint first, then the return contract, then the eligibility caveat. Efficient, though the trailing parenthetical 'returns no days then' is telegraphic and slightly 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 2-param read tool with no output schema, the description covers return shape, cardinality, and the Connect+ gate, which is what an agent needs to call it correctly. Date-format edge cases and pagination are left to the schema, which is acceptable 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 coverage is 100%, so both date params and their YYYY-MM-DD UTC format are already fully documented; baseline 3 applies. The description only echoes startDate/endDate in the URL without adding format, timezone, or range-limit 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?
States a specific verb+resource (GET food log range), names the endpoint, and describes the return shape (`{dailyNutritionSummaries}`, one day-log per day with anything logged). That scope is enough to distinguish it from siblings like get_nutrition_daily_food_log 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?
Declares a strong selection criterion: it is the ONLY food-logging call that works without Connect+ (and returns no days in that case). It doesn't explicitly name the alternative sibling calls (e.g. get_nutrition_daily_food_log) for the Connect+ case, but the eligibility rule is clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered. The description adds real value beyond that by disclosing the payload shape (`PersonalRecord[]`, an array verified live against a test account) and warning about the singular method name versus plural type name â exactly the kind of detail that prevents a mis-parse, especially since no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single sentence, so nothing is padded, and the verb is front-loaded. But the phrasing is dense and awkwardly formatted (backticks, bold emphasis, parenthetical 'verified live'), which hurts readability more than the length does.
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 tool with annotations and no output schema, the description covers the main missing piece (return is an array). It still leaves unexplained what a personal record is and how `displayName` is resolved when no arguments are accepted, but those gaps are modest given the tool's simplicity.
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 empty, so per the calibration this earns the baseline 4. The description's 'no args' note is consistent with the schema, though it sits awkwardly beside the `{displayName}` path segment.
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 (GETs the personal-record endpoint), so an agent can tell this retrieves personal records. However, it muddles the picture by naming a `{displayName}` path segment while simultaneously saying 'no args', without explaining how that value is supplied. No close sibling exists among the tools, so sibling differentiation is not required.
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, no alternative named, and no exclusions or prerequisites. The agent gets an endpoint string but no routing guidance whatsoever.
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.
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 safety is covered. The description adds only that the sport value is upper-cased and validated, without saying what happens on an invalid sport, which sports are accepted, or what the response contains. Minimal value beyond 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?
One short sentence, so nothing is wasted, but this is under-specification rather than conciseness â the sentence spends its length on a sibling reference instead of the tool's function. Front-loading is absent because there is no purpose statement to front-load.
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 getter with no output schema and a 0%-documented required parameter, the description should explain what is returned (zones, sport scoping) and which sport values are legal. Instead it covers only input normalization, leaving the agent guessing about results and valid 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 the single `sport` parameter. It partially helps by stating the value is upper-cased and validated, but it never lists valid sports or the validation rules, and it points to a differently-named tool (`getFunctionalThresholdPowerRange` vs the snake_case siblings) that the agent must mentally map.
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 â it only describes how the `sport` argument is normalized, delegating meaning to the tool name alone. It also fails to distinguish this from the sibling `get_power_zones`, which is presumably the unfiltered counterpart. This is closer to a parameter note than a purpose 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?
There is no when-to-use guidance at all: no mention of how this differs from `get_power_zones` or `get_functional_threshold_power_range`, and no preconditions. The only hint is a cross-reference used to explain validation behavior, not to route the agent between tools.
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.
defaults metric="distance", groupbyactivities=true; both dates routed through formatDate
| 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only default parameter behavior ('metric="distance"', 'groupbyactivities=true'), not aggregation semantics, result shape, or any constraint on the read itself.
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 single clause is free of padding, but it is drastically undersized for a 4-parameter analytical tool and is not front-loaded with any statement of what the tool returns.
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 return shape is not covered elsewhere, and the description says nothing about it. With four parameters and only defaults documented, an agent cannot confidently decide what this tool produces or what metric values to pass.
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% â the two date params are documented, but `metric` and `groupbyactivities` are bare. The description partly compensates by disclosing their defaults, which the schema does not, but it never enumerates valid `metric` values or explains what grouping by activities changes in the output.
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 name implies a verb+resource (get a progress summary over a date range), but the description never states what a 'progress summary' is, what it aggregates, or in what units. It only documents parameter defaults, which is not purpose. Among dozens of `get_*` siblings, nothing here differentiates this tool's scope.
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 indication of when this is preferable to `get_stats`, `get_daily_stats`, `get_weekly_steps`, or the other range/summary siblings, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behaviour: an all-or-nothing parameter contract that throws on partial input, and a hard 366-day cap on the ranged branch. It does not describe the returned payload, but the error and limit disclosures are the higher-value additions.
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 two branches front-loaded and no filler. The endpoint-path notation ('.../latest/{displayName}') is slightly cryptic and internal-facing, costing it a point, but nothing is wasted and the constraint (366-day cap) lands at the end where it is needed.
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?
Invocation is fully covered, including the failure mode and range cap, and the readOnly annotation covers side effects. However, with no output schema, the description says nothing about what a prediction response contains or how many race distances it covers, leaving the agent to guess at the shape of the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema expresses no dependency between the three parameters (required is empty), so the description's all-or-nothing rule is information the schema cannot convey. It also clarifies that no-params and all-params are the only two legal states. With 67% schema coverage on the date fields and enum already documenting 'type', this compensates well.
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 plainly states that the tool returns race predictions; it only describes the two request branches and the URL shapes each one hits. The verb ('hits') and resource are implied rather than named, so an agent must lean on the tool name to infer the actual purpose. It is behaviourally specific but purpose-vague, and it differentiates itself from siblings only by implication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear operational fork: omit all params to get the latest prediction, or supply all three to get a ranged result, and it warns that a partial combination throws. That is real when-to-use guidance. It stops short of naming any alternative sibling or stating a preference between the two modes beyond the parameter rule.
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.
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?
The readOnlyHint annotation already establishes this as a safe read. The description does add one behavioral detail beyond the annotations â that null values are dropped â and hints at the output shape. However, it omits pagination, ordering, and completeness behavior for the date range, so the added context is thin.
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 single clause is compact and wastes no words, but it leads with internal implementation jargon (allMetrics.metricsMap) that a caller will not recognize. Brevity here shades into under-specification rather than disciplined 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?
With no output schema, the description carries the burden of explaining what the tool returns, yet it never names resting heart rate and instead describes an undocumented internal field. For a simple date-range tool it omits the domain context and the sibling differentiation an agent needs, leaving it materially 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%, so start and end are already documented as YYYY-MM-DD UTC dates. The description adds nothing about parameter semantics, which is the expected baseline when the schema carries full 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?
The description describes an internal data transformation ('reshapes allMetrics.metricsMap into [{calendarDate, value}]') rather than the tool's domain purpose. It never states that this returns resting heart rate data, and 'reshapes' is an implementation verb, not a user-facing one. It also fails to distinguish this from the near-identical sibling get_rhr_day.
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 closely related get_rhr_day alternative. An agent has no basis for choosing between get_rhr_daily and get_rhr_day since the description offers neither scope nor differentiation.
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.
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 provide readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the default value aggregation="weekly", which is genuinely useful behavioral context not present in the schema. However, it says nothing about what data is returned, date-range limits, or any other operational 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?
The description is a single semicolon-separated fragment with no sentence structure and no front-loaded purpose. It is certainly concise, but it is under-specified rather than appropriately sized: it omits the tool's function entirely, so the brevity comes at the cost of usefulness.
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 data-retrieval tool with no output schema and a domain-specific concept ('running tolerance'), the description should explain what is returned and when to use it. Instead it only documents one parameter's default, leaving the core purpose, return values, and usage context 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 description coverage is 67% (startdate and enddate are documented; aggregation is not). The description partially compensates by stating the default (weekly) and allowed set for aggregation, which adds meaning beyond the schema's enum. It does not explain how daily vs. weekly aggregation differ in output, but this is adequate for the one undocumented 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 never states what the tool does; it only specifies the aggregation default and allowed values. The name 'get_running_tolerance' implies a retrieval of a running metric, and the aside about FTP/lactate methods hints at the domain, but the description itself provides no purpose statement an agent could use to select this 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 and no explicit alternative identified. The mention that aggregation is 'narrower than the FTP/lactate methods' implies a relationship to siblings like get_lactate_threshold or get_functional_threshold_power_range, but it does not say when this tool should be chosen over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 one genuinely non-annotation fact: this tool hits /workout-service/schedule rather than /calendar-service, which implies a different backend and possibly different auth or failure behavior, but it discloses nothing about what is returned or about error conditions.
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 clause, so there is no bloat â but it is under-specified rather than concise. The one sentence spends its words on an endpoint distinction instead of front-loading what the tool actually retrieves.
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 full schema coverage and annotations covering the safety profile, no output schema is required and the missing return description is acceptable. What is missing is any statement of what distinguishes a 'scheduled workout' lookup from the other scheduled-workout siblings beyond the internal base URL.
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, 100% schema coverage, and the schema stating 'Numeric id', the schema already does the work. The description adds nothing about id format, accepted string-vs-integer forms, or valid ranges, 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 never states what the tool does â it only notes that it uses a different service base than getScheduledWorkouts. The name implies fetching a single scheduled workout by id, and the sibling comparison confirms it is distinct from the list variant, but the verb/resource is left to inference 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?
There is no explicit when-to-use guidance or prerequisite. The base-URL contrast with getScheduledWorkouts hints that the two are not interchangeable, but it is an implementation detail rather than a routing rule an agent can act on when choosing between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the non-obvious fact that `month` is converted from 1-indexed input to 0-indexed on the wire, but this is input-handling detail rather than tool behavior; it says nothing about scope, pagination, or what a 'scheduled workout' record 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 single sentence is dense with zero filler, so it is efficiently sized. But it is not front-loaded with purpose â the one thing an agent needs first â and reads like an implementation note rather than a tool 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 two-required-parameter query tool with no output schema and three-plus look-alike siblings, the description omits purpose, scope, and differentiation entirely. Annotations cover safety only, leaving the operational picture 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 coverage is 0%, so the description carries the full burden, and it does provide real value: `month` is 1-12, converted to 0-indexed on the wire, and `year>=2000` is validated. However, it never explains what these parameters scope (e.g., which period's scheduled workouts are returned) or the accepted string forms despite the schema allowing integer|string.
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. It contains only parameter validation notes (`month` 1-12, `year>=2000`), so an agent must infer the purpose from the name alone. It does nothing to distinguish this from get_next_scheduled_workout, get_scheduled_workout_by_id, or get_scheduled_workout_summaries.
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 any alternative. With at least three closely-named sibling tools for scheduled workouts, the absence of routing guidance is a serious gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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: a just-scheduled workout is in the month feed at once but abseâĻ
| 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?
Goes well past the readOnlyHint/openWorldHint annotations: it discloses the transport (POST of a fixed GraphQL query), that dates are validated before splicing, that GraphQL errors arrive as HTTP 200 with an `errors` payload converted to GarminError, and that the feed lags writes. These are exactly the operational traits an agent needs to interpret failures and staleness.
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 dense run-on sentence studded with backticked identifiers, and it opens on the implementation detail ('POSTs the fixed GraphQL query...') rather than the user-facing purpose. The clipped trailing 'abseâĻ' also leaves the important lag sentence unfinished.
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 value, and it does: compact rows keyed by scheduledWorkoutId, with null-id Garmin Coach entries disambiguated via fbtAdaptivePlanId. The only shortfall is the truncated lag statement and the absence of any note on volume/pagination.
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 date parameters are already documented as YYYY-MM-DD UTC. The description adds that the dates are validated and spliced into the query, but no additional syntax, range limits, or semantics 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 resource and scope: 'every scheduled workout in the range, plan or self-scheduled', returning 'compact rows'. It details the distinguishing fields (scheduledWorkoutId, tpType, fbtAdaptivePlanId) so an agent knows what comes back, but never names the sibling tools (get_scheduled_workouts, get_scheduled_workout_by_id, get_next_scheduled_workout) it competes 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?
Usage is only implied through the date-range scope and the 'It LAGS writes' caveat, which does tell the agent when this feed may be stale. There is no explicit when-to-use versus the other scheduled-workout getters, so the agent must infer the choice from the return shape.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only readOnlyHint and openWorldHint, so the description's disclosure of the 28-day-per-request cap, automatic chunking, de-duplication by calendarDate, and sorted output is genuinely useful behavioural context an agent would otherwise discover only by failing. It stops short of describing return shape 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 sentence with no filler, and the most important constraint (the 28-day cap) is front-loaded. The bold/backtick markdown is slightly noisy but not wasteful.
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 annotations describing the response, the description should explain what a sleep-daily record contains and what the range returns, but it never does. It answers 'how' (chunking) while leaving 'what' entirely unanswered.
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 start and end are documented as YYYY-MM-DD UTC dates), so the schema carries parameter meaning. The description adds only the implicit range limit, which is a behavioural rather than a semantic detail â 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 never states what the tool does â no verb and no resource. It only describes a chunking constraint on 'Garmin's endpoint', leaving the agent to infer from the name that it returns daily sleep data. Sibling get_sleep_data is not distinguished from it at all.
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 this versus the closely related get_sleep_data (or get_sleep_data's range variant). The 28-day limit hints at range-splitting behaviour but does not tell the agent which tool to pick for which need.
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.
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 the safety profile is covered, but the description adds nothing about behavior â it only describes a value coercion. It also does not disclose what data is fetched, for what date range, or in what form, leaving the behavioral picture empty.
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, so there is no bloat, but the content is misplaced and uninformative â brevity achieved by saying the wrong thing. Under-specification, not 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 read tool that fetches a health metric, the description omits the metric, the date semantics beyond the schema, and any routing against sibling health-data tools. With no output schema, the description should carry this burden and 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 coverage is 100% and the sole `cdate` parameter is fully documented in the schema, so the baseline would be 3. However, the description introduces the name `lastSevenDaysAvgSpO2`, which is not a parameter at all, actively confusing rather than clarifying the input.
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 that the tool retrieves SpO2 data. Instead it describes an internal coercion of a string `lastSevenDaysAvgSpO2` to a number, which is an implementation detail rather than the tool's purpose. An agent reading this cannot tell what resource the tool 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 guidance on when to use this tool, no prerequisites, and no mention of the many sibling data-retrieval tools (get_respiration_data, get_hrv_data, get_heart_rates) it must be distinguished from. Nothing helps the agent decide to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 supply readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds no behavioral context whatsoever - no indication of what data is returned, what 'stats' covers, or whether results are date-scoped beyond the required cdate. It does not contradict the annotations, but it contributes nothing.
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 brevity here is under-specification rather than conciseness - there is no substance to front-load. A two-token description for a tool with many near-duplicate siblings leaves the agent with nothing to 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?
No output schema, no parameter context in the description, and a crowded namespace of stats-like siblings. Given the complexity of the surrounding API and the ambiguity of the name, the description is wholly inadequate for correct selection or 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% and the single cdate parameter is fully documented in the schema (format, UTC, example). The description adds no parameter meaning, but per the high-coverage baseline the schema carries the load, so 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 entire description is 'alias of `getUserSummary`', which restates the tool's identity rather than stating what it does. 'Stats' is vague, and the referenced target `getUserSummary` is not present in the sibling list (only the snake_case `get_user_summary` is), so an agent cannot resolve the alias. No verb+resource is given.
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, despite dense overlap with siblings like get_user_summary, get_daily_stats, and get_stats_and_body. The alias framing weakly implies equivalence to another operation, but since the target is unresolvable it gives no actionable routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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=true and openWorldHint=true, so safety is covered. The description adds the useful detail that this is an aggregation that internally delegates to a body-composition service, hinting at composite/possibly heavier behavior, but it omits any error behavior, latency, or partial-failure notes.
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 no padding, front-loading the merge behavior. It is efficient, though the internal-service jargon slightly reduces readability over plain resource language.
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 at least sketch the merged return shape, and it only gestures at it via internal block names. For a composite/aggregating read tool, the missing return-value and merge-semantics detail is 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?
Schema description coverage is 100% and the single 'cdate' parameter is fully documented in the schema, so the baseline is 3. The description adds no syntax or format meaning 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?
The description conveys that this returns a composite of user summary stats plus the body-composition 'totalAverage' block, but it does so through internal references ('merges getUserSummary', 'delegating to getBodyComposition') rather than stating the user-facing resource. An agent unfamiliar with those sibling endpoints cannot confidently tell what data comes back, and it isn't clearly distinguished from get_stats, get_daily_stats, or get_user_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?
There is no when-to-use guidance at all. With siblings like get_stats, get_daily_stats, get_user_summary, and get_body_composition, the definition never says when the composite call is preferable to calling those individually, nor any exclusions or prerequisites.
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.
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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond identity (no data shape, no caveats, no auth/rate-limit notes), and 'identical URL' is an implementation detail of little agent value. No contradiction with 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?
Extremely short and front-loaded with no filler sentences. The 'identical URL' clause is somewhat superfluous implementation detail, keeping 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 one-parameter, read-only, alias tool with full schema coverage and annotations, the minimal description is nearly sufficient. Still, it never says what stress data is returned or that it mirrors get_all_day_stress's output, leaving the agent to infer 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 cdate parameter is fully documented in the schema as an ISO date in UTC. The description adds nothing about the parameter, 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 never states a verb or resource in its own right; it defines the tool only by reference to a sibling ('identical URL to getAllDayStress'). Combined with the name get_stress_data an agent can infer it retrieves stress data, but the purpose is established indirectly 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?
Calling it 'an alias' implies the tool is interchangeable with get_all_day_stress, which is useful routing information and implicitly answers 'which of these do I call'. It stops short of any explicit when-to-use/when-not statement or conditions under which one should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, so safety is covered structurally. The description adds only that the endpoint is the 'phased' variant, with no mention of auth scopes, error behavior for unknown planIds, or response shape. It contributes almost nothing 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?
It is short and free of padding, which is good, but it is under-specified rather than concise â a single URL fragment that is not front-loaded with a human-readable purpose. Size is fine; usefulness per sentence is low.
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 a large, dense sibling namespace, the description should at minimum explain what is returned and how this plan type relates to get_training_plans and get_adaptive_training_plan_by_id. It does neither, leaving the agent unable to invoke the tool with confidence.
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% (planId documented as 'Numeric id'), so the schema carries the parameter burden and baseline 3 applies. The description only echoes the path placeholder {planId} and adds no format, constraint, or sourcing guidance (e.g., where to obtain a valid planId).
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 raw HTTP endpoint restatement ('GETs `/trainingplan-service/trainingplan/phased/{planId}`') rather than a statement of what the tool does. An agent can infer it retrieves a training plan by id and that the plan is 'phased', but nothing explains what a phased training plan is or how it differs from the many sibling get_*_by_id tools. This is effectively a tautology of the name.
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_training_plans, get_adaptive_training_plan_by_id, get_training_plan_workouts, and get_scheduled_workout_by_id, the description gives the agent no basis for choosing this tool over any of them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 the safety profile is covered without the description. The description adds nothing beyond 'no params', which the empty schema already makes self-evident â no return shape, no pagination behavior, no indication of whether plans are user-scoped or global.
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 clause with no padding, and the endpoint is front-loaded. It is efficient, though the extreme terseness comes at the cost of substance rather than reflecting 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 and a large sibling set of closely related training-plan tools, the description should at minimum describe the shape of the result and how this list differs from get_training_plan_by_id. Neither is present, leaving the agent unable to predict 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?
The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. The statement 'no params' is consistent with the empty schema, though it is redundant.
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 essentially restates the tool name ('get_training_plans' â 'GETs /trainingplan-service/trainingplan/plans') with no explanation of what a training plan is or what the response contains. It names an HTTP verb and a raw endpoint rather than the user-facing resource or scope, and it does nothing to distinguish itself from siblings like get_training_plan_by_id, get_training_plan_workouts, or get_adaptive_training_plan_by_id.
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 params' weakly implies a list-everything operation, but there is no explicit when-to-use, no when-not-to-use, and no reference to the several sibling training-plan tools an agent must choose between. The agent gets no routing guidance whatsoever.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful context beyond them: the underlying GraphQL call and its required arguments, the fact that Garmin chooses the window size, and that an empty array signals no enrolled plan. It does not cover auth or 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?
Two dense sentences with no filler, but the lead is internal GraphQL plumbing ('POSTs GraphQL trainingPlanScalar...') rather than the tool's purpose, which is weak front-loading for a selector-facing 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 usefully describes the returned DTO shape and the empty-array case, which is valuable. However, it omits when-to-use guidance, which matters given many closely related training-plan 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 coverage is only 50%: calendarDate is documented, but the nested options (lang, firstDayOfWeek) are not. The description partially compensates by revealing that all three arguments are REQUIRED by Garmin even though the schema marks options as optional. It still does not explain what lang or firstDayOfWeek actually affect.
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: it fetches workout schedule entries for enrolled training plans, broken out by plan. It does not explicitly distinguish itself from near-siblings like get_training_plans or get_training_plan_by_id, but the return shape and 'one entry per enrolled plan' framing give an agent enough to identify 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?
There is no statement of when to use this tool versus alternatives such as get_training_plans, get_adaptive_training_plan_by_id, or get_scheduled_workouts. The note that 'Garmin picks the window' is behavioral, not usage guidance.
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.
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 backs unitSystem), and this one reads .../settings
| 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. Beyond that the description discloses nothing behavioral: no auth requirements, no shape or size of the response, no indication of what happens for accounts lacking the resource. All of its content is endpoint-mapping rather than 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?
The core disambiguation is front-loaded, which is good, but it is delivered as one long semicolon-chained run-on that repeats the same 'three endpoints, three methods' contrast twice. Much of the middle clause restates the mapping already implied by the opening 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 zero-parameter read with annotations and no output schema, the description covers the disambiguation problem thoroughly but leaves the content gap open: with no output schema, an agent still cannot tell what fields this 'settings' payload returns â only what it is not (not `unitSystem`, not the name fields). Minimum viable, but 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?
The tool takes zero parameters, so per the baseline this dimension is a 4. The description makes no attempt to add parameter meaning, which is acceptable here since there is nothing to document.
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?
It names a specific verb and resource (GETs `/userprofile-service/userprofile/settings`) and aggressively disambiguates from the two near-identical siblings `getUserProfile` and `getUserSettings`, even warning that the paths differ by one character. What it never states is what the returned settings actually contain, so the agent knows which endpoint this is but not what it is for.
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 routes by contrast â `getUserSettings()` backs `unitSystem`, `getUserProfile()` backs `displayName`/`fullName`/`userName` â which lets an agent infer that unit-system and name lookups belong elsewhere. However, it never positively states a condition under which this tool should be chosen over those two, leaving usage implied rather than specified.
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.
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 no behavioral context at all: it doesn't say whether 'end' is the anchor and weeks counts backward, whether gaps are zero-filled, or what the aggregation granularity is. With annotations doing the safety work, the bar is lower, but this adds essentially nothing.
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 compact clause with no filler, which is good, but it is under-specified rather than concise: the one sentence spends its budget on a parameter constraint while omitting purpose entirely. Appropriate length for the content, wrong content priority.
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 should at minimum state what is returned and how the date window is computed. It supplies neither, and it never mentions the required 'end' parameter or the relationship to sibling step tools, so an agent cannot 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 coverage is 50%: 'end' is documented in the schema (YYYY-MM-DD UTC), while 'weeks' has no schema description. The description compensates for exactly that gap by giving the default (52) and the constraint (positive integer). However, it omits the semantic relationship between 'end' and 'weeks' (e.g., whether weeks is counted backward from end), leaving the aggregation window 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?
The description never states what the tool does; it only constrains one parameter. An agent must infer from the name get_weekly_steps that this returns aggregated weekly step counts, and nothing distinguishes it from siblings like get_daily_steps, get_steps_data, or get_weekly_stress. This is effectively a restatement of parameter trivia rather than a purpose 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?
There is no when-to-use guidance, no mention of when to prefer this over get_daily_steps or get_steps_data, and no prerequisites or date-range context. The agent is given nothing to route on.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 structurally. The description adds nothing behavioral beyond that - no mention of what window is returned, granularity, units, or behavior when data is missing. Its only content is a parameter-handling cross-reference, so it contributes almost nothing 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?
It is short, but brevity here is under-specification rather than economy - the single sentence is a dependency pointer with no front-loaded statement of purpose. No sentence tells the agent what the tool is or when to call 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 2-parameter, no-output-schema tool, the definition supplies no purpose, no return semantics, no date-window behavior, and no differentiation from a large sibling set of stress and weekly-rollup tools. It is not usable as a standalone definition.
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 (YYYY-MM-DD UTC) but `weeks` is bare. The description does acknowledge `weeks` by pointing to getWeeklySteps for its default and validation, which is at least an attempt to cover the gap, but it outsources the meaning to another tool's definition rather than stating the default or valid range here. An agent cannot resolve the parameter from this tool's 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 never states what the tool does. It is a cross-reference fragment ('same `weeks` default/validation as `getWeeklySteps`') that assumes the reader already knows what weekly stress data means and what the sibling returns. The name is the only signal of verb+resource, and the description adds none of the necessary scope (weekly stress aggregation from what source, over what date range).
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_stress_data, get_all_day_stress, get_weekly_intensity_minutes and get_weekly_steps in the same family, the description gives the agent no basis for choosing this tool over those, nor any prerequisite or exclusion.
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.
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.
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 and openWorldHint, but the description adds useful behavioral detail: default start and limit values and the fact that the result stays nullable rather than being coalesced to an empty array. This goes beyond the safety profile supplied by 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 short and avoids padding, but it is a sentence fragment rather than a structured definition. It front-loads parameter defaults while omitting basic framing about what is being 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 read-only list tool with no output schema and many similar siblings, the description should establish purpose, scope, and when to use it. Instead it covers only pagination defaults and null behavior, leaving major 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 parameter meaning. It supplies defaults for both parameters (start=0, limit=100), which is valuable, though it still does not explain what start and limit represent semantically.
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. It only documents pagination defaults and null handling, leaving the actual purpose ('get workouts') to be inferred entirely from the tool name.
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 get_workouts versus siblings such as get_workout_by_id, get_scheduled_workouts, or get_activities. The description contains no context, prerequisites, or exclusions.
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, 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, logFood, quickAddFood, deleteFoodLogs) need it; without it they throw GarminConnectPlusRequiredError instead of the bare 403 Garmin sends
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only readOnly/openWorld, so the description carries the rest and delivers: it reads from the cached socialProfile endpoint, states that usually no extra request is made, and explains how subscription status is derived. It even discloses downstream error semantics, which is rich 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-loaded with the plain-language purpose before the implementation detail, and every clause is informative. It is a single dense sentence with heavy parenthetical nesting, which costs some readability, but little could be cut without losing the derivation and error semantics.
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 burden of explaining the return value, and it does so precisely (true when hasPremiumSocialIcon/userRoles conditions hold). Given zero parameters and existing annotations, nothing an agent needs to invoke and interpret 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 the schema-based baseline of 4 applies. The description correctly adds no parameter guidance because there is none 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 precise predicate and its exact computation: true when hasPremiumSocialIcon is true or userRoles holds a ROLE_SP_FEATURE_n entry. It is unmistakably distinct from any sibling, several of which are named as dependencies. An agent knows exactly what this tool answers.
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 CONNECT_PLUS_METHODS that require this check and the failure mode (GarminConnectPlusRequiredError instead of a bare 403), giving strong context for when the call matters. It stops short of an imperative 'call this before X', but the conditions that select this tool are clear and nothing is misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely useful behavior beyond that: required custom headers, and specifically that a 409 is re-raised as GarminConnectionError with a duplicate message. It stops short of covering auth/header acquisition or any return 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?
It is a single dense semicolon-chained sentence loaded with internal jargon (`NK`, `origin`, `{ext}`) and it opens with the endpoint rather than the tool's purpose. It is not bloated, but it is not front-loaded around what an agent most needs to know.
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 non-trivial import operation the description does cover mechanics and the duplicate-error path well. However, with no output schema present it should say what a successful import returns (e.g., created activity id), and it never explains how the load-bearing `NK` header is obtained, which an agent needs to actually invoke this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already states the file is an absolute path to a .fit/.gpx/.tcx file, so the accepted-extension constraint in the description is largely redundant. The one added nuance is that the extension is parsed out to build the URL, which is minor.
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 explains a multipart upload to a specific endpoint and notes it makes Garmin treat the file as an import rather than a device sync, so the goal is inferable. But it is framed in protocol/implementation terms rather than stating plainly that it imports a local activity file, and it never distinguishes itself from the sibling `upload_activity`.
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 a closely named sibling (`upload_activity`) whose relationship to this tool is left entirely unaddressed. The agent must 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.
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 far beyond the annotations (readOnly=false, openWorld=true, destructive=false) by disclosing exact side-effect behavior: nothing is saved, courseId is null, the track is resampled (13 points become 37), elevations/timestamps are null, courseName comes from the GPX <name>, and a GarminError is thrown on an empty response. This is rich behavioral context the annotations do not 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?
Dense but front-loaded: endpoint first, then the critical parse-only behavior bolded, then edge behaviors. Every clause carries signal, though the run-on semicolon structure is heavier than 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?
With no output schema, the description compensates fully by describing the return shape (courseId null, resampled track, null elevations/timestamps, courseName) and the empty-response error. Combined with the annotations covering safety/open-world, 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?
Schema coverage is 100% and the single filePath param is documented in the schema, so the baseline is 3; however the description adds meaningful value by restricting accepted input to '.gpx only' (explicitly noting only .gpx was verified) even though the schema lists .fit/.gpx/.tcx, plus the transport field name 'file'. This narrows and corrects the schema 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 action (multipart POST that parses a GPX course), names the endpoint, and front-loads the crucial 'saves NOTHING' semantics that separate it from persistence tools like create_course_from_gpx. An agent can immediately tell this is a parse-only operation rather than a create/import that persists.
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 establishes the usage context (parse-only, no save, .gpx only) so the agent knows when this applies versus a saving variant, but it never names an explicit alternative or states 'use X to persist'. Context is clear but exclusions/routing to siblings are left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavioral context the annotations don't: that tracking-preference settings are left untouched and that the tool presupposes an unconfigured account. It says nothing about effects on existing data 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?
The definition is a single compact clause pair with no filler, but it is front-loaded with a negative statement before any positive framing, which makes it read as a caveat with no antecedent. Brevity is fine; ordering is suboptimal.
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-required-parameter mutation with no output schema and 33% schema coverage, an agent needs at minimum what the tool creates and what the numeric parameters mean. The description supplies neither, covering only exclusions.
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% â periodStartDate documents its format, but cycleLength and periodLength carry no unit (days? entries?), range, or meaning anywhere. The description does not compensate at all, leaving two of three required parameters semantically opaque.
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 â no verb+resource statement like 'initializes menstrual cycle tracking.' It only asserts exclusions ('does NOT also update tracking-preference settings', 'not intended for an already-configured account'), leaving the positive purpose to be inferred from the tool 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?
It does name an alternative for a related need (`updateMenstrualSettings`) and gives one negative precondition (not for an already-configured account), which implicitly defines when this tool IS appropriate. However, it never states the primary when-to-use condition, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: the failure mode ('one date alone throws') and the fact that the same events surface in getScheduledWorkouts' feed as itemType 'event'.
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 compact sentence, but it is front-loaded with a cross-reference ('Events also appear in...') rather than the primary action, and the semicolon chain makes it dense. The most important content (what the tool does) sits after the endpoint trivia.
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-optional-param list tool with annotations covering safety, the call semantics (date combinations, error case) are adequately covered. With no output schema present, however, the description gives no sense of what an event record contains or whether results are paginated.
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 real semantics the schema lacks: the two dates must be supplied together (or not at all) and the range is inclusive. This is meaningful constraint information beyond the per-field format descriptions.
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 a clean verb+resource phrase like 'lists calendar events'; instead it opens with a cross-reference and an endpoint path ('this GETs /calendar-service/events'). The resource is inferable from the name and endpoint, and it does differentiate from getScheduledWorkouts' month feed, but the core purpose statement is vague and back-loaded.
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 the usable parameter combinations: both dates for an inclusive range, no params for the whole account, and explicitly warns that one date alone throws. It also points to getScheduledWorkouts as an overlapping source, giving the agent routing context, though it doesn't frame a full when-to-use-this-vs-that rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context by disclosing that the response is an envelope `{ coursesForUser: CourseSummary[] }` rather than a bare array, which is exactly the kind of detail 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?
A single sentence that front-loads the endpoint and then the return-shape caveat, with no filler. The trailing-slash note is slightly pedantic but arguably useful for an agent replicating the call.
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 the return payload and does so precisely via the envelope shape. For a zero-parameter read tool this is nearly sufficient; only pagination/empty-result behavior is left 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?
The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing parameter-related the description needs to 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?
The description names the exact upstream endpoint (`/web-gateway/course/owner/`) and, combined with the tool name and return shape (`coursesForUser`), makes it clear this lists the user's own courses. It does not explicitly contrast with single-course readers like get_course, but the resource and scope 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?
There is no when-to-use guidance and no named alternative. An agent must infer from the sibling list that get_course handles a single course while list_courses enumerates them; the description itself offers no routing help.
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). 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, else SNACKS; with a meal and no time it picks a time thatâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (not read-only, not destructive, open-world), and the description adds substantial context beyond them: the subscription gate, the mealId dependency, the resulting 400 'mealId must not be null' error, and the fact that a clearer error is thrown first. The meal/time resolution rules are also disclosed. It loses a point because the final sentence is truncated ('it picks a time thatâĻ'), leaving that behavior unexplained.
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 and endpoint are front-loaded, which is good. However the text is dense and run-on, mixing API mechanics, defaults, and error behaviors in long sentences, and it terminates mid-sentence, so structure and completeness of thought suffer.
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 a nested object parameter and no output schema, the description supplies the prerequisites, error conditions, default-resolution logic, and notes the return value ('the whole day's log'). The truncated ending is the main gap, but overall it is close to 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?
Top-level schema coverage is 0% and the single parameter is a nested object, so the description carries the burden. It compensates well by spelling out the FoodLogInput shape, naming fields not described in the schema (foodId, servingId, regionCode, languageCode), giving defaults (servings=1, source='GARMIN'), and explaining that the catalogue food's source/regionCode/languageCode should be passed for a search result.
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 ('log food'), names the exact endpoint (PUT /nutrition-service/food/logs), and specifies that it logs one REGULAR_LOG item and returns the whole day's log. It is distinguishable from get_nutrition_daily_food_log and delete_food_logs, though it never explicitly contrasts with the close sibling quick_add_food.
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 important prerequisite (requires Garmin Connect+ subscription, check with has_connect_plus) and warns that a mealId from in-app nutrition setup is required. However, it gives no guidance on when to choose this over quick_add_food or create_custom_food, so routing between logging options 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.
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.
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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description goes further by disclosing that this is a multi-call orchestration, that missing parameters are silently resolved, that a final POST occurs, and that it throws when no workout exists. It still omits permissions/authentication needs and whether the push overwrites anything already on the device.
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 that front-loads implementation mechanics instead of the outcome, and includes raw endpoint paths and argument tuples ('/device-service/deviceservice/mylastused', 'getWorkouts(0,1)') that are noise compared to the sibling tool names. The content is relevant but not efficiently organized.
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-required-parameter mutation with no output schema, the description covers parameter resolution and one failure mode but says nothing about what success looks like, required permissions, or side effects on the target device. Adequate but leaves real gaps for a state-changing operation.
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% but both schema descriptions are merely 'Numeric id'. The description adds substantial meaning: deviceId falls back to the last-used device's userDeviceId, workoutId falls back to the first result of getWorkouts(0,1), and the operation errors if no workout is found. That resolution/optionality semantics is not derivable from 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 never states the end goal in plain terms ('push a workout to a user's device'); it opens with 'multi-call' and then lists internal resolution steps. The final clause about the 'push message on the final POST' implies a write effect, but the agent has to reconstruct the purpose from the name plus implementation detail.
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 alternatives such as schedule_workout, preview_workout, or download_workout, nor any prerequisites (e.g., an existing workout or paired device). The only implied guidance is that both parameters are optional because they get auto-resolved.
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). 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. Needs Connect+
| 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), so the bar is lower, and the description still adds real behavioral context: the Connect+ subscription gate and the check-with has_connect_plus path. It doesn't describe failure modes beyond the schema's 400 note, keeping 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?
Front-loads the subscription requirement and packs endpoint, entry shape, and type into a compact block with little waste. The trailing "Needs Connect+" repeats the opening sentence, a minor redundancy that costs it 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 write tool with annotations covering safety and no output schema, the description supplies the subscription gate, the endpoint, the entry semantics, and a pointer to logFood for meal rules. Required fields are enumerated, and the nested schema handles meal/time defaults, so little 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?
Top-level schema coverage is reported at 0%, but the nested input object does document date, meal, and time, and the description restates the required name/macro set. It adds the 'no food behind it' meaning but no format or default detail beyond what the nested schema already carries, so a 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 and resource ('an entry by name + calories/carbs/protein/fat with no food behind it'), and the 'QUICK_ADD ... no food behind it' phrasing meaningfully distinguishes it from log_food (which logs an existing food). It stops short of naming the sibling it contrasts with, so it lands at clear-but-not-fully-differentiated.
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 one concrete prerequisite ("Requires a Garmin Connect+ subscription (check with has_connect_plus)") and defers meal rules to logFood, which implies a usage context. However it never states when to pick this over log_food or create_custom_food, so the when-versus-alternative 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.
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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds real value by clarifying the operation is a PUT rather than a DELETE (explaining the non-destructive hint despite the 'remove' name) and that it follows a 404-handling pattern. However, it never explains what that 404 pattern actually does, so the disclosure is suggestive rather than actionable.
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 very short and front-loads the key PUT-vs-DELETE distinction, which is efficient. But it is a sentence fragment that omits any statement of purpose, so brevity here reads as under-specification rather than disciplined 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 two-parameter mutation tool with no output schema and only 50% schema coverage, the description omits parameter meaning, return/confirmation behavior, and any explanation of the referenced 404 pattern. An agent cannot call it confidently from this definition alone.
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 50% schema coverage and 2 required parameters, the description says nothing about gearUUID or activityId. The schema only describes activityId ('Numeric id') and leaves gearUUID bare, so the description fails to compensate for the coverage gap that the dimension requires.
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 in words what the tool does; it leans entirely on the name 'remove_gear_from_activity' to convey the purpose and instead spends its text on implementation details (HTTP verb, error handling). An agent can infer 'detach gear from an activity' from the name, but the description itself adds no explicit verb+resource statement and does not differentiate from the sibling add_gear_to_activity beyond a method contrast.
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, no prerequisites, and no explicit routing to the sibling add_gear_to_activity. The reference to 'same 404-handling pattern as addGearToActivity' is an implementation hint, not usage context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 (a write/mutation), openWorldHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond that: it is a POST with no JSON body, and it triggers a server-side reload/recomputation of offloaded data. It does not cover auth, rate limits, or side effects on existing data, but the added context is meaningful.
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 no filler. The core action and the reason (offloaded data forced back) are front-loaded, and the endpoint/method detail is secondary but still 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 simple one-parameter mutation with 100% schema coverage, no output schema, and annotations covering safety, the description is nearly complete. It explains what the tool does, the HTTP method, and why it exists. Minor missing details (e.g., async timing) are not critical 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%: the single `cdate` parameter is fully documented in the schema as a YYYY-MM-DD UTC date. The description only echoes `{cdate}` in the endpoint string without adding format or meaning beyond the schema. Baseline 3 is appropriate 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?
The description names a specific action (reload/recompute a day's data) and the resource (a date's wellness epoch data). It is immediately distinguishable from all sibling tools, which are primarily get/add/create/delete/set operations. No ambiguity about what the tool does.
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 clear context for when to use the tool: Garmin offloads older data, so this forces it back. There is no explicit exclusion or named alternative, but no sibling tool offers a similar reload/recompute function, so alternatives are not needed. The scenario is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
dateStr routed through formatDate
| 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive write with external effects. The description adds nothing beyond that â it does not say what scheduling does, whether it overwrites an existing scheduled workout for that date, or what permissions are required. It does not contradict the annotations, but it contributes no behavioral context of its own.
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 single fragment is short but does not earn its place â it is an internal code reference rather than agent-facing information. Brevity without substance is under-specification, not 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?
This is a state-mutating scheduling tool with no output schema and no annotation coverage of scheduling-specific behavior (e.g., overwriting existing entries for a date, timezone handling, whether the workout must already exist). The description supplies none of the information 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%: dateStr is documented as 'Calendar date, YYYY-MM-DD (UTC)' and workoutId as 'Numeric id'. The description's only parameter-related content is an implementation note about formatDate, which adds no usable semantics. Baseline 3 applies because the schema carries the full 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?
The description never states what the tool does. '`dateStr` routed through `formatDate`' is an implementation detail, not a purpose statement; an agent cannot tell from this that the tool schedules a workout, nor distinguish it from siblings like create_workout, unschedule_workout, or get_scheduled_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 when-to-use guidance, no prerequisites, and no mention of alternatives such as unschedule_workout or create_workout. The agent is left to infer everything from the tool name and sibling list.
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). GETs /nutrition-service/food/search?searchExpression&start&limit (defaults 0/20): {results: Food[], moreDataAvailable}; catalogue foods carry source: "FATSECRET" and several servings each. Needs Garmin Connect+, which needs a paired Garmin device (a bare 403 ForbiddenException without it)
| 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 and open-world, while the description discloses substantial extra behavior: the exact endpoint, default start/limit values, response shape, catalogue source metadata, subscription gating, paired-device requirement, and the 403 error when prerequisites are absent. This is exactly the kind of context that helps an agent avoid a failed 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 description is compact and front-loads the subscription requirement, endpoint, and response shape. The later bolded repetition of 'Needs Garmin Connect+' is somewhat redundant, but the overall structure remains 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 supplies the key return shape ({results, moreDataAvailable}) and catalogue metadata. It also covers authentication and error behavior, though it leaves some pagination and limit-detail 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. It names the endpoint parameters and gives defaults for start/limit (0/20), but it does not explain the meaning of query beyond 'searchExpression', nor does it define limit bounds or start offset 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?
States a specific resource (food search) and scope (catalogue foods with source FATSECRET, returned via a Garmin nutrition endpoint). It implicitly distinguishes catalogue foods from custom foods, but does not explicitly name a sibling alternative such as get_custom_foods, 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?
Provides a clear prerequisite (Garmin Connect+ subscription) and points to has_connect_plus for checking it, plus a warning that a 403 occurs without the subscription. However, it gives no explicit guidance on when to choose this tool over siblings like get_custom_foods or quick_add_food.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolves to null on success. Live-verified: description read back via getActivity after the call
| Name | Required | Description | Default |
|---|---|---|---|
| activityId | Yes | Numeric id | |
| description | 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 safety profile is covered. The description does add genuinely useful behavior beyond them: it discloses the return value (null on success) and the verification path via getActivity, which no structured field supplies. It still omits what is actually mutated and whether the write is idempotent.
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-loads its only content, but that content is about the return value rather than the purpose. Nothing is padded, but the space is allocated to the wrong concern for a definition this terse.
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 reasonably covers return behavior, but for a two-parameter mutation it omits what gets written, size/format constraints on `description`, and how to confirm the change. An agent knows the callback result but not what the call changes.
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 the `description` parameter has no schema description at all. The tool description adds nothing about either parameter, so the undocumented half is left completely unexplained. It does not compensate 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?
The description never states what the tool does: it only says it 'resolves to `null` on success' and that the description was read back via getActivity. An agent must infer the verb+resource entirely from the name, and there is no differentiation from sibling setters like set_activity_name or set_activity_feel.
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 the many sibling set_activity_* tools. The only implicit cue is 'description', which the name already carries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation safety profile is covered. The description adds real context beyond that: Garmin auto-fills typeId/sortOrder so the caller need only supply the key, and validation happens client-side ('Throws GarminError before any request') for invalid keys. The only weakness is that the valid-key sentence is truncated ('outside the nine').
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 that are front-loaded with the essential constraint, but they are dense with REST/HTTP implementation detail and the second sentence is cut off mid-thought ('outside the nine'), so it is under-specified rather than genuinely 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 two-parameter mutation with no output schema, the description provides useful auto-fill and validation context, but the truncated sentence leaves the list of valid keys unexplained and no auth/permission or side-effect details are given. It is adequate but clearly 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 coverage is only 50% (activityId documented as 'Numeric id'; eventType is an enum with no description). The description adds that only typeKey is required and that Garmin supplies typeId/sortOrder, which is useful, but it references payload field names (typeKey/typeId/sortOrder) that don't match the actual schema parameters (activityId, eventType), creating a mild mapping ambiguity.
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 the effect (setting an activity's event type) but frames it in raw HTTP terms ('Partial PUT /activity-service/activity/{id} with {activityId, eventTypeDTO: {typeKey}}') rather than plainly stating the user-facing intent. It does not distinguish this from the close sibling set_activity_type, which an agent could easily confuse with event type. The mechanics are specific, but the purpose statement is developer-centric.
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 guidance is given, and no alternative tool is named. The closest thing is 'The typeKey alone is enough,' which is a payload note rather than usage guidance. The agent must infer the context (setting an event/race category on an existing activity) on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, but the description adds real specifics: replace-all (not partial merge), payload sent verbatim (so no server-side validation/coercion), and explicit irreversibility. These go beyond the annotations and materially change how an agent should behave.
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?
Extremely terse and front-loaded â the two highest-stakes facts (replace-all, IRREVERSIBLE) come first with zero filler. It is nearly a fragment rather than a sentence, but no word 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 destructive, nested-object mutation with no output schema, the definition covers irreversibility and replace semantics but leaves the payload structure (what exerciseSets entries look like) and the id meaning unaddressed. Adequate but with clear gaps for an agent assembling a 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 coverage is 50% (activityId is only 'Numeric id'; payload is undocumented). The description adds the meaningful fact that payload is sent verbatim, but it says nothing about the shape of exerciseSets or the activityId semantics, 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?
The description never states the actual purpose (writing/replacing an activity's exercise sets) in a verb+resource sentence; the reader must infer it from the tool name. 'replace-all semantics' hints at a write to exercise sets but does not name the resource or distinguish it from the get_activity_exercise_sets sibling 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 one directive â 'confirm with the user before calling' â which is genuinely useful for a destructive operation. However, it offers no when-to-use/when-not guidance, no mention of the read counterpart get_activity_exercise_sets, and no prerequisites such as required scopes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only declare a non-read-only, non-destructive write; the description goes further by disclosing that the backend rejects values outside 0/25/50/75/100 even though Garmin itself can store arbitrary numbers. It also states the clearing semantics for null. It omits auth requirements and whether existing values are 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?
One dense sentence that front-loads the target field and then the constraint, with no filler. The opening 'Partial PUT of summaryDTO.directWorkoutFeel' is implementation jargon that costs readability without adding agent-relevant 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 two-parameter setter with no output schema, the description covers the value domain, the meaning of the scale, rejection behavior, and how to clear the field. The unresolved null-versus-schema mismatch and the untold activityId semantics are the remaining 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 50% and the feel parameter is a bare anyOf enum with no description, so the text carries the load: it names the allowed values, labels their meaning (very weak to very strong), and adds clearing behavior. The activityId parameter gets no added semantics, and notably the text claims null is accepted while the schema's anyOf permits only 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?
States a specific verb+resource: it sets an activity's workout feel value (summaryDTO.directWorkoutFeel) with the exact allowed scale. The name-plus-field identification makes it distinguishable from most siblings, though it never differentiates from the near-neighbor set_activity_perceived_effort, which an agent must infer.
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. It mentions that null clears the value, which is behavioral rather than routing guidance, and the closest sibling (set_activity_perceived_effort) is not mentioned at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolves to null on success. Live-verified: value read back via getActivity after the call, not just that the request was accepted
| 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, destructiveHint=false, openWorldHint=true. The description usefully adds that success returns null and that the value was live-verified by reading it back via getActivity â genuine value beyond annotations. It omits whether the existing name is overwritten, auth/permission needs, and 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?
Short, but it is a sentence fragment that leads with return semantics instead of purpose, so the most important information is not front-loaded. Brevity here reflects under-specification rather than 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?
No output schema exists and the description does cover the return value, but for a two-required-parameter mutation with one undocumented parameter and no purpose statement, the definition leaves the agent guessing about what the tool actually changes.
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% (activityName has no description), and the description adds nothing about either parameter â not the id format beyond 'Numeric id', not any constraint on the name string. With two required parameters it should carry more weight than this.
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 â it only says the call 'resolves to `null` on success' and how to verify the result. An agent must infer the purpose entirely from the name set_activity_name. The description is about return behavior, not the action performed.
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 routing among the many siblings (set_activity_description, set_activity_type, set_activity_feel, etc.) that mutate activity fields. The verification hint via getActivity is the only contextual clue offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing Garmin's non-obvious times-ten storage convention, the out-of-range 400 `MEASUREMENT_NOT_VALID` behavior, and a specific read-modify-write hazard (PUTting back the stored start-coordinate pair yields a 400). This is exactly the server-specific behavior 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?
Three dense clauses/ sentences, no filler, and the scaled-value contract is front-loaded before the error and anti-pattern notes. Each sentence carries a distinct, non-redundant 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 two-parameter mutation tool with no output schema, the description covers the value contract, the clear operation, an observed server rejection, and the read-modify-write pitfall. Nothing needed to invoke it safely against Garmin 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 `rpe` property has no schema description, yet the description fully specifies its semantics: integer 1-10 accepted, transmitted as 10-100, and null accepted to clear. The `activityId` parameter is left to the schema's 'Numeric id', so one parameter remains thin, but the critical encoding detail is supplied.
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: a partial PUT that sets the activity's perceived effort (RPE). It is immediately distinguishable from siblings like set_activity_feel, set_activity_description, or set_activity_name, which touch different fields of the same activity.
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 the valid input range (1-10 integer) and the clearing condition (`null` clears it), which is usable guidance. However, it never states when to choose this tool over adjacent siblings such as set_activity_feel, nor any preconditions for the target activity, so the when-to-use dimension is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolves to null on success. Live-verified: activityTypeDTO read back via getActivity after the call
| 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, destructiveHint=false, and openWorldHint=true. The description adds only that the call returns null on success and can be verified via getActivity, but says nothing about what existing type assignment is overwritten, whether typeId/typeKey/parentTypeId must be consistent, 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?
It is short, but the space is spent on a return-value aside rather than the tool's purpose, so it is under-specified rather than concise. Nothing is front-loaded because the core action is never stated.
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 four-parameter mutation with 25% schema coverage, no output schema, and no parameter documentation, the description is inadequate. It does not tell an agent what the tool changes or how to build a valid 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 only 25% â three of four required parameters (typeId, typeKey, parentTypeId) have no schema descriptions at all, and the description adds zero parameter meaning. The relationship between typeId, typeKey, and parentTypeId is completely undocumented.
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. It opens with a fragment about the return value ('resolves to `null` on success') and a verification note, leaving the actual purpose (assigning an activity type to an activity) to be inferred entirely from the name and sibling set.
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 distinction from near-siblings such as set_activity_event_type or set_activity_name, and no mention of prerequisites like valid typeId/typeKey values. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description does add real behavioral information beyond them â accepted value ranges imply out-of-range input is rejected, and `when` defaults to the current time. However, it says nothing about what happens on invalid input, whether a reading at an existing timestamp is overwritten, or any 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?
One tight, semicolon-joined sentence with no filler â every clause carries a constraint or a default. It is front-loaded with the highest-value information, though it front-loads validation rather than 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 5-parameter write tool with no output schema, the description omits too much: no purpose statement, no semantics for `notes`, no indication of whether this inserts or upserts, and no description of the response. The validation ranges are valuable but do not make the definition 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 only 20% (just `when`), so the description carries most of the burden and largely does: it gives explicit bounds for systolic, diastolic, and pulse, and supplies the default for `when` that the schema omits. It leaves `notes` entirely undocumented and its 'all integers' claim sits awkwardly against the schema's `number` types, which permit decimals.
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 â it opens directly with validation ranges. The verb+resource in the name ('set_blood_pressure') lets an agent infer that this records a blood pressure reading, and the sibling set (get_blood_pressure, delete_blood_pressure) reinforces that, but the description itself contributes nothing to 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 use this versus alternatives, no prerequisites, and no mention of how it relates to get_blood_pressure or delete_blood_pressure. The agent gets constraints but no routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. [] clears all defaults. Concurrent callers can clobber each other 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, but the description goes well beyond them: it discloses the GET-then-PUT whole-record rewrite (so unrelated fields are preserved), the concurrency/clobbering hazard between callers, the explicit IRREVERSIBLE warning, and the case-sensitivity rule. This is exactly the extra behavioral context an agent needs for a destructive mutation.
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 implementation, casing rule, and warning in order. Dense but nearly every clause carries actionable information; the parenthetical history about the dead endpoint is slightly extraneous but justifies the unusual design.
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 2-param destructive mutation with no output schema, the description covers side effects, casing, clearing semantics, and the confirmation requirement. It does not describe the success response or any auth/permission prerequisites, 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 description coverage is 0%, so the description must compensate, and it largely does: it explains that activityTypeKeys uses lowercase keys like "running" matching createGear, that each key becomes `{activityTypeKey, defaultGear: true, preferredGear: false}`, and that `[]` clears all defaults. gearUUID is left implicit but is self-evident from the name.
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 ('set gear defaults') immediately, and adds the disambiguating note that the old dedicated default-gear endpoint is dead and there is no `setGearDefault`. In a sibling set that also contains get_gear_defaults and create_gear, this makes the tool's distinct role obvious 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?
Explains the operational context well: read-modify-write flow, that `[]` clears all defaults, and that callers must confirm with the user first. It does not explicitly name a read alternative (e.g. get_gear_defaults) or state when not to use it, so routing guidance is clear but not exhaustive.
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 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 strictly ascending (Garmin 400s `"Zone Floor values must be ascendiâĻ
| Name | Required | Description | Default |
|---|---|---|---|
| update | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only providing basic hints (readOnly=false, destructive=false), the description adds critical behavior: it does a GET, overlays fields, PUTs, and reads back; it notes that a sport without a profile starts from DEFAULT; that setting restingHeartRate turns off auto-update; that Garmin does not recompute floors; and that floors must be strictly ascending or it 400s. This is rich and non-obvious.
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 dense but front-loaded with the main operation, then details constraints. It is appropriately sized for a complex mutation, though the truncated ending ("ascendiâĻ") slightly hurts clarity. 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?
Given the complexity (READ-MODIFY-WRITE, nested object, no output schema), the description covers everything an agent needs: the sequence, defaults, side effects, error conditions, and floor requirements. It is 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?
Even though the schema has 0% description coverage (only type info), the description compensates extensively: it explains the overlay object, lists each field and its meaning (sport defaults to DEFAULT, zoneFloors need 5 bpm values, restingHeartRate side effect, trainingMethod enum values, etc.). This adds substantial 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?
The description states a specific verb+resource: it modifies heart rate zones for a profile, using a precise READ-MODIFY-WRITE pattern with exact HTTP endpoints. It distinguishes itself from sibling tools like get_heart_rate_zones and delete_heart_rate_zones by describing the multi-step write 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 clearly implies usage: you call it to set/update heart rate zones, with a specific sport or DEFAULT. However, it does not explicitly say when to call it versus alternatives or preconditions (e.g., need a profile), though the READ-MODIFY-WRITE pattern implicitly suggests the operation is idempotent and requires reading first.
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 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, so irreversibility is partly known. The description adds the crucial detail that only the calendar entry goes and the underlying template persists, which the annotations cannot express, plus an explicit 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?
A single front-loaded sentence with no wasted clauses; the destructive consequence leads. Minor deduction for the redundant, oddly capitalized 'irreversible IRREVERSIBLE' repetition that mildly muddies the 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 one-parameter destructive tool with annotations covering the safety profile and no output schema, this covers the essential agent-facing facts. It omits what happens if the scheduledWorkoutId is invalid or not found, a small remaining 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?
Only one parameter, and the schema at 100% coverage documents it as 'Numeric id'. The description adds no type, format, or lookup guidance 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?
States a specific verb+resource ('removes the calendar entry') and immediately disambiguates scope from the sibling delete_workout by noting the workout template is preserved. An agent can distinguish this from delete_workout and delete_calendar_event 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 clear operational directive ('confirm with the user before calling') and implies when this is preferred over delete_workout by stating the template survives. It stops short of explicitly naming alternatives or the condition that would pick delete_workout instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}; Garmin answers with no body, so it resolves to null. 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 only cover readOnly=false, openWorld=true, destructive=false. The description goes well beyond them: it discloses the full GET-then-PUT round trip, that the whole record is rewritten (not a patch), that the server returns no body so the call resolves to null, and that concurrent callers can clobber each other. This is exactly the extra behavioral context the description should 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?
It leads with the key concept 'READ-MODIFY-WRITE' and every clause (field list, null-clears rule, PUT target, null result, concurrency warning) earns its place. It is a single dense, semicolon-chained sentence that is somewhat run-on but wastes 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?
For a 2-param mutation tool with a nested object and no output schema, the description supplies the mechanism, the update semantics, the return value (null), and the concurrency hazard. There is essentially nothing else an agent needs before calling 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 only 50% and the schema documents the nested fields without semantics. The description compensates by enumerating the overlayable fields and, importantly, explaining that null clears an optional field â meaning the schema alone cannot convey. eventId is left to the schema, but the added null/overlay semantics lift this above 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?
The description names a specific verb+resource and, crucially, an unusual mechanism (READ-MODIFY-WRITE via GET/overlay/PUT). It is unmistakably distinct from siblings like create_calendar_event, delete_calendar_event, get_calendar_event, and list_calendar_events. An agent knows exactly what operation this performs 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 explains how to use it â overlay a set of optional fields and pass null to clear one â which is real usage guidance. It does not, however, explicitly state when to prefer it over siblings or name any alternatives/exclusions, so it stops short of the top bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 annotations by disclosing the read-modify-write pattern, that the WHOLE record is PUT back (so concurrent callers can clobber), that it throws before any request on invalid input, and that just-created courses may 429. This is exactly the behavioral detail 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?
Dense and front-loaded: the mechanism leads, followed by concurrency, validation, and rate-limit notes in order of importance. The 2026-09-24 observation date is minor provenance padding, but every fragment otherwise 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 mutation tool with no output schema, it covers behavior, failure modes, and concurrency adequately. It omits the response shape and auth requirements, but annotations cover the open-world/read-only profile, leaving 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 coverage is only 50%, so the description must compensate. It does so by revealing that at least one of the two change fields must be supplied and that a blank name is rejected, adding real meaning about the nested 'changes' object beyond 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?
States a specific verb and resource (updates a course record) and describes the exact mechanism (GET, overlay, PUT back to /course-service/course/{courseId}). It distinguishes itself clearly from get_course/list_courses/create_course by being the write path, though it never names a sibling 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?
Gives clear operating context: this is the same request Garmin's web editor sends on Save, and it notes the concurrency hazard and 429 condition. It does not explicitly route the agent between alternatives like update_workout or update_calendar_event, but the when-to-use context is solid.
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). The same PUT carrying both ids. FULL REPLACE: a nutrient or brand left out is removed (verified: the brand was dropped). Needs Connect+
| 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 states that a FULL REPLACE removes any nutrient or brand not supplied, explicitly noting data loss ('the brand was dropped'). That is a destructive update per the MCP semantics of destructiveHint, yet the annotations declare destructiveHint=false. The description therefore contradicts the structured safety signal, and an agent trusting the annotation would under-warn the user about losing existing field 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?
It is short, but a quarter of it is wasted on a duplicated subscription statement ('Requires a Garmin Connect+ subscription' ... 'Needs Connect+'). It also front-loads the prerequisite rather than the action, and the phrase 'The same PUT carrying both ids' is opaque without context for what 'the same' refers to.
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 object, no output schema, and no field documentation in the schema, the description covers the subscription gate, the full-replace hazard, and the paired ids, which is a fair amount. It still omits how the caller obtains foodId/servingId (e.g. get_custom_foods) and whether a representation is returned, leaving the agent to guess at the surrounding workflow.
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, and it delivers the single most important semantic: omitted fields inside `input` are deleted, not merged, which directly governs how an agent constructs the payload. 'The same PUT carrying both ids' also signals that foodId and servingId are supplied together, though it does so cryptically rather than naming them.
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 actually states the action; it opens with a subscription prerequisite and implementation trivia ('The same PUT carrying both ids'). The reader must infer from the tool name plus the FULL REPLACE note that this edits an existing custom food's nutrition fields. It conveys the resource type and mutation nature indirectly, but a specific verb+resource statement is missing.
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 one concrete precondition and even names the sibling to check it with ('Requires a Garmin Connect+ subscription (check with has_connect_plus)') plus a repeat of the same requirement ('Needs Connect+'). However, it never distinguishes this from create_custom_food, delete_custom_food, or get_custom_foods, so an agent gets a gate but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 declare destructiveHint=true and readOnlyHint=false, yet the description goes further: it specifies replace-not-merge behavior, the validation contract on cycleDatesLists (non-empty, consecutive, within [startdate, enddate]), the concrete error type thrown on violation (GarminError), and the required user-confirmation step. That is substantive behavioral detail beyond what the structured fields 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?
A single dense sentence with the most important fact ('full replace, not a merge') front-loaded and no filler. There is a minor formatting glitch running the validation clause directly into 'IRREVERSIBLE' with no separator, which slightly hurts scanability but wastes no 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?
For a destructive, no-output-schema mutation tool this covers the essentials an agent needs before calling: irreversibility, validation rules, and the error it will raise. It omits any note on authentication/scope requirements and says nothing about the options parameter, so it is strong but not exhaustive.
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, and it does for the most important parameter: it explains the nested cycleDatesLists structure (groups of consecutive dates bounded by startdate/enddate) and the relationship between it and the two date parameters. The options.todayCalendarDate parameter remains undocumented in both schema and description, which keeps this below 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?
The description names the key semantic ('full replace, not a merge') which clarifies the operation is a whole-resource replacement rather than a patch, and combined with the name update_menstrual_calendar the agent can infer verb and resource. It does not, however, distinguish itself from nearby siblings such as update_menstrual_settings or update_menstrual_daily_log.
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 one explicit usage directive â 'confirm with the user before calling' â which is real guidance for an irreversible operation, but it never states when to use this tool versus update_menstrual_daily_log, update_menstrual_settings, or confirm_menstrual_period_start. Usage is implied by the calendar-replacement semantics rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Adds substantial behavior beyond the annotations: it discloses that the operation is a full-day replace (destroying unrelated existing fields), enumerates an error condition (no optional field -> GarminError), and documents the load-bearing undefined-vs-empty-string distinction for notes plus a discharge value constraint. This is exactly the destructive/auth/edge-case 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?
Dense but front-loaded with the highest-stakes fact (full-day replace) and every clause carries distinct information about errors or edge cases. The semicolon-packed formatting is slightly run-on, but 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 destructive nested-object mutation with no output schema and no annotations beyond the safety hints, the description covers the behavioral essentials an agent needs (replace semantics, required-field rule, notes/discharge edge cases, irreversibility). Remaining gaps are the undocumented option fields and the absence of any return-value mention.
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 documented; the eight nested option fields are bare). The description meaningfully compensates for two of them: it explains notes semantics and the NO_DISCHARGE exclusivity rule, both of which are impossible to infer from the schema. It does not cover flow, moods, symptoms, etc., so it does not 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?
The description never states plainly what the tool does (e.g. 'updates the menstrual daily log for a date'); it opens with behavioral policy ('full-day replace, not a merge'). The verb+resource is only inferable from the tool name, and there is no differentiation from siblings like update_menstrual_calendar or init_menstrual_cycle_setup. Adequate but the purpose itself is under-specified.
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 strong operational guidance: at least one optional field is required or it errors, the call is irreversible, and the agent should confirm with the user first. It does not, however, say when to prefer this over sibling write tools, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower, and the description still adds meaningful behavior: it discloses the exact multi-step GET-overlay-PUT flow, the validation failure (empty `settings` throws `GarminError`), and that the update is a merge rather than a replace. What it omits is the full set of POST/PUT side effects or what a partial overlay does to unmentioned 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?
It is a single dense sentence, but it is front-loaded with the critical validation constraint and every clause (validation, GET, overlay, PUT, id resolution) carries operational value. The run-on semicolon structure is slightly heavy but wastes 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?
For a nested-object mutation with no output schema and 0% schema coverage, the description supplies the mechanics an agent needs to call it correctly (merge behavior, required non-empty settings, endpoint flow, id handling). It leaves gaps on the allowable contents of `settings` and error cases beyond the empty check, but is otherwise 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?
With 0% schema coverage the description must carry parameter meaning, and it does: it explains that `settings` is overlaid onto existing userMenstrualCycleSettings (patch semantics for the free-form object), that it must be non-empty, and that options.userSettingsId feeds the `id` when resolvable. It adds real semantics beyond the bare schema, though the valid keys inside `settings` remain undocumented.
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 name says 'update_menstrual_settings' and the description reveals the operation overlays `settings` onto the current `userMenstrualCycleSettings`, so the resource and mutation are inferable. However, it never states a plain purpose sentence and does nothing to distinguish this from close siblings like update_menstrual_calendar, update_menstrual_daily_log, or init_menstrual_cycle_setup â it jumps straight into implementation mechanics.
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 several other menstrual-related mutators in the sibling list. No prerequisites, no exclusions, and no alternative routing are mentioned; the only condition given (non-empty `settings`) is a runtime validation rule, not usage guidance.
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.
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 write/open-world/non-destructive, and the description adds concrete behavior: multipart upload, plain endpoint path, no extension suffix, and no import headers. It still leaves auth requirements and response handling 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 definition is a single front-loaded sentence that earns its length by distinguishing the endpoint and header behavior from `importActivity`. It is dense with internal shorthand such as 'PLAIN' and 'load-bearing', which slightly harms 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 one-parameter upload tool with annotations covering safety and no output schema, the description supplies the key routing context and endpoint distinction. It could say more about authentication or expected import behavior, but the core call-completeness 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?
The single `filePath` parameter is fully documented in the schema, so the baseline is 3. The description adds no syntax or file-type guidance beyond the schema, which already covers `.fit`, `.gpx`, and `.tcx`.
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?
It names the operation as a multipart upload and pins the exact `/upload-service/upload` path, then distinguishes it from the `importActivity` sibling by the absence of import headers. Although it relies on the tool name for the activity resource, the verb and contrast are specific enough for selection.
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 frames this as the ordinary device-sync-shaped upload and contrasts it with `importActivity`'s spoofed-client import, so the agent has an alternative and condition. It does not spell out broader prerequisites, but the routing guidance is clear.
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.
add_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 190 tools
With 190 tools, several have overlapping or aliased purposes, such as get_stats/get_user_summary and get_stress_data/get_all_day_stress, which can confuse selection. Many descriptions are detailed, but the sheer breadth and near-duplicate activity/summary endpoints create unclear boundaries.
Tool names are overwhelmingly snake_case with predictable verb_noun patterns like get_, create_, update_, delete_, and set_. Minor deviations exist, including noun-only accessors like display_name and user_name, plus state-style names like has_connect_plus.
A 190-tool surface is far beyond a well-scoped MCP server and is extremely heavy for an agent to navigate. Even for a broad Garmin Connect API wrapper, this count creates severe selection and maintenance overhead.
The surface is remarkably complete across activities, wellness, nutrition, workouts, courses, gear, badges, challenges, menstrual data, devices, and calendar events. Minor gaps remain, such as no delete or update path for some read-only domains like hydration and goals.
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.
AI coach for Garmin: builds training plans and structured workouts, synced straight to your watch.
Connect your health, fitness, nutrition, sleep, and wearable data to your AI assistant.
