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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/non-idempotent/non-destructive profile is covered structurally. The description adds value beyond that by noting attribution to the authenticated user and reinforcing the singular-WRITE semantics that the annotations only imply. It doesn't mention the return payload, but an output schema exists, so that is acceptable.

Agents need to know what a tool does to the 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 operation and its singular/WRITE semantics, then the when-to-use trigger, then the read alternative. 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?

Annotations, 100% schema coverage, and an output schema mean most structured burden is covered, and the description fills the purpose, trigger, and read/write routing gaps. It could go one step further by distinguishing the related update/delete message siblings (icu_update_activity_message, icu_delete_activity_message), which are also singular write operations.

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

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

Schema description coverage is 100% with only two parameters (activity_id, content), both documented in the schema. The description implies what goes into content ("note or comment") but adds no format, length, or validation detail beyond the schema. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb and resource ("POST a new note or comment on a specific activity") and explicitly labels the singular form as the WRITE operation. It distinguishes itself from the read sibling icu_get_activity_messages (plural) by name, so an agent can separate the two without opening either schema.

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

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

Provides an explicit "use when" trigger with three concrete user-utterance examples ("add a note to this ride that I felt strong", "comment on yesterday's run", "leave a training note"). It also names the alternative for the opposite case: "To READ existing notes use icu_get_activity_messages (plural)."

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=false, and openWorldHint=true, so the mutation profile is known. The description adds that a whole plan lands on the calendar at once (which contextualizes destructiveness) and the folder_id prerequisite, but says nothing about what happens to pre-existing entries on those dates or whether re-running duplicates the plan.

Agents need to know what a tool does to the 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 action and resource, then prerequisite, then sibling disambiguation. 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?

A destructive, non-idempotent bulk-scheduling tool with an output schema and full parameter docs; the description covers purpose, prerequisite, and alternatives. What is missing is the overwrite/conflict behavior when dates already hold events, which matters for a destructive operation.

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

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

Schema description coverage is 100%, so all four parameters including extra_workouts_json and athlete_id are documented in the schema. The description adds only the notion of a chosen start date; it does not explain the optional extra_workouts_json semantics or coach/athlete_id behavior beyond the schema.

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

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

States a specific verb (schedule), a specific resource (an entire training plan / workout-library folder), and the target surface (athlete's calendar) with the start-date scoping. It explicitly names the sibling tools it is not, so differentiation is immediate.

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

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

Gives an explicit prerequisite workflow ("Use after icu_get_workout_library to find a plan's folder_id") and contrasts with three siblings: icu_create_event/icu_bulk_create_events build new events, icu_duplicate_events copies existing. When-to-use and when-not-to-use are both 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context about batch efficiency and the duplicate-events alternative, but does not disclose bulk failure behavior, partial success, or batch limits. 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?

The description is four sentences, front-loaded with the primary action and efficiency rationale. The alternative and resource pointers follow without redundant detail, leaving syntax detail to the schema where it belongs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 rich schema, annotations, and output schema, the description is largely complete for selecting and invoking the tool. It points to the necessary workout-syntax and event-category resources, but omits batch limits and partial-failure semantics that would matter for a bulk mutation.

Complex tools with many parameters or behaviors need more documentation. Simple 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's events parameter already fully documents payload shape, workout syntax, enums, and pitfalls. The description adds the relationship to icu_create_event and resource pointers, but the schema itself repeats those same references, so the top-level description adds little parameter 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 ('Create MANY new calendar events') plus batch scope, and distinguishes itself from looping icu_create_event. It also names icu_duplicate_events as the alternative for copying existing events, so an agent can identify the tool 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?

Explicitly says to use this for many events in one batch and that it is more efficient than looping icu_create_event. It also gives a clear alternative condition: use icu_duplicate_events instead when copying existing events forward.

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 real context beyond the annotations: what the upsert key is, that the matching scope is 'set by the same OAuth app', and that entries lacking external_id always duplicate. Since destructiveHint=true, it could say more about what happens to fields omitted on the update path, but the core mutation behavior is disclosed rather than left to inference.

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

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

Two short sentences with the operation and its constraint front-loaded; the update-versus-create rule follows immediately. Nothing redundant and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and annotations carry the safety profile, so the description does not need return values. For a destructive bulk write, though, it omits batch-size limits, error/partial-failure behavior, and whether unmentioned fields on updated activities are preserved or cleared.

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

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

Schema coverage is 100%, so a 3 baseline applies, but the description genuinely adds meaning: external_id is revealed as the upsert key inside activities_json, a field the schema only calls 'JSON string containing array of manual activities'. athlete_id is not discussed, so this falls short of being self-contained.

Input schemas describe structure but not intent. Descriptions should explain 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 (batch-create manual activities) plus the defining constraint (no device upload) and the write semantics (UPSERT on external_id). It is clearly separable from siblings like icu_get_activities_by_date, icu_bulk_create_events, and any FIT-file upload path.

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

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

The 'no device upload' qualifier implicitly routes device-file scenarios elsewhere, and the external_id rules tell the agent exactly which condition produces an update versus a create. However, no sibling alternative is named explicitly and no prerequisites (scope, permissions, batch limits) are 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?

The key behavioral trait not derivable from annotations is stated plainly: 'Nothing lands on the calendar' — items go into library folders. That is genuinely useful disambiguation for a non-readOnly, non-idempotent write tool. It does not disclose partial-failure/atomicity behavior for a bulk operation, which matters given idempotentHint=false.

Agents need to know what a tool does to the 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 action and scope, then the behavioral constraint, then the alternatives. No repetition of the verbose syntax text that lives in the schema.

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

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

With annotations, a full schema, and an output schema, the description covers purpose, the library-vs-calendar distinction, and sibling routing. The one missing piece for a bulk write is what happens on partial failure or whether the call is atomic.

Complex tools with many parameters or behaviors need more documentation. Simple 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 parameter description already carries the full workout-syntax reference, including the pointer to intervals-icu://workout-syntax. The tool description only restates 'each item is shaped like an icu_create_workout call', which the schema also says, 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 (bulk create), resource (reusable workouts), and location (library folders or plans) in one call, with emphasis on the MANY/bulk nature. It also distinguishes itself from sibling tools by name (icu_bulk_create_events, icu_apply_training_plan).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 away: dated calendar workouts go to icu_bulk_create_events and scheduling a finished plan goes to icu_apply_training_plan. No guidance on when to use this versus single-item icu_create_workout, and no stated prerequisite that the target folder must already exist.

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, and the description adds meaningful behavioral detail: the operation cannot be undone, and safe mode partitions events into `deleted` and `skipped` based on date. It does not describe failure behavior for invalid IDs, but the partition logic is a substantial disclosure beyond annotations.

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

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

The description is front-loaded with the purpose and destructive warning, then explains the safe-mode partition and the environment override in two compact sentences. Every sentence adds useful information with no repetition or waste.

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

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

With a full input schema, an output schema, and annotations covering safety and idempotency, the description supplies the remaining important context: bulk scope, irreversibility, and safe-mode partitioning. An agent has enough information to call this destructive 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 input schema already explains `event_ids` as a JSON array string and `athlete_id` as an optional coach-managed athlete filter. The description refers only generically to the input list and adds no parameter-level semantics beyond the schema, which is the baseline 3 when schema coverage is complete.

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

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

The description states a specific verb and resource: delete MANY calendar events in a single batch call. The use of "MANY" and "batch" clearly distinguishes this bulk operation from the single-event sibling icu_delete_event.

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

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

It clearly establishes the context for use: bulk deletion of many events in one call, and it explains the default `safe` mode versus `full` mode. It does not explicitly name icu_delete_event as the alternative for single-event deletion, so it falls short of full when/when-not guidance.

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

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

Annotations cover the safety profile (idempotent=true, destructive=false), and the description adds real context beyond them: partial-update semantics ('Only the flags you pass are changed'), scope restriction to workout events, and how non-matching events surface under `skipped`. That is exactly the behavioral detail an agent needs before a bulk mutation.

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

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

Front-loaded with the action, then the mechanism, then the scoping constraints and the sibling pointer. Every sentence carries either a usage scenario, a constraint, or an identifier caveat; nothing is redundant.

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

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

Covers bulk scope, selection modes, mutation semantics, event-type filtering, ID provenance, and sibling routing; an output schema exists so the `skipped` reporting need not be further expanded. Nothing an agent needs to call 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%, so the baseline is 3; the description still adds meaning by specifying that IDs are calendar event IDs from icu_get_calendar_events / icu_get_upcoming_workouts, not workout-library IDs — a genuinely error-prone confusion. It does not re-explain the date-range vs. event_ids mutual exclusion, which the schema already handles.

Input schemas describe structure but not intent. Descriptions should explain 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 pair (hide/reveal, lock/unlock) on a specific resource (MANY planned WORKOUT calendar events) and explains the exact underlying UI flags it toggles. It is unambiguously distinguishable from icu_update_event and icu_bulk_delete_events.

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

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

Gives the canonical scenario (build a block ahead, hide it, reveal week by week; lock key sessions) and an explicit routing rule: 'For one event use icu_update_event.' It also states the negative case — only WORKOUT events are touched; notes, races and targets are skipped.

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 mutation and open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds genuinely useful behavior: content shape is item_type-dependent and must be read from a resource BEFORE constructing, and chart/panel/zones/stream types should omit content entirely.

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

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

Three tight sentences, front-loaded with purpose then usage then the prerequisite for content. Nothing is padded and the resource hint arrives before the agent would start constructing arguments.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no explanation, and the content-shape dependency is redirected to a resource. The only gap is that coach-only athlete_id behavior and the non-idempotent nature of creation are left to the schema/annotations.

Complex tools with many parameters or behaviors need more documentation. Simple 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 every parameter in depth. The description largely defers ('see that param's description') rather than adding new semantics, and the resource pointer for content is already present in the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a custom addition to the user's Intervals.icu account') and immediately grounds it in concrete user intents ('add a custom field for RPE', 'create a custom power zone set'). The create verb naturally separates it from the get/update custom-item 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?

Gives explicit trigger phrases that show exactly when to reach for this tool, and directs the agent to match intent against item_type. It does not name when to use a sibling instead (e.g., icu_update_custom_item for existing items), so it falls short of full when/when-not coverage.

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

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

Annotations only declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantive behavior the annotations cannot: that WORKOUT description text is parsed server-side into device-syncable steps with zones and training load, and it flags silent failure modes (bare pace strings dropped, repeats collapsing to one iteration without blank lines, bare '- 20s' becoming work rather than rest). That is exactly the non-obvious behavior an agent needs to know before calling.

Agents need to know what a tool does to the 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 correctly: the create statement comes first, then routing rules, then reference pointers. Slightly long across three paragraphs and part of the resource-pointer prose duplicates the schema, but every paragraph carries distinct routing or reference 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?

For an 18-parameter create tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: sibling routing, the required payload location for workout events, and the reference resources. Return values need no explanation because an output schema exists, and no material call-time decision is left unaddressed.

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

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

Schema description coverage is 100% and the schema itself is unusually rich, so the baseline is 3. The description's parameter-level content (put workout syntax in `description`, consult the event-categories resource for `category`/`training_availability`) largely restates what the schema already says, adding only a resource pointer rather than new semantics for the 18 parameters.

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

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

Opens with a specific verb and resource ('Create ONE new calendar event from scratch'), with the 'ONE' emphasis immediately bounding scope. It then names the two closest siblings (icu_bulk_create_events, icu_duplicate_events) and the condition that separates them, 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?

Explicit when-to-use-this vs when-to-use-alternative: 2+ events → bulk create instead of a loop; copying existing events forward → duplicate_events because it reuses the payload. It also directs the agent to the two resources needed for enum values and workout syntax, closing the main usage gaps in advance.

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, non-destructive, non-idempotent, open-world profile, so the safety bar is low. The description adds the domain framing (equipment usage/maintenance) but says nothing about duplicate handling given idempotentHint=false, or what happens when a gear name already exists.

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

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

A single front-loaded sentence with the verb first and examples that earn their place by clarifying what 'gear' covers. Nothing redundant.

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

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

With full schema coverage, annotations, and an output schema, the return value and safety semantics are already covered, so the description is nearly sufficient. The only real gap is the absence of usage guidance for a mutation tool in a large sibling set.

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

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

Schema description coverage is 100%, including the lengthy gear_type enumeration and the coach-oriented athlete_id note, so the schema carries all parameter meaning. The description adds no parameter-level detail and the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a new gear item') and adds the domain purpose ('tracking equipment usage and maintenance') with concrete examples. It is distinguishable from the sibling create/read/update/delete gear tools by the verb alone, though it never names them.

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

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

No when-to-use guidance, no prerequisites (e.g., whether gear must be attached to an athlete, coach vs. self), and no exclusions. Only a generic purpose phrase implies usage; the agent must infer everything else.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the mutation and safety profile is covered. The description contributes the trigger semantics (distance, time, or both), but says nothing about duplicate-reminder behavior, whether a reminder with no alert is valid, or permission/auth needs for coach-scoped writes. Adequate but thin against a lowered bar.

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

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

A single sentence with no filler, front-loading the verb and resource followed by the one non-obvious behavioral detail. 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?

With an output schema present, annotations covering the safety profile, and full schema descriptions for all five parameters including the coach-facing athlete_id, the agent has enough to call this correctly. The remaining gap is the missing relationship to the update sibling, which is a routing concern rather than a completeness failure for the call itself.

Complex tools with many parameters or behaviors need more documentation. Simple 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%, including worked examples for text, time_alert, and distance_alert, so the schema already does the heavy lifting. The description's 'distance, time, or both' confirms the two alert parameters are combinable, which is marginal added meaning. Baseline 3 applies.

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

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

The description names a specific verb and resource — 'Create a maintenance reminder for a gear item' — and adds the trigger model (distance, time, or both), which is the core semantics of the resource. It does not explicitly distinguish itself from the sibling icu_update_gear_reminder, so it falls short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative (icu_update_gear_reminder) or of what happens if a reminder already exists. The only usage signal is implicit in the trigger wording.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the write profile is covered. The description adds only the field groupings (outdoor vs indoor FTP), and stays silent on the meaningful behavioral question for a non-idempotent create: whether a duplicate sport_type is rejected or replaces the existing thresholds.

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

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

A single front-loaded sentence with no filler; the resource and the key qualifier (per-sport) come first. It is efficient, though the trailing field list largely duplicates the schema property names.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explained. However, for a non-idempotent mutation with an optional coach-scoped athlete_id, the description omits duplicate-handling behavior and any permission/scope prerequisites, leaving an agent to infer them from annotations alone.

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

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

Schema description coverage is 100%, with each parameter carrying its own unit-bearing description (watts, bpm, min/km, min/100m). The description merely restates those field names, adding no unit, format, or defaulting semantics beyond the schema.

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

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

States a specific verb and resource ("Create a per-sport threshold record") and enumerates the metric families covered (FTP, FTHR, pace, swim). The 'create' verb implicitly separates it from the sibling icu_get_sport_settings and icu_update_sport_settings, though neither is named explicitly.

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

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

There is no guidance on when to create versus when to use icu_update_sport_settings, nor any note about what happens if a record already exists for the given sport_type. The athlete_id parameter's coaching use case is only explained in the schema, not in the description.

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 mutation profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the bar is lower. The description adds meaningful context beyond that: the created object is reusable and lives in a library/plan rather than the calendar, which is a behavioral fact the schema cannot express. No permission, rate-limit, or failure-mode detail, keeping it below a 5.

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

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

Opens with the single most important disambiguator (library, not calendar), then a compact routing paragraph. No filler sentences, no restatement of 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?

For a 13-parameter mutation tool, the description covers placement semantics, sibling routing, and preconditions (folder must exist, obtained via icu_get_workout_library, which the schema names). An output schema exists, so return values need no explanation.

Complex tools with many parameters or behaviors need more documentation. Simple 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 description text contains no parameter-level guidance beyond the folder/plan distinction already implied by folder_id. With the schema (including the very detailed 'description' syntax block) doing the work, 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 (Save) plus resource (one reusable workout) and its destination scope (library folder or training plan), then explicitly excludes the calendar. That negative scoping distinguishes it from icu_create_event, which the description names directly.

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

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

Gives explicit when-to-use-this routing for five siblings: icu_create_event for scheduling, icu_bulk_create_workouts for two or more, icu_update_workout for edits, icu_create_workout_folder for new containers, icu_apply_training_plan for calendar placement. Each alternative is paired with the condition that selects it.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the mutation/idempotency profile is carried structurally. The description adds genuinely non-schema context: the output id is meant to be reused as folder_id, and the created object is not a calendar entity. It stops short of noting side effects such as duplicate names or athlete scoping consequences for coaches.

Agents need to know what a tool does to the 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, the object distinction is front-loaded, and the second sentence carries the actionable chaining information. No filler or restatement of the tool name.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description still flags the one thing an agent must do with the result (reuse the id as folder_id). Combined with full parameter documentation and annotations, 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% and folder_type already spells out FOLDER vs PLAN in detail, including the icu_apply_training_plan link. The description repeats the folder/plan distinction in passing but adds no syntax or defaulting 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 ('Create a new LIBRARY folder or training PLAN to hold workouts') and explicitly excludes a plausible misread with '— not a calendar item', which separates it from icu_create_event. An agent can distinguish it from icu_create_workout and icu_create_event without opening any schema.

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

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

Names the exact downstream consumers ('Pass the returned id as folder_id to icu_create_workout or icu_bulk_create_workouts') and the browse alternative ('use icu_get_workout_library'). This covers both when to use it and what to use instead for the adjacent read case.

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 flag destructiveHint=true and idempotentHint=true, but the description adds genuinely non-obvious behavior: a '(deleted)' placeholder persists in the thread, the deleted text is returned for possible re-posting, and the original timestamp is unrecoverable. That post-delete state and data-loss caveat are exactly what an agent needs before committing a destructive call.

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

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

The action is front-loaded in the first sentence, followed by when-to-use, the author constraint, the side effect, and the return value. Each sentence carries distinct information with no repetition of annotations 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?

For a destructive two-parameter tool with an output schema, the description covers selection, precondition, side effect and the recoverability caveat. The output schema relieves it of describing return formatting, and it still explains the meaningful part of the return (text for re-posting, lost timestamp).

Complex tools with many parameters or behaviors need more documentation. Simple 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 already states that message_id comes from icu_get_activity_messages and that activity_id is the Intervals.icu activity ID. The description adds only the author-ownership constraint, so the schema is doing the heavy lifting and baseline 3 applies.

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

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

Specific verb-plus-resource: deletes one of the user's own notes from an activity. It is immediately distinguishable from the sibling triad icu_get_activity_messages, icu_add_activity_message and icu_update_activity_message because the description names the delete action and its author-only scope.

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

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

Gives concrete user-intent triggers ('delete my comment on that run', 'remove the note I left yesterday') and a hard precondition (only the author's own notes). It does not explicitly say when to prefer icu_update_activity_message instead of deleting, so it stops short of full alternative routing.

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

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

Annotations already flag destructive/idempotent, but the description adds substantial context beyond them: the safe-mode gate, that past events are silently skipped rather than errored, the shape of the response envelope, and the env var needed to override. That is exactly the behavioral detail an agent needs before committing an irreversible action.

Agents need to know what a tool does to the 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 destructive warning and the ONE-scope constraint are front-loaded in the first sentence, and the safe-mode caveat follows immediately. Every sentence carries actionable 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 two-parameter destructive mutation with full schema coverage and an output schema, the description covers the reset risk, the default mode, refusal behavior, and the response envelope. There is nothing an agent needs before calling it that 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 both event_id and athlete_id are already documented in the schema. The description mentions deletion by ID but adds no extra semantics about athlete_id scoping or formatting, so the baseline 3 applies.

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

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

The description opens with a precise verb and resource ('Permanently delete ONE calendar event by ID') and capitalizes ONE, which implicitly contrasts with the sibling icu_bulk_delete_events. The agent can tell exactly what is affected and how much.

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

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

It gives clear operational context: safe mode is the default, past events are refused, and a hint points to INTERVALS_ICU_DELETE_MODE=full. What it lacks is an explicit pointer to the bulk alternative (icu_bulk_delete_events) or preconditions for the athlete_id override, so a 4 rather than a 5.

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 known. The description adds genuinely new context beyond that: deletion is permanent, it cascades to maintenance reminders, and lingering activities are unaffected -- exactly the side-effect detail an agent needs before a destructive call.

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

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

Two short, front-loaded sentences with zero filler: permanence and cascade come first, the non-effect on activities second. Every clause carries information.

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

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

An output schema exists, so return values need not be described, and the cascade/permanence behavior is covered. Only minor gaps remain, such as whether deletion requires confirmation or whether athlete_id must match the gear owner.

Complex tools with many parameters or behaviors need more documentation. Simple 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 documented in structured fields and the baseline is 3. The description adds no extra meaning about gear_id or the athlete_id coach-scoping parameter.

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

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

The description names a specific verb and resource ('Permanently delete a gear item') and clarifies scope via the cascade note about maintenance reminders. It is distinguishable from siblings like icu_delete_event or icu_delete_workout by the resource noun, though it never explicitly contrasts with them.

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

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

Usage is implied by the destructive wording, and the note that activities survive removal helps an agent judge consequences. However, there is no explicit when-to-use vs alternative (e.g., icu_update_gear for retiring gear) nor preconditions such as confirmation or coach scope.

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 readOnlyHint=false, but the description adds important behavioral context: the deletion is permanent, cannot be undone, and affects only the library workout rather than linked calendar events. It does not discuss permissions or rate limits, but the core destructive behavior is well explained.

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

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

The description is short, front-loaded with the destructive library scope, and has no wasted text. The distinction from calendar events and the confirmation guidance each earn their place.

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

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

For a destructive mutation with full annotations, complete schema coverage, and an output schema, the description covers the essential context: scope, irreversibility, sibling alternative, and user confirmation. 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%, and both parameters are documented in the schema. The description reinforces that only one workout is deleted, but it does not add parameter-specific meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: permanently delete one workout from the library. It also explicitly distinguishes this from deleting calendar events with icu_delete_event, so an agent can separate it from the many sibling deletion and workout tools.

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

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

It gives clear usage context: use this for library workouts, use icu_delete_event for calendar events, and confirm with the user before calling if unsure. The alternative and the condition selecting it are named directly.

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 destructive=true, but the description adds context annotations cannot carry: irreversibility, that applied calendar events survive the delete, and that `safe` mode (the default) refuses non-empty folders and reports them in the `skipped` envelope. That is real behavioral disclosure, not restatement, and it does not conflict with the idempotent/openWorld hints.

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

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

Front-loaded with the verb and cascade scope, then consequences, then sibling routing, then the safe-mode caveat. Every sentence changes agent behavior; nothing is boilerplate or repeated from the schema.

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

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

An output schema exists so return values need no explanation, yet the description still flags the `skipped` envelope an agent must inspect to interpret a partial refusal. For a destructive cascade delete with only two parameters, 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 both parameters are documented in-schema (folder_id sourced from icu_get_workout_library, athlete_id for coach multi-athlete use). The description reinforces the singular 'ONE' constraint on folder_id but adds no new format, range, or lookup semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('permanently delete'), the exact resource ('ONE library folder or training plan'), and the cascade scope ('AND every workout in it'). It also names the two sibling operations that handle the narrower cases (icu_delete_workout, icu_delete_event), so an agent can distinguish it from nearby tools 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 alternatives: single library workout -> icu_delete_workout, lingering calendar events -> icu_delete_event. It also states a precondition ('Confirm with the user before calling if unsure') and the default-mode behavior that selects a different outcome, which is exactly the when/when-not 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 already cover read-only, idempotent, non-destructive and open-world, so the safety profile is known. The description adds real behavioral detail beyond that: the file is the unmodified upload in whatever format the device produced, and the response shape changes depending on output_path (saved to disk vs base64 embedded). It could still say more about size/streaming limits, but the output schema carries return structure.

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

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

Front-loaded with purpose, then differentiation, then the output_path behavior — an efficient order. There is mild repetition between the opening line and 'Downloads the ORIGINAL uploaded file', but nothing that obscures the decision.

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

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

Two parameters with full schema coverage, plus an output schema, so the description needs only to cover intent, sibling differentiation and the output_path branch — all of which it does. Nothing an agent needs to invoke it correctly appears to be 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 goes beyond the schema by explaining the consequence of output_path: if set, the file is written there; if not, base64 content is embedded in the response. That is meaningful semantics the schema's one-line description does not convey.

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

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

States a specific verb (download) and resource (the original activity file) and immediately clarifies that the original device-produced format is returned. It explicitly distinguishes itself from download_fit_file and download_gpx_file, so an agent can select between the three without reading 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 two concrete alternatives and the exact condition that separates them: this tool gives the ORIGINAL file, while the siblings force FIT or GPX conversion. The when-to-use rule 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 already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds that the output is a converted FIT representation rather than the original upload, which is useful context, but says nothing about writing to output_path, overwriting an existing file, or failure modes. With annotations carrying the main burden, a 3 is appropriate.

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

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

Two compact sentences with zero filler; the purpose comes first and the sibling differentiation follows immediately. 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, return-value explanation is not required, and the description covers purpose and sibling selection adequately for a simple two-parameter download tool. It is slightly incomplete in not mentioning that the file can be saved to disk via output_path, which is the only remaining ambiguity.

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

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

Schema coverage is 100%, so activity_id and output_path are fully documented in the schema including the optional/null default. The description adds no syntax, format, or path-behavior detail for either parameter, so the baseline 3 applies.

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

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

States a specific verb (download/convert) and resource (activity) plus the output format (FIT), and explicitly names the two sibling tools it differs from with their formats. An agent can pick this over icu_download_activity_file and icu_download_gpx_file 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?

It gives clear selection context by contrasting the three download variants and noting FIT targets Garmin/most training platforms, which implicitly tells the agent when to pick this one. No explicit 'when not to use' or prerequisite (e.g. activity must exist) is stated, so it falls short of a 5.

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

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

Annotations already provide high behavioral context (readOnly, idempotent, etc.). The description adds valuable domain-specific context by defining the intended use case (GPS devices, mapping software) and the output format itself, enhancing the agent's understanding without duplicating structured data.

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

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

The description is perfectly concise, using two sentences to deliver maximum value. The primary differentiator is stated in the first sentence, making the information highly accessible to the agent.

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

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

The definition is entirely complete for its role. Given the rich annotations and schema, the description successfully provides the necessary context (format, use case, and sibling differences) required 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?

With 100% schema coverage, the schema already details the parameters (`activity_id` and `output_path`). The description focuses entirely on the file format and its intended use, providing no necessary semantic information about the parameters beyond what is in the schema, thus achieving baseline adequacy.

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

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

The description clearly states the tool's function: downloading an activity converted to GPX format. It distinguishes this tool by naming its siblings and the specific format of the output, leaving no doubt about its purpose.

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

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

It provides perfect usage guidelines by explicitly contrasting the GPX format with other common formats (upload original, FIT format). This immediately tells the agent when to select this tool versus the `download_activity_file` or `download_fit_file` siblings.

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: copies reuse the source payloads rather than constructing new ones. It stops short of saying what happens if an event already exists on a target date, or how partial failures across a multi-ID input are handled.

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

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

Three short sentences, all front-loaded: the operation first, then when to use it, then the disambiguation. No filler and nothing that repeats structured fields verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 mutation semantics are covered by annotations plus the payload-reuse note. The one residual gap is collision/overwrite behavior when a copy lands on a date that already has an event, which matters for a non-idempotent write 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 event_ids, athlete_id, num_copies, and weeks_between are already documented. The "N weeks" and "next 4 weeks / next 3 Mondays" examples loosely illustrate weeks_between and num_copies, but they do not add precision beyond the schema 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?

"COPY existing events forward in time by N weeks" gives a specific verb (copy/duplicate), the resource (existing events), and the transformation (shift forward by weeks). It explicitly distinguishes itself from icu_create_event and icu_bulk_create_events, both of which appear in the sibling list.

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

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

Provides two concrete user phrasings that should trigger the tool ("repeat this workout for the next 4 weeks", "duplicate Monday's run on the next 3 Mondays") and names the alternative tools with the condition that separates them (reuse existing payloads vs build new events).

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is fully covered. The description adds the useful ordering guarantee ('chronologically before and after') and the symmetric N-per-side window, but says nothing about edge behavior when fewer neighbors exist or how missing/boundary activities are handled.

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

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

Two compact blocks: the core behavior first, then usage triggers. Zero filler and nothing the agent must read past to get the essential semantics.

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

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

With an output schema present, rich annotations, and fully documented parameters, the definition covers what an agent needs to select and call it. Only boundary/edge behavior near the start or end of activity history 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% and each parameter (count, athlete_id, activity_id) is self-documented. The description's '(N each side)' reinforces that count is per-direction rather than a total, which is a small but genuine clarification beyond the schema's 'Number of activities before and after'.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Fetch') and a precisely scoped resource: activities chronologically adjacent to a reference activity, N per side. That scope is unmistakably different from icu_get_recent_activities or icu_get_activities_by_date, though no sibling is named explicitly.

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

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

It supplies concrete trigger scenarios ('what did I do around this race?', training-context queries, progression comparisons) that let an agent pattern-match a request to this tool. It stops short of stating when NOT to use it or naming the alternative to pick instead (e.g., date-range or search tools).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds important behavioral context beyond annotations: results are newest-first, a window exceeding limit drops the oldest first, and widening limit or narrowing the window is required to reach the very oldest records.

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

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

The definition is front-loaded with the core purpose and immediately follows with the sibling distinction and truncation caveat. Every sentence contributes operationally useful information; there is no filler or repetition.

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

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

Given that annotations cover safety and an output schema exists, the description provides the remaining selection-critical context: date-window semantics, ordering, limit behavior, truncation direction, and the alternative tool. 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 all four parameters are already documented structurally. The description still adds meaningful semantics beyond the schema for the key parameters: the window is oldest..newest, dates are YYYY-MM-DD, limit governs truncation, and truncation drops oldest records first.

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

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

The description states a specific verb and resource ("List activities") together with the exact scope ("EXPLICIT date window") and output shape ("LIGHT summary per item"). It explicitly distinguishes itself from the sibling icu_get_recent_activities by contrast in anchoring and cap behavior, so an agent can select it without opening either schema.

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

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

It names the alternative tool and the condition that selects it: icu_get_recent_activities is for today-anchored recent history capped at 100, while this tool is for arbitrary historical windows. It also gives concrete use cases such as reconstructing training history and finding the oldest activity in a period.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety needs no restating. The description adds real behavioral context beyond them: the result is a single JSON blob of top-level metrics rather than granular data, which tells the agent about payload shape and depth. No gaps that matter for a read tool of this kind.

Agents need to know what a tool does to the 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 verb and the emphasized scope word SUMMARY, then use cases, then disambiguation. Nothing is redundant with the annotations 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-value documentation is not the description's burden. Between the payload summary, the use cases, and the explicit sibling routing, an agent has everything needed to select and 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 description coverage is 100% for the single required activity_id, so the schema already carries parameter meaning. The description adds no format, source, or validation detail beyond it. 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 ("Fetch the headline SUMMARY of one activity") and enumerates the payload contents. It explicitly contrasts itself with the intervals and streams tools, so an agent can distinguish it from siblings 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 example utterances ("how was my ride?", "tell me about activity X") and names both alternatives with the exact condition that selects them (lap-by-lap → icu_get_activity_intervals; second-by-second → icu_get_activity_streams). Routing is fully determined.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the lower bar applies. The description adds useful behavioral context about the returned structure: per-lap segments with targets, actual values, and interval types. It does not mention authentication or rate limits, but those are less central 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?

The description is front-loaded and compact. The first sentence states the main operation and return shape; the second gives usage cases; the third routes to alternatives. Every sentence earns its place.

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

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

Given the simple one-parameter schema, existing output schema, and clear annotations, the description is complete enough for an agent to select and call the tool correctly. It explains the tool's distinct role relative to nearby activity-data tools.

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

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

There is one required parameter and schema description coverage is 100%, so the schema already explains activity_id. The description reinforces that the tool operates on one activity, but it does not add format, validation, or lookup guidance beyond the schema.

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

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

The description uses a specific verb and resource: fetch the per-lap/per-interval breakdown of one activity. It clearly states what each segment contains (target, actual power/HR/pace, segment type) and distinguishes this from summary metrics and raw streams.

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

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

It gives explicit use cases such as workout-compliance analysis, lap-by-lap review, and checking whether intervals were hit. It also names alternatives directly: get_activity_details for headline summary metrics and get_activity_streams for raw second-by-second data.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description goes meaningfully beyond that by disclosing return ordering (chronological), message fields (author, content, timestamp, seen-flag), and the non-obvious tombstone behavior where deleted notes persist as "(deleted)" placeholders with a deleted timestamp — that last detail is real behavioral value an agent could not 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 the core purpose, then the READ/WRITE disambiguation mnemonic, then trigger phrases, then return shape. Every sentence earns its place; the parenthetical mnemonics are compact disambiguators rather than filler.

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

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

An output schema exists, so the description doesn't need to detail return values — yet it still summarizes ordering and the deleted-placeholder quirk, which is exactly the edge case that would otherwise surprise an agent. For a one-parameter read tool with full annotation coverage, nothing needed 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?

Single parameter with 100% schema description coverage ("The Intervals.icu activity ID"), so the schema carries the semantics. The description's phrase "a specific activity" reinforces but adds no format, ID-source, or validation detail 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 and resource ("Read the notes and comments attached to a specific activity") and explicitly contrasts with the write sibling via the "plural = READ" / "singular = WRITE" mnemonic. An agent can distinguish this from icu_add_activity_message, icu_update_activity_message, and the activity-detail siblings 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 three concrete user-phrasing triggers ("what did my coach say about that ride?", "show me the comments on yesterday's run", "any feedback on this workout?") and names the correct alternative tool for the write case. When-to-use and when-not-to-use 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?

Beyond the read-only annotations, the description discloses important behavior: heavy payload size, raw versus corrected heart-rate data, latlng null handling, left/right balance FIT convention, and a stream_notes caveat returned with the response. These details materially affect how an agent should interpret and request the data.

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

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

The description is long but appropriately so for a complex raw-data tool. It is front-loaded with the core purpose, then follows with usage guidance, the accepted stream list, and targeted caveats; every paragraph adds actionable information.

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

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

Given the output schema and annotations, the description supplies everything an agent needs to decide whether to call the tool, choose streams, and interpret special cases. The main behavioral risks around payload size, default streams, and corrected heartrate are all covered.

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

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

Although schema coverage is already 100%, the description adds substantial semantic value: it lists accepted stream types, explains that default streams exclude raw_heartrate and fixed_heartrate, documents latlng as [lat, lng] pairs with nulls, and clarifies the right-pedal convention for left_right_balance. It also warns about corrected heartrate versus raw_heartrate, which is essential for correct parameter selection.

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

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

The description uses a specific verb and resource: fetch raw per-sample time-series for one activity, with second-by-second arrays for power, HR, cadence, and related signals. It explicitly distinguishes this from sibling tools by naming get_activity_details for summary metrics and get_activity_intervals for per-lap breakdown.

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

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

It states when to use the tool (visualization or custom analysis of the underlying signal) and when not to use it (most ride-summary questions should use get_activity_details or get_activity_intervals). It also warns that the payload is heavy and gives practical guidance about default versus explicitly requested streams.

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 this as a safe, read-only, idempotent operation. The description adds the default window behavior ('365-day forward window so the full ATP is returned') and how to narrow it, which is useful but only marginally beyond what the schema's default and description already convey. No additional behavioral details (e.g., what happens when no ATP exists) are provided, but with strong annotation coverage this is adequate.

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

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

The description is front-loaded with purpose, then use cases, then default behavior, then exclusions. Every sentence earns its place: the example queries, the window guidance, and the sibling exclusions all directly help an agent decide when to call this tool. No redundancy or 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 tool has an output schema and full annotation coverage, the description needn't explain return formats or safety. It covers purpose, when to use, when not to use, and default window behavior—everything an agent needs to call it correctly. Athlete_id for coaches is covered in schema, so no gap.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description repeats the default window and narrowing advice, which is already in the days_ahead schema description. It adds no new meaning for days_back or athlete_id beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb ('Read') and resource ('Annual Training Plan (ATP)'), plus the exact data it returns: weekly TSS targets, Base/Build/Peak phases, and week notes. It explicitly names sibling tools it is NOT, making it unmistakable which tool to select.

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

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

Provides concrete example user questions that map directly to this tool, specifies the default 365-day window and when to narrow it, and explicitly lists alternatives (icu_get_upcoming_workouts, icu_get_calendar_events, etc.) with their distinct scopes. This is textbook when-to-use / 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?

While the annotations handle safety, the description adds valuable context regarding the content returned (notes vs. metrics) and the functional behavior of the default athlete selection.

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

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

The definition is highly concise, front-loading the main purpose and organizing secondary information (like alternatives and default behaviors) efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 breadth of data returned, the description is complete, covering what is retrieved, how options are used, and pointing to the correct sibling tools for modification.

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

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

Although the schema covers the technical aspect, the description provides the crucial operational semantics of the `athlete_id`: defaulting to the authenticated user while allowing coaches to specify a managed athlete ID.

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

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

The description clearly states the tool's primary function is to retrieve an athlete's profile and lists the specific types of data included, such as sport settings and CTL/ATL/TSB.

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

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

It provides excellent guidance by suggesting an alternative tool (`icu_update_athlete_notes`) for related tasks and explains the conditional use of the `athlete_id` parameter for coaches.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the remaining burden is low. The description adds genuine behavioral context the annotations don't: the analysis is confined to one activity and at least one of duration/distance must be supplied. It stops short of describing result ordering/format, but the output schema covers return values.

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

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

Three tight sentences: the core operation and constraint come first, the sibling disambiguation second, and usage examples third. No filler, no repetition of schema content.

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

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

With annotations covering safety, an output schema covering return values, and a fully documented 5-parameter schema, the description supplies exactly the missing piece: single-activity scoping and the duration/distance requirement. Nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%, so all five parameters are already documented with defaults and examples. The description's examples ('20-min power', '5k splits') reinforce duration/distance semantics but add no syntax or interaction detail beyond the schema. Baseline 3 is appropriate.

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

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

Uses a specific verb ('Find the top-N peak efforts') bounded by an explicit scope ('WITHIN a single activity') and a parameterized resource ('stream + target duration or distance'). It also names the class of siblings it differs from ('get_*_curves'), so an agent can distinguish it 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 states when to use this tool versus the curve tools ('which span many activities') and supplies two concrete use cases ('best 20-min power on this ride', 'top 5k splits in this run'). It also states a hard precondition: at least one of duration or distance is required.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing that results are unfiltered and enumerating the entry types returned, which tells the agent what to expect in the payload. It stops short of noting size/pagination behavior for wide date windows.

Agents need to know what a tool does to the 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 lines: scope statement first, use cases second, sibling routing last. Every sentence carries information an agent needs; there is no repetition 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?

Output schema exists so return values needn't be explained, annotations cover safety, and the schema covers all three parameters. The only residual gap is a trivial one: the sibling is referenced as "get_event" rather than its full name icu_get_event, which could momentarily confuse routing.

Complex tools with many parameters or behaviors need more documentation. Simple 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 days_back, days_ahead and athlete_id are fully documented in structured form and the baseline applies. The description alludes to a "date window" but adds no syntax, defaults or edge-case guidance beyond the schema.

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

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

States a specific verb (fetch) and resource (calendar entries) plus the scope (a date window, ALL entry types enumerated: workouts, notes, races, goals, life-event blocks). It explicitly marks itself as the unfiltered/broad variant, which separates it from icu_get_upcoming_workouts and icu_get_event.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 trigger queries ("what's on my calendar?", "show this week", broad calendar queries) and names both alternatives with the condition that selects each — filtered workout-only lookups go to icu_get_upcoming_workouts, single-event lookups go to get_event. 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, non-destructive, so safety is covered; the description adds real context by noting that `content` here is the same structure as in the list result, which tells the agent what to expect from the focused fetch. It does not cover what happens for an unknown or out-of-scope item_id, and does not mention the athlete_id scoping for coaches, leaving a small 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?

Two short sentences, front-loaded with the operation and followed by the sequencing constraint, with zero filler. Every clause carries information.

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

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

An output schema exists, so return-value detail is not needed, and the sequencing plus the content-field equivalence give the agent enough to call it correctly. Only the edge behavior (missing ID, athlete scoping) is unaddressed, which is minor for a read-only lookup.

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

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

Schema description coverage is 100% with only two simple parameters, so the schema already carries the parameter meaning; the description adds nothing about item_id format or the athlete_id coach-scoping parameter. 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 ('Fetch the full configuration of ONE custom addition by ID') and the emphasis on 'ONE' plus 'by ID' distinguishes it cleanly from the sibling icu_get_custom_items list tool. An agent can pick between them 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?

'Use AFTER icu_get_custom_items has returned an ID' names the sibling and the exact precondition, and adds the user intent ('wants to inspect a specific chart/field/zone/panel') that selects this tool over the list. This mirrors the strongest calibration example for 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 readOnly/idempotent/non-destructive, so the description focuses on behavior: one call returns every custom item across all types, with an enumerated list of the type categories and the note that each item carries a `type` field so filtering is client-side. That is real behavioral context (no server-side type filter). It stops short of saying anything about result volume or pagination for large accounts, which is the main remaining unknown.

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

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

Front-loaded with the purpose, then usage triggers, then the return inventory, then exclusions — a clean information hierarchy. The long parenthetical enumeration of chart/field/stream/zone types is dense, but it earns its space by telling the agent exactly what comes back; the example utterances could be trimmed slightly without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, yet the description still summarizes the aggregate return shape and the per-item `type` discriminator, which is exactly the context an agent needs to decide between one broad call and a targeted one. Combined with the explicit exclusion routing, nothing needed 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?

There is only one optional parameter and the schema already documents it at 100% coverage ('Athlete ID (for coaches managing multiple athletes)'). The description adds nothing about athlete_id — no default-athlete behavior, no coach-context guidance — so this sits at the baseline for a fully described single parameter.

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

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

States a specific verb and resource ('List the user's custom additions to their Intervals.icu account') and immediately scopes it as read-only inventory of the user's own customizations. It distinguishes itself from siblings by naming the built-in equivalents (sport settings, profile data) that live in other tools, 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?

Gives concrete trigger phrasings ('show my custom charts', 'what custom zones do I have') and an explicit exclusion clause: do NOT use for built-in zones, built-in fields, or athlete profile data, with icu_get_sport_settings named as the alternative. Both the when and the when-not are stated outright.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context about the returned details (description, workout structure, metrics), but does not disclose anything about errors, permissions, or pagination.

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

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

A single, front-loaded sentence with no wasted words. The key constraint, fetching exactly one event by ID, is stated 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, full parameter descriptions, and annotations covering safety, the description is nearly complete for this simple read tool. It could add a note about using athlete_id for coach access, but that is already in the schema.

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

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

Schema description coverage is 100%, so event_id and athlete_id are already documented in the schema. The description only restates that retrieval is by ID and adds no extra parameter semantics, which is the expected baseline.

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

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

The description states a specific verb and resource: fetch one calendar event by ID. The emphasis on 'ONE specific' implicitly contrasts with list-oriented siblings like icu_get_calendar_events, but no sibling is named explicitly.

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

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

Usage is implied by 'by ID': call this when you already have an event ID and need that single event. It does not explicitly say when not to use it or name the list tool as the way to discover IDs.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by explaining that the series includes past history plus future projections from planned calendar workouts, which clarifies the data source and scope. It does not cover pagination or auth requirements, but those are minor given the rich annotations and output schema.

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

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

The description is front-loaded with the core purpose and return values, followed by compact 'Use for' and 'NOT for' routing lines. Every sentence earns its place: there is no filler, and the exclusions are directly tied to sibling alternatives.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 output schema exists, the description need not explain return values, and the annotations cover safety and idempotency. The description is complete for this tool: it explains purpose, data source, when to use it, and when to use a sibling instead. Nothing an agent needs in order 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%, so all three parameters (days_back, days_ahead, athlete_id) are already fully documented in the schema. The description implies that days_back covers past history and days_ahead covers projections, but it does not add syntax, units, or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Fetch), resource (Performance Management Chart time-series), and the exact metrics returned (daily CTL, ATL, TSB). It explicitly distinguishes itself from sibling tools like icu_get_fitness_summary and icu_get_wellness_data, 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?

Provides explicit positive use cases ('show my fitness chart', 'CTL trend last 90 days', projected TSB) and explicit negative cases with named alternatives for training recommendations, HRV/sleep trends, and single-day wellness records. This is exactly the when/when-not/alternatives guidance that enables correct tool routing.

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

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

Annotations already declare this a safe, idempotent, open-world read, so the description focuses on what the read returns (interpretation and recommendations, not just raw numbers) and on the identity default. That default-to-authenticated-athlete behavior is real context absent 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?

The metric list and the core purpose are front-loaded, followed by usage examples and the one parameter caveat. Every sentence carries information and there is no filler or repetition.

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

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

With an output schema present, return structure need not be explained, and the one optional parameter is fully covered. For the intended training-status use case nothing essential is missing; only a contrast with the sibling fitness-chart tool would make it airtight.

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

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

Schema coverage is 100%, but the description still adds the key semantic that omitting athlete_id reads the authenticated athlete and that coaches supply the id to read a managed athlete. This goes slightly beyond the schema's 'for coaches managing multiple athletes' note.

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

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

States a specific verb+resource ('Get an athlete's current fitness / fatigue / form snapshot') and enumerates the exact metrics (CTL, ATL, TSB, ramp rate). It does not explicitly distinguish itself from the nearby icu_get_fitness_chart tool, so the agent must infer snapshot-vs-chart.

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

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

Provides concrete trigger phrases ('how's my form?', 'am I overtrained?', training-status checks) that map user intent to the tool. It also clarifies the coach vs. self-read case, but never states when to prefer a different tool such as the fitness chart.

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 this as a read-only, idempotent, non-destructive open-world query, so the safety profile is covered. The description adds real semantic context beyond that: it explains that the output is a time-in-zone distribution and that values are elevation-normalized. It does not discuss cost, pagination, or data availability for activities without elevation data, which keeps it out of the top band.

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

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

Two short sentences, with the core definition and the elevation-normalization qualifier front-loaded before the sibling redirect. Every clause carries information; nothing 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 not be explained, and the annotations cover the safety profile. With a single fully documented parameter and a clear statement of what the histogram represents, nothing an agent needs to call 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?

There is only one parameter (activity_id) and schema description coverage is 100%, so the schema fully carries the load. The phrase 'within a single activity' reinforces the scoping but adds no syntax or constraint detail beyond the schema, which matches the baseline for fully documented parameters.

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

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

States a specific operation (time-in-zone distribution of grade-adjusted pace), a specific scope (a single activity), and the key qualifier (elevation-normalized). It also names the sibling it is not, so an agent can distinguish it from icu_get_pace_histogram without opening either schema.

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

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

Gives an explicit use case (trail running where raw pace is misleading) and an explicit routing rule to the alternative (raw pace -> icu_get_pace_histogram). Both when-to-use and when-to-use-something-else are stated outright.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the useful scope word 'all' and names the stat categories returned, but says nothing about pagination, whether archived/retired gear is included, or how reminders are surfaced — and the output schema already documents return shape.

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

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

A single well-formed sentence with the resource first and the returned data enumerated parenthetically. No filler, no redundancy.

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

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

For a one-optional-parameter read-only list tool with annotations and an output schema, the description is nearly sufficient — return content is sketched and scope is stated. The remaining gap is the default behavior when athlete_id is null, which is the only decision an agent actually has to make.

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

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

Only one optional parameter (athlete_id) exists and schema description coverage is 100%, so the schema already explains the coach/multi-athlete scoping. The description adds no meaning beyond it — it does not say what happens when athlete_id is omitted, which is the one ambiguity the schema leaves open.

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

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

Specific verb + resource ('List all gear items') plus an enumeration of the contents (distance, time, activity count, maintenance reminders). It is the only read/list gear tool among siblings dominated by create/update/delete gear operations, so the agent can identify it without ambiguity, though the description never explicitly contrasts itself with those mutators.

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

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

Usage is implied by the verb 'list all' — the agent can infer this is the retrieval endpoint for gear inventory. However there are no explicit when-to-use/when-not statements, no mention of prerequisites (e.g. authentication or athlete scoping), and no reference to the sibling gear-mutation tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds genuine value by disclosing that peak_hr_bpm is the curve's top and has been clipped to configured max HR at import, plus that zone bands are NOT returned. It stops short of describing pagination, aggregation mechanics across the window, or how multiple activities are combined.

Agents need to know what a tool does to the 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 the tool returns, then intended use, then exclusions. Every clause carries information; the em-dash parenthetical defines the curve precisely rather than padding.

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

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

An output schema exists, so return shape need not be described, and annotations cover safety. The description is complete regarding misuse risks (zones, max HR, histogram confusion). The remaining gap is the days_back vs time_period precedence, which neither description nor schema resolves.

Complex tools with many parameters or behaviors need more documentation. Simple 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 all four parameters; baseline is 3. The description only alludes to 'the chosen window' without clarifying how days_back and time_period interact or which takes precedence — the one ambiguity in an otherwise well-covered schema.

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

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

States a specific verb and resource — 'Fetch the HR-vs-duration curve — best (highest) sustained HR across durations from 5s up to 1h, aggregated over the chosen window' — with the aggregation scope spelled out. This cleanly separates it from icu_get_power_curves, icu_get_pace_curves and icu_get_hr_histogram without opening any schema.

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

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

Gives an explicit intended use ('Use for cardiovascular-fitness trends') and names two alternatives with their selecting conditions: icu_get_sport_settings for HR zones/max HR, and get_hr_histogram for time-in-zone distribution. 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, non-destructive and openWorld, so the safety profile is covered. The description adds a real behavioral distinction beyond that: results are scoped to one activity and expressed as bucket/time-per-bucket rather than cross-activity best efforts. No auth, rate-limit, or cost notes, which keeps it from a 5.

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

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

Three short fragments, front-loaded with the core result shape, then the sibling contrast, then the use case. No repetition of the name and no wasted clauses.

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

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

An output schema exists, so return-value explanation is correctly omitted; the description covers purpose, scope, and the main alternative. Only marginal omissions remain (e.g., what happens if the activity lacks HR data), which are low-risk for a read-only single-parameter tool.

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

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

Schema coverage is 100% and the single parameter is self-documented as 'Activity ID to analyze', so the description adds nothing about the parameter. Baseline 3 applies when the schema carries the full burden.

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

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

States a specific verb and resource (time-in-zone distribution of heart rate) plus an explicit scope: a single activity, with histogram buckets and time per bucket. It also names the sibling it is not (icu_get_hr_curves, best efforts across many activities), so an agent can separate it from the multi-activity curve tools 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 context ('cardiovascular load breakdown and HR-zone time-in-zone') and explicitly routes the multi-activity best-efforts case to icu_get_hr_curves. No explicit when-not conditions or mention of the pace/power histogram siblings, so it falls short of the top tier.

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 non-destructive, so the description is free to spend its words on substance: the duration range covered, the aggregation window, and that use_gap applies Grade-Adjusted Pace normalization for hills. It does not discuss athlete scoping or whether results are per-activity or cross-activity beyond 'aggregated over the chosen window'.

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

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

Three compact sentences, front-loaded with what the tool returns, then the use case, then the sibling redirect. No restatement of the name 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?

An output schema exists so return values need not be described, and all five parameters are documented in the schema. The only gap is the absence of guidance on athlete_id scoping for coaches and on precedence between days_back and time_period, which matters for a windowed aggregation tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that use_gap normalizes for hills (the schema only names GAP) and that results are aggregated over the chosen window, which ties days_back and time_period together. It does not clarify how days_back and time_period interact when both are supplied.

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

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

States a specific verb and resource ('Fetch the pace-vs-duration curve') and immediately pins down the semantics: best sustained pace across 5s to 1h, aggregated over the chosen window. That is enough to separate it from icu_get_pace_histogram and other curve tools without opening a schema.

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

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

Gives a positive use case ('run/swim fitness trends and race-time predictions') and an explicit exclusion with the named alternative: use get_pace_histogram or get_gap_histogram for time-in-zone distribution within a single activity. Both when-to-use and when-not-to-use are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds scope detail not in annotations — analysis is confined to a single activity and returns bucketed time-in-zone rather than summary values. It does not say anything about bucket resolution, zone boundaries, or behavior for activities lacking pace data, so it falls short of a 5.

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

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

Four short sentences, zero filler, with the core definition front-loaded and differentiation/routing trailing. Each sentence carries distinct information: what it is, how it differs, when to use it, and the GAP alternative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the return format and annotations covering safety, the description supplies the remaining essentials: single-activity scope, distribution semantics, and sibling routing. Minor gaps remain around what happens when pace data is absent or how buckets are defined, but nothing critical to correct invocation is missing.

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

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

Only one parameter exists and schema coverage is 100%, so the schema already documents activity_id fully. The description reinforces scope ('within a single running activity') but adds no format, ID-source, or constraint details beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Time-in-zone DISTRIBUTION of pace within a single running activity,' and clarifies the return shape (histogram buckets, time per bucket). It explicitly distinguishes itself from two siblings (icu_get_pace_curves, icu_get_gap_histogram), so an agent can select it without opening any schema.

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

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

Gives an explicit when-to-use ('pace-distribution / consistency analysis'), names the scoping difference from icu_get_pace_curves (one activity vs many), and routes elevation-normalized use to icu_get_gap_histogram. Both alternatives and the condition selecting each 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 safety (readOnly, idempotent, non-destructive), so the description's job is added context, which it delivers: the mutual-exclusivity rule for window parameters, the 90-day default, and the fact that fitted models (CP, W', Pmax, FTP), VO2max and MAP are included when available. It does not mention result size, rate limits, or what happens if multiple windows are supplied.

Agents need to know what a tool does to the 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 usage, then window selection, then the sibling exclusion — a sensible order with no filler. The middle sentences run a bit long, but every clause carries meaning.

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

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

An output schema exists, so return values need not be spelled out, and the description still summarizes the payload shape (sustained watts/W/kg plus fitted models and VO2max/MAP). For a nine-parameter, all-optional read tool, nothing an agent needs in order 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 baseline is 3; the description earns above that by explaining the either/or relationship among days_back, time_period, start_date/end_date, season and periods, and by showing a multi-period example (['s0', 's1', 'all']). It does not mention sport_type or full_curve, but those are well documented in the schema.

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

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

States a concrete verb and resource plus scope: 'power-vs-duration curve — best (highest) sustained watts and W/kg across durations from 5s up to 6h, aggregated over the chosen window.' It also distinguishes itself from the nearest lookalike by naming icu_get_power_histogram as the tool for in-activity distribution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use cases (FTP estimation, peak-power tracking, durability, strengths/weaknesses) and an explicit exclusion routing to icu_get_power_histogram. It also states the selection rule among window parameters — 'Pick ONE window' — and that the default is the last 90 days.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious context: the result is a distribution of time across power buckets for exactly one activity, which tells the agent what the data represents and that it is scoped per-activity, not aggregate.

Agents need to know what a tool does to the 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 definition, then a contrast sentence, then example queries. Three short lines with little waste; the closing example phrasing is slightly redundant but earns its place as a routing cue.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and the single parameter is fully documented, so the description needn't explain return values. What remains is the scoping and sibling distinction, both covered. A mention of bucket/zone configuration expectations would round it out, but 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?

Only one parameter, and schema description coverage is 100% ('Activity ID to analyze'), so the schema carries the semantics. The description's 'within a single activity' mildly reinforces the scope but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb/resource combination: time-in-zone distribution of power within a single activity, plus the output shape in parentheses (histogram buckets, time per bucket). It explicitly contrasts itself with icu_get_power_curves, so an agent can distinguish it from the most confusable 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?

Names the alternative (icu_get_power_curves) and the condition that selects this tool: 'best efforts across many activities' vs single-activity distribution, reinforced by example phrasings ('how was my workout intensity distributed?'). It gives positive selection criteria but no explicit exclusions (e.g. what to use for non-power histograms, though hr/pace/gap siblings are obvious from names).

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, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that by disclosing the response shape is deliberately lightweight and enumerating the summary fields, which tells the agent this call is cheap and not a full-detail fetch. It does not mention pagination or rate limits, keeping it short of a 5.

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

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

Two short sentences: the capability and its output shape come first, then the disambiguation. Every clause carries information, and the quoted user phrasings are compact and directly usable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, annotations cover the safety profile, and the schema fully documents all three optional parameters. The description fills the remaining gap that structured fields cannot express: what the summary contains and which sibling to pick instead.

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

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

Schema description coverage is 100% with all three params documented, so the baseline is 3. The description only echoes the default window (last 30 days) that days_back already declares in the schema, adding no new meaning for limit or athlete_id, so no credit above baseline.

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

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

States a specific verb and resource ('List the athlete's most recent activities') with explicit default scope (last 30 days) and a concrete characterization of the payload ('LIGHT summary per item' naming distance, duration, power, HR, training load). It also names the two sibling tools it is not, so the agent can distinguish it without opening any schema.

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

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

Gives explicit trigger phrasing ('what have I done recently?', 'show last week's rides') and routes alternatives by condition: 'For one specific activity by ID use icu_get_activity_details; to search by name/tag use icu_search_activities.' Both the when-to-use and the when-to-use-something-else are present.

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?

While annotations cover safety, the description adds critical operational behavioral traits, specifically that 'A season runs until the day before the next one starts' and that 'the newest season is open-ended.' This is crucial business logic not in the schema.

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

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

The description is highly efficient, front-loading the core purpose first, followed by usage context, and finally, specific technical constraints. Every sentence adds significant 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?

The combination of functional explanation, workflow integration with dependent tools, and defining season boundaries makes this definition exceptionally complete for an agent.

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

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

With 100% schema coverage, the description does not need to elaborate on the nature of the parameters. It provides context (for coaches managing multiple athletes) but does not add semantic meaning beyond the schema's definition. Baseline score appropriate.

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

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

The description immediately and clearly states the function ('List the athlete's training SEASONS') and identifies the data returned (name, start, end, curve ID). It is highly distinct from sibling tools.

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

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

It provides clear usage scenarios ('which seasons do I have?') and explicitly defines the sequence of use, directing the agent to call `icu_get_power_curves` after retrieving the season's `curve_id`.

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 read-only annotations, the description discloses important behavioral context: zones are derived from thresholds unless set explicitly, are stamped into activities at import, and drive time-in-zone, HRSS, and TSS calculations. This gives the agent crucial domain context for interpreting and trusting the returned zones.

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

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