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

Goes well beyond the annotations by disclosing server-side dedup semantics: an identical measurement is kept once even though the write is not idempotent, while a differing reading at the same timestamp becomes a second weigh-in. It also explains that Garmin reports everything as 'processed' and that corrections require a delete-first flow — critical context for a non-idempotent 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?

Four tight sentences, front-loaded with the core purpose, then alternatives, then the dedup/correction rules. The dedup sentence is dense but every sentence earns its place; 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 13-parameter mutation with an output schema and annotation coverage for safety, the description supplies the missing operational nuance: alternative selection, dedup behavior, and the delete-to-correct workflow. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so every field is already documented in the schema, and the description's field list (fat, water, muscle, bone, BMI) merely summarizes a few of them. No format, unit, or constraint guidance is added 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?

Opens with a specific verb+resource ('Record a weigh-in with body composition') and enumerates the fields captured. It explicitly distinguishes itself from the sibling add_weigh_in ('A plain add_weigh_in carries weight only'), so an agent can route between 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?

States exactly when to pick this over the alternative (full smart-scale reading vs weight-only) and names the sibling. It also lays out the correction workflow: delete the wrong entry first, finding its id via list_weigh_ins.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description adds crucial timestamp interpretation rules (local vs offset) and the fact that adding another doesn't correct but creates a new entry, which is not in 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?

Four sentences, each front-loaded with purpose, alternatives, timestamp behavior, and correction workflow. No redundancy; every sentence adds unique 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?

Complete for a simple mutation tool: covers purpose, alternatives, timestamp semantics, and correction path. Output schema exists, so return values needn't be described.

Complex tools with many parameters or behaviors need more documentation. Simple 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 description adds timezone handling semantics for the timestamp parameter beyond its schema description, clarifying how offsets affect filing. This is valuable but only expands one of three parameters, so not a full 5.

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

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

States a specific verb 'Record' and resource 'one body weight' with platform and scope, and distinguishes from sibling add_body_composition by specifying 'no body composition'. This lets an agent pick the right 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?

Explicitly directs to add_body_composition for smart scale readings with fat/water/muscle/bone, and advises using delete_weigh_in for corrections rather than adding another. Provides clear when-to-use and 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.

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description still adds real value: the failure mode where scheduling fails but the error carries the new workout's id, and the reply carrying schedule_id. It does not mention auth requirements or rate limits, but the disclosed side-effect semantics go 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?

Purpose is front-loaded and the paragraph stays on topic; step structure, targets, swim rules and scheduling each get one sentence. The target enumeration partly restates schema field names, which is the only mild redundancy.

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

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

Given an output schema exists, the description need not explain return values, and it covers everything else an agent needs: sport-to-target mapping, step termination modes, repeat support, swim specifics, and the scheduling side effect. Nothing material for correct invocation 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 100%, so the baseline is 3; the description earns above that by adding cross-field semantics the schema does not encode — which sports accept which target types (pace/speed/HR/power/cadence for runs and rides, stroke/equipment/pool length for swims) and the constraint that swim distances must be whole lengths.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Create a run, ride or pool swim workout") and immediately names the sibling it is not ("For strength workouts use create_strength_workout"). An agent can distinguish it from create_strength_workout and the generic create_workout_from_dto 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?

Explicit routing rule for strength workouts, plus a clear signal for when to pass schedule_date and what that implies. It does not address other plausible siblings (schedule_workout, create_workout_from_dto, list_workouts), so it is clear context without full exclusions.

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 only cover the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds non-obvious behavior: without schedule_date it is saved but not scheduled, with it the schedule happens in the same call, the reply carries schedule_id, and — critically — a scheduling failure leaves the workout intact with an id the caller should reuse rather than recreating. That failure-recovery guidance is exactly what 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 paragraphs, front-loaded with purpose, then naming/routing, then scheduling semantics and failure handling. Every sentence carries distinct, actionable information with 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?

An output schema exists, so return values need not be enumerated, yet the description still surfaces the one return detail that matters operationally (schedule_id and the id returned on partial failure). Combined with sibling routing and naming rules, nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic meaning beyond the schema by tying exercise naming to find_exercise's category/exercise keys and by clarifying the save-vs-schedule dual nature of schedule_date. It adds real value, though it does not describe every field (e.g. weight_kg, reps/sets defaults).

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

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

States a specific verb and resource ('Create a strength workout to follow later') plus the composite structure ('Each exercise becomes a block of sets with a rest between them'). It explicitly names the siblings it is not (create_endurance_workout, log_strength_session), so an agent can route 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 explicit when-to-use-this and when-to-use-alternatives: runs/rides/swims go to create_endurance_workout, already-completed sessions go to log_strength_session. It also prescribes find_exercise as the source of valid exercise names and warns that unknown names are rejected.

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=false, openWorld=true, idempotent=false and destructive=false, so the write/network profile is covered. The description adds genuinely non-redundant behavior: the payload is 'Sent to Garmin as given' and exercise names are not validated against the catalogue, which tells the agent malformed input will not be caught locally.

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

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

Two short sentences, no filler. The disambiguating constraint and the preferred-alternative routing are both front-loaded before any 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description supplies the two things an agent actually needs here — that the DTO is unvalidated and that a builder is usually preferable — though it says nothing about auth prerequisites or failure behavior for malformed DTOs.

Complex tools with many parameters or behaviors need more documentation. 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 already documents it at 100% coverage with additionalProperties=true, so the baseline is 3. The description goes beyond that by explaining what happens to the DTO once supplied (pass-through, no catalogue validation), which changes how carefully an agent must construct it.

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

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

States a specific verb and resource ('Create a workout') and immediately scopes it as a raw-DTO path 'for shapes the builder omits'. The second sentence names the sibling create_strength_workout as the preferred route, so an agent can separate this from the builder tools without reading either schema.

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

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

Explicitly says to prefer create_strength_workout 'where it can express it', which is a real routing rule rather than an implied one. It does not mention create_endurance_workout or any other builder sibling, so coverage of alternatives is partial 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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still adds genuine value beyond them: the deletion is permanent with 'no undo', and a copy already shared to Strava or another connected app stays there — a non-obvious side effect an agent could otherwise miss.

Agents need to know what a tool does to the 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 short sentences, front-loaded with the irreversible action, then the usage condition, then the alternatives and the external-copy caveat. Every sentence carries distinct information 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?

An output schema exists so return values need not be explained. For a one-parameter destructive tool, the description covers purpose, condition, alternatives, irreversibility, and external side effects — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single activity_id parameter is fully described in the schema as 'Garmin's activity id, from list_activities'. The description confirms single-activity scope but adds no syntax or format detail 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?

States a specific verb and resource — 'Permanently delete one activity from Garmin Connect' — with the scope 'one activity' made explicit. It is readily distinguishable from siblings like update_activity or edit_activity_sets.

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

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

Gives an explicit when-to-use condition ('an activity that should not exist, such as a session logged twice') and names the alternatives for adjacent needs: edit_activity_sets for sets and update_activity for renaming. It also clarifies both alternatives keep the activity, sharpening the boundary against this destructive tool.

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 destructiveHint=true, but the description adds material consequences beyond that: deletion is permanent, nothing restores it, and day summaries and weight trends change. This is useful behavioral context for a destructive 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?

Three sentences, front-loaded with the core action and identifiers. Each sentence earns its place by adding usage guidance or consequence information, with no filler.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the remaining operational context: identifier source, correct usage, irreversibility, and downstream effects. Nothing essential 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 description coverage is 100%, so sample_pk and day are already documented in the schema. The description repeats that sample_pk comes from list_weigh_ins and that the pair identifies the weigh-in, but adds no new format or constraint meaning beyond the schema 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: permanently delete one weigh-in. It also names the exact identifiers, sample_pk and day, and ties them to list_weigh_ins, so the agent can distinguish it from add_weigh_in, add_body_composition, and list_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?

Explicitly says when to use it: to remove a wrong or duplicate reading. It also gives the corrective workflow, directing the agent to delete and then use add_weigh_in or add_body_composition, which is a clear alternative path.

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 establish destructiveHint=true and idempotentHint=true, but the description adds non-obvious behavior: deletion is permanent and unrecoverable, and the recovery path is to call get_workout first because its raw field holds the full definition. That recovery guidance is not derivable 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?

Front-loads the destructive action and its scope, then spends the remaining sentences on routing and recovery. Every sentence earns its place with 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?

An output schema exists so return values need no explanation, and the description handles the hard parts: disambiguating among many delete/unschedule/get siblings and warning about irreversibility. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single workout_id parameter is already documented in the schema (sourced from list_workouts or list_scheduled_workouts). The description 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?

States a specific verb+resource+scope: permanently delete a saved workout (a plan) from the account's workout library. The parenthetical clarifies the domain object and cleanly separates it from sibling resources like activities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 two alternatives and the conditions that select them: unschedule_workout to remove from a date while keeping the workout, and delete_activity for completed sessions. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 declare destructiveHint=true and idempotentHint=false, and the description explains the underlying mechanic the annotation only implies: deleting renumbers subsequent sets, so repeating a delete hits a different set. It also discloses the batch numbering semantics ('within one call, every number means the set as numbered before it') and the return contract. This is materially more than the annotations provide.

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

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

The core action and the set-number addressing model are front-loaded, and each remaining sentence carries a distinct rule. It is dense and slightly long for a three-parameter tool, but no sentence is filler.

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

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

For a non-idempotent batch mutation with an output schema, the description covers the hazards (renumbering, batch-relative numbering), the naming convention, and the sibling escape hatch. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond field docs: how set numbers are interpreted within a single batched call, that unspecified fields stay unchanged, and that the exercise must be the category/exercise_name pair. It stops short of documenting individual fields, which the schema already does.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Correct a strength activity's sets: exercise, reps or weight, or delete sets') and explicitly separates itself from update_activity, which handles renames and descriptions. An agent can distinguish it from sibling mutators 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?

Explicit routing instructions: name exercises via find_exercise's category/exercise_name, read set numbers from get_activity_sets, use update_activity for renames/descriptions. The 'use the numbers this returns for any further edit' rule is actionable when-to 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 (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower, but the description adds real behavior: matching is by word starts, plurals and gym slang (rdl, ohp, skull crusher) are understood, and results come from a bundled catalogue with no Garmin request or login. That last point is genuine operational context an agent would otherwise have to infer.

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

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

Front-loaded with what the tool does, then routing, then matching semantics, then the offline data source. Every sentence carries distinct information; none is 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?

An output schema exists so return values need no explanation, and the description covers routing, matching behavior, and the no-login data source. 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%, so the baseline is 3, but the description meaningfully deepens the query parameter by explaining the matching algorithm ('lat pull' finds 'Lat Pull-down') and alias handling. It adds semantics the schema's terse examples do not convey.

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

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

States a specific verb (Search) and resource (Garmin's strength exercise catalogue), plus the ordering (best match first) and the result shape (display name, category, exercise variant). It explicitly distinguishes itself from match_exercise, which is the nearest 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?

Names the exact downstream tools it precedes (create_strength_workout, log_strength_session, edit_activity_sets) and the condition that selects it ('whenever the Garmin pair is not known'), including why those tools reject other names. It also names the alternative (match_exercise) with the condition that selects it ('exactly one exercise or nothing').

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?

Adds important behavior beyond the annotations: it reports token existence and age without calling Garmin, so revoked tokens still appear authenticated. This is a critical limitation that an agent cannot infer from the schema or read-only/idempotent hints alone.

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

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

The description is front-loaded with the core purpose, then adds the failure-first guidance and the important revocation caveat. Every sentence earns its place and there is no redundant 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?

Given the zero-parameter schema, output schema availability, and simple status-check purpose, the description is complete. It explains both the normal use case and the key limitation about revoked tokens, so an agent has what it needs to invoke it correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description appropriately focuses on behavior rather than inventing parameter details.

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

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

States a specific verb and resource: checking whether the server holds a Garmin login. It clearly distinguishes itself as a status/auth check rather than a data retrieval tool, and the sibling list contains no tool with the same purpose.

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

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

Gives clear usage context: 'Call this first if anything fails.' It also explains why a positive status may be misleading and that other calls reveal revocation. It does not explicitly state when not to use it, but the guidance is strong enough for correct selection.

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 safety is covered; the description adds value by disclosing the return shape (type, UTC and local wall clock start time, duration, distance HR, calories, raw record) and by stating a deliberate scope limitation. It does not mention auth requirements or rate limits, but it adds real behavioral context beyond the annotations.

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

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

Front-loaded with the primary action and return contents, then the id provenance, then the scope exclusion. Two tight sentences with no filler; every clause carries routing or content 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes the key fields and clearly marks the boundary against the per-set and per-lap tools. For a single-required-param read tool in a large sibling set, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the schema already documents activity_id; the description adds meaning by listing the three tools that produce valid ids (list_activities, recent_strength_sessions, week_summary), which is more than the schema's single mention of list_activities. Above the baseline 3 because the provenance guidance is genuinely additive.

Input schemas describe structure but not intent. Descriptions should explain 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 (return one) and resource (activity by id) and enumerates the fields returned, then explicitly distinguishes itself from get_activity_sets and get_activity_laps by naming the scope it omits (per-set, per-lap). An agent can select this over its close siblings without opening either schema.

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

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

Gives explicit routing: the id comes from list_activities, recent_strength_sessions or week_summary, and it names concrete alternatives with the condition that selects them (get_activity_sets for strength exercises/reps/weights, get_activity_laps for run/ride/swim laps and pacing). Both when-to-use and when-to-use-something-else are covered.

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 readOnly/idempotent/openWorld, so the bar is lower, but the description adds a real cost disclosure: "Two Garmin requests." It also previews the shape of the summary (avg pace, halves comparison, fastest/slowest), which is behavioral context beyond the hints, though it does not discuss pagination 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?

Three short sentences, front-loaded with the return payload, then routing, then cost. Nothing redundant and no filler.

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

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

With an output schema present, return values need not be detailed, yet the description still frames what the summary contains and which sibling handles the non-lap case. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, whose description already points at list_activities as the id source. The description 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?

States a specific verb and resource (return the laps of a run or ride) plus the swim variant (pace per 100 m/yd), and explicitly distinguishes itself from the sets-based sibling. An agent can tell what it returns 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 when-not rule (strength sessions have sets, not laps: use get_activity_sets) and names the user question it answers ("did my pace hold up?"). Alternative routing is unambiguous.

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 cover the safety profile (readOnly, idempotent, openWorld), so the description only needs to add context — and it does: rest periods are omitted by default and only appear with include_rests, and set_number is the handle that edit_activity_sets consumes to correct or delete sets. That cross-tool semantics is non-obvious and valuable, though nothing is said about pagination or failure modes for non-strength activities beyond the scope 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?

Three short paragraphs, front-loaded with the return contract, then the set_number/edit_activity_sets linkage, then sibling routing. Every sentence carries distinct information with 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?

An output schema exists, so return-shape documentation is a bonus rather than a requirement, and the description still summarizes the payload. Scope limits, the default for rests, and the sibling alternatives are all covered — nothing an agent needs before calling 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 the baseline is 3; the description goes beyond it by explaining the behavioral effect of include_rests (rests are excluded unless it is set) and by grounding activity_id in the workflow (its role as the key passed to edit_activity_sets).

Input schemas describe structure but not intent. Descriptions should explain 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 ('Return a strength activity's sets') and enumerates the returned content (category, name, reps, weight in kg, duration, total volume). It actively distinguishes itself from siblings, noting that runs/rides/swims have no sets and pointing to get_activity_laps 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?

Explicit routing: use this for strength activities, use get_activity_laps for runs/rides/swims, and use recent_strength_sessions when you want the last few sessions in one call. Both the when and the when-not are stated with the alternative named.

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 request-cost model ('One Garmin request whatever the range, so keep it to days') and the output fidelity contract ('Garmin's JSON as it comes: field names are Garmin's and nothing is converted'). Annotations only say readOnly/idempotent/openWorld; the cost and raw-payload behavior 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?

Purpose is front-loaded in the first sentence, then routing guidance, then cost, then payload shape. Every sentence carries distinct information and none repeats the name or 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?

An output schema exists so return structure need not be re-explained, yet the description still flags the practically important fact that fields are raw/unconverted Garmin names. Combined with the request-cost note and the sibling routing, 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 schema already documents start and end including end's default-to-single-day behavior, so the schema does the heavy lifting. The description only gestures at the range ('each day from start to end') without adding format or boundary semantics, 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 ('Return Garmin's own body battery record for each day from start to end') plus a distinguishing modifier ('unprocessed'), which separates it from the aggregation siblings it explicitly names. An agent can tell it apart from get_day_summary and get_trend without opening either schema.

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

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

Gives explicit routing rules with named alternatives and the conditions that select them: get_day_summary for one day's high/low, get_trend with metric body_battery for daily highs over weeks or months. It also states when to use this tool itself (the detail behind a day's number).

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 readOnly/idempotent/openWorld, yet the description adds substantial extra behavior: partial failures become null and are listed under 'unavailable', total failure or Garmin rate limiting returns an error, and sleep is attributed to the day it ended on. These are non-obvious traits the annotations do not convey.

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

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

Front-loaded with the returned value set, then routing rules, then failure semantics. The metric enumeration is long but each item earns its place by defining scope; no filler sentences.

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

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

Even though an output schema exists, the description fully covers scope, alternatives and error behavior. Nothing an agent needs to select and call this tool correctly is missing.

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

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

Schema coverage is 100% for the single 'day' parameter, so the baseline would be 3. The description adds one meaningful semantic rule beyond the schema — 'a night's sleep belongs to the day it ended on' — clarifying what date to pass for sleep data.

Input schemas describe structure but not intent. Descriptions should explain 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 (aggregate one calendar day's metrics) and enumerates the exact contents returned: steps, calories, heart rate, stress, body battery, sleep, HRV, readiness and weigh-in. It is clearly distinguishable from siblings like list_activities, week_summary and get_trend.

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

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

It explicitly states when NOT to use it (the day's activities → list_activities with start_date/end_date) and names alternatives with their selecting conditions: per-metric tools for one metric, week_summary for seven days, get_trend for a range. Nothing 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.

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: null handling ('the reply is null, or its fields are') and the date-membership rule ('a night belongs to the day it ended on'). It stops short of auth/rate-limit detail, so a 4 rather than 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 return fields, then the date and null semantics, then the sibling pointers. Efficient overall, though the include_readings sentence largely duplicates the schema field 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 an output schema present, return values need not be spelled out, and the description still covers fields, date semantics, null behavior, and alternatives. Nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the 'day' semantics and 'include_readings adds the five-minute readings' but adds little beyond what the schema already states, matching the baseline 3 for full-coverage schemas.

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

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

States a specific verb and resource ('Return one night's heart rate variability in milliseconds') and enumerates the exact fields returned (night average, five-minute high, weekly average, status, baseline band). It also distinguishes itself from siblings by explicitly naming get_day_summary and get_trend, so an agent can route without opening other 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?

Names the alternatives and the conditions that select them: nightly average/status are also in get_day_summary, and 'over weeks or months use get_trend with metric hrv'. This is explicit when-to-use/when-to-use-elsewhere 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 readOnly/openWorld/idempotent, yet the description adds real behavioral context beyond them: deterministic ordering (newest first, undated last), the activity_id linkage, and the two-request-then-cached cost profile. That is exactly the extra context annotations cannot 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-loads what the tool returns, then routing, then cost. Efficient overall, though the "which get_activity opens" clause is slightly compressed and the request-count sentence reads as jargon.

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

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

An output schema exists, so return values need no explanation; the description still gives ordering, linkage, and cost context. Nothing needed to invoke this zero-param tool correctly is missing.

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

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

Zero parameters, so the baseline is 4; the schema has nothing to describe. The note that activity-borne records carry an activity_id adds output-field meaning but does not change the parameter story.

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

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

Starts with a specific verb ("List") and resource ("personal record"), scopes it to the whole account, and conveys shape (named, in units) so it is clearly distinguishable from get_trend 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?

Explicitly routes to alternatives: activity-borne records point to get_activity via activity_id, and range-based metric questions point to get_trend. The agent knows when this tool is the right call and when it is not.

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, openWorld), yet the description still adds non-obvious behavior: it returns null when no sleep was recorded, it defines the night-to-date attribution rule, and it discloses the upstream request cost relative to get_day_summary. Those are exactly the kind of rate/cost and edge-case disclosures annotations cannot carry.

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

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

Front-loaded with the returned fields, then the date-attribution rule, then the sibling/cost tradeoff. Two tight paragraphs, no filler, and the most decision-relevant content comes 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?

With an output schema covering return values and annotations covering safety, the description fills the remaining gaps: the empty-result behavior, the date semantics, and when to pick a sibling tool instead. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100% for the single `day` parameter, so the schema already documents it as a date the night ended on. The description's 'last night is today's date' restates that same rule rather than adding new syntax or format guidance, 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 ('Return one night's sleep') and enumerates exactly what is returned: start/end, total, deep, light, REM, awake time, sleep score, average respiration. It also distinguishes itself from get_day_summary and get_trend, so an agent can differentiate it from siblings 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?

Explicit routing: use this for a single night, use get_day_summary for the bundled summary, and use get_trend with metric sleep or sleep_score for multi-night totals. It even quantifies the cost difference (five Garmin requests vs one), giving the agent a concrete reason to prefer this tool.

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 and openWorld, but the description adds real behavioral detail: hourly totals are GMT not local time, total is null rather than 0 when Garmin did not answer, and include_buckets surfaces quarter-hour granularity. It stops short of mentioning auth needs, rate limits or error cases beyond the null semantics.

Agents need to know what a tool does to the 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 primary return shape, then routing alternatives, then edge-case semantics. Every sentence carries distinct information with 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?

Output schema exists so return values need not be re-explained, annotations cover the safety profile, and the description still supplies the timezone, null-vs-zero and bucket caveats an agent would otherwise miss. Nothing material is absent for a two-parameter read tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema; the description only restates include_buckets' effect and implies the day scope. The GMT-vs-local note describes the output rather than adding parameter meaning, 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 ('Return one day's steps') plus the exact return shape (total and 24 hourly totals). It explicitly disambiguates from siblings by naming get_day_summary and get_trend, so an agent can choose correctly 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?

Names two alternatives and the precise condition that selects each: get_day_summary for the total beside the day's other numbers, get_trend with metric steps for range/average/change. This is explicit when-to-use routing rather than implied 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, openWorld), so the bar is lower; the description adds real behavioral context by disclosing that the reply is null (or its fields are) when a day has no stress data, and that include_samples inflates the response to hundreds of three-minute readings. It stops short of covering auth/quota details, but the return-size and empty-data behavior are the material risks here.

Agents need to know what a tool does to the 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 return shape, then routing, then edge cases; every sentence carries information. It is slightly more prose-heavy than needed and could compress the sibling-comparison sentence, 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?

An output schema exists, so return values need not be explained, yet the description still outlines them and covers the two risky edge cases: null replies for days with no data and response bloat from include_samples. For a 2-parameter read tool with full annotation coverage, nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description nonetheless adds meaning beyond the schema's terse 'Add the three-minute readings' by quantifying the volume ('run to hundreds') and prescribing default-off behavior. The 'day' parameter (YYYY-MM-DD) is already fully specified 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?

Names a specific verb and resource ('Return one day's stress') and enumerates the returned fields: average, peak, minutes at rest, low/medium/high bands, unmeasured. It also explicitly distinguishes itself from get_day_summary and get_trend, so an agent can route 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?

States when to use alternatives explicitly: the daily average alone lives in get_day_summary, and multi-week/month aggregates in get_trend with metric stress. It also gives a conditional rule for include_samples ('leave it off unless the shape of the day matters'). Nothing 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.

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds real behavioral context: Garmin recomputes readiness through the day, only the AFTER_WAKEUP_RESET entry is the morning score, it costs one Garmin request, and it returns null/empty when nothing was recorded. Some of the response-shape detail overlaps the output schema, keeping this just 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?

Front-loads what is returned, then the use case, then the differentiators vs siblings, closing with cost and return behavior. Dense but every sentence carries distinct information; 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 single-parameter read with an output schema and full annotations, the description supplies everything an agent needs: scope, alternatives, recompute semantics, request cost, and empty-result behavior. Nothing actionable 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% (the single 'day' parameter is fully documented with format YYYY-MM-DD), so the schema carries parameter semantics. The description adds no syntax or formatting meaning beyond it; baseline 3 is appropriate.

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

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

States a specific verb and resource: returning every training readiness entry Garmin recorded for one day, and names the exact fields returned (score, level, factors). It also tells the agent what the tool is NOT for by citing get_day_summary and get_trend, so it is distinguishable from siblings 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?

Explicitly routes usage: 'Use it for why the score is what it is,' and then draws boundaries against get_day_summary (which already gives the morning score) and get_trend with metric readiness (which follows weeks/months). This is explicit when-to-use and when-to-prefer-alternatives 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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description still adds real context beyond them: a single Garmin request, null returned when Garmin reports nothing for the date, and that the payload is unprocessed Garmin JSON with Garmin's own field names. It stops short of describing payload structure, which is reasonable given an output schema exists.

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

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

Three sentences, front-loaded with what is returned, followed by routing and edge-case behavior. No filler and 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?

For a single-parameter read tool with annotations covering safety and an output schema covering return values, the description supplies the remaining essentials: routing to siblings, single-request cost, and null semantics. Nothing needed to call it correctly is missing.

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

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

There is only one parameter and schema description coverage is 100% ('The date to report on, YYYY-MM-DD'), so the schema already carries the syntax. The description's 'for one date' confirms the granularity but adds no format or edge-case detail beyond the schema, making baseline 3 appropriate.

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

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

States a specific verb and resource (return Garmin's training status) plus the scope (one date) and the payload contents (status, training load, VO2 max context). It explicitly names sibling alternatives it is not, so an agent can distinguish it from get_training_readiness and get_trend 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?

Explicit routing: 'For VO2 max over time use get_trend with metric vo2max (running) or vo2max_cycling; for whether to train today, get_training_readiness.' It names both alternatives and the condition that selects each, 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.

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

Annotations cover only the safety profile (readOnly/idempotent/openWorld), and the description adds substantial behavior the annotations cannot: automatic aggregation switching (daily up to two months, weekly up to a year, monthly beyond), a hard two-year range cap, per-metric Garmin request cost (steps ~14 requests/year vs one for weight), and the exact semantics of 'change' (last whole period's average minus the first, short periods excluded).

Agents need to know what a tool does to the 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 outcome, then density-packed supporting detail. The per-metric request counts are useful for latency expectations rather than filler. It is long for a description, but nearly every clause carries operational information, so only minor trimming is possible.

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

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

Although an output schema exists, the description still explains the summary fields (days_with_data vs periods_with_data for VO2 max, average/min/max, first/last day, change definition), which prevents misreading. With four parameters, a hard range limit, and metric-dependent granularity all covered, nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description exceeds that by glossing metric meaning — hrv, readiness is the morning score, stress is the day's average, body_battery is the day's high, vo2max is running vs vo2max_cycling — and by explaining that aggregation is inferred from the range when omitted, which changes the shape of the 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?

The description states a specific job — how one metric moved over a range, returning average, extremes and change — over a named enumerable set of metrics. It clearly differentiates from single-metric siblings (get_steps, get_hrv) and from get_day_summary by scope. An agent can select 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?

Explicit routing: 'For one day use get_day_summary or that metric's own tool; for every weigh-in rather than one a day, list_weigh_ins.' It also states range limits (two years) and implies when to prefer this aggregate view. Both the when-to-use and the when-not-to-use cases are covered with named alternatives.

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 and openWorld, so safety is covered. The description adds non-obvious behavioral context: the 'raw' field holds Garmin's complete definition (every step, target, repeat), and it clarifies the workout-vs-activity distinction that an agent would otherwise get wrong. It stops short of stating error behavior for an unknown id.

Agents need to know what a tool does to the 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, return shape first, then usage, then the sibling boundary. Every sentence carries distinct information with 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?

An output schema exists, so return values need not be spelled out, yet the description still orients the agent on the raw field's contents. Combined with the annotations and the activity/workout disambiguation, nothing needed to select or call 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?

Schema description coverage is 100% and the schema already documents workout_id as coming from list_workouts or list_scheduled_workouts, so the description's identical provenance note is largely redundant. High coverage sets the baseline at 3; nothing extra (validity, id format) is added.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Return one saved workout by id') and enumerates the exact fields returned (name, sport, description, estimated duration, raw). It also distinguishes itself from siblings like list_workouts and get_activity without requiring the schema to be opened.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage contexts ('before scheduling or pushing it', 'check what create_strength_workout or create_endurance_workout built'), names the id sources (list_workouts, list_scheduled_workouts), and draws a boundary exclusion ('a completed session is an activity: read it with get_activity or get_activity_sets').

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 (readOnlyHint, idempotentHint, openWorldHint), so the description's added value is the sort order, the cross-parameter dependency constraint, and the strength-session follow-up workflow. It does not discuss pagination behavior, though the schema's start/limit fields imply 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?

Four short sentences, each carrying distinct information: ordering, scope exclusion, filter constraints, and the strength-session workflow. Front-loaded and free of 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 an output schema present, return values need no explanation. The description covers ordering, scope, filter dependencies, and the follow-up tool for strength data, leaving no gap an agent would need in order 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 100%, so the baseline is 3, but the description adds genuinely new meaning: the end_date-depends-on-start_date constraint (a cross-field rule not encoded in the schema) and a concrete value example for activity_type. It also clarifies that a separate call is needed for exercise-level 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?

States a specific verb and resource ('List activities') plus an ordering guarantee ('newest first'), and immediately distinguishes scope from the sibling list_workouts by clarifying these are 'Completed activities, not planned workouts.' An agent can separate this from get_activity (single fetch) and list_workouts 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 concrete usage conditions: filter by type and date range, end_date requires start_date, and route strength sessions through activity_type=strength_training followed by the sets fetch. It excludes planned workouts but never names the alternative (list_workouts) explicitly, so routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds context beyond that: it is a single Garmin request, and critically it discloses a limitation (the last-used device is not shown), which prevents a wrong default assumption. A minor gap is that 'one Garmin request' hints at quota but doesn't state any rate limit.

Agents need to know what a tool does to the 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 what is listed, then the usage rule, then the operational cost. Every sentence carries distinct information 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 zero-parameter, read-only listing tool with an output schema present, the definition supplies everything needed: what is returned, why to call it, what it omits, and its cost 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?

The tool takes zero parameters, so the baseline is 4. The description nonetheless maps the output field device_id to its downstream consumer (push_workout_to_device), which adds meaning that the empty input schema cannot carry.

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

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

States a specific verb and resource ('List the Garmin devices paired with the account') and enumerates the returned fields (device_id, name, product, primary activity tracker). An agent can tell this apart from siblings like list_activities or garmin_status 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?

Explicitly tells the agent when to use this: to obtain the device_id that push_workout_to_device requires. It also names the consequence of skipping it (a push without device_id prefers the last-used device, which this list does not reveal), which is a precise when/when-not rule.

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 earns credit for disclosing the filtering semantics beyond the annotations: completed activities, naps and badges are dropped, and the surrounding months' grid days are excluded. It does not discuss pagination or auth, but the exclusion rules are the important behavioral trait here.

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

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

Front-loaded with what is listed, followed by exclusions and then the sibling routing in a logical order. The second sentence is dense but every clause carries a distinct, actionable rule; 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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps an agent would face: what qualifies as a result, what is silently filtered out, and how the returned schedule_id is used. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters (year, month) are documented with ranges and examples in the schema. The description only reinforces the monthly scope and adds no syntax, format or constraint detail beyond what the schema already 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?

The first sentence names a specific verb (list), a precise resource (workouts scheduled on the Garmin calendar), and a scope (one month), then states the returned fields (schedule_id, workout_id, date). An agent can distinguish it from list_workouts and list_activities immediately from the text 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 explicitly routes to alternatives with the selecting condition: use list_activities for completed sessions on those dates, and list_workouts for saved workouts whether scheduled or not. It also flags the downstream consumer ('The schedule_id is what unschedule_workout takes'), which is prescriptive guidance rather than a restatement of the name.

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 cover read-only/idempotent safety, but the description adds real behavioral context: it includes every reading on multi-reading days, returns oldest-first, and surfaces body composition plus a delete-compatible sample_pk. It stops short of describing pagination or date-range bounds, which is a minor 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?

Front-loaded with the core behavior, then the sibling routing. Every clause is informative, though the three-way comparison against get_trend and get_day_summary makes it slightly dense.

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

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

With an output schema present, return values need no explanation, and the description still covers ordering, deduplication of multi-reading days, the end default, and alternative tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3. The description adds meaning beyond the schema by stating that end defaults to start, a defaulting behavior the schema does not encode.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List every weigh-in') with an explicit range and ordering ('from start to end, oldest first'). It clearly distinguishes itself from sibling read tools by naming get_trend and get_day_summary as alternatives for different views.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routes the agent: use get_trend for a single daily value with average/change, use get_day_summary for the day's last weigh-in, and use this tool for every reading. It also tells the agent the returned sample_pk is what delete_weigh_in consumes.

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 and openWorld. The description adds real behavioral context beyond that: the library holds saved workouts not on the calendar, the returned fields (name, sport, duration) exclude steps, and paging via start 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?

Front-loads what is listed and its scope, then routes to alternatives, then covers paging. Three sentences, no waste, 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?

With an output schema present the description needn't explain returns, and annotations cover safety; it still adds the not-on-calendar distinction and paging note. Folder/library-level filtering isn't mentioned, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so both limit and start are already documented, including that start is an offset, not a date. The description restates only the start-skip behavior, adding little beyond the schema; baseline 3 applies.

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

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

States a specific verb (list) and resource (saved workouts in the library) and clarifies scope: plans to follow with name, sport, duration but not steps. It distinguishes itself cleanly from list_scheduled_workouts, list_activities and get_workout in the 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?

Explicitly routes the agent: use list_scheduled_workouts for what is planned on which date, list_activities for sessions already done, and get_workout for one workout's full step structure. Names alternatives with the conditions that select them.

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 past the thin annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the Strava/third-party public post risk and that deleting from Garmin does not remove it there, plus the duplicate-detection behavior (identical session is a no-op; any changed set creates a second activity). This is exactly the pre-call context an agent needs for a write 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?

Purpose is front-loaded and the four paragraphs each carry distinct payloads (destination/encoding, external-sharing risk, naming convention, duplicate/correction behavior). It is dense but not padded; a small amount of repetition around 'appears in Garmin Connect' could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 input schema and an output schema present, the description covers the missing pieces an agent cannot infer: external sharing side effects, duplicate semantics, exercise naming source, and the correct remediation tool. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by telling the agent how the exercise fields must be populated (Garmin's category + exercise_name pair, sourced from find_exercise) and that the session is taken 'as it happened, exercise by exercise with the reps and weight of every set', 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?

Opens with a specific verb+resource+destination: 'Log a completed strength session to Garmin Connect as an activity.' The phrase 'completed strength session' implicitly distinguishes it from the sibling create_strength_workout (which builds a plan), and the non-obvious encodings (FIT file, Strength Training activity with sets intact, name/notes mapping) make the outcome 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 concrete routing: name exercises via find_exercise's category/exercise_name pair, and correct a logged session with edit_activity_sets rather than re-logging. It does not explicitly contrast itself with create_strength_workout or create_workout_from_dto, but the 'completed session' framing covers the main 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?

Beyond the readOnlyHint/idempotentHint/openWorldHint annotations, it discloses the matching contract in detail: only certain matches return, the accepted equivalence classes (exact/normalised, typo, plural/hyphenation, one hit adding at most an implement), and the null fallback. 'No Garmin request' reinforces the local, non-open-world 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 action and null-return contract are front-loaded, followed by usage guidance and then the matching criteria. Every sentence carries information; nothing is redundant 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?

An output schema exists so return shape needn't be re-explained, yet the description still clarifies the one return value that matters (null on ambiguity). For a single-param matching tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with a single documented param, so baseline is 3. The description adds genuine meaning by specifying provenance ('such as one exported from another app') and that the input is a single free-text name, which tells the agent what shape of string to pass.

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

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

The description states a precise verb and resource ('map one free-text exercise name onto exactly one catalogue exercise') plus the failure mode (returns null when no single match is certain). It is immediately distinguishable from the sibling find_exercise, which returns a ranked list rather than one binding answer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 exact scenario ('converting names from another source, where a wrong guess would log the wrong lift') and explicitly routes the agent to find_exercise when it wants to browse candidates and choose. Both when-to-use and the alternative are spelled out.

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 (non-readOnly, non-idempotent, openWorld, non-destructive), and the description goes well beyond them: async queued delivery at next sync, deterministic device fallback logic, refusal behavior when resolution fails, and that the reply names the chosen device. 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?

Front-loaded with the core behavior, then the optional-parameter resolution, then the disambiguation from schedule_workout. Dense but every sentence adds actionable information with 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 two-parameter mutation with an output schema present, the description covers everything the agent needs: delivery timing, id sourcing, fallback resolution, refusal behavior, and the sibling alternative. Nothing material is missing, and return values are rightly left to the 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%, so the baseline would be 3, but the description adds real meaning beyond the schema by spelling out the multi-step fallback used when device_id is omitted and reaffirming that list_devices supplies valid ids. This is exactly the kind of semantic detail the schema cannot express.

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

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

States a specific verb and resource ('Queue a saved workout for one of the account's watches') and immediately clarifies the delivery model ('arrives at the watch's next sync, not immediately'). It also distinguishes itself from sibling schedule_workout, so an agent can tell the two apart 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?

Gives an explicit routing rule to a sibling: 'Pushing does not schedule it: to put it on a date, use schedule_workout.' It also documents the full default-device resolution chain and the failure case ('refused and asks for a device_id'), leaving no ambiguity about when this tool is appropriate.

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 readOnly/idempotent/openWorld annotations, it discloses request cost ('one Garmin request per session plus one, and one more the first time in a process'), failure semantics ('a session whose sets cannot be read carries sets_error'), and rate-limit behavior ('a rate limit stops the call'). These are exactly the operational traits 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?

Front-loaded with what the tool returns, then routing guidance, then operational caveats. Every sentence carries non-redundant information (sibling routing, set_number caveat, request budget, error field) with 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?

An output schema exists, so return-shape explanation is not required, yet the description still flags the sets_error case. Combined with explicit routing to list_activities and get_activity_sets/edit_activity_sets, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents count and include_sets, establishing a baseline of 3. The description reinforces the cost implication of include_sets via the per-session request count, but adds no syntax, default, or format detail 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?

States a specific verb (List) and resource (recent completed strength sessions) with scope and ordering ('newest first') and enumerates the payload ('exercises, reps and weights and its total volume'). It clearly differentiates itself from list_activities and get_activity_sets, which an agent could otherwise confuse with this aggregated 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?

It names the alternative explicitly ('One call instead of list_activities plus get_activity_sets per session'), states the exclusion ('It takes no dates: for a period, use list_activities with activity_type strength_training and start_date'), and warns about a downstream workflow prerequisite ('read a session with get_activity_sets before correcting it with edit_activity_sets'). Both when-to-use and when-not-to-use are covered.

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 declare idempotentHint=false but not the consequence; the description spells out that re-scheduling adds a duplicate entry rather than updating. It also discloses that the return value is the calendar entry keyed by schedule_id, a behavioral detail no annotation covers.

Agents need to know what a tool does to the 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 two tightly worded sentences that each deliver a distinct operational fact (return identity, duplicate behavior). No filler or restatement of 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 only two required, fully documented parameters and an output schema present, the description covers everything needed: input source for the workout id, date semantics via schema, and return/id behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by disambiguating workout_id from the returned schedule_id consumed by unschedule_workout. This prevents a common tool-chaining error that the schema alone would not prevent.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Put a saved workout on the calendar for a date'), scoping it clearly against siblings like list_scheduled_workouts and delete_workout. An agent can distinguish this from unschedule_workout and push_workout_to_device 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 describes the alternate workflow: repeated scheduling creates a second entry, and moving a workout requires unscheduling the old entry first. It names the sibling tool (unschedule_workout) that handles the inverse operation, giving the agent concrete 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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so safety/idempotency are covered. The description adds genuinely useful context beyond them: only the calendar entry is removed while the saved workout persists. It stops short of noting reversibility or error behavior on a bad id, 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?

Short, front-loaded, and every clause earns its place: the core effect first, then the id-source guidance, then the two alternative-routing sentences. 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?

An output schema exists so return values need not be explained, and the single parameter is fully documented in the schema. Combined with annotations and the routing guidance, 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%, so baseline is 3, but the description adds meaning: it names the valid sources of schedule_id and warns it is 'not the workout_id', directly addressing the most likely invocation error beyond the terse schema text.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Remove one entry from the Garmin calendar') and immediately clarifies scope ('the saved workout itself is kept'). It distinguishes itself from delete_workout and schedule_workout, so an agent can select 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?

Names where the required id comes from (list_scheduled_workouts, schedule_workout, create_* with schedule_date), and explicitly routes the move case to unschedule+schedule_workout and the delete case to delete_workout. When-to-use and alternatives are both explicit.

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 (which only carry readOnly=false, idempotent=true, destructive=true, openWorld=true). It discloses partial-update semantics ('what is not given is left as it is'), destructive replacement semantics ('the new text replaces the old'), and a genuine non-atomic failure mode: name and description are separate Garmin requests, so a failed second call leaves the first applied. That failure-mode disclosure is exactly the kind of behavior 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 sentences, front-loaded with the core action, then alternatives, then the failure caveat. Every sentence carries distinct information; no restatement of the title or schema.

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

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

An output schema exists, so return values need not be explained. Combined with annotations covering the safety profile and the description covering partial-update, replacement, alternatives, and partial-failure behavior, an agent has everything needed to call this mutation 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 real meaning the schema does not: the nullable name/description parameters are optional and unspecified ones are left untouched, and any supplied value overwrites rather than merges. It stops short of describing format or length constraints, hence 4 rather than 5.

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

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

States a specific verb+resource pair ('Rename an activity, replace its description, or both') and immediately delimits scope against two named siblings: edit_activity_sets for set-level edits and delete_activity for removal. An agent can distinguish this tool from every related sibling 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?

Explicitly routes the agent: use edit_activity_sets for a strength session's exercises/reps/weights, use delete_activity to remove the activity. Both when-to-use and when-not-to-use are stated with the alternative named, 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.

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds cost telemetry ('three Garmin requests per day plus one for the activities, over 20 in all'), an explicit throttling warning, a 50-activity cap, and a non-obvious data convention ('a night's sleep belongs to the day it ended on') that materially affects interpretation.

Agents need to know what a tool does to the 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 scope are front-loaded in the first sentence, followed by routing, then cost caveats. Every sentence carries actionable information with no filler, despite the density.

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

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

An output schema exists, so return-shape explanation is unnecessary; the description instead covers the things structure can't: sibling routing, request cost, call-frequency limits, and the sleep-day attribution rule. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the sole parameter is fully documented, so the baseline is 3. The description adds genuine meaning beyond the schema by specifying that the default 'today' is evaluated in the account's timezone and clarifying end_day as the last day of the seven-day window.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Summarise') and resource (the seven days ending on end_day), then enumerates exactly what is returned: steps, resting heart rate, sleep hours, morning readiness, and activities (up to 50). This is instantly distinguishable from day- and trend-level siblings.

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

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

Explicitly routes the agent: get_day_summary for one day in full, get_trend for a single metric over longer ranges, and a hard caution not to call week_summary repeatedly because of its request cost. When-to-use, when-not-to-use, and alternatives are all named.

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