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

While annotations already signal a non-read-only write operation, the description adds that the message is attributed to the authenticated user. However, it does not elaborate on other behavioral aspects like visibility or modifications beyond attribution. With annotations present, this is adequate but not rich.

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

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

The description is extremely concise—just a few sentences that immediately state the action, provide usage examples, and differentiate from a sibling. Every sentence adds value, and no extraneous information is present.

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

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

For a simple write operation, the description provides essential context: what it does, examples, and alternative. The output schema exists to cover return values. It might miss a note on whether the message is private or visible, but overall it is complete enough.

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

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

The input schema covers both parameters with descriptions, achieving 100% coverage. The description adds minimal value, only restating 'note or comment' similar to the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (POST a new note or comment) and resource (on a specific activity). It explicitly distinguishes from the sibling tool icu_get_activity_messages for reading, ensuring no confusion.

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

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

The description explicitly says when to use this tool (when user wants to leave a note/comment) and provides concrete examples. It also tells when not to use it and directs to the alternative for reading.

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, openWorldHint=true, so the agent knows this mutates state. The description adds useful scope context by stating the recomputation hits HISTORICAL activities broadly, but it does not say what exactly is overwritten, whether the change is reversible, or what permissions/athlete scoping apply.

Agents need to know what a tool does to the 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 core action, followed by the sibling distinction and the usage trigger. No redundant or filler text; every sentence carries information.

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

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

Because an output schema exists, return values need not be explained, and the description covers the what, when, and the alternative. It is nearly complete for a bulk-mutation tool, with only minor missing detail on authorization/athlete scoping given the destructive and open-world nature.

Complex tools with many parameters or behaviors need more documentation. Simple 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 sport_id and athlete_id are already documented in the schema. The description adds no additional parameter-level meaning (no format, defaults, or scoping nuance beyond what the schema provides), so a baseline 3 is appropriate.

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

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

The description names a specific verb ('Recompute') and concrete resources ('training load, zones, and derived metrics on HISTORICAL activities'), so an agent knows exactly what the tool does. It also explicitly contrasts itself with the sibling update_sport_settings, which 'just stores new values,' making the boundary between the two unambiguous.

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

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

It gives a clear triggering condition ('Use after changing FTP/FTHR/pace to backfill chart math') and names the alternative it is not (update_sport_settings). The only gap is that it does not state when NOT to use it (e.g., for new activities or live data), so it lacks an explicit exclusion.

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 destructiveHint=true and readOnlyHint=false. The description adds no behavioral details beyond scheduling onto calendar; it does not contradict annotations but also lacks extra context like whether it overwrites or merges events. With annotations present, a score of 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?

Three well-structured sentences: first states purpose, second provides prerequisite, third differentiates from alternatives. No unnecessary words, fully front-loaded.

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

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

Given the tool has an output schema and moderate complexity, the description covers purpose, prerequisite, and differentiation. Return values are handled by the output schema, so the description is complete.

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

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

Input schema has 100% coverage with descriptions for all 4 parameters. The description does not add parameter-level details beyond what the schema already provides, so baseline score of 3 is justified.

Input schemas describe structure but not intent. Descriptions should explain 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 action ('Schedule an entire training plan...onto the athlete's calendar') and the resource ('workout-library folder'), distinguishing it from sibling tools like icu_create_event, icu_bulk_create_events, and icu_duplicate_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?

Explicitly mentions to use after icu_get_workout_library to obtain the folder_id, and directly contrasts with three alternative tools (icu_create_event, icu_bulk_create_events, icu_duplicate_events), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false and destructive=false, so the safety profile is covered. The description adds batch semantics and points to the relevant resources, but says nothing about partial-failure behavior, validation/rejection of malformed payloads, or whether the whole batch is atomic — a meaningful gap for a non-idempotent bulk write.

Agents need to know what a tool does to the 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 top-level description is three tight sentences, front-loaded with the batch scope and immediately followed by the alternative. The enormous workout-syntax detail is carried by the schema parameter, not the description, so the description itself stays lean.

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

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

Given an output schema exists, return values need no explanation, and the description covers scope, payload shape, the sibling alternative, and resources for enums/DSL. For a tool this complex the only missing piece is failure/atomicity behavior of the batch.

Complex tools with many parameters or behaviors need more documentation. Simple 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 extensive param documentation already lives in the schema. The description contributes only framing ('each shaped like an icu_create_event payload') and resource pointers, which is the expected baseline 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 (create), resource (calendar events) and scope (MANY / single batch call), and explicitly distinguishes itself from both icu_create_event and icu_duplicate_events. An agent can route between the three 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 an alternative and the condition that selects it ('For copying existing events forward use icu_duplicate_events instead'), and justifies the tool's existence vs looping create_event. It does not spell out when a single create_event is preferable to the bulk form, but the batch-vs-loop framing covers most of the routing decision.

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 description discloses key behavioral traits beyond annotations: the UPSERT logic (updating existing records), the condition of matching external_id within the same OAuth app, and the exclusion of device uploads. Annotations already mark it as destructive and non-readOnly, but the description explains the specific destructive mechanism and auth scope.

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

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

The description is two sentences, front-loaded with the core purpose and then elaborating on behavior. Every sentence adds value without redundancy. No filler or unnecessary words.

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

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

Given the presence of output schema and annotations, the description covers the essential behavioral contract: upsert logic, manual-only scope, and OAuth app restriction. It could mention error handling or batch size limits, but is mostly complete for practical use.

Complex tools with many parameters or behaviors need more documentation. Simple 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 adds significant meaning: it explains that activities_json contains the external_id field for upsert matching, and clarifies athlete_id is for coaches. This goes beyond the schema descriptions, which only name the parameters.

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

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

The description clearly states the tool performs batch creation of manual activities with UPSERT behavior, and distinguishes itself by specifying 'no device upload' and the unique upsert-on-external_id mechanism. This differentiates it from siblings like icu_bulk_create_events and individual activity 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?

The description explains the upsert behavior and OAuth app constraint, providing clear context for when to use this tool (for batch manual activity management with external_id matching). However, it does not explicitly state when not to use it or mention alternatives, such as individual create/update 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 indicate a mutating, non-idempotent, open-world operation. The description adds the important behavioral constraint 'Nothing lands on the calendar', clarifying side effects and scope. It does not cover partial-failure behavior or auth requirements, but annotations cover the safety profile, so the added context earns a 4.

Agents need to know what a tool does to the 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 with no filler. The core purpose is front-loaded in the first sentence, and the alternative routing is packed into the remainder. 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 rich schema covering the complex workouts parameter, the presence of an output schema, and annotations, the description is complete enough for an agent to select and invoke the tool correctly. It explains scope, gives examples, and names the alternatives for adjacent use cases.

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

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

Schema coverage is 100%, and the schema itself contains an extensive description of the workouts string syntax and athlete_id parameter. The tool description only repeats that items are shaped like icu_create_workout calls, which adds little beyond what the schema already states. 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 ('Save'), resource ('reusable workouts'), and scope ('LIBRARY folders or plans'), with an example ('filling out a training plan'). Explicitly distinguishes from siblings by naming icu_bulk_create_events and icu_apply_training_plan as alternatives for calendar use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use and when-not-to-use guidance: 'for dated calendar workouts use icu_bulk_create_events, and to schedule a finished plan use icu_apply_training_plan.' Also notes each item is shaped like an icu_create_workout call, guiding bulk vs single invocation.

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 set destructiveHint=true, idempotentHint=true. The description adds behavioral context: the safe mode partition (deleted vs skipped) and the env var override. 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?

Description is brief (three sentences) but packed with essential info: purpose, destructiveness, safe mode behavior, and env var. No redundant words.

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

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

Given the output schema exists and annotations cover safety, the description adequately explains the core behavior (bulk deletion with safe partitioning). It omits details like rate limits or auth, but those are implicit from annotations and context.

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

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

Input schema has 100% coverage with descriptions for both parameters (event_ids as JSON array, athlete_id optional). The description adds no extra parameter-specific meaning beyond what the schema provides.

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

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

The description clearly states 'Delete MANY calendar events in a single batch call', specifying the verb, resource, and scope. It distinguishes from siblings like icu_delete_event and icu_bulk_create_events, as the tool name implies.

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

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

The description warns 'Destructive — cannot be undone', and explains the safe vs full delete modes with env var control. While it doesn't explicitly list when not to use, it provides clear context for selecting this tool over alternatives.

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

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds context about reading external schemas but does not disclose additional traits like permission requirements, rate limits, or side effects beyond creation.

Agents need to know what a tool does to the 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 three sentences long with no wasted words. It front-loads the purpose, then provides usage examples, and finally directs to additional resources. Perfectly concise.

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

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

Given the tool's complexity (multiple item types with varying content schemas), the description covers core usage and points to external resources for details. It does not explain return values, but an output schema exists. A minor gap is the lack of error handling or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple 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 baseline is 3. The description adds value by pointing to intervals-icu://custom-item-schemas for the content parameter, which is essential for correct usage.

Input schemas describe structure but not intent. Descriptions should explain 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 verb 'Create a custom addition' and specifies the resource 'user's Intervals.icu account'. It provides examples of user intents, making it easy to distinguish from sibling tools like icu_update_custom_item.

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

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

The description explicitly tells when to use the tool by listing example user statements ('add a custom field for RPE', etc.) and advises matching intent to item_type. It also references an external schema for content construction, providing clear context.

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 is a non-read-only, open-world, non-destructive, non-idempotent mutation. The description adds useful context: it creates exactly one event, workout syntax in the description field is parsed into structured device-syncable steps, and alternative tools should be used for bulk or duplication. It does not warn about duplicate event creation on retry or mention permission prerequisites, but overall it adds meaningful behavioral context beyond the annotations.

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

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

Three tightly focused paragraphs. The purpose and scope are front-loaded, alternatives are enumerated clearly, and resource pointers close the description without redundant detail. Every sentence adds 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 a 15-parameter mutation tool with an output schema, the description covers its purpose, sibling alternatives, and relevant resources, while the schema covers parameter details. A minor gap is the absence of an explicit non-idempotency warning about retries creating duplicates, but annotations and the bulk/duplicate routing largely cover the agent's needs.

Complex tools with many parameters or behaviors need more documentation. Simple 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 documents all 15 parameters in detail, including the workout syntax. The description points to the same resources the schema already references and adds no new parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

States a specific verb (create) and resource (calendar event) with scope clarified as 'ONE new calendar event from scratch.' It differentiates from sibling tools by explicitly naming icu_bulk_create_events and icu_duplicate_events and describing when each applies.

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

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

Explicitly routes multi-event creation to icu_bulk_create_events and existing-event duplication to icu_duplicate_events. It also specifies which resource to consult for category and training_availability guidance, leaving no ambiguity about when to use this tool.

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

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 safety profile is covered structurally. The description adds no behavioral context beyond that: it says nothing about duplicate names (relevant given idempotentHint=false), permission requirements, or whether the new gear is auto-assigned to activities.

Agents need to know what a tool does to the 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, resource second, and domain examples last. No filler, no repetition of schema or annotation 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile; the description covers purpose adequately for a 4-parameter create tool. The only real gap is the absence of any note on duplicate handling or the coach/athlete_id scenario.

Complex tools with many parameters or behaviors need more documentation. Simple 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 name, active, gear_type and athlete_id are all documented in the schema itself, including the gear_type vocabulary list. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Create a new gear item') and clarifies the domain with concrete examples (bikes, shoes, trainers). It is distinguishable from icu_update_gear, icu_delete_gear and icu_get_gear_list by the verb, though it does not explicitly call out the near-neighbor icu_create_gear_reminder.

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

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

The phrase 'for tracking equipment usage and maintenance' implies why an agent would create gear, but there is no explicit when-to-use statement, no prerequisite (e.g. athlete_id for coaches), and no named alternatives. Usage is inferable rather than stated.

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

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

Annotations declare write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds that the reminder can be triggered by distance, time, or both, which is behavioral context beyond the annotations. However, it doesn't mention what happens on duplicate creation, permission needs, or whether the reminder is immediately active.

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

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

One sentence that front-loads the action and resource, with zero wasted words. The trigger condition is integrated 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 presence of an output schema, the description needn't explain return values. It covers the core purpose and trigger mechanism. Missing usage guidelines and any edge-case behavior, but for a straightforward creation tool with full schema coverage and annotations, it's largely complete.

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

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

Schema coverage is 100%, so all five parameters are fully described in the schema. The description adds no new parameter meaning beyond the schema; the only added value is the trigger concept, which aligns with the existing distance_alert/time_alert parameters. 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 (Create) and resource (maintenance reminder for a gear item), and the trigger mechanism (distance, time, or both) distinguishes it from siblings like icu_create_gear or icu_update_gear_reminder. No ambiguity about what the tool produces.

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

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

No guidance on when to use this versus icu_update_gear_reminder, nor any note about prerequisites (e.g., gear must exist). The description only says what it does, not when to choose 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 this as a non-read-only, open-world, non-idempotent, non-destructive write. The description adds that the record is per-sport and enumerates the threshold families, but says nothing about duplicate handling, authorisation, or what happens to existing records. With annotations covering the safety profile, this is a modest but real addition.

Agents need to know what a tool does to the 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 a clear verb and a compact enumeration of the covered metrics. 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?

An output schema exists, so return values need not be described. However, as a mutation on a resource that also has get/update/apply siblings, the absence of usage routing and mutation semantics leaves the definition only minimally complete.

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

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

Schema description coverage is 100%, so every one of the 7 parameters is already documented in the schema with useful detail (units, examples, coach context). The description only echoes the metric families and adds no format or constraint information beyond what the schema provides. 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 states a specific verb (Create) and resource (per-sport threshold record) and enumerates the covered metric families (outdoor/indoor FTP, FTHR, pace, swim). It does not name the sibling tools or explain how it differs from create_sport_settings, get_sport_settings, or update_sport_settings, so it stops short of 5.

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

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

There is no when-to-use guidance, no indication of when to choose create vs update_sport_settings or apply_sport_settings, and no prerequisites. The agent is left to infer usage from the name alone.

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

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

Annotations already indicate a non-read-only, non-destructive write operation. The description adds useful behavioral context beyond that: it saves a single reusable workout to a library or plan, does not touch the calendar, and is not bulk. It doesn't detail potential side effects like duplicate creation on repeated calls, but the idempotentHint=false annotation already signals that risk.

Agents need to know what a tool does to the 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 concise, front-loads the core purpose and key exclusion, and then efficiently routes to all relevant sibling tools in three sentences. Every sentence adds actionable value with no filler.

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

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

For a 13-parameter write tool with an output schema and 100% schema coverage, the description adequately covers the operation's scope, destination, and sibling alternatives. The detailed parameter semantics and return structure are already handled by the schema, so nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The outer description does not add parameter-level semantics beyond the schema, though the schema itself contains an extensive workout syntax reference for the description parameter. The description's main contribution is clarifying the destination (library folder or plan), which is already partially reflected by folder_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 states a specific verb ('Save'), a precise resource scope ('ONE new reusable workout into a LIBRARY folder or training plan'), and an explicit exclusion ('it does not go on the calendar'). It also differentiates itself from related siblings by naming create_event, bulk_create_workouts, and update_workout.

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

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

The description gives explicit routing guidance for exactly when to use this tool versus alternatives: calendar scheduling goes to icu_create_event, multiple library workouts go to icu_bulk_create_workouts, edits go to icu_update_workout, and folder/plan creation goes to icu_create_workout_folder. This leaves no ambiguity about the intended use 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 indicate this is a mutating, non-idempotent, non-destructive operation, and the description's 'Create' is consistent with that. Beyond annotations, it adds useful context: the object belongs to the workout library rather than the calendar, and the result is meant to be consumed as a folder_id by other tools.

Agents need to know what a tool does to the 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, no fluff, with the core purpose front-loaded and the downstream usage stated immediately after. Every sentence earns its place.

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

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

For a create tool with only one required parameter, full schema coverage, and an output schema, the description provides enough orientation: what is created, what it is not, how to use the result, and where to look for existing folders. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents name, athlete_id, description, and folder_type. The description adds no new parameter-level detail beyond reinforcing the FOLDER/PLAN distinction, which is already present in the schema.

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

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

The description states a specific verb and resource ('Create a new LIBRARY folder or training PLAN') and immediately distinguishes this from a calendar item, which separates it from event-creation siblings. It also names the downstream workflow, so an agent knows exactly what the tool is for.

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

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

It explicitly says what this tool is not ('not a calendar item'), where the returned id should be passed (icu_create_workout or icu_bulk_create_workouts), and how to browse existing folders (icu_get_workout_library). This gives clear when-to-use and alternative 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?

Beyond annotations (destructiveHint=true), the description adds that deletion is permanent and cannot be undone, and details the safe mode refusal of past events and the envelope responses.

Agents need to know what a tool does to the 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 two sentences, front-loaded with the key action and destructive nature, followed by mode and response details. No wasted words.

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

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

For a simple deletion tool with an output schema, the description covers the essential behavior (permanent delete, safe mode, response format) without needing to explain return values.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add additional meaning beyond what the schema provides.

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

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

The description clearly states it permanently deletes ONE calendar event by ID, distinguishing it from sibling tools like icu_bulk_delete_events (bulk) and icu_update_event (update).

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

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

The description explains the destructive nature and safe mode behavior, but does not explicitly mention when to use this tool versus alternatives. However, the name and context imply single-event deletion.

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

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

The annotations already indicate destructive=true, idempotent=true, and readOnly=false. The description adds crucial context not covered by annotations: the deletion is permanent, it cascades to maintenance reminders, and it does not affect activities. This is valuable behavioral detail, though it doesn't mention authentication, rate limits, or recovery options.

Agents need to know what a tool does to the 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 concise sentences, front-loaded with the core action and followed by an important clarification. Every sentence earns its place with no redundancy.

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

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

Given the tool's destructive nature and the presence of an output schema, the description provides all necessary context: it confirms permanence, mentions the cascade to reminders, and clarifies that activities are unaffected. The annotations and output schema cover the rest.

Complex tools with many parameters or behaviors need more documentation. Simple 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 both parameters. The description does not add any parameter-specific information beyond what the schema provides, which is the baseline expectation (3) when schema coverage is high.

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

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

The description states a specific verb ('Permanently delete'), a specific resource ('gear item'), and explicitly scopes the effect ('and its maintenance reminders' / 'Activities that used this gear are not affected'). This distinguishes it from sibling tools like icu_update_gear and icu_create_gear_reminder.

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

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

The description clearly conveys when to use this tool (to delete a gear item) and the scope of the deletion, including that activities are unaffected. However, it does not mention alternatives (e.g., archiving vs. deleting) or prerequisites, 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?

Even though destructiveHint is already set, the description adds important context: the deletion is permanent and cannot be undone, it applies only to library workouts, and it does not delete associated calendar events. This goes beyond the annotation by clarifying exactly what gets destroyed and what does not.

Agents need to know what a tool does to the 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 with no filler. The destructive nature is front-loaded, followed by scope and the relevant alternative. Every sentence earns its place.

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

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

For a simple two-parameter destructive tool with a full output schema and supportive annotations, the description covers what is deleted, what is not deleted, how to delete related records, and a user-confirmation safeguard. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents workout_id and athlete_id. The description does not add new parameter-level meaning beyond confirming the singular 'ONE workout' target, but it also does not need to compensate for schema gaps.

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

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

The description states the exact verb and resource: 'Permanently delete ONE workout from the LIBRARY.' It also clearly distinguishes this from calendar-event deletion, which is handled by a different tool, so there is no ambiguity about what this tool operates on.

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

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

The description explicitly says when to use this tool versus alternatives: it deletes library workouts only, while calendar events must be deleted with icu_delete_event. It also instructs the agent to confirm with the user before calling if unsure, which is a clear usage safeguard.

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?

Discloses behavior beyond annotations: if output_path is set, file saved; otherwise base64 content. 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?

Three sentences, front-loaded purpose, then details. No unnecessary words, well structured.

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

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

Complete given output schema and input schema coverage. Covers core functionality, differentiation, and optional behavior.

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

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

Schema coverage 100% so baseline 3. Description adds context: output_path optional with save vs base64 behavior, adding value beyond 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?

Clearly states it downloads the original activity file (FIT, TCX, GPX) and distinguishes from sibling tools (download_fit_file, download_gpx_file). Verb and resource are specific.

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

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

Explicitly explains when to use this tool (for original file) vs alternatives (forced conversions), naming the sibling tools and their differences.

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 indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: the tool converts the activity to FIT format and targets Garmin/training platforms. This goes beyond annotations without contradicting them.

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

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

The description is two concise sentences. The first sentence specifies the core action, and the second provides differentiation. No unnecessary words, and the information is effectively front-loaded.

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

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

Given the presence of an output schema and high schema coverage, the description sufficiently explains the tool's purpose and how it differs from siblings. It does not need to explain return values since the output schema covers that.

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

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

Schema coverage is 100% and parameter descriptions are adequate. The description does not add new information about the parameters beyond what is in the schema, so it meets the baseline but does not exceed.

Input schemas describe structure but not intent. Descriptions should explain 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 verb 'Download' and the resource 'activity converted to FIT format', specifying its intended use for Garmin and training platforms. It explicitly differentiates from sibling tools by naming alternative formats, making the purpose unambiguous.

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

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

The description names two alternatives (download_activity_file and download_gpx_file) and explains their differences, guiding when to use this tool. However, it lacks explicit when-not-to-use scenarios or prerequisites, which would make it 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool converts the activity to GPX format, which is a specific behavioral trait beyond the annotations. No contradictions.

Agents need to know what a tool does to the 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 two sentences, front-loading the purpose and adding differentiation. Every word serves a purpose with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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's simplicity, strong annotations, and an output schema, the description is complete. It explains the conversion format and how it differs from siblings, leaving no obvious gaps for an agent.

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

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

The input schema already covers 100% of parameter descriptions (activity_id and output_path). The description does not add extra meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool downloads an activity converted to GPX format for GPS devices and mapping software. It explicitly distinguishes itself from sibling tools download_activity_file and download_fit_file by naming the formats, providing clear purpose and differentiation.

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

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

The description implies when to use this tool: when you need GPX format. It explicitly contrasts with two sibling tools, giving context for selection. While it doesn't list when not to use, the differentiation is strong enough for an agent to decide.

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?

Description notes that the tool reuses existing event payloads, adding context beyond annotations. Annotations indicate mutation (readOnlyHint false) but non-destructive (destructiveHint false). Minor gap: no mention of potential limits or side effects, but sufficient for typical use.

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

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

Three sentences, front-loaded with the core action, and no unnecessary words. Every sentence adds value, achieving maximum conciseness.

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

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

For a simple duplication tool with good annotations and output schema, the description covers purpose, usage, behavior, and differentiation completely. No missing information for effective use.

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

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

Input schema has 100% coverage with clear descriptions for all four parameters. Description does not add new parameter semantics beyond schema explanations. A score of 3 reflects that the schema already handles parameter meaning adequately.

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

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

Description clearly states the tool copies events forward in time using verb 'COPY' and specifies the resource ('existing events'). It explicitly distinguishes from sibling tools icu_create_event and icu_bulk_create_events, meeting the highest standard.

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

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

Description provides explicit usage scenarios with examples ('repeat this workout for the next 4 weeks') and clarifies when NOT to use it (when building new events from scratch), offering clear alternative 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds no behavioral context beyond that (no note on what happens if the reference activity is missing, ordering guarantees, or result shape). Minimum-viable but consistent with 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?

Two tight sentences, front-loaded with the operation and its distinctive symmetric-window semantics, followed by compact usage examples. No filler.

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

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

For a read-only tool with a full output schema and 100% schema coverage, the description supplies what is needed to select and call it. It could be slightly stronger with an edge-case note on an unknown activity_id, but nothing essential is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's '(N each side)' mildly reinforces the semantics of count, 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 ('Fetch') and resource ('activities') with a precise anchor: chronologically before and after a reference activity, N each side. This scope is inherently distinguishable from date-range or recent-activity siblings, though no sibling is named to make the contrast explicit.

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

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

Gives three concrete when-to-use triggers ('what did I do around this race?', training-context queries, progression comparisons), which is clear usage context. It stops short of stating when NOT to use it or naming an alternative such as a date-range or search tool.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds that results are newest-first, oldest dropped if limit exceeded, and that it returns a 'light summary.' These add context beyond annotations, but could further clarify what 'light summary' entails.

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

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

The description is extremely concise, using only a few sentences. It front-loads the core purpose, contrasts with a sibling, and uses bullet-like dashes for clarity. Every sentence serves a purpose with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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's complexity (4 params, output schema exists, rich annotations), the description is complete. It explains date window, ordering, limit behavior, and offers usage guidance. The output schema likely covers the return structure, so no further detail needed.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description reinforces date format (YYYY-MM-DD), defaults, and the limit's impact on dropping oldest items. It adds value by explaining behavior, but the schema already covers basic parameter meanings.

Input schemas describe structure but not intent. Descriptions should explain 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 that the tool lists activities within an explicit date window with a light summary. It specifies the verb 'list' and resource 'activities,' and immediately contrasts with the sibling icu_get_recent_activities, making its purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides when to use this tool vs. the sibling, including concrete use cases like 'all my runs from June to November 2025' and advice on handling the limit parameter. It also explains ordering and dropping behavior for oldest items.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds that it returns a single JSON blob with top-level metrics, which is additional behavioral context but doesn't contradict annotations. It doesn't disclose potential limitations like rate limits or authorization, but the safety profile is already well-covered.

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

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

The description is extremely concise, consisting of three sentences. The first sentence defines the tool's purpose, the second gives example use cases, and the third points to alternatives. Every sentence adds value and nothing is extraneous.

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

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

The tool has one simple parameter and an output schema exists. The description explains what the output contains (headline summary with top-level metrics). Given the low complexity, this description is fully complete for an agent to select and invoke the 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?

The input schema has one parameter (activity_id) with description 'Activity ID to fetch'. Schema description coverage is 100%, so the baseline is 3. The description does not add further meaning beyond the schema's own description, so it stays at 3.

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

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

The description clearly states it fetches the headline SUMMARY of one activity, listing specific metrics like name, sport, date, distance, duration, training load, weather, and all top-level metrics. It also distinguishes between this tool and its siblings icu_get_activity_intervals and icu_get_activity_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?

The description explicitly provides use cases (e.g., 'how was my ride?', 'tell me about activity X') and tells when not to use it: for lap-by-lap or per-interval breakdown use icu_get_activity_intervals, for second-by-second time-series use icu_get_activity_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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description does not need to repeat that. It adds value by describing the returned data structure (segments with targets, actuals, types). No contradictions or missing behavioral info.

Agents need to know what a tool does to the 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 three sentences, front-loaded with core purpose, followed by usage guidance. Every sentence adds value with 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?

For a tool with one parameter and an output schema, the description covers everything needed: what it returns, when to use it, and how it differs from related tools. The output schema handles return format details.

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

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

The only parameter, activity_id, is fully described in the input schema (100% coverage). The description does not add additional semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Fetch' and the resource 'per-LAP / per-interval breakdown of one activity', listing specific data elements (target, actual power/HR/pace, segment types). It distinguishes itself from sibling tools like get_activity_details and get_activity_streams, making the purpose unmistakable.

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

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

Explicit usage context is provided: 'workout-compliance analysis, lap-by-lap review', along with direct alternatives: 'For headline summary metrics use get_activity_details; for raw second-by-second data use get_activity_streams.' This is exemplary 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?

Beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), the description details the return format: 'every message in chronological order with author, content, timestamp, and seen-flag'. This adds meaningful behavioral context not present in annotations.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, and each sentence serves a clear role: definition, usage examples, return specification, and sibling differentiation. No wasted words.

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

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

The tool is simple (1 param, output schema exists, annotations clear). The description fully covers what the tool does, when to use it, what it returns, and its sibling relationship. No gaps for an agent to act on.

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

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

Schema coverage is 100% with the single parameter 'activity_id' already described. The description does not add further parameter semantics, but baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the verb ('Read') and resource ('notes and comments attached to a specific activity'). It also distinguishes itself from the sibling tool 'icu_add_activity_message' by marking it as READ vs WRITE, leaving no ambiguity about the tool's 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?

The description provides explicit when-to-use examples like 'what did my coach say about that ride?' and 'show me the comments on yesterday's run'. It also tells when NOT to use this tool by directing to icu_add_activity_message for posting new messages, effectively giving usage boundaries.

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/destructive flags, but the description adds substantial non-obvious behavior: payload heaviness warning, and the crucial heartrate-vs-raw_heartrate semantic — that heartrate is pre-corrected and capped at max HR while raw_heartrate exposes the clipped peak. This corrects a real misinterpretation risk.

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

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

Front-loads the core purpose, then usage routing, then filter values, then the important heartrate nuance. Dense but every paragraph earns its place; the multi-paragraph layout could be slightly tighter but nothing is wasted.

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

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

Output schema exists so return shape needn't be explained. Given the tool's complexity, the description covers what it returns, when to choose it vs siblings, valid filters, and the subtle raw_heartrate caveat — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and already documents both params, so baseline is 3. The description goes beyond by enumerating the accepted stream-type values (including ones the schema does not list) and warning that the default set excludes raw_heartrate/fixed_heartrate — real added 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?

Specific verb ('Fetch') plus resource ('RAW per-sample time-series') with an explicit enumeration of what streams are returned. It clearly distinguishes itself from sibling summary tools (get_activity_details, get_activity_intervals) and from the mutation sibling (update_activity_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?

Explicit when-to-use ('visualization or custom analysis') and when-not ('Most "how was my ride?" questions are better answered by get_activity_details or get_activity_intervals'), naming the specific alternatives. This is exactly the routing guidance an agent needs.

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 behavioral details beyond annotations: defaults to 365-day window, suggests narrowing for specific queries. Annotations already indicate read-only, idempotent, non-destructive, and open world, so description complements well.

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

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

Two paragraphs: first defines tool, second lists use cases and exclusions. No fluff, every sentence adds 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?

Fully addresses what the tool returns, default behavior, and when to use it. Output schema exists but description doesn't need to detail return values.

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

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

Schema covers all 3 parameters with descriptions. Description adds usage context (default 365, narrow for month/week) and hints for days_back, but schema already provides basics.

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

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

Description clearly states 'Read the Annual Training Plan (ATP) on the calendar' with specific elements (TSS, phases, notes). Distinguishes from sibling tools like icu_get_upcoming_workouts by explicitly naming what it is NOT.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use cases ('what's my weekly TSS target?', 'what training phase am I in?') and lists three sibling tools NOT to use, guiding correct tool selection.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the default target identity and the coach-scoped athlete_id override.

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

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

Two compact sentences, front-loaded with the tool's purpose and followed by the default/override behavior. Every clause adds useful information with no filler.

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

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

With an output schema present and rich annotations, the description does not need to explain return values. It covers the tool's purpose, default behavior, and sole parameter sufficiently for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that athlete_id defaults to the authenticated athlete and is specifically for coaches reading managed athletes.

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

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

The description states a specific verb and resource ('Get an athlete's profile') and enumerates the returned data: sport settings and current CTL/ATL/TSB. It does not explicitly differentiate from siblings such as icu_get_sport_settings or icu_get_fitness_summary, though the combined scope implies a broader profile read.

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

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

It provides clear context for the optional athlete_id: defaults to the authenticated athlete, while coaches can pass an ID for a managed athlete. However, it gives no guidance on when to choose this tool over related siblings like icu_get_sport_settings or icu_get_fitness_summary.

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 indicate read-only, non-destructive, idempotent behavior. Description adds context about scope (single activity) and parameter dependencies. No contradictions.

Agents need to know what a tool does to the 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 with no wasted words. Front-loaded with core purpose, then differentiation, examples, and requirement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 core functionality, differentiation, examples, and requirement. Output schema exists so return values are handled. Minor gap in behavior when both duration and distance are given.

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

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

Schema has 100% coverage with descriptions. Description echoes schema terms and adds examples but does not provide additional semantic beyond 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 clearly states the tool finds top-N peak efforts within a single activity, with specific verb 'find' and resource 'peak efforts'. It distinguishes from sibling get_*_curves tools that span many activities.

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

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

Provides explicit examples ('what was my best 20-min power') and states requirement for at least one of duration or distance. Could be clearer on handling when both duration and distance are provided.

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 indicate read-only, non-destructive, idempotent. Description adds that it fetches ALL entries and lists types, but doesn't mention pagination or limits. Good but not exhaustive.

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

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

Three sentences, front-loaded with purpose, then usage guidelines and alternatives. Every sentence adds value, no wasted words.

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

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

Given output schema exists, return values need not be detailed. Covers purpose, usage, alternatives. Missing minor details like maximum range or ordering, but overall complete.

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

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

Input schema has 100% description coverage for all three parameters. Description does not add additional parameter-level details beyond the schema, 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?

The description clearly states it fetches all calendar entries (workouts, notes, races, goals, life-event blocks) and distinguishes from siblings like icu_get_upcoming_workouts and 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?

Explicitly states when to use this tool (broad calendar queries) and when to use alternatives (icu_get_upcoming_workouts for filtered workouts, get_event for specific event).

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, destructiveHint, idempotentHint, and openWorldHint, fully covering the safety profile. The description adds value by explaining that the content field mirrors the list result, providing contextual consistency. 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?

Two concise sentences with no wasted words. The first sentence states the primary action, the second provides usage guidance and a helpful note about the output. Information is front-loaded.

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

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

Given the presence of an output schema, the description does not need to detail return values. It covers the tool's purpose, usage sequence, and relationship to sibling tools, making it complete for effective use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra meaning by implying item_id comes from the list tool, and explaining the athlete_id is for coaches managing multiple athletes. This goes beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain 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 fetches the full configuration of one custom addition by ID. It distinguishes itself from the sibling tool icu_get_custom_items by explicitly saying it focuses on a single item after the list has been obtained.

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

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

The description explicitly instructs to use this tool AFTER icu_get_custom_items has returned an ID, providing a clear workflow. It also notes that the content field is the same as in the list, helping the agent understand the relationship between the two tools.

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

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

Annotations already declare read-only, non-destructive, idempotent. Description adds behavioral details: returns all types in one call, client-side filtering via type field. No contradictions.

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

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

Well-structured with summary, usage guidance, return details, and exclusions. Slightly verbose but each sentence adds 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?

Given output schema exists, description covers usage, return types, and filtering without needing to detail return values. Complete for the tool's purpose.

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

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

Schema coverage is 100%, and description does not add new meaning beyond the schema's own description of athlete_id for coaches.

Input schemas describe structure but not intent. Descriptions should explain 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 lists custom additions to Intervals.icu account, with specific examples. It distinguishes from sibling tools that handle built-in data.

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

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

Provides explicit when-to-use (user asking about their own customizations) and when-not-to-use (built-in zones, fields, etc.) with alternative tool references.

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, destructiveHint, idempotentHint, and openWorldHint, indicating a safe read operation. The description adds value by specifying the return includes 'description, workout structure, and metrics', which goes beyond annotations.

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

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

The description is a single, concise sentence that front-loads the key action and includes important details about what is returned. No extraneous 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 exists (so return format is documented elsewhere), the description sufficiently covers the tool's purpose and what is fetched. For a simple retrieval tool, it is complete enough.

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

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

Input schema has 100% coverage describing both parameters (event_id and athlete_id). The description does not add extra semantic detail, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Fetch ONE specific calendar event by ID', specifying the verb, resource, and scope. It distinguishes itself from sibling tool icu_get_calendar_events which likely fetches multiple 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?

The description implies usage when a single event's full details are needed, but does not explicitly state when not to use or suggest alternatives. However, the context of siblings and the tool name provide adequate guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds that it returns both past history and future projections from planned calendar workouts, which is useful behavioral context 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?

Description is concise, front-loaded with the main purpose, and uses bullet-like structure for examples. No unnecessary sentences.

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

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

Given the output schema exists, description adequately covers the return values (daily CTL, ATL, TSB) and scope (history + projections). No gaps for an agent to understand the tool's output.

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

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

Input schema has 100% coverage on parameter descriptions; description does not elaborate further on parameters. Baseline 3 is appropriate as schema already handles meaning, and description provides usage context but no additional parameter semantics.

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

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

Description clearly states the tool fetches a Performance Management Chart time-series with daily CTL, ATL, and TSB. It includes specific verb 'fetch' and resource, and distinguishes from siblings via explicit NOT-for sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use-case examples are given (e.g., 'show my fitness chart', 'CTL trend last 90 days') and clear alternatives are stated (icu_get_fitness_summary, icu_get_wellness_data, icu_get_wellness_for_date), providing both when-to-use and when-not-to-use.

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 read-only, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds value beyond that by noting the response includes interpretation and training recommendations (not just raw numbers) and by clarifying the default scoping to the authenticated athlete with a coach override path.

Agents need to know what a tool does to the 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, each earning its place: metrics first, then trigger conditions, then scoping. The most load-bearing information is front-loaded and there is no filler.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, when to use it, and the athlete-scoping rule. Nothing required to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema's 'default: null' does not: that omitting athlete_id resolves to the authenticated athlete, and that passing it is specifically for coaches reading a managed athlete. This clarifies null-vs-value semantics beyond the schema text.

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

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

The description uses a specific verb ('Get') and resource ('athlete's fitness/fatigue/form snapshot') and enumerates the exact metrics returned (CTL, ATL, TSB, ramp rate), so an agent knows precisely what comes back. It does not explicitly differentiate from the closest sibling icu_get_fitness_chart, though the word 'snapshot' versus 'chart' implies a current-state vs time-series distinction.

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

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

The description gives concrete triggering questions ('how's my form?', 'am I overtrained?') and a category of use ('training-status checks'), which is clear context. It offers no explicit exclusions or named alternatives (e.g. get_fitness_chart for trends), so routing is left partly to inference.

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

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

Annotations already declare readOnlyHint=true and other safety hints. The description adds behavioral context by noting elevation normalization, which is beyond the annotations. No contradictions. Could mention rate limits or auth, but not critical given 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?

Two sentences with no wasted words. First sentence defines the core function; second sentence provides usage guidance. Front-loaded with key information.

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

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

With an output schema present, return values are covered. The description is sufficient for a simple read-only tool with one parameter and clear annotations. No missing context.

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

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

Schema coverage is 100% with a single parameter (activity_id) already described as 'Activity ID to analyze'. The description does not add any further semantics beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it provides a time-in-zone distribution of grade-adjusted pace (GAP) for a single activity, with elevation normalization. It uses specific verbs and resources, and explicitly distinguishes itself from the raw pace histogram sibling tool.

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

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

The description explicitly recommends using this tool for trail running where raw pace is misleading, and directs users to icu_get_pace_histogram for raw pace. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without description help. The description adds that the result includes derived usage stats and maintenance reminders, which is useful content disclosure, but says nothing about pagination, caching, or how far back the stats 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?

One sentence, front-loaded with the verb and resource and with the return contents in a tight parenthetical. Nothing is wasted or 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, so return-value detail is not required, and the single optional parameter is documented in the schema. The description is nearly sufficient; the only missing nuance is the coach/multi-athlete scoping behavior of omitting athlete_id.

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

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

Schema description coverage is 100% for the single optional athlete_id parameter, so the schema carries this dimension. The description contributes nothing about the parameter and its use of 'all gear items' slightly undersells that results are scoped when athlete_id is supplied; 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 ('List') and resource ('all gear items') and enumerates the payload (distance, time, activity count, maintenance reminders), so an agent knows exactly what comes back. It doesn't explicitly differentiate itself from near siblings like icu_create_gear or icu_update_gear, but the read-only list intent is unambiguous.

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

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

There is no statement of when to reach for this tool versus alternatives (e.g. icu_get_custom_items, gear-reminder tools), and no mention of the optional athlete_id scoping for coaches. Usage is only implied by the word 'List'.

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 safe read-only, idempotent profile. The description adds genuine behavior beyond them, notably that peak_hr_bpm is the top of the curve and has already been clipped to the configured max HR at import, plus that it does not return zone bands. This is useful nuance, though return structure and aggregation mechanics are left to the output schema.

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

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

Front-loads the core definition, then segments usage and disambiguation into tight sentences with zero filler. Every sentence carries either scope, routing, or behavioral 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 explanation is unnecessary. Combined with the routing guidance and the behavioral note about max-HR clipping, the description is complete for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters (days_back, athlete_id, sport_type, time_period) are already documented in the schema. The description references the 'chosen window' but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch the HR-vs-duration curve') and defines exactly what the curve contains: best sustained HR across durations from 5s to 1h, aggregated over the window. It also distinguishes itself from icu_get_sport_settings and get_hr_histogram by name.

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

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

Gives explicit intended use ('Use for cardiovascular-fitness trends') and names two alternatives with the conditions that select them: sport_settings for HR zones/max HR, hr_histogram for time-in-zone distribution within a single activity.

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, destructiveHint, idempotentHint, openWorldHint. Description adds that the output is a histogram with time per bucket, providing useful context 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?

Three sentences: defines the tool, distinguishes from sibling, and suggests use. No wasted words.

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

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

Given the presence of an output schema and a single parameter with full schema coverage, the description sufficiently explains the tool's purpose and usage.

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

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

Schema coverage is 100% with a description for activity_id. Description does not add additional parameter information 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?

Description clearly states it returns 'time-in-zone distribution of heart rate within a single activity' with histogram buckets. It differentiates from sibling tool icu_get_hr_curves, which focuses on best efforts across many activities.

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

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

Explicitly suggests use for cardiovascular load breakdown and HR-zone time-in-zone. Provides an alternative tool (icu_get_hr_curves) but does not specify when to avoid using this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real semantic behavior beyond that: the aggregation window, the 5s-to-1h duration span, and the fact that use_gap=True applies hill normalization via Grade-Adjusted Pace. It stops short of describing coverage limits or empty-data behavior, but the added context is substantive.

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

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

Three compact sentences, front-loaded with the core definition, then the usage guidance, then the exclusion and alternative. Every sentence carries distinct information with no repetition of 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 five optional parameters all documented in the schema and an output schema present, the description is not obligated to describe return values. It supplies the metric definition, the when-to-use, the GAP nuance, and the sibling fallback — everything an agent needs to select and call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description explains the *purpose* of use_gap ('normalize for hills via Grade-Adjusted Pace') and clarifies what the curve's duration range means, adding meaning the bare schema text does not carry. It remains silent on the interplay of time_period vs days_back, which keeps it from a 5.

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

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

States a specific verb ('Fetch') and resource (pace-vs-duration curve), then defines the metric precisely: 'best (fastest) sustained pace across durations from 5s up to 1h, aggregated over the chosen window.' The alternative tool is named directly, so an agent can separate this from the histogram 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 both positive and negative routing: 'Use for run/swim fitness trends and race-time predictions' and 'For time-in-zone distribution within a single activity, use get_pace_histogram (or get_gap_histogram) instead.' The condition that selects the alternative is explicit, and it even notes the use_gap variant to pass.

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 indicate safe read and idempotence; description adds that it operates on a single activity and returns time per bucket, which is beyond the annotations.

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

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

Three concise sentences: purpose, differentiation, usage. No wasted words, front-loaded.

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

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

Complete for a single-parameter tool with output schema; covers scope, usage, and alternatives.

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

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

Schema coverage is 100% with clear description of activity_id; description does not add further meaning but parameter is self-explanatory.

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

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

Clearly states it returns pace distribution histogram buckets for a single activity, and explicitly differentiates from sibling icu_get_pace_curves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use for pace-distribution / consistency analysis' and mentions alternative icu_get_gap_histogram for elevation-normalized pace.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavioral context beyond them: what the curve aggregates (highest sustained watts per duration) and the 5s-to-1h range. It does not discuss auth scope or how the aggregation window interacts with parameters, so not a full 5.

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

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

Two compact sentences plus a routing clause; the core definition is front-loaded and every clause carries 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?

With an output schema present, return format needn't be explained, and rich annotations carry the safety profile. The description covers what the tool computes, when to use it, and which sibling to use instead — sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so all four parameters (days_back, athlete_id, sport_type, time_period) are already documented. The description's reference to the 'chosen window' loosely maps to days_back/time_period but adds no syntax, format, or interaction 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 (fetch) and resource (power-vs-duration curve), then defines it precisely: best sustained watts across durations from 5s to 1h, aggregated over the chosen window. It explicitly names the sibling icu_get_power_histogram as the different tool, so an agent can distinguish 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?

Gives concrete use cases (FTP estimation, peak-power tracking, strengths/weaknesses across duration profiles) and an explicit when-not/alternative: time-in-zone distribution belongs to icu_get_power_histogram. 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 cover safety (readOnlyHint true, destructiveHint false, idempotentHint true). The description adds meaningful behavioral context by specifying the output format (histogram buckets with time per bucket) and the single-activity scope, which goes beyond what annotations provide.

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

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

The description is extremely concise: two sentences. The first sentence defines the output, the second provides usage context and sibling differentiation. Every word adds value with 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 simple tool with one parameter and an output schema, the description is complete. It explains what the tool returns (histogram buckets), the scope (single activity), and typical use cases, without needing to detail return format since output schema exists.

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

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

Input schema has 100% coverage with a clear description of the single required parameter 'activity_id'. The description does not add further semantic details about the parameter beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns a time-in-zone distribution of power for a single activity as a histogram. It explicitly distinguishes itself from a sibling tool, icu_get_power_curves, by noting the difference in scope (single activity vs. best efforts across many activities).

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

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

The description provides explicit guidance on when to use this tool: 'Use for how was my workout intensity distributed?, training-zone breakdown.' It also contrasts with icu_get_power_curves, helping the agent choose between similar 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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by specifying the light summary content and default date range, which goes beyond the annotations.

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

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

The description is only three sentences, each serving a clear purpose: stating function, suggesting use cases, and providing alternatives. No unnecessary words, and the core information is front-loaded.

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

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

For a read-only list tool with an output schema, the description covers what it returns, default behavior, and when to choose alternatives. It is sufficiently complete for an agent to decide to invoke it.

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

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

Input schema has 100% description coverage for all 3 parameters. The description mentions the default 30-day range but does not add new semantics beyond what the schema already provides, so baseline of 3 is appropriate.

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

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

The description clearly states 'List the athlete's most recent activities' with a specified default timeframe and content summary (distance, duration, etc.). It also distinguishes itself from sibling tools by naming alternatives for specific use cases.

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

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

The description explicitly provides use cases ('what have I done recently?', 'show last week's rides') and tells when not to use it, directing to icu_get_activity_details for single activities and icu_search_activities for name/tag searches.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered; the description goes well beyond them by disclosing return contents, units for each zone set (bpm, %FTP, % of threshold pace), the derivation/stamping behavior at import, and the downstream impact on time-in-zone, HRSS and TSS. That is rich behavioral context an agent can act on.

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

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

The purpose is front-loaded in the first sentence, followed by field/units detail and a disambiguation clause. It is slightly verbose in its emphasis on being the only source, but every sentence provides usable information.

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

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

For a read-only settings getter with full schema coverage and an output schema, the description supplies everything an agent needs: what is returned, the units, and why these values matter downstream. Nothing material is missing.

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

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

Schema description coverage is 100% for the single athlete_id parameter, and the description does not add any syntax or semantics for it. Baseline 3 applies since the schema carries the parameter meaning.

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

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

The description names a specific verb (Get) and resource (per-sport thresholds plus the athlete's power/HR/pace zones), and enumerates the concrete fields returned (FTP, FTHR, max HR, run pace, swim threshold). It further distinguishes itself from the curve siblings by stating zones are not derived from curve data, so an agent can separate it from get_power_curves/get_hr_curves 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?

It clearly states the condition for use ('This is the ONLY source of the athlete's real zones') and draws an explicit boundary against reasoning from curve data or other numbers. It stops short of naming a specific sibling alternative to prefer, but the when-to-use context 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations: it filters out non-workout calendar entries, returns calendar event IDs (not library template IDs), and clarifies the relationship to event and library tools. It does not contradict any 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 efficient: two short paragraphs with no fluff. The primary purpose and scoping are front-loaded, followed by usage guidance and routing. Every sentence earns its place and aids decision-making.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 presence of an output schema (not shown) and the rich annotations, the description covers everything needed: what it returns, how to interpret the IDs, when to use it, and when to use alternatives. It is complete for correct invocation and selection among many siblings.

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

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

Schema coverage is 100% – both `limit` and `athlete_id` have descriptive text in the schema. The description does not add extra meaning to the parameters; it only implicitly references the use case. Since the schema fully documents the parameters, baseline 3 is appropriate.

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

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

The description clearly states the tool fetches planned workout entries from the upcoming calendar, explicitly filtering out notes, races, and goals. It distinguishes itself from workout-library templates and names sibling tools, making its purpose unmistakable.

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

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

It provides explicit use cases ('what's my next workout?', 'what training is planned') and gives clear routing: use icu_get_calendar_events for all calendar entries, icu_get_workouts_in_folder for library templates, and event-specific tools for IDs returned by this tool. This leaves no ambiguity about when to use 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds two useful behavioral facts beyond that: the default 7-day window and the guarantee that this tool always returns a multi-day list rather than a single record. Output format details are left to the output schema, which is fine.

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

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

The core behavior and default are front-loaded in the first clause, followed by use cases, then the two sibling disambiguations. Every sentence carries information; none is 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, rich annotations, and full parameter documentation, the description only needs to cover scope, routing, and the default range — all of which it does. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so both parameters (days_back, athlete_id) are already documented. The description only restates the default of 7 days, which the schema's default field already conveys, and adds nothing about the athlete_id scoping beyond what the schema says. Baseline 3 applies when the schema carries parameter semantics.

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

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

States a specific verb+resource (fetch wellness records) with an explicit scope (range of recent days, default last 7). It names the two most confusable siblings (icu_get_fitness_chart and icu_get_wellness_for_date) and states what distinguishes this tool from each, 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 concrete use cases (trends, weekly summaries, 'how has my sleep been this week?', recovery curves) plus explicit routing rules: fitness chart series go to icu_get_fitness_chart, a single date goes to icu_get_wellness_for_date. Both the when-to-use and when-not-to-use conditions 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds only the single-date scoping constraint; it does not say what happens when no record exists for that date (error vs empty) or what the record contains, though an output schema exists.

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

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

Front-loads the core scope in the first sentence, then earns its remaining lines with routing examples and the alternative tool. 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?

Complete enough for a simple read tool: annotations carry safety, the output schema covers return values, and routing to the range-based sibling is explicit. Only the missing-record behavior is 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%, so both the date format (YYYY-MM-DD) and athlete_id purpose are already documented in the schema. The description reinforces single-date usage but adds no format or constraint detail beyond the schema.

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

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

States a specific verb (Fetch) and resource (wellness record) scoped to ONE specific date, and explicitly distinguishes itself from the sibling icu_get_wellness_data for ranges.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 triggering examples ("show my HRV for Monday", "wellness on 2026-03-15") and an explicit exclusion with the alternative tool for ranges, weeks, or trends.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope about what is listed (personal, shared, followed plans) but does not describe return format, pagination, or other behavioral details beyond what annotations provide.

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

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

Two efficient sentences: the purpose is front-loaded, and the follow-up usage guidance follows naturally. No filler or repetition; 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?

With an output schema present, the description need not explain return values. It communicates what the tool lists and how to use folder IDs downstream. Minor ambiguity exists because it says 'Each folder ID' can be passed to icu_apply_training_plan, potentially conflating folder IDs with training plan IDs, but overall the description is complete enough for correct invocation.

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

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

Schema description coverage is 100%, and the single athlete_id parameter is fully documented in the schema ('Athlete ID (for coaches managing multiple athletes)'). The description adds no additional meaning about the parameter, so the 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 ('List') and resources ('workout-library folders + training plans') with clear scope ('personal, shared, and followed plans'). It distinguishes itself from siblings by naming downstream tools (icu_get_workouts_in_folder, icu_apply_training_plan) that are used after this call, so an agent can tell what this tool is for 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?

Clearly indicates the follow-up actions: folder IDs can be passed to icu_get_workouts_in_folder to see contents or to icu_apply_training_plan to schedule. It does not explicitly state when not to use this tool or name a competing alternative, but the context is sufficient for an agent to know this is the entry point for the workout library.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the returned attribute set, but says nothing about pagination, ordering, or whether an empty folder returns an empty list — modest added value on top of 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?

A single front-loaded sentence: verb, scope, then the attribute list. Nothing is padded or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 need not explain return values; it names the key fields anyway. What remains thin is the absence of any guidance on folder-vs-training-plan IDs or result volume, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are documented structurally, giving a baseline of 3. The description contributes only the nuance that folder_id may also denote a training plan, which the schema does not convey.

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

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

States a specific verb (list) and resource (workouts in a library folder or training plan), plus the fields returned. It scopes to one specific folder, which loosely separates it from icu_get_workout_library, but it never names or contrasts that sibling explicitly.

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

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

There is no when-to-use guidance and no alternative named. The phrase 'one specific library folder or training plan' implies you must already know the folder/plan ID, but the agent is left to infer whether this or icu_get_workout_library is the right call.

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