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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses the FTP resolution chain ('ftp_w, else from the activity's own record') and gives interpretive context for the decoupling metric. It stops short of stating failure modes, e.g. what happens when no FIT data exists for the activity.

Agents need to know what a tool does to the 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 one-line purpose followed by a scannable bullet list of outputs; each bullet names a distinct metric family. The enumeration is long but load-bearing for an agent deciding whether this tool answers its question.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 metric list effectively doubles as a return-value contract, and the FTP dependency and metric interpretation are covered. The missing piece is the data precondition: nothing says the activity's FIT file must first be fetched (e.g. via garmin_download_activity_fit), which an agent needs to know before calling.

Complex tools with many parameters or behaviors need more documentation. Simple 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; the description earns an extra point by explaining the ftp_w fallback behavior that the schema field text omits, telling the agent it can pass null/minimal input and still get power metrics when a cycling FTP is recorded.

Input schemas describe structure but not intent. Descriptions should explain 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 ('compute training metrics for one activity from its second-by-second FIT data') and then enumerates exactly which derived metrics are produced, which cleanly separates it from raw-data siblings like garmin_get_activity or garmin_get_activity_streams. Scope is further pinned down with 'works for multisport legs too'.

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

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

Implied usage is clear (compute per-activity training metrics), and conditional prerequisites are noted ('with an FTP, in power zones', 'needs FTP'). But it never states when to prefer this over garmin_training_summary, garmin_compare_activities, or garmin_get_activity_laps, nor what to do if the FIT file isn't downloaded yet.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds material behavior those annotations cannot express: deep=true downloads FIT files if needed, which is a network/IO side effect worth flagging and is disclosed. It also implicitly bounds input to 2–6. What's missing is any note on latency or cost of deep mode.

Agents need to know what a tool does to the 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 capability and metric list, then the deep-mode modifier, then a worked example — a logical order with no filler. The parenthetical defining efficiency factor is long but genuinely informative for interpreting results, so it earns its 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?

There is no output schema, so the description carries the burden of explaining return content — and it does, enumerating the compared metrics plus what deep mode adds (aerobic decoupling, HR zone time, best efforts). An agent has everything needed to choose and call the 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 67% and the one undocumented parameter (activity_ids) is compensated for by the description stating 'compare 2–6 activities', matching minItems=2/maxItems=6. deep is explained in both schema and prose. It adds value over the schema but does not, for example, clarify what activity_ids refer to or how to obtain 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?

States a specific verb ('compare') and resource (2–6 activities) and immediately enumerates exactly which fields come back (date, type, duration, distance, pace/speed, HR, power avg/NP, elevation, training effect/load, cadence, efficiency factor). This is clearly distinguishable from single-activity siblings like garmin_get_activity or garmin_analyze_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 a concrete usage scenario ('Am I getting fitter on my Tuesday interval run?' → list those runs, then compare them) and explains when to escalate to deep=true for FIT-based analysis. It does not explicitly contrast with garmin_analyze_activity or say when comparison is the wrong choice, so it falls short of the top band.

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

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

Annotations signal a non-read-only but idempotent, non-destructive write, and the description corroborates and enriches this: it discloses the exact output path (<data dir>/exports/<activity_id>.fit), that an existing export is preserved rather than overwritten, and that a multisport leg yields the whole multisport file. These are exactly the side effects and edge cases an agent needs and that annotations alone 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?

Three tight sentences, front-loaded with the action and return value, followed by the file-format guarantee and the overwrite/multisport edge cases. No sentence is redundant or restates the title.

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

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

With no output schema, the description still specifies what is returned (a path) and the exact filename convention, plus overwrite behavior and multisport handling. For a one-parameter export tool this covers everything needed to invoke it correctly and interpret 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 single parameter is fully documented in the schema (100% coverage) and even points to garmin_list_activities as its source, so the description need not explain it further. The description adds no additional semantics about activity_id, which is fine given the schema but keeps this at 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 verb and resource ('Save the original FIT file of an activity') plus the destination and return value, which cleanly separates it from parsed-data siblings like garmin_get_activity or garmin_get_activity_streams. An agent can tell immediately that this yields a raw file, not a JSON activity 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?

The description names concrete downstream consumers (Intervals.icu, Golden Cheetah, spreadsheet converters), giving a clear context for when to pick this over the parsed-activity siblings. It does not explicitly say when NOT to use it — e.g., steer toward garmin_get_activity_streams for programmatic analysis — so the routing is implied rather than complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered; the description adds real value by enumerating exactly what comes back (summary metrics, split summaries, structured workout, multisport parent/child IDs) — understanding that the payload can be large and nested. It omits any note on auth, rate limits, or behavior for invalid/expired activity IDs, which keeps it below 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 purpose and the usage chain are front-loaded, which is good, but the return-value sentence is a single very long parenthetical enumeration of ~20 metrics. That wall of field names is informative yet poorly structured — it would read far better as a short list or a note pointing to response_format='json' for the full 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?

There is no output schema, so the description must carry the return shape — and it does, itemizing metrics, splits, workout, and multisport IDs. Combined with the ID-source guidance and the response_format hint, an agent has everything needed to call this correctly on the first try.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds the provenance of activity_id ('from garmin_list_activities'), which tells the agent where the value must come from — genuine meaning beyond the schema's 'e.g. 12345678901'. It says nothing extra about response_format beyond what the enum already conveys.

Input schemas describe structure but not intent. Descriptions should explain 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 full details for one Garmin activity') with an explicit scoping constraint ('by ID'), which cleanly separates it from garmin_list_activities, garmin_get_activity_laps, and garmin_get_activity_streams. An agent can place this tool without opening any schema.

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

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

Gives the prerequisite explicitly ('Get IDs from garmin_list_activities') and a concrete chain example ('Tell me about yesterday's run' -> list, then call this with its id). It does not say when to prefer garmin_analyze_activity, garmin_get_activity_laps, or garmin_download_activity_fit instead, so the sibling differentiation stops short of full routing guidance.

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

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

Annotations already declare it read-only, idempotent and non-destructive, so the description adds value by disclosing the network behavior: the FIT file is downloaded on first use and then cached. It also discloses what data comes only 'when the device recorded them', which sets correct expectations about missing fields — a 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?

Front-loaded with the core purpose, then a dense field inventory, then usage and caching notes. The return-field sentence is long but each clause maps to real output content rather than filler.

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

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

There is no output schema, so the description carries the full burden of describing return values — and it does so thoroughly, covering lap fields, swim-specific fields, multisport sessions, and FIT-only metrics, plus the caching behavior. An agent has enough to call it correctly and interpret 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?

Schema description coverage is 100% and every parameter (activity_id, lap_offset, response_format) is documented in-schema, including the enum. The description adds no syntax or overflow guidance (e.g. when to use lap_offset on very long activities), 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?

States a specific verb and resource ('Get the laps... of one activity, from its original FIT file') and enumerates the returned granularity, so an agent knows this is the lap/session-level view rather than the activity overview. No sibling is named, so routing between it and garmin_get_activity or garmin_get_activity_streams 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?

'Use it for interval sessions, splits and pacing' gives concrete use conditions, and 'For a multisport leg ID, returns only that leg's laps' clarifies a scope boundary. It lacks explicit when-not guidance or a named alternative for activity-level summaries.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, but the description layers on substantial extra behavior: automatic coarsening for long activities, omission of zeros in cadence averages, and a privacy warning that 'position' reveals where the user was. This is exactly the kind of context annotations cannot convey.

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

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

Front-loaded with the core summary, then organized by returns, defaults, zooming, and the position/dev_fields caveats. Slightly long and repeats a few schema defaults (10 s, 500 points), but every block carries actionable information, so it earns most of its length.

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

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

No output schema exists, so the description carries the burden of explaining returns; it does so clearly (per-field min/avg/max plus columnar t-series with one array per field). The only minor gap is not stating error conditions for an activity lacking requested fields (e.g., what happens if power is absent), but overall 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?

Schema coverage is 100%, so baseline would be 3, but the description adds genuine meaning: units for every field (bpm, W, m/s, °C, etc.), the semantics of performance_condition (-20..+20), cumulativeness of distance, dev_* field lookup via available_fields, and how resolution_s/max_points interact. This goes well beyond the schema's one-line 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?

States a specific verb and resource ('Get second-by-second data from one activity's FIT file') and immediately adds the key constraint ('downsampled to fit in context'). It distinguishes itself from siblings by referencing garmin_get_activity_laps for finding window offsets, so an agent can route here vs. a laps or analyze tool without opening schemas.

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

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

Explains default behavior (which fields, 10s resolution, 500 points), how to zoom ('start_s/end_s and a smaller resolution_s'), and where to get offsets from garmin_get_activity_laps. It also gives an explicit guardrail: only request 'position' when the user asks for location or route analysis.

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

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

Annotations already cover the safety profile, and the description adds genuinely new behavior: it reads a local cache (implying possible staleness), only days with recorded weigh-ins appear, the default window is 365 days, and the response includes period change plus an optional weight goal. A hint about needing garmin_sync first would push it higher.

Agents need to know what a tool does to the 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: what comes back, the recording caveat, and the default window. Field list is front-loaded and 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?

No output schema exists, so the description does its part by enumerating return fields, units, provenance, period change, and the goal. The main gap is not stating how cached data relates to freshness/sync, which matters for a cache-backed 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%, so the baseline is 3, but the description adds the default 365-day window that the start_date field does not document. That is real meaning beyond the schema, though response_format and end_date behavior are left 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?

States a specific verb and resource ('Get weigh-ins from the local cache') and enumerates the returned metrics, so an agent can tell it apart from garmin_get_daily_health or garmin_get_profile. It does not explicitly name a sibling it differs from, which holds it back from 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?

'From the local cache' and 'Only days with a weigh-in appear. Defaults to the last 365 days' imply when the data is available, but the description never says when to choose this over adjacent tools (daily health, profile) or whether a sync is needed first. 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.

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: data comes from a local cache covering all history, today's values are partial, and a hard 92-day row limit exists. It does not say what happens when the cache is empty or stale, which matters given a garmin_sync sibling.

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

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

Front-loaded purpose sentence, then a compact field inventory, then aggregation semantics, limits, and examples in a clear progression. The dense metric list is information the agent needs to answer 'what can I ask this for', so nothing reads as filler.

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

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

There is no output schema, and the description compensates by enumerating the returned metrics and the aggregation shape in detail. The one gap is operational: it says data comes from the local cache but never indicates that a sync may be required first or how to detect an empty cache, which is relevant given the garmin_sync and garmin_sync_status 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?

With 75% schema coverage the baseline is 3, and the description earns above that: group_by has no schema description yet the text explains week is Monday-based and what week/month aggregation actually computes (averages per day, min/max for HR and stress, totals for steps and intensity minutes). start_date/end_date semantics (default last 14 days, today partial) and the response_format tradeoff are also covered.

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

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

The opening sentence gives a specific verb and resource (day-by-day wellness and recovery data) and enumerates the exact metrics returned, so an agent can tell this is the rolled-up daily wellness view rather than a single-metric tool. It does not explicitly contrast with overlapping siblings such as garmin_get_sleep, garmin_get_hrv, or garmin_get_intraday, so the boundary is inferable but not stated.

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

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

Usage is well scaffolded: the 14-day default, the 92-day cap on daily rows, and the rule to switch to group_by="week" or "month" for longer windows are all stated, plus two worked examples mapping a user question to parameters. What is missing is any explicit exclusion (e.g. when to prefer garmin_get_intraday for same-day detail or garmin_get_sleep for a single night).

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

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

Beyond the annotations, the description discloses that data comes from a local cache, that 5-minute readings may be fetched from Garmin when older than the synced detail window, the default and maximum ranges, and the compatible-watch requirement. This is rich behavioral context for a read-only 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 description is front-loaded with the core purpose and return values, then proceeds to parameter effects and constraints. Every sentence adds useful information without redundancy.

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

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

There is no output schema, but the description thoroughly explains the returned HRV metrics and the optional 5-minute readings. For a read-only cache-backed tool with clear annotations, nothing essential is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining the readings_date effect, the 28-night default, and the 366-night cap, though it does not discuss response_format.

Input schemas describe structure but not intent. Descriptions should explain 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: get nightly HRV from the local cache. It enumerates exactly what is returned (last-night average, highest 5-minute value, 7-day average, baseline range, and Garmin status), making it distinguishable from broader health/recovery 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?

Usage context is clear: default date range, maximum per call, how readings_date changes behavior, and the hardware prerequisite. It does not explicitly name alternative siblings such as recovery trends, but the conditions for correct use are well explained.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantive behavior on top: on-demand remote fetching for days older than 150, degraded data availability because Garmin retains intraday HR/HRV for only ~4-5 months, and the fallback that ancient days may return only the day summary. Device prerequisites for HRV and SpO2 are also surfaced.

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

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

Purpose and metric list are front-loaded in the first sentence, then return shape, then availability caveats, then defaults — a logical order. It is dense but nearly every clause carries operational information; the defaults sentence slightly duplicates schema defaults.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 itself and does so precisely: per-metric min/avg/max, day summary values such as resting HR and Body Battery charged/drained, and a columnar series of local HH:MM timestamps plus values. Together with the retention caveats, an agent knows both what it will get and how complete it will be.

Complex tools with many parameters or behaviors need more documentation. Simple 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 75%, so the baseline is 3, and the description earns an increment by giving units and ranges for each metric value (bpm, Body Battery 0-100, HRV in ms, SpO2 in %) plus restating the effective defaults for date, metrics and interval. Only response_format is left entirely to the schema, so it stops short of 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 first sentence gives a specific verb (get), resource (one day's health data) and a clear differentiator (averaged into intervals, listing the four metrics). The intraday/interval framing implicitly separates it from summary-style siblings like garmin_get_daily_health and garmin_get_hrv, but no sibling is named, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 unusually clear: it states defaults (today, all four metrics, 15-minute intervals), that the last 150 days are pre-synced while older days trigger an on-demand Garmin fetch, and that HRV/SpO2 require a compatible watch with pulse ox enabled. What's missing is explicit routing — it never says when to prefer garmin_get_daily_health or garmin_get_hrv instead.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is free. The description adds real behavioral context beyond that: data is fetched on demand and cached (implying possible latency and staleness) and the 7-day default / 31-day cap. It doesn't explain cache refresh behavior or failure modes, 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 tight sentences/short paragraphs: the first front-loads what is returned, the second carries fetch/caching and window limits. No filler, every clause 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?

No output schema exists, so the description must carry the return payload, and it does list the metric groups and hydration units. It lacks detail on the shape of meal entries or how goals are represented, so an agent knows what it gets only at a coarse level.

Complex tools with many parameters or behaviors need more documentation. Simple 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 start_date default ('last 7 days') that the schema lacks and the 31-day span limit, which is genuinely new constraint information an agent needs to avoid empty or rejected calls.

Input schemas describe structure but not intent. Descriptions should explain 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 food logged in Garmin Connect (or linked apps like MyFitnessPal) per day, enumerating the returned metrics (calories, carbs, protein, fat vs goals, meals) plus hydration in ml. No sibling tool covers nutrition, and the enumerations make the scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 operating window ('defaults to the last 7 days, at most 31 per call'), which tells an agent how to size requests, and the data-source note implies when this tool applies versus activity/sleep/health siblings. It stops short of explicitly naming an alternative or a when-not condition, but no sibling overlaps on this data.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that by spelling out what comes back (units and locale, time zone, preferred training days, zone floors with the max HR/LTHR/resting HR used, latest fitness age). It does not mention cost of the network call or how markdown vs json differ in completeness.

Agents need to know what a tool does to the 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 blocks, front-loaded with what is returned and followed by the decision rule. Every sentence carries information an agent needs; nothing is filler.

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

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

With no output schema, the description correctly carries the return-value burden and does so in useful detail, plus the prerequisite usage rule. Minor gap: it does not tell the agent that returning json preserves the full structured zone/HR data that markdown may compress.

Complex tools with many parameters or behaviors need more documentation. 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 optional parameter and schema description coverage is 100%, with the enum values fully documented in-schema, so the baseline of 3 applies. The description never mentions response_format or when to prefer json for structured zone data, adding no 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?

Names a specific verb and resource ('Get the user's Garmin profile settings') and enumerates the exact scope: HR zones per sport and fitness age. That enumerated scope makes it unmistakable against siblings like garmin_get_daily_health or garmin_get_intraday, which cover time-series health data rather than configuration/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?

Gives two concrete activation conditions: 'before interpreting heart rate data (to know the user's zones)' and 'when the user asks about their zones, max HR, lactate threshold or fitness age.' Clear and actionable, but no explicit exclusions or named alternative tools for overlapping questions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds that data comes from a local cache (implying possible staleness absent a sync), the per-call cap of 92 nights, and that JSON mode expands the payload with score components. It does not say what happens when the cache is empty or not yet synced.

Agents need to know what a tool does to the 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 paragraphs, front-loaded with the verb and resource, then the return contents, then the date and volume rules. The long field list earns its place because there is no output schema to describe the payload.

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

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

With no output schema, the description correctly compensates by enumerating return fields and JSON extras, and it covers date semantics and volume limits. The one gap is cache-related behavior — what is returned when a night has not been synced — which matters given 'local cache' and the existence of garmin_sync.

Complex tools with many parameters or behaviors need more documentation. Simple 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; the description goes beyond it by explaining the date-semantics convention (a night belongs to the wake-up date) and the 92-nights-per-call limit that constrains start_date/end_date. It also clarifies that response_format switches payload richness, adding meaning beyond the enum labels.

Input schemas describe structure but not intent. Descriptions should explain 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 nightly sleep from the local cache') and then enumerates exactly what data comes back (bed/wake time, sleep stages, score, respiration, stress). No sibling in the list covers sleep, and the field enumeration makes the scope unmistakable.

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

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

'A night belongs to the date you woke up' plus the default window (last 14 nights) and the 92-night ceiling give the agent concrete calling context. It stops short of naming when to prefer a sibling (e.g., garmin_get_daily_health or garmin_get_hrv) for overlapping wellness questions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, lowering the bar. The description still adds genuine context: 'Fetched live from Garmin' (reinforces openWorld and warns of network dependence) and, more importantly, that it returns a clear 'not tracked' message when cycle tracking isn't set up — an empty-state behavior the annotations cannot express.

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

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

Front-loaded with the resource and payload, then the empty-state caveat, then the default date. All sentences earn their place; the only slight redundancy is 'Defaults to today', which the schema also states.

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

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

There is no output schema, so the description carries the return-value burden — and it discharges it by enumerating every field the call yields plus the not-tracked fallback. With two well-documented parameters and a safety profile already in annotations, an agent has everything needed to call 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 100% and the 'date' parameter already documents its default and pattern; the description's 'Defaults to today' and 'day view' merely restate that. The response_format enum is untouched in the description, so it adds essentially nothing beyond the structured schema. Baseline 3 is correct.

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

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

States a specific verb (Get) and a unique resource (menstrual cycle tracking), then enumerates exactly the fields returned: cycle day, phase, period/cycle length, predicted next cycle, fertile window, ovulation date, symptoms and notes. No sibling tool covers this domain, so it is trivially distinguishable from garmin_get_daily_health or garmin_get_body_composition.

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

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

The '(day view)' qualifier and 'Defaults to today' give the agent clear context for when this is the right call: a single date's cycle state. It stops short of naming alternatives or an explicit when-not, but no sibling overlaps enough to need that routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the data comes from a local cache that auto-refreshes when older than an hour, and results are paged with a total match count. It stops short of describing pagination semantics for the total (whether total reflects filters), 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?

The core capability and scope are front-loaded in the first sentence, and the examples and sibling pointer are clearly delineated. It is somewhat long, but each element (return fields, examples, cache note, sibling routing) carries distinct 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 14-parameter read tool with no output schema, the description lists the returned summary fields and states the JSON/markdown response distinction, plus the paging model. Combined with 100% schema coverage, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value: the examples demonstrate how activity_type, start_date, sort_by, and include_multisport_legs combine for real intents, and they clarify the parent-type expansion and the 'never double counts' behavior of multisport legs in a way the schema terse descriptions do not.

Input schemas describe structure but not intent. Descriptions should explain 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 (search/list) and resource (Garmin activities) with scope ('all history, from the local cache') and ordering ('newest first by default'). It also names the sibling garmin_get_activity as the tool for a single activity's full details, so an agent can distinguish the two 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?

Provides four concrete natural-language query examples mapped to specific parameter combinations, covering filtering by type/date, sorting, and multisport legs. It explicitly routes detail-seeking calls to garmin_get_activity and notes the cache-refresh condition that governs data freshness.

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

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

The annotations already declare readOnlyHint, idempotentHint, closed-world, and non-destructive behavior, and the description adds important operational constraints: a single SELECT/WITH statement, max_rows default 200, and a 10-second timeout. It also explains date formats, units, SQLite dialect support, and how multisport records are structured, which materially helps correct invocation.

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

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

Despite its length, the description is front-loaded and well-structured: purpose first, then view definitions, raw JSON access, date/unit conventions, SQL dialect notes, rules, and an example. The column lists and example earn their place because they directly enable correct query construction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complex SQL-query tool with no output schema and low schema description coverage, so the description must carry substantial context. It does so by documenting available views and columns, raw JSON escape hatches, date and unit semantics, SQL dialect features, execution limits, and an example query, leaving little ambiguity for an agent to call it correctly.

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

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

Schema description coverage is only 33%, so the description carries most of the parameter burden. It explains the SQL parameter extensively and clarifies max_rows behavior and default, but it does not mention the response_format parameter or distinguish its json and markdown options.

Input schemas describe structure but not intent. Descriptions should explain 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: run one read-only SQLite query against the local Garmin cache. It also distinguishes this tool from its siblings by positioning it for analyses the other tools don't cover, such as custom aggregations, correlations, records, and cross-year comparisons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear usage context: use it for analyses not covered by other tools, prefer the views first, and use raw JSON only for fields not in the views. It does not name specific sibling tools as alternatives, which keeps it just below fully explicit routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real value beyond them: the response composition (status, flagged days, weekly averages, correlations with strength), the 180-day ceiling, and an honest statistical caveat about causation and noise. It stops short of describing pagination or how the 180-day limit is enforced when exceeded.

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

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

Front-loaded with the core purpose in the first clause, then return contents, caveats, and limits in a logical order. Two compact paragraphs with no filler; only the causation caveat slightly overlaps the noise warning.

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

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

No output schema exists, so the description carries the full burden of describing returns — and it does so concretely (status comparators, flagged days, weekly averages, correlation pairs). For a read-only analytics tool with a fully documented 3-parameter schema, 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?

Schema coverage is 100%, so a baseline 3 applies, but the description genuinely adds meaning the schema lacks: the default range (last 8 weeks) and the maximum window (180 days), which govern how start_date/end_date should be chosen. The response_format enum is fully documented in the schema and needs no prose.

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

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

Specific verb+resource: 'Relate training load to recovery markers, day by day' with the exact metrics enumerated (resting HR, HRV, sleep score/duration, Body Battery, stress). The rolling-baseline and correlation framing clearly separates it from point-query siblings like garmin_get_hrv, garmin_get_sleep, and garmin_get_daily_health without needing to name 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?

Gives clear operating context — defaults to the last 8 weeks, hard cap of 180 days, and warns that 'short periods give noisy results', which implicitly steers the agent toward longer windows. It does not explicitly say when to prefer point-query siblings over this trend view, so no exclusion guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description adds the substantive behavior — this is a diagnostic that returns a configuration report rather than Garmin data, and it names the specific fields surfaced. With no output schema, spelling out the report contents is exactly the value the description should add.

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

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

Front-loaded with the core action, followed by a compact inventory of reported fields, then the usage rule. Three short paragraphs, no filler, and each element adds information an agent would otherwise have to guess.

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

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

Covers purpose, return contents, and invocation triggers for a zero-required-param diagnostic, which is nearly everything needed. The one omission is failure semantics — whether a broken connection raises an error or is reported in the output — which matters for a tool whose whole job is checking health.

Complex tools with many parameters or behaviors need more documentation. 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 optional parameter, response_format, and the schema documents it at 100% coverage including the markdown/json enum and default. The description says nothing about it, but the schema already does the work, 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 and resource: verify the Garmin Personal API connection and report its configuration, then enumerates exactly what is reported (key source, token/expiry, key expiry, time zone, server version). That is far more concrete than the sibling getters. It does not explicitly distinguish itself from garmin_sync_status, which is the one sibling an agent could plausibly 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?

Gives two explicit trigger conditions: call it first after any garmin_* tool fails with an auth error, or when the user asks whether the connection is set up. That is clear when-to-use guidance with a real diagnostic role. It stops short of a when-not-to-use clause or naming garmin_sync_status as the alternative for sync-state questions.

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

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

Goes well beyond the annotations: it discloses the fire-and-forget async behavior, the cache-side effect of mode='full' ('forget what's cached'), and the throughput cost of fit_files (~2 activities/s, one request per activity). Annotations only carry the safety profile (readOnly=false, idempotent=true); the description supplies the operational semantics they cannot express.

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

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

Front-loads the async/cache contract, then uses a tight bullet list for the when-to-use cases and a short paragraph for domains. Slightly long, but every sentence (including the fit_files cost note) carries information an agent needs.

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

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

With no output schema, the description correctly explains the return contract (returns immediately, no result payload) and routes the agent to garmin_sync_status for results. Combined with 100% param coverage and annotations, nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value by giving scenario-anchored examples ('from="2019-01-01"', 'mode="full" after editing many activities') and by spelling out the default domain set. It stops short of listing every domain's effect, which the schema enum already covers.

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

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

Specific verb + resource + destination: 'Start downloading Garmin data into the local cache.' It also states the asynchronous contract up front ('Runs in the background and returns immediately'), which distinguishes it from every read-only getter sibling.

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

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

Explicitly says 'You rarely need this' because other tools sync automatically, then enumerates the three concrete cases where it is needed (fresh data, extending history, full re-download). It also names garmin_sync_status as the progress-tracking alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real content beyond that: it enumerates headers such as per-domain date range, day counts, all-history flags and last successful sync, and mentions error reporting. It stops short of saying how partial or failed syncs are represented.

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

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

Two short sentences, front-loaded with what is shown, followed by a compact enumeration of returns. Every clause carries information, though the 'Returns:' block is a dense run-on that could be structured more crisply.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 return values, and it does so across sync-level and per-domain detail. It is only slightly incomplete in omitting the response_format choice and how a failed or never-run sync is reported.

Complex tools with many parameters or behaviors need more documentation. Simple 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 optional response_format enum, so the schema already documents the only parameter fully. The description adds nothing about format selection, 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?

States a specific verb and resource: it shows the contents of the local Garmin cache plus the progress of the current or last sync. That is clear enough to act on, but the description never distinguishes this from the close sibling garmin_status or from garmin_sync, which an agent could plausibly pick instead.

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

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

Usage is only implied: an agent can infer this is the tool to call before or after garmin_sync to check coverage and errors, but the description never says when to use it, when not to, or which sibling it replaces. No prerequisites 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it defines intensity zones (low = HR 1–2, moderate = 3, high = 4–5), explains CTL/ATL/TSB/ACWR semantics with the ~1.5 risk threshold, and discloses how missing Garmin load is estimated (Banister TRIMP scaled to the user's own activities) plus that the response reports the estimated share.

Agents need to know what a tool does to the 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 deliverable is front-loaded in the first sentence and the remaining paragraphs cover estimation caveats and defaults, each earning its place. It is on the longer side and the zone/ACWR detail is dense, but not padded with filler.

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

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

With no output schema, the description must convey what comes back, and it does: metrics per period, intensity distribution with a pattern classification, and the load trend block. Defaults, filtering, multisport/walking handling, and the estimation caveat cover everything needed to call it correctly.

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

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

Schema coverage is 80%, so the schema carries most parameter meaning and baseline is 3. The description adds real value on top: it clarifies the sport filter accepts either a parent type or an activity type (e.g. virtual_ride), and that week/month grouping defaults to week over the last 12 weeks.

Input schemas describe structure but not intent. Descriptions should explain 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 (summarize) and a precisely scoped resource: per-week/per-month aggregates of sessions, hours, distance, elevation, load, intensity distribution and load trend. The aggregation scope makes it immediately distinguishable from per-activity siblings like garmin_get_activity or garmin_list_activities without opening those schemas.

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

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

It gives concrete operating context: defaults to the last 12 weeks grouped by week, and filtering is done via sport (with examples such as running, cycling, or a type like virtual_ride). It does not state when to prefer garmin_query, garmin_recovery_trends, or per-activity tools instead, so there are no explicit alternatives or exclusions.

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