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

Annotations already establish that this is a write operation (readOnlyHint=false) and not destructive. The description adds one useful behavioral rule: at least one limit must be set. Beyond that, it does not explain what happens when multiple limits are supplied or describe side effects, which is acceptable given the existing annotations but not richly transparent.

Agents need to know what a tool does to the 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 brief sentences communicate the core purpose, give an illustrative example, and state an important constraint. There is no filler and the example is front-loaded, making this easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, returning details do not need to be explained, and the annotations cover safety-relevant behavior. The description captures the main operation and the 'at least one limit' rule. However, for a tool with six parameters and weak schema descriptions, the lack of explicit mapping between 'limits' and the actual parameter names leaves meaningful ambiguity.

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

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

Schema description coverage is only 17%, so the description carries an unusually high burden for explaining parameters. It introduces the concept of 'limits' and gives the 600 km example, but it never names days, hours, activities, or distance_km as the limit fields, nor does it clarify how multiple limits interact. gear_id and name semantics are left entirely to the schema. Some meaning is added, but not enough to compensate for the sparse 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 ('Add') and resource ('replacement or maintenance reminder to gear'), reinforced with a concrete example like 'replace shoes after 600 km'. It is clearly distinct from the sibling update_gear_reminder because it describes creating a new reminder, not modifying an existing one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 makes the intended use case clear (adding a reminder to gear) and adds a usage constraint ('Set at least one limit'). However, it never mentions alternatives like update_gear_reminder or explains when the agent should pick this tool over a related one, so the differentiation is left mostly to the tool name and the agent's 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 signal a non-read, non-idempotent mutation. The description adds meaningful behavior beyond that: it discloses the bulk side effect ('Adds many events') and the exact date mapping ('Each workout lands on start date + its plan day'), plus a precaution to confirm the plan first. This is valuable 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?

Two sentences with no filler. The primary action is front-loaded, and the follow-up sentences add precise behavioral details and a warning. 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 only 2 fully described parameters, an output schema, and annotations covering mutation/idempotency, the description is nearly complete. It covers the source (PLAN folder), the date mapping, and the bulk-event side effect. It could explicitly mention non-idempotency or what happens on repeat calls, but that is already implied by annotations and 'Adds many events.'

Complex tools with many parameters or behaviors need more documentation. 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 semantic value by explaining how start_date maps to individual workouts ('start date + its plan day') and reinforcing that plan_id must reference a PLAN folder, which goes slightly 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 states a specific verb and resource: 'Copy all workouts of a training plan from the library ... onto the calendar.' It clearly distinguishes from siblings like list_workout_library (read) and create_events (individual events) by naming the PLAN folder source and the action of applying a full plan.

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

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

The description implies when to use it (to schedule a training plan) and points to list_workout_library for finding plan ids, but it does not explicitly contrast with alternatives such as create_events or duplicate_events. No when-not guidance is provided.

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

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

Beyond the annotations, the description discloses key behavior: duplicate entries with the same date, category and name are skipped unless allow_duplicates is true, planned workouts sync to the watch, and the result exposes workout_check. This is meaningful behavioral context that annotations alone would not convey.

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

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

The description is long but every part earns its place: the first paragraph covers core behavior and workflow, and the second paragraph is a dense but structured syntax reference with examples. It is front-loaded and contains 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?

Given the tool's complexity, an output schema, and the annotations, the description is highly complete: it covers entry types, limits, duplicate handling, synchronization, user agreement, post-call warning handling, and the full syntax needed to build workout descriptions. Nothing essential for correct invocation seems missing.

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

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

The description adds substantial meaning beyond the schema, especially for the workout-syntax parameter: it explains step format, durations, distances, repeats, labels, power, and unsupported bpm ranges. It also clarifies allow_duplicates behavior with concrete conditions. This more than compensates for the 50% schema description 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?

Description uses a specific verb ('Add') and resource ('athlete calendar'), and enumerates the accepted entry types: workouts, races, notes, holidays/sickness. The scope is further clarified by the 50-per-call limit and the watch-sync note, which helps distinguish this from library-oriented siblings like create_workouts.

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

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

The description gives clear preconditions — 'Show the plan to the user and get agreement before calling' — and a follow-up action: check workout_check and fix warnings with update_event. It does not explicitly name alternatives or conditions when NOT to use this tool, so it stops short of a full 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=false, idempotentHint=false, and destructiveHint=false, so the description is not burdened with basic side-effect disclosure. It adds context by noting the created object is meant to 'hold reusable workouts,' but it does not reveal any additional behavioral traits such as permission requirements, cascading effects, or response semantics.

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

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

The description is a single, front-loaded sentence that conveys the core purpose without filler. Every word contributes to the meaning, and the optional plan behavior is efficiently parenthesized rather than expanded unnecessarily.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, has an output schema, and annotations cover its basic behavioral profile, so the description does not need to explain return values or safety. However, given the low schema coverage and the lack of explicit guidance about the kind default and when versus sibling tools to use, the description is adequate but not fully complete on its own.

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

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

Schema description coverage is only 33%, and the description does not compensate for the gap. It hints at the kind parameter by saying 'folder (or a training plan),' but it does not explain the name requirement, the description parameter, or the fact that kind defaults to FOLDER. The description adds minimal meaning beyond what the schema already reveals.

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

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

The description states a specific action ('Create'), a resource ('folder' or 'training plan'), and a location ('in the workout library'), making the tool's purpose immediately clear. It also distinguishes the object from related sibling tools like update_folder by focusing on creation rather than modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the tool should be used: when creating a library folder or plan. However, it does not explicitly explain when not to use it or how it compares to alternatives such as create_workouts, apply_plan, or update_folder, so an agent must infer the decision boundary.

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 mark this as a mutating, non-destructive operation. The description adds a useful behavioral note that activities are not tied to gear automatically by creation but rather through device sync or manual linking in Intervals.icu. It does not discuss duplicate handling, idempotency, or required permissions, but it does not contradict annotations either.

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

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

The description is concise and front-loaded: the first sentence says what the tool does and the second adds relevant linkage context. No filler, though the second sentence is arguably optional for simply invoking the tool.

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

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

The definition is adequate for a simple create operation, especially with an output schema present, but it leaves gaps around parameter semantics and sibling-tool selection. It is not misleading, yet an agent would still need to infer name/notes/purchased behavior from the schema alone.

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

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

With schema description coverage at only 20%, the description needed to explain the other parameters. It only adds meaning for starting_distance_km ('distance already covered') and gives an example value for the type enum; name, notes, and purchased remain unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb/resource pairing ('Add gear') and gives a concrete example ('a new pair of running shoes'), plus the optional starting-distance wrinkle. This is enough to distinguish creation from sibling update/list/reminder tools such as update_gear and add_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?

No explicit guidance on when to choose create_gear over its siblings. The second sentence explains that gear is linked via sync or manually, but it never states exclusions, prerequisites, or conditions that should route an agent to update_gear/list_gear/add_gear_reminder.

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. The description adds valuable behavioral context beyond that: the activity counts toward training load, and details should be confirmed before logging. 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 short sentences, each earning its place: purpose, date constraint, and behavioral warning. The most important usage constraint is front-loaded, and there is no filler or repetition.

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

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

For a mutating tool with an output schema and existing annotations, the description covers the essential side effects and constraints. It could have specified the expected date format or listed required fields more explicitly, but the schema partially covers those and the overall guidance is sufficient.

Complex tools with many parameters or behaviors need more documentation. 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 description adds some meaning beyond the input schema by specifying 'today or past dates only' and giving a treadmill example for the type/name fields. However, with 9 parameters and only 56% schema coverage, many parameter nuances are left to the schema or inference. It is adequate but not rich.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb and resource: 'Log an activity that was not recorded by a device.' The treadmill example and date restriction make the tool's purpose concrete and distinguish it from other activity tools like search_activities or get_activity.

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

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

It gives clear context for when this tool applies: only for non-device-recorded activities, and only for today or past dates. It also tells the agent to confirm details with the user first. It does not explicitly name alternative sibling tools, but the usage boundary is clear enough.

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 mutating and open-world profile. The description adds valuable behavioral specifics: a per-call limit of 50, a validation result (workout_check), and the recommendation to use update_workout for warnings. It also documents the exact syntax rules, which is essential. No contradiction with annotations.

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

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

The description is long but every sentence carries necessary detail for correct usage. It is front-loaded with the main purpose, then dives into syntax rules. No redundant phrasing; it's dense but efficient for the complexity involved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema, so return values need not be explained here. The input schema is nested and complex; the description covers the most error-prone part (text syntax) and gives operational guidance (limit, validation, follow-up). An agent has enough to call it correctly.

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

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

With medium schema coverage (~50%), the description compensates heavily by explaining the workout text syntax for the 'description' parameter, which is the most complex field. It also clarifies that '400m' means 400 minutes, not meters. Other params like folder_id and type are covered in the schema, so the added value is appropriately concentrated.

Input schemas describe structure but not intent. Descriptions should explain 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 'Save reusable workouts in a library folder or plan' with a limit, specifying the verb and resource. It also distinguishes itself from update_workout by mentioning fixing warnings with that tool, so the agent knows this is the creation half of a create/fix pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tells when to use this tool (for saving reusable workouts) and gives follow-up guidance: check workout_check in the result and use update_workout to fix warnings. It doesn't explicitly name alternatives to avoid using, but the context is clear enough that an agent won't mistakenly choose a sibling like create_folder.

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 show readOnlyHint=false, so the description's 'Copy' action is consistent. The description adds a crucial behavioral requirement ('Confirm with the user first') and implies non-destructive copying of originals, which goes beyond the structured annotations.

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

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

Two sentences, front-loaded with the action and example, and ending with a critical confirmation instruction. Every word 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?

For a simple tool with full schema coverage and an output schema, the description covers purpose, a concrete example, and a key procedural requirement. It doesn't elaborate on how copies and weeks_between combine, but that is reasonably implied by 'later weeks' and the schema defaults.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents ids, copies, and weeks_between. The description adds no further parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb ('Copy') and resource ('calendar events') with a clear temporal scope ('to later weeks'). The title and example further clarify the exact use case, distinguishing it from sibling tools like create_events or update_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?

The example ('repeat this week's workouts for the next 3 weeks') provides clear context for when to use the tool. It does not explicitly mention alternatives or exclusions, but the scenario is specific enough for an agent to select it appropriately. The added 'Confirm with the user first' is a valuable procedural guideline.

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, so the tool is known to be a mutation. The description adds that it copies workouts to later weeks, but does not disclose side effects such as whether original workouts are preserved, potential conflicts, or permission requirements. It adds minimal behavioral context beyond the example.

Agents need to know what a tool does to the 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 sentence that front-loads the core action and provides a clear example. There is no filler, making it efficient and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 are not the description's responsibility. However, the description omits important operational details such as whether 'ids' must belong to the same plan, constraints on 'copies' relative to plan length, and what happens if weeks overlap. The example gives some context but overall leaves key behavioral questions unanswered.

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

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

Schema description coverage is only 33% (only weeks_between has a description). The tool description does not explain the meaning of 'ids' or 'copies'. The example ('repeat week 1 for weeks 2–4') hints at the relationship but is not explicit about how each parameter maps. The description fails to compensate for the low 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 states a specific verb ('copy'), resource ('workouts inside a training plan'), and qualifier ('to later weeks'), with a concrete example. This clearly distinguishes it from generic tools like update_workout or create_workouts.

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

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

The description implies usage for repeating workouts across weeks but does not explicitly state when to use this tool versus alternatives (e.g., duplicate_events for events, or manually creating workouts). No exclusions or alternative routing is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuine value beyond annotations by enumerating the actual content returned (zones, aerobic decoupling, HR recovery, fitness/fatigue) and noting the optional intervals. It stops short of describing response size or performance characteristics, but with an output schema present that gap is minor.

Agents need to know what a tool does to the 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 dense sentence that front-loads the core purpose and the id format hint, followed by the field list. It is efficient with no filler, though the long enumeration of metrics could have been structured as a list for faster scanning. The 'see list_activities' pointer is a useful, low-cost addition.

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

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

With an output schema, full parameter coverage, and safety annotations in place, the description covers what the tool returns well. It clarifies the id format and flags that include_raw output is large (via schema). Nothing critical for a correct call is missing, though it could note the interplay between include_raw and include_intervals.

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

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

Schema coverage is 100% and each parameter (id, include_raw, include_intervals) has a descriptive schema entry. The description adds marginal value by explaining that include_intervals yields 'the list of intervals/laps with pace and HR', which enriches the schema's terse 'Include intervals/laps' note. This meets the baseline for a fully-covered schema without going beyond it.

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

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

The description uses a specific verb ('Get') and resource ('one activity') and enumerates precisely what is returned: summary metrics, description, zone times, aerobic decoupling, HR recovery, fitness/fatigue, and optionally intervals. It distinguishes itself from list_activities/search_activities by emphasizing it targets a single activity id, and even notes the id format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it (when you need details of one activity) and points to list_activities for obtaining ids, which is helpful routing. However, it never explicitly contrasts with the many activity-specific siblings (get_activity_streams, get_activity_histogram, get_activity_best_efforts) to say 'use this for summary details, not those'. No explicit exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not burdened with repeating those. It adds that the tool 'returns when each effort happened,' giving useful output context beyond the schema. No contradictions 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 sentences, each earning its place: the first defines the tool's purpose with concrete examples, the second gives the alternative tool and clarifies the output. No fluff, front-loaded with the primary use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 5 parameters, a conditional metric/dimension relationship, and an existing output schema, the description covers the main use, gives examples, and routes to the alternative. Minor gap: it doesn't explicitly state that distance_m and duration_s are mutually exclusive based on metric, but the schema's enum and parameter descriptions already hint at this. The overall guidance 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 coverage is 100% – every parameter has a description in the schema. The description's examples (e.g., best 1 km, best 5 min) illustrate usage but do not add new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema handles parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain 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 best efforts within a single activity, gives concrete examples (fastest pace over a distance like best 1 km, highest average HR/power over a duration like best 5 min), and explicitly names the sibling get_athlete_curves as the alternative for cross-activity bests. This distinguishes it from other activity-related tools with a specific verb and resource.

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

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

It explicitly says 'For all-time or period bests across activities use get_athlete_curves,' providing a direct when-not-to-use condition and pointing to the correct sibling. It also implies the tool is for within-activity analysis, leaving no ambiguity about scope.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral detail about the output format (ranges, time, and % of total) and the finer-grained comparison, providing value beyond the annotations without contradiction.

Agents need to know what a tool does to the 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 exceptionally concise, consisting of two sentences that pack the core purpose and a distinguishing comparison. There is zero fluff, and the key information (what it does, for what scope) is front-loaded. 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 and full parameter documentation, the description is largely complete. It explains the output (histogram with ranges, time, and %), scopes it to one activity, and gives a granularity comparison. It does not mention potential limitations (e.g., activity types), but given the schema and annotations, nothing essential is missing.

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

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

Schema description coverage is 100%, so all three parameters are already well-documented in the schema (id, metric enum, bucket_size defaults). The description adds minimal semantic value beyond the schema, mentioning the metric types but not enhancing parameter understanding. 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 'Get' and the resource: how much time was spent at each heart rate, pace, or power level in one activity. It specifies the output (histogram with ranges, time, and % of total) and differentiates from 'time in zones' by noting finer granularity, which distinguishes it from any zone-based 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 provides clear context by noting 'in one activity' and that it is 'finer-grained than time in zones,' which implies when this tool is appropriate. However, it does not explicitly name an alternative tool or state when not to use it, so it falls short of full explicit 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the segment-range scoping and metric details, which are useful, but does not disclose additional behavioral traits such as limits, errors, or dependencies. This is acceptable but not exceptional given the annotation coverage.

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

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

Two short sentences with no filler. The core action and resource appear first, followed by a useful example and a clear use case. 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 tool with three well-documented parameters, an output schema, and read-only/idempotent annotations, the description provides sufficient context: what metrics are returned, how the segment is specified, and when it is useful. Nothing critical is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies. However, the description's example 'from 10:00 to 20:00' adds a concrete illustration of how start and end values are expressed in the 'm:ss' format, going slightly beyond the schema's dry description.

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

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

The description uses a specific verb ('Get') and clearly names the resource: stats for a selected part of an activity, listing pace, heart rate, cadence, and intensity. The example 'from 10:00 to 20:00' distinguishes this from whole-activity tools like get_activity and from time-series tools like 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 suggests when to use the tool: 'Use it to compare the first and second half or a climb.' This provides a clear usage context, though it does not explicitly name alternatives or state when not to use it, so it falls short of a full 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?

Beyond the readOnly/idempotent annotations, it discloses two non-obvious behaviors: data is downsampled into averaged time windows, and GPS coordinates are returned only when 'latlng' is explicitly requested. This materially shapes how an agent interprets results. 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, each earning its place: what it returns, when to use it, and an important caveat. Main purpose is front-loaded.

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

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

With a full input schema, output schema, and safety annotations, the description covers the remaining contextual needs: temporal resolution, aggregation, and the GPS caveat. No critical information is missing for an agent to select and call the tool.

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

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

Schema already describes all five parameters, so baseline is 3; the description adds semantic value by explaining the aggregation behavior behind max_points and the conditional inclusion of GPS behind types, which are not inferable from the schema alone.

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

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

States a clear verb and resource: retrieve second-by-second stream data for one activity (HR, pace, cadence, etc.). It implicitly differentiates from list/summary siblings, but does not explicitly name an alternative tool, so it stops short of full sibling 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?

Gives concrete use cases ('analyse pacing, HR drift or how effort changed during the session'), making the intended context clear. It does not say when not to use it or name alternatives such as get_activity_histogram, so exclusion guidance is missing.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature of the tool. The description adds useful behavioral context beyond annotations, such as pace curves including critical speed as a threshold estimate and HR/power curves representing highest averages over durations. It does not contradict the annotations.

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

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

Three concise sentences front-load the core operation, add one valuable interpretive detail, and then provide targeted use cases. There is no filler or redundant restating of schema 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 rich input schema, output schema, and safety-related annotations, the description is complete enough for an agent to select and invoke the tool correctly. It covers the core purpose, metric families, and typical use cases, while defaults and formats are documented in the schema.

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

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

All five parameters are fully described in the input schema, so the baseline is 3. The description adds interpretive context by linking pace to standard distances, HR/power to standard durations, and mentioning critical speed, but it does not materially improve on the schema's already thorough parameter documentation.

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

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

The description opens with a specific verb and resource: 'Get personal bests for a sport over one or more periods,' and clarifies the two output families (pace/time vs. HR/power). It is clear and unambiguous, but it does not explicitly distinguish itself from sibling tools like get_activity_best_efforts or get_fitness_summary.

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

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

The description gives concrete usage context: 'Use it for PRs, race predictions and fitness progress (compare periods such as 42d vs 1y).' It clearly states when this tool is appropriate, but it does not mention when not to use it or name competing tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds usage context but no additional behavioral traits such as data freshness, authentication requirements, or response caveats. It does not contradict the annotations.

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

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

Two sentences with no filler. The first sentence states the resource and contents, and the second gives a practical use case. It is appropriately front-loaded and every sentence earns its place.

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

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

Given that the tool has no parameters, has annotations covering its read-only/idempotent nature, and has an output schema to describe return values, the description is complete. It tells the agent what data is available and when to use it, leaving no critical gap.

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

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

The tool has zero parameters, so there is no parameter burden to compensate for. The description adds value by listing what fields the profile contains, which helps the agent understand what to expect even though the input schema is empty.

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

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

The description uses a specific verb and resource ('Get the athlete profile') and enumerates the concrete contents: time zone, units, weight, resting HR, and per-sport settings. This clearly distinguishes it from the sibling tools, none of which claim this resource.

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

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

It explicitly states when to use the tool: 'Use it to interpret zones and paces or before planning workouts.' This gives clear context, though it does not name alternatives or exclusions. Since no sibling tool appears to compete for the same purpose, the lack of exclusions is acceptable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that the response includes the full workout description, which tells the agent what to expect beyond basic event fields. No contradiction with annotations.

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

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

The description is one efficient sentence with the verb and resource front-loaded. It includes valuable distinguishing details (event types, full workout description) without any filler or 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 single-parameter read-only tool with comprehensive annotations and an output schema, the description covers all necessary call context: what the entity is, how to select it, and a key detail about the returned data. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the id parameter's description in the schema already says 'Event id (from list_events).' The tool description's 'by id' simply restates the schema, adding no new parameter semantics, so the baseline of 3 is appropriate.

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

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

The description states a precise verb ('Get'), a specific resource ('one calendar event'), and selection by id. It also disambiguates from siblings like list_events and get_workout by naming the event types (planned workout, race, note) and noting the full workout description is included.

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

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

Usage context is implied: you call this when you have an event id and want a single event. However, the description does not explicitly contrast with list_events, update_event, or get_workout, nor does it say 'use list_events to find the id first' — that cross-reference only appears in the schema's id description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety traits. It adds behavioral context by specifying the default time range (last 6 weeks) and the nature of the returned data (daily series, weekly totals). This goes beyond annotations and helps the agent understand what to expect without overloading.

Agents need to know what a tool does to the 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 zero waste. The first sentence packs the core purpose, metric definitions, output structure, and default range. The second sentence gives usage guidance. All critical information is front-loaded, and every clause earns its place.

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

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

With an output schema present, the description need not detail return values. It covers the tool's scope, defaults, usage context, and the data it returns. For a read-only, idempotent tool with fully documented parameters, 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% – both 'newest' and 'oldest' are described with defaults and format. The description does not add parameter-specific details beyond the schema, as the defaults and date format are already present. Baseline 3 is appropriate because the schema handles parameter documentation adequately, and the description's mention of the default range reinforces but does not extend 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 clearly states the tool's purpose: retrieving training fitness (CTL), fatigue (ATL), and form (TSB), with precise definitions of each metric. It also specifies the output format (daily series, weekly totals by sport) and default time range. This is a specific verb+resource description that distinguishes it from generic sibling tools like get_wellness, which covers different wellness metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states 'Use it for questions about training load, freshness or trends,' giving clear when-to-use guidance. It does not explicitly mention alternatives or when not to use it, but the context is sufficient for an agent to select this tool over others. Sibling differentiation is implied by the metric specificity rather than explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral nuance: the 'if any' clause indicates the tool may return an empty result when no plan exists, and it specifies the returned fields (plan name, start date, workouts by day). This adds value beyond the annotations without contradiction.

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

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

The description is a single, front-loaded sentence that immediately states the purpose and lists the key output fields. It contains no filler or redundant phrasing, making it highly efficient for an agent to parse.

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

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

Given the tool has no parameters, an output schema is present (as noted in context), and annotations cover safety, the description provides sufficient information: the resource type, the conditional nature ('if any'), and the expected return contents. Nothing essential is missing for a correct call.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and it adds no parameter-specific detail. Per the baseline for 0 parameters, a score of 4 is warranted.

Input schemas describe structure but not intent. Descriptions should explain 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 'Get', the resource 'training plan', and specifies the returned data: plan name, start date, and workouts by day. It distinguishes from siblings like get_athlete_profile (profile info) and list_workout_library (library of workouts) by focusing on the currently followed plan.

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

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

The description implies the tool is for retrieving the active plan, not for browsing the workout library or fetching a specific workout. However, it does not explicitly name alternatives or provide exclusions, leaving some inference to the agent. The context is clear enough for a competent agent to decide, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it defaults to the last 14 days, includes period averages, and specifies the Intervals.icu 1–4 scales for subjective ratings. No contradictions 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 tight sentences with no filler. The first sentence front-loads the data contents, the second states the default range and intended use case. Every clause earns its place.

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

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

Given the rich annotations, fully documented parameters, and presence of an output schema, the description is complete for an agent to select and invoke the tool correctly. It covers what data is returned, the default date window, and the intended use case, leaving no critical gap.

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

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

Schema description coverage is 100%, so the schema already documents the two parameters (newest and oldest) with their defaults. The description's mention of 'Defaults to the last 14 days' reinforces the schema but does not add new semantic meaning beyond what the parameter descriptions already provide. 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 uses a specific verb ('Get') and resource ('daily wellness data') and enumerates the exact fields returned, including resting HR, HRV, sleep, weight, steps, readiness, and subjective ratings. It clearly distinguishes itself from siblings like update_wellness and get_fitness_summary by naming the wellness/recovery domain and its data scope.

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

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

The description explicitly states 'Use it for recovery and readiness questions,' giving clear context for when to select this tool. It does not name alternative tools or exclusion conditions, but the guidance is sufficiently clear for an agent to route wellness/recovery queries here.

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 non-destructive behavior, so safety is covered. The description adds one genuinely useful trait beyond the annotations: the returned workout includes its steps serialized in Intervals.icu text format.

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

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

The description is a single front-loaded sentence with no filler or repetition of the tool name/title. Every word adds information about the operation or its output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, idempotent getter with one fully described parameter, an output schema, and strong annotations, the definition covers everything needed to invoke it correctly. The workflow hint (id from list_workout_library) completes the 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?

The single required parameter is fully documented in the schema (100% coverage) as 'Workout id (from list_workout_library)'. The description does not add parameter semantics beyond the schema, 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 uses a specific verb ('Get') and resource ('one workout from the library'), and adds the key detail that it returns the workout's steps in Intervals.icu text format. This clearly separates it from list_workout_library and from create/update workout tools.

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

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

The phrase 'from the library' plus the parameter description 'Workout id (from list_workout_library)' strongly signal the workflow: list workouts to obtain an id, then get that specific workout. It does not explicitly name when-not-to-use alternatives, but the context is clear enough for an agent to choose it over sibling 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 cover read-only, idempotent, and non-destructive behavior, so the description adds valuable behavioral context: it returns completed activities, newest first, with pace/GAP, heart rate, training load, and totals per type. No contradiction 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?

Two dense, efficient sentences: action, scope, ordering, key output fields, defaults, and the relevant alternative. Every clause earns its place and the core purpose is front-loaded.

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

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

With full schema parameter coverage, a true output schema, and safety annotations, the description covers the essential decision factors: what is returned, how it is ordered, the default window, and when to use get_activity instead. No critical calling detail is missing.

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

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

The schema documents all four parameters at 100% coverage, so the baseline applies. The description's mention of a date range and default of 30 days reinforces the oldest/newest parameters but does not add meaning beyond what the schema already provides.

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

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

The description clearly states the verb and resource: it lists completed activities in a date range, with ordering, key metrics, and per-type totals. It explicitly distinguishes from get_activity but does not differentiate from the sibling search_activities, leaving some sibling ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 alternative: 'Use get_activity for details of one activity,' and states the default 30-day window. It does not explain when search_activities should be preferred, so usage guidance is strong but not exhaustive.

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, covering the safety profile. The description adds a minor behavioral detail (comments may come from a coach or athlete) but does not disclose pagination, return format, or any other operational traits. It adds some value but not substantial context.

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

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

The description is a single, efficient sentence that immediately states the action and object. It contains no filler or redundant phrasing, and the parenthetical example adds context without bloat.

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

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

The tool is simple (one parameter, straightforward action), has a complete output schema, and annotations cover safety and idempotency. The description, combined with the schema and annotations, provides everything an agent needs to correctly invoke the tool. No missing critical information.

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

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

Schema description coverage is 100% – the 'id' parameter is fully documented with type, example, and origin. The description does not add any additional parameter information, so the baseline of 3 applies. No extra semantics are needed since the schema is sufficient.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List') and the resource ('comments and notes on one activity'). It is specific enough to distinguish from sibling tools like get_activity or get_activity_streams, as it uniquely targets comments/notes. No ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 no guidance on when to use this tool versus alternatives. It does not mention that it is the tool for retrieving comments, nor does it exclude any scenarios. An agent must infer from the name and description 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context: the default date range (today and next 2 weeks) and that workout steps are included as text, which is beyond what annotations provide. No contradictions detected.

Agents need to know what a tool does to the 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 with no fluff. The primary purpose is front-loaded, followed by content types, default range, and usage. Every sentence earns its place and the structure is efficient and easy to parse.

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

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

For a read-only list tool with an output schema and rich annotations, the description covers the essential context: what it lists, the default time window, and a suggested use case. It does not explain return structure (covered by output schema) or parameter details (covered by schema). The only minor gap is explicit guidance on alternative tools, but that is handled in usage guidelines.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including defaults for oldest and newest. The description adds minimal extra meaning, only hinting at include_descriptions via 'workout steps as text.' This meets the baseline 3 for high schema coverage; the description does not meaningfully compensate for any 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 clearly states the tool lists calendar entries and enumerates the specific types (workouts, races, notes, holidays, sickness, injuries), making the resource and scope unambiguous. It also implies a distinction from activity listing by focusing on planned vs. completed activities, helping an agent differentiate it from list_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 gives a clear context: 'Use it to see what is planned or to compare the plan with completed activities.' This tells the agent when to use it, but it does not explicitly name alternatives or exclusion conditions, such as 'use list_activities for completed activities' or 'use get_event for a single event.' Thus it stops short of full explicitness.

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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about what data is included and the example reminder threshold, but it does not disclose operational details such as pagination, default retired-gear filtering, or type-filter behavior beyond the schema.

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

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

The description is a single well-structured sentence that front-loads the action and resource, then gives concrete examples and the key return fields. Every phrase adds value and there is no redundancy with the annotations.

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

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

For a simple read-only list tool with zero required parameters, a full output schema, and strong annotations, the description is largely complete. The only minor gap is that it does not call out optional filtering or retired-gear handling, but the schema covers those 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?

Schema description coverage is 100%, so both the optional type and include_retired parameters are already documented in the input schema. The description adds no parameter-level guidance beyond generic examples of gear types, so the baseline 3 is appropriate.

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

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

The description opens with the specific verb-resource pair "List gear" and then expands with concrete examples (running shoes, bikes) and the data returned (distance, time, activity count, maintenance/replacement reminders). This clearly distinguishes the tool from sibling mutation tools like update_gear or add_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?

It is clear that this tool is for retrieving gear inventory with accumulated stats and reminders, so an agent can infer when to call it. It does not explicitly state when not to use it or name alternatives, but the read-only verb and the resource focus provide enough context for correct selection among siblings.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by clarifying that this returns a summary view (name, sport, duration, load) and explicitly does not include workout steps, which is a meaningful behavioral boundary.

Agents need to know what a tool does to the 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 with no filler. The primary purpose is front-loaded, the contents are listed concisely, and the pointer to get_workout is placed at the end without disrupting the main statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 listing tool with an output schema, full parameter coverage, and comprehensive annotations, the description is complete. It tells the agent what is returned, the optional filter, and where to go for more granular workout steps, with nothing essential missing.

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

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

The schema already fully documents the single optional folder_id parameter with the description 'Only this folder or plan,' so the tool description does not need to add parameter details. Nothing in the description contradicts or enhances the schema's parameter 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?

The description states a specific verb ('List') and resource ('the athlete's workout library'), then enumerates the contents: folders, training plans, and workouts with name, sport, duration, and load. It also distinguishes this tool from get_workout by noting that the steps of a workout are not included here, 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 explicitly routes the agent to get_workout when the steps of a workout are needed, which provides clear guidance for a closely related alternative. It does not enumerate other sibling tools like list_activities, but the scoping to 'workout library' and 'training plans' is enough to imply when this tool is appropriate.

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

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

The description goes beyond the annotations by explaining that the tool creates a manual activity matching the plan, which is a meaningful side effect. It also states the date constraint. This aligns with annotations (readOnlyHint=false, destructiveHint=false) and adds useful context 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 with no filler. It front-loads the main purpose and immediately follows with the key behavioral and date constraints, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a single well-documented parameter and an output schema, the description covers the essential aspects: what it does, why it is used, when it applies, and its side effect. 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% and the single parameter id is fully described as 'Planned workout event id.' The description does not add further parameter-level detail, but since the schema already documents the only parameter, 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 identifies the specific action (marking a planned workout as completed) and the resource (planned workout), and adds the key clarifying detail that it creates a manual activity matching the plan. This distinguishes it from sibling tools like update_workout or create_manual_activity by tying the activity to a plan.

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

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

The description provides clear usage context: it is for sessions done without a watch and only for today or past dates. It does not explicitly name alternative tools or state when not to use it beyond the date restriction, but the context is strong enough for an agent to decide appropriately.

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 useful behavioral details not fully captured by annotations: case-insensitive substring matching, the '#' tag prefix convention, and the fact that search is not date-dependent. The readOnlyHint/idempotentHint annotations already cover safety, so the description adds meaningful behavioral context without contradiction.

Agents need to know what a tool does to the 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 focused sentences with no filler. The first sentence defines the core behavior and query syntax; the second gives the intended use case. Information is front-loaded and every sentence earns its place.

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

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

For a simple read-only search tool with a complete input schema and an output schema, the description provides everything an agent needs: search modes, syntax examples, case sensitivity, and the intended scenario. No important operational detail is missing.

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

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

The input schema already covers both parameters completely, so the baseline is 3. The description adds value by clarifying that name matching is case-insensitive substring and by providing a concrete tag example ('#race'), enriching the query parameter semantics beyond the schema.

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

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

The description states a specific action ('Search all activities') and specifies two distinct search modes (name substring or tag prefix). It also clarifies that it searches by name/tag rather than date, which differentiates it from siblings like list_activities or get_activity.

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

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

The description gives a clear use case: 'Use it to find specific sessions regardless of date.' This provides context for when to invoke it, though it does not explicitly name alternatives or state when not to use it. Some sibling differentiation is implicit in the name/tag search behavior.

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, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: results are limited to past activities, intensity is expressed as % of threshold, and the threshold type depends on the selected metric. This helps the agent understand what the search actually means.

Agents need to know what a tool does to the 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 with no filler. The core action and criteria are front-loaded, and the example is compact and clarifying. Every sentence contributes meaning.

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

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

For a read-only search tool with an output schema and safety annotations, this description is largely complete. It explains the core concept and intensity semantics. The main gaps are not stating duration units explicitly and not addressing how this tool relates to search_activities, but these are minor given the schema and parameter names.

Complex tools with many parameters or behaviors need more documentation. 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 71%, so the description partially compensates by explaining that intensity is a percentage of threshold and giving an interval example. However, it does not clarify that durations are in seconds (the example uses minutes while parameter names end in `_s`), and the min/max duration parameters still rely on their names rather than explicit description.

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

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

The description uses a specific verb and resource: 'Find past activities containing intervals of a given duration and intensity.' The concrete example ('4–6 minute reps at 95–105% of threshold') makes the tool's purpose unmistakable. It does not explicitly distinguish itself from sibling search tools like search_activities, but the interval-specific matching criteria make the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage context is implied: use this tool when you need past activities containing intervals matching duration and intensity criteria. However, there is no explicit when-not-to-use guidance or mention of alternatives such as search_activities or list_activities, leaving the agent to infer the boundary between sibling 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?

The annotations already establish that this is not read-only and not destructive, but the description adds a meaningful behavioral detail: it performs a partial update and leaves unspecified fields untouched. This prevents an agent from assuming omitted fields are reset to defaults, which is valuable beyond the annotation hints.

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

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

Two compact sentences: the first states the action and scope, the second clarifies update semantics. Every phrase earns its place, and the most important 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 partial-update mutation tool, the description covers the resource, the editable fields, and the key behavioral rule. The output schema and annotations cover return behavior and safety, and the schema documents the required id. It could be slightly more complete by noting how to obtain the id, but that is already present in the schema parameter description.

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

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

With only 56% schema description coverage, the description compensates by naming nearly every parameter in natural language, including 'perceived exertion (RPE)', 'feel', 'tags', and 'race/commute flags'. It helps map user intent to schema field names, though it does not add constraints or replacement semantics that are already 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 uses a specific verb ('Edit') and resource ('a completed activity'), then enumerates the exact editable fields. This clearly separates it from create/get tools in the sibling list, such as create_manual_activity and get_activity.

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

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

The phrase 'Edit a completed activity' implies the tool is for modifying an existing activity rather than creating one, and 'Only the fields you pass are changed' gives useful update semantics. However, it does not explicitly state when to prefer this over sibling tools like update_workout or create_manual_activity, nor does it provide exclusions.

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

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

Annotations already mark the tool as non-read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: only passed fields are changed, user confirmation is required, and the workout description parameter has a strict syntax with edge cases like '400m' meaning minutes. No contradiction with annotations.

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

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

The description is front-loaded with the core action and confirmation requirement, then moves into a dense but necessary syntax reference. The long second paragraph earns its place because it documents a complex parameter format with examples and edge cases; 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?

Given the 11-parameter schema, the output schema, and the annotations, the description is complete enough for an agent to invoke the tool correctly. It covers the partial-update behavior, the user-confirmation requirement, and the one truly complex parameter (workout text syntax). Remaining parameter details are already present in the schema.

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

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

With 73% schema coverage, the schema already documents most parameters. The description adds critical meaning for the description parameter by fully explaining workout text syntax, units, repeats, and unsupported bpm ranges, and it clarifies that all optional parameters only apply when explicitly passed.

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

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

The description opens with a specific action and resource: 'Change a calendar event', then lists concrete operations (move date, rename, rewrite workout steps). It clearly conveys partial-update semantics, but it does not explicitly differentiate this tool from siblings like update_workout or create_events, so it stops short of a 5.

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

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

The description provides an operational guideline: 'Confirm the change with the user first', and implies use when modifying an existing calendar event. However, it never states when to prefer this tool over update_workout or create_events, nor does it give exclusions or alternative routing.

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

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

Annotations already carry the safety profile (not read-only, not destructive, idempotent), and the description adds no behavioral context beyond that—no information about partial-update behavior, what happens if the id doesn't exist, or rename-specific side effects. It neither contradicts nor enriches the annotations.

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

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

A single tightly-written sentence that front-loads the primary action before the secondary one. Economical and readable, though it spends its limited words on the confusing 'or plan' phrase rather than clarifying scope.

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

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

An output schema exists so return values are covered, but with 0% param documentation the description must fill the gap. It doesn't state that only the required 'id' is needed for a partial update, whether name and description are independently updatable, or how the folder/plan ambiguity is resolved—leaving a simple tool under-specified.

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

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

With 0% schema description coverage, the description must compensate, and it partially does: 'name' maps to the rename action and 'description' maps to the change-description action. However, it doesn't clarify the role of 'id' when targeting 'a folder or plan,' leaving the semantics of the one required parameter ambiguous.

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

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

Uses a specific verb ('Rename'/'change') with a clear resource ('workout library folder'), and the title reinforces this. However, 'or plan' muddies the target resource—a plan is a distinct entity with its own sibling tools (get_training_plan), so it's unclear whether this tool operates on folders, plans, or both.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tool versus alternatives. Among siblings like update_workout, update_event, and create_folder, nothing explains when updating a folder is appropriate, what distinguishes it from updating a plan, or any prerequisites. The context is left entirely to inference.

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

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

Annotations already indicate a non-read-only, non-destructive, idempotent mutation. The description adds crucial behavioral context: 'Only the fields you pass are changed' clarifies partial update semantics, and the retirement example shows a specific use case. This adds value beyond the 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?

Two sentences, zero redundant words. The key actions are front-loaded, the example is illustrative, and the partial-update note is placed last. Every phrase 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 tool with 4 flat parameters and an output schema present, the description covers the core behavior and the retirement workflow. It doesn't mention that id is required, but the schema clearly marks it required and explains its source. No critical information is missing for an agent to correctly invoke the tool.

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

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

Schema description coverage is 50% (id and retired documented; name and notes not). The description compensates by explaining that 'name' is for renaming and 'notes' for updating notes, and illustrates 'retired' with a dated example. It doesn't detail the id parameter, but the schema already says 'from list_gear', so the necessary meaning is covered.

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

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

The description states specific actions ('Rename gear, change its notes, or retire it') with a clear resource (gear), and differentiates from create_gear by referencing it for adding a replacement. This distinguishes it from sibling create_gear without needing to open schemas.

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

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

The description gives a clear context for retirement (e.g., worn-out shoes) and points to create_gear for adding a new pair, implying a workflow. It doesn't explicitly state when not to use this tool, but since it's the only update tool for gear, the guidance is adequate for selecting 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?

With annotations already indicating a mutable, non-idempotent operation, the description adds useful behavioral context by explaining that reset starts counting again and presenting the three modes. It does not describe parameter exclusivity or side effects, but the annotations lower the burden and the description adds meaningful context.

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

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

A single sentence conveys the essential operations and even adds a clarifying parenthetical for reset. No filler, no repetition of schema details, and the core action 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 tool with 7 parameters and low schema coverage, the description omits important operational constraints: whether reset can be combined with new limits, whether snooze_days is exclusive with days, and what happens when no operation parameter is provided. The presence of an output schema helps but does not resolve these gaps.

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

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

Schema description coverage is only 29%, so the description must compensate. It maps reset to 'starts counting again', snooze to 'snooze it', and change to 'change its limits', but it does not explicitly map days, distance_km, or name to those limits. The grouping is helpful but leaves ambiguity.

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

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

The description names a specific verb ('Reset... snooze... change') and a specific resource ('a gear reminder'), and clarifies the three distinct operations the tool performs. It clearly differentiates from the sibling add_gear_reminder by addressing existing reminders rather than creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context for when to use the tool, particularly for resetting after maintenance, snoozing, or changing limits. It does not explicitly exclude add_gear_reminder for new reminders or describe when snoozing is preferable to changing limits, but the intent is clear.

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=false, destructiveHint=false, idempotentHint=true), the description discloses key hidden behaviors: partial updates ('Only the fields you pass are changed'), non-removable measurements, and clearing semantics for ratings (0) and comments (empty string). This meaningfully informs the agent about side effects without contradicting any annotation.

Agents need to know what a tool does to the 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 with no filler. The purpose is front-loaded, the partial-change rule is immediate, and the removal/clearing semantics are presented compactly. Every sentence adds needed information, and the JSON formatting of the quoted empty string is a minor but acceptable touch.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 description covers the non-obvious mutation behavior for a 15-parameter tool and relies on the schema for ranges and required date. It slightly under-specifies the measurement grouping (steps is not mentioned and 'sleep' could conflate sleep_quality with sleep_hours/sleep_score), but with an output schema present and annotations providing idempotency/safety, this is not a critical gap.

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

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

With only 53% schema description coverage, the description compensates by grouping parameters (weight, resting HR, HRV, sleep, ratings, comments) and explaining how to clear ratings and comments, which is not in the schema. It stops short of documenting every un-described parameter (e.g., steps), but the added partial-update and overwrite semantics are valuable.

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

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

The description opens with 'Log or correct wellness data for one day' – a specific verb (log/correct), resource (wellness data), and temporal scope (one day), followed by the categories of fields. This clearly separates it from sibling get_wellness and other update_* 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 states the action and scope ('Log or correct wellness data for one day') and adds partial-update behavior, which conveys when it should be used. It does not explicitly name alternatives or exclusions, but given the sibling list includes only get_wellness as the read counterpart, the usage context is clear enough.

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

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

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the key partial-update behavior ('Only the fields you pass are changed') and clarifies that the description parameter uses a specific workout text syntax. It does not discuss auth, rate limits, or side effects, but given the annotations, the added behavioral context is sufficient.

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

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

The core action is front-loaded in the first sentence, and the subsequent syntax block is dense but directly necessary for correctly formatting the description parameter. Every sentence adds operational value; there is no filler.

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

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

For a tool with 8 parameters and a syntax-heavy description field, the definition covers the main complexity: partial updates, field mappings, and the workout text grammar. The output schema exists, and the annotations cover the safety profile, so nothing critical is missing for an agent to call 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?

With schema description coverage at 50%, the description compensates substantially: it maps 'name, steps, sport, folder' to the relevant parameters and provides a detailed syntax guide for the description parameter, including durations, distances, repeats, sections, power, and unsupported bpm ranges. This goes far beyond the schema's minimal descriptions.

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

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

The description opens with 'Change a library workout (name, steps, sport, folder)', giving a specific verb, resource, and the fields affected. This clearly distinguishes it from sibling tools like create_workouts, duplicate_workouts, and get_workout by scoping it to modifying an existing library 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 conveys that this tool is for modifying an existing library workout and that it performs a partial update ('Only the fields you pass are changed'), so the usage context is implied. However, it does not explicitly name alternatives such as create_workouts for new workouts or duplicate_workouts for copying, nor does it state when not 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.