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

Annotations already declare readOnlyHint and openWorldHint, but the description adds real behavioral context: two API calls (activity + all streams), a method reference via get_guide, the moving-vs-pause rule, grade confidence flagging, and the caveat that climb gains are not total elevation gain. These are meaningful disclosures beyond the annotations, though error/permission behavior is not covered.

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

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

Front-loads the use case, then packs per-segment fields, defaults, caveats, and cost into a dense but scannable block. Every sentence carries information, though the middle paragraph is thick enough to slow reading slightly.

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 12 parameters and no output schema, the description carries the return-value burden and does list the emitted per-segment fields and text-vs-json behavior. Cost, method guide, and key caveats are present; only edge cases like invalid activity ids are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics: defaults vary by sport (foot vs bike), max_segments applies to the text listing, and segment thresholds interact with grade confidence. This meaningfully complements the schema.

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

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

States a specific verb (analyze/split) and resource (climbs, descents, sections, pauses) and scopes it to recordings without meaningful intervals. This clearly separates it from the interval-oriented siblings like get_activity_intervals or find_similar_intervals.

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

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

Gives a clear when-to-use trigger: activities without useful intervals such as tours, mountain hikes, and trail runs. It implies but does not explicitly name the alternative (interval analysis) or state exclusions, so it stops just short of a full routing rule.

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

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

Annotations only declare readOnlyHint/openWorldHint, and the description confirms read-only while adding substantial behavioral detail: alignment is by order/duration/distance/target intensity and never by names, laps splitting one effort are merged, time past the plan is reported separately, and unpaired runs return up to three candidates. This is meaningful disclosure well beyond structured fields.

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

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

The purpose is front-loaded and every sentence carries information, but the body is a dense, run-on block of clauses that is hard to parse on first read. It could be trimmed and bulleted without losing content.

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

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

For a 9-parameter, nested-object tool with no output schema, the description does the heavy lifting well: it enumerates the per-step metrics returned, alignment confidence, deviation notes, and the unpaired fallback. A brief note on failure behavior when nothing can be paired would make it fully complete.

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

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

Schema coverage is 100% (baseline 3), and the description adds real meaning: event_id defaults to the paired event, planned_workout_doc is the add_or_update_event document format used when the event was deleted, and the tolerance parameters drive flagging/splitting behavior. The uplift over the already-complete schema is modest but genuine.

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

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

The opening line states a precise verb+resource: check how a planned workout was executed, or evaluate each detected interval of a single activity when no plan exists. The scope is specific and clearly distinct from generic activity-listing or compliance tools, though it never names a sibling (e.g. get_plan_compliance) to sharpen the contrast.

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 covers the two usage modes (with a plan vs. without) and names the plan sources (planned_workout_doc, event_id, or the paired event), so an agent knows when this applies. It stops short of stating when NOT to use it or which sibling to prefer for closely-related questions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description still adds substantial context beyond them: read-only confirmation, the cost model ('one API call per activity and duration (up to 250) plus the list and gear calls'), an important caveat that different bikes' power meters are not calibrated, and that no verdict is returned.

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

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

Front-loaded with the 'Use to...' purpose sentence, then dense but valuable detail on inputs, cost, and caveats. Every clause carries information, though the second block is a long run of comma-separated facts that could be slightly more 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?

For a 10-parameter, no-output-schema analytical tool, the description explains what the result matrix contains (activities by duration with best average of the stream plus best activity per duration), the selection inputs, cost, and caveats, and points to a method guide. It is complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates a few constraints (limit 10/max 25, at most 10 durations, last-90-days default) but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('compare peak efforts ... of several activities side by side') and immediately distinguishes itself from the sibling by noting 'One activity in detail: get_best_efforts.' An agent can tell this apart from get_best_efforts and compare_power_streams without opening a schema.

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

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

Gives concrete when-to-use scenarios ('development over a block, races, or whether a new bike or power meter reads differently') and explicitly names the single-activity alternative. The condition that selects the alternative tool is spelled out, so nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the reiterated 'Read-only' is redundant but consistent. The description adds real behavioral substance beyond that: no calibration and no correction factor, sensor names sourced only from the file's device data, samples excluded as coasting/missing/outliers, and the statistical outputs produced per mode.

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

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

Front-loaded with the purpose and the one-ride/several-ride fork, and each sentence carries information. The two dense paragraphs are long for a tool description, but no sentence is filler and the ordering is logical.

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

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

No output schema exists, yet the description spells out the returned metrics (offset in W and %, per power band, 30/60 s windows, drift over quarters, lag, best efforts, exclusions) and the multi-ride aggregation (median, between-ride SD, range, per bike and power meter). It also points to the method guide. Nothing needed to call or interpret this 12-parameter tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds mode-dependent semantics the schema cannot express: which parameters apply only to one ride (start_index/end_index) versus several (start_date/end_date/limit/detail_level), plus 'duplicates ignored, cut to limit' for activity_ids. That meaningfully exceeds the schema's per-field 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 first sentence states a specific verb and resource: 'compare two power meters recorded on the same ride (watts vs secondary_power by default)'. It also defines scope (one ride or across several rides), which distinguishes it from compare_best_efforts and compare_workouts without opening a schema.

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

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

It clearly branches on the selecting condition: pass activity_id for one ride, or omit it / pass activity_ids for several rides, with defaults (180 days, newest first, limit 10, max 20). It does not name sibling alternatives explicitly, so an agent must infer routing, but the mode selection guidance is precise.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the API-call cost ('one API call per activity plus 1-3'), how intervals are classified (main set, surges, other, excluded), the comparison inclusion rule (length ±25%, intensity ±8 points of FTP), the reliability caveat (n < 3 not reliable), that RPE is whole-activity only, that gear/power meter differences are flagged, and that no verdict is issued.

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

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

The purpose is front-loaded in the first clause, followed by dense but relevant operational detail. It is long and packed with parentheticals, which slightly taxes readability, but nearly every sentence carries information an agent needs to invoke and interpret 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?

For a 19-parameter, no-output-schema tool, the description covers selection scope, filtering defaults, interval classification, computed metrics (power, NP, HR, max HR, cadence, W/bpm), trend semantics, reliability thresholds, and known limitations. An agent has enough to call it correctly and interpret results without a return schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: how the reference pattern is chosen (reference_activity_id, else the newest), that query and activity_ids are alternatives, and how interval filters replace defaults (e.g. min_intensity replacing the 70% floor). This adds genuine semantics beyond per-field schema text.

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

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

States a specific verb and resource (compare repeated executions of the same workout over time) with the scope qualifier 'on truly comparable work intervals.' This clearly differentiates it from siblings like compare_best_efforts, find_similar_intervals, and compare_power_streams, which handle different comparison units.

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

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

Gives a concrete usage trigger ('repeated executions of the same workout over time, e.g. every 3 x 10 min threshold session') and points to the method guide via get_guide. It does not explicitly name which sibling to use instead when the user wants a different kind of comparison, so routing is implied rather than spelled out.

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

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

Adds a lot beyond readOnlyHint/openWorldHint: API call cost ('one API call, +2 with a reference, +1 gear catalog'), defaulting behavior for sport and date windows, and a genuine comparability caveat ('watts of different power meters are not comparable, use % of FTP'). The description even points to a method guide via get_guide.

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

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

Purpose is front-loaded and every sentence carries information, including return fields and the guide pointer. It is dense with nested parentheticals, which makes it slightly harder to scan, but given 18 parameters the length is largely earned.

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

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

With no output schema, the description explicitly enumerates return fields (date, sport, interval summary, load, FTP at the time, gear, power meter, compliance, comparability score 0-100 with reasons), covering the gap. Defaults, cost, and alternatives are all present, so an agent needs nothing further to call it correctly.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real meaning: the derivation of the reference window (length ±25%, intensity ±8 points of FTP), the 365-day default lookback, and how sport_types defaults. It does not document every parameter, but the interaction semantics it covers are the ones an agent cannot infer 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?

Opens with a specific verb+resource+scope: 'find earlier activities with intervals of a given length and intensity', and explicitly names the sibling it is not ('Details: get_activity_intervals; same workout over time: compare_workouts'). An agent can distinguish it from the other ~50 siblings without opening a schema.

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

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

States the two mutually exclusive invocation modes ('Pass min/max_secs and min/max_intensity, or reference_activity_id') and the precedence rule ('explicit values win'). Also routes the agent to the right alternatives (get_activity_intervals for details, compare_workouts for the same workout over time).

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

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

Annotations already declare readOnlyHint=true, and the description restates 'Read-only' (redundant but consistent). It adds genuine behavioral context beyond annotations: default date window, page size, that any filter/sort/offset/format switch yields a paged listing with total and next offset, and that unnamed activities are hidden unless opted in.

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

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

Front-loads the purpose and default behavior before detailing output modes, filters, and the alternative tool. It is dense and slightly overpacked across line breaks, but nearly every clause carries information useful for invocation.

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 12-parameter tool with no output schema, the description covers defaults, filters, paging, output modes, and the single-activity alternative, plus a pointer to the guide method. It is close to complete, lacking only explicit return-shape detail, which is partially implied by detail_level and output_format.

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 12 parameters, making 3 the baseline. The description reinforces the filter/sort/offset and detail_level/output_format behavior and the interaction that any of them triggers paging, but adds little syntax beyond what the schema already states.

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

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

States a specific verb and resource ('find activities and their ids in a date range') and gives a concrete example ('all rides on one bike over a season'). It also differentiates from the sibling for single-activity depth by naming get_activity_report, so an agent can tell it apart from the many get_activity_* tools without opening schemas.

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

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

Provides clear usage context and defaults ('default the last 30 days up to today, 10 per page') and explicitly routes the agent to get_activity_report for one activity in depth. It does not state hard when-not conditions, but the scope rules (nothing outside the date range, unnamed hidden) effectively bound usage.

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

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

Adds context beyond annotations: 'Facts and counts, no verdict', and an explicit cost signal ('1-3 API requests'), plus a pointer to the methodology guide. The 'read-only' restatement duplicates readOnlyHint, but the request-count and no-verdict framing are genuinely useful behavioral disclosures.

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 dense paragraphs, front-loaded with the primary 'use to' clause and the mode split before the enumeration. Long but essentially every clause carries content; the method/guide pointer is minor overhead.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly: it specifies what is reported for a single activity and for a period, the default window and max range, and the request cost. An agent can call it correctly in either mode without further context.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the activity_id mode switch and detail_level semantics. The description reinforces the period defaults but introduces no syntax or format detail the schema lacks, so baseline 3 applies.

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

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

States a specific verb+resource: auditing where an activity's data came from and what is missing, with an explicit dual mode (single activity vs period coverage). It enumerates the concrete things reported (sync/source, stops, laps vs intervals, sensors, coverage), which separates it from generic readers like get_activity_streams and get_activity_details, though it never names a sibling directly.

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

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

Opens with 'Use to check...' and gives the selecting condition between the two modes (with activity_id = one activity, without = period completeness). It omits explicit exclusions or named alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' merely confirms that. However, it adds genuinely useful behavioral context: it enumerates the return payload (summary, fueling, weather, W′ balance), documents the null/NaN convention for missing custom field values, and notes fields are 'read from the athlete's own definitions'. No contradiction with annotations.

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

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

Front-loaded with the 'Use when...' routing sentence, and most sentences carry payload detail. Slightly dense and the trailing 'Read-only. Method: intervals://methods/activity-data' clauses add marginal value, but nothing is wasted enough to hurt usability.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly (summary fields, custom fields, null semantics, what full adds). Combined with 100% schema coverage on inputs, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by clarifying what detail_level=full adds ('time in zones, running dynamics and other raw fields') and what custom fields contain (name, code, value, units), adding meaning 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?

States a specific verb+resource (fetch one activity's full details) and explicitly positions it relative to a sibling: 'needed beyond get_activity_report'. An agent can distinguish this from get_activity_report, get_activity_intervals, and get_activity_streams without opening the schema.

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

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

Names the alternative tool (get_activity_report) and the condition that selects this one ('full summary, thresholds or device custom fields ... beyond'). The detail_level semantics (compact/standard/full) further guide selection, so the routing decision is explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Read-only, one API call'. It adds genuinely useful non-obvious context: results are computed by Intervals.icu, pace/GAP buckets are speeds in m/s rendered as a pace range, and bucket_size only affects power and hr.

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

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

Front-loads the purpose in the first clause and follows with concrete examples, then output format. Slightly dense with parenthetical asides, but every sentence carries information and there is no filler.

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

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

With no output schema, the description usefully describes the return shape (seconds and % per bucket) and the units for each metric. It also points to intervals://methods/comparisons for methodology. Complete enough to invoke correctly, though pagination/volume of buckets is not addressed.

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 enum values, defaults and bucket_size semantics are already documented in the schema. The description's restatement of units (W, bpm, m/s) and the bucket_size restriction largely duplicates it, adding no syntax or edge-case detail beyond the schema.

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

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

States a specific verb+resource (time distribution of one activity) and immediately scopes it as 'independent of zone definitions', which cleanly distinguishes it from the sibling get_intensity_distribution. The concrete examples (polarisation, time above FTP, pace spread) pin down exactly what output to expect.

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

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

'Use for...' gives a clear usage context and the 'independent of zone definitions' framing implies when this is preferable to zone-based siblings. However, it never explicitly names an alternative tool or states when NOT to use it, so the routing signal is implicit rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description goes well beyond them with a real cost model ('2 API calls, +1 for streams, +1 for a paired event'), cadence conventions that depend on sport, and what include_planned_types actually surfaces (the matched planned step and time beyond plan). This is exactly the kind of context annotations cannot carry.

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

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

Purpose is front-loaded in the first clause, with supporting semantics and routing packed into two dense paragraphs; nearly every sentence carries information. The trailing methods-URI pointer and some clause packing make it slightly heavier than ideal, but nothing is clearly wasted.

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

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

For a 7-parameter tool with a nested object and no output schema, the description covers cost, cadence semantics, stream evaluation, planned-step matching, and the json alternative's contents. Only fine-grained return-shape detail is left implicit, which is a minor gap given the schema handles enums and 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 coverage is 100% so the baseline is 3, but the description adds genuine semantics: stream_types values are illustrated ('Stamina,secondary_power', the custom/all shorthands) and its per-interval output (start/end/min/max/mean/delta), and it explains that planned_workout_doc implies include_planned_types. Useful supplement rather than mere repetition.

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

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

States a specific verb+resource with scope: 'per-interval numbers of one activity (laps or detected efforts)' followed by the exact metrics returned. It also explicitly carves itself away from siblings, routing the no-intervals case to analyze_climbs and cross-referencing list_activity_streams for available 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?

Gives a clear when-to-use ('use for per-interval numbers') plus one explicit alternative condition ('Without intervals use analyze_climbs') and points to supplementary methods docs via get_guide. It does not address the nearer siblings like find_similar_intervals or compare_workouts, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the parenthetical '(read-only)' merely restates structured data rather than adding new context. The description does contribute the shape of the payload (per-message author, time, type, text), which is useful behavior detail beyond the annotations.

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

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

A single sentence that front-loads the action ('Use to read...') and folds the returned fields into one compact clause. No filler.

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

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

With no output schema, the description usefully enumerates the fields each message contains, so an agent knows what it gets back. It is nearly complete for a simple single-parameter read tool, though it omits ordering or volume expectations.

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

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

Only one parameter exists and schema description coverage is 100% (activity_id with an example format), so the schema already carries the semantics. The description adds nothing about the parameter, making the baseline 3 appropriate.

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

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

States a specific verb and resource: read notes and comments on a single activity, and enumerates the fields returned (author, time, type, text). This is clearly distinct from siblings like get_activity_details or get_activity_streams, though it does not name an alternative explicitly.

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

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

The opening 'Use to read...' implies the usage context (retrieving activity commentary) but gives no when-not guidance, no prerequisites, and no comparison to sibling tools that also surface activity data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces the safety profile while adding genuine behavior: 3-4 API requests, conditional branching based on activity data, and the compact/full output distinction. It stops short of noting rate limits or exact response shape, but adds substantial context beyond the annotations.

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

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

Front-loads the routing directive and every subsequent sentence carries decision-relevant detail with no filler. It is dense and slightly run-on, but each clause earns its place by describing a branch or alternative.

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

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

Despite no output schema, the description enumerates what the overview and report contain (thresholds, device, custom fields, fueling, weather, W′ balance, data-quality notes) and how output varies with detail_level. For a 9-param composite tool with nested objects, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema carries most parameter meaning (baseline 3). The description goes further by explaining when parameters matter in practice, e.g. that planned_workout_doc is for cases like a deleted event, and it ties include_climbs to the without-intervals/500 m default.

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

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

States a specific verb+resource (a full activity report for one activity) and its scope: overview, plan vs execution, power-meter check, climbs and data quality in a single call. It distinguishes itself from verbose siblings by naming exactly which of them it subsumes and then routing to them for full detail.

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

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

Explicitly says 'use first for any question about one activity', states the conditions that trigger each sub-analysis (paired event or planned_workout_doc for plan-vs-execution; without intervals or above 500 m gain for climbs; enough valid paired samples for the second power meter), and names five alternatives for full detail.

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

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

Goes well past the readOnlyHint/openWorldHint annotations, which only confirm safety. It discloses the three output modes and their return shapes, the default stream set and that 'all' expands it, the 2000/20000 point cap with a continue hint instead of silent truncation, that downsample skips rather than averages, and that time is seconds-since-start with pauses appearing as jumps.

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

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

Front-loaded with the use case, then organized by output mode and stream selection, with zero filler sentences. It is dense and packed into one block, which costs a little scannability, but no sentence is redundant.

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

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

There is no output schema, so the description carries the return-value burden and does so fully: what summary returns (units, statistics, first/last), what full returns (CSV row per sample), what json returns (one object with arrays and next_start_index), and how empty/null values read. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema doesn't: the concrete default stream list, the semantics of 'all', the max_points default and the continuation behavior, and that slices can be expressed by index or by time. It stops short of clarifying every parameter (e.g. the index coordinate system is only hinted via get_activity_intervals).

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

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

States a specific verb and resource ('raw time-series samples of one activity') and immediately scopes it against the summary tools ('when summaries are not enough'). Sibling tools like get_activity_details or get_activity_intervals are distinguishable from this at a glance, and the enumerated streams (power, HR, cadence, altitude, custom like Stamina) confirm the exact payload.

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

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

Gives a clear selection condition ('when summaries are not enough') and routes discovery to list_activity_streams plus the intervals://methods/activity-data guide. What's missing is an explicit when-not or a named summary-tool alternative, so the agent still has to infer which sibling to fall back to.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read-only' is somewhat redundant, but the description adds real behavioral context: one API call, the defaults applied (Ride, 5 s to 60 min, both seasons), and the non-obvious filtering rule that non-curve-point durations are dropped. It also sketches the return shape (watts and W/kg per duration with the setting activity).

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

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

Front-loaded with the 'Use for' purpose, then returns, then defaults, then alternatives — a sensible priority order. It is terse to the point of using compressed fragments (s0, s1, W/kg) that trade a little readability for brevity, but nothing is wasted.

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

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

Despite no output schema, the description covers return content (watts and W/kg per duration, with the activity), defaults, filtering behavior, and sibling routing. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description restates the key defaults and the duration semantics, which is helpful but additive rather than revealing anything the schema lacks; baseline 3 applies.

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

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

States a specific verb+resource+scope: an athlete's best power per duration across whole periods (season bests, cross-season progress, custom ranges). It clearly separates itself from get_best_efforts (single activity) and get_hr_curves/get_pace_curves (other metrics) by name.

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

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

Explicitly routes the agent: 'One activity: get_best_efforts; HR and pace: get_hr_curves, get_pace_curves', and points to a deeper method guide via get_guide. The 'Use for...' opener states the intended scenario, so when/when-not is largely covered.

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

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

Annotations already establish readOnlyHint=true, but the description adds genuinely new behavioral facts: account internals (e-mail, API keys, OAuth scopes) are never returned, and the profile's time zone defines "today" for all other tools. That last point is important cross-tool semantics not derivable from 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?

Front-loaded with the selection cue and field list, then layers the privacy boundary and cross-tool semantics. The parenthetical "(read-only)" and the trailing "Details:" line are efficient, though the sport-setting sentence is slightly list-heavy.

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

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

With no output schema, the description carries the return-shape burden and does so: it enumerates returned fields, one line per sport setting, and explicitly excludes account internals. Nothing needed to call this correctly or interpret its output 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 refresh, athlete_id and output_format are already documented in the schema, and the description adds no parameter-level syntax or defaults beyond that. Baseline 3 applies; the field enumeration is about the return payload, not the inputs.

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

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

Names a specific resource (athlete profile) and enumerates the fields it returns: name, sex, DOB, location, time zone, units, weight, height, resting HR, gear, plan/coach, plus per-sport settings. It explicitly differentiates from siblings by routing detail requests to get_sport_settings, get_training_zones and get_gear_list.

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

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

"Use for who the athlete is" gives a clear selection cue, and the trailing routing line names three sibling tools for deeper detail, which prevents overlap. It stops short of explicit when-not conditions (e.g. don't call for activity data), but the alternative routing is concrete enough to guide selection.

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

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

Annotations only cover read-only/open-world, so this description carries the rest and does so well: it discloses the return shape (average in W/bpm/m/s with pace, elapsed h:mm:ss, sample indices usable as start_index/end_index), a notable edge case (windows spanning a recording pause are flagged), a hard limit (longer than the activity = not available), and cost (one API call per duration or distance plus 1-2).

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

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

Front-loaded with the 'Use for...' purpose and organized into purpose / returns / limits / alternatives / method, with no filler sentences. It is dense and abbreviation-heavy (W, bpm, m/s, h:mm:ss) and runs long, but every clause carries information.

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

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

With no output schema, the description fully compensates by documenting return fields, units, index semantics, pause flagging, defaults and a known unavailability condition, and it names the sibling tools for adjacent use cases. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the durations/distances interplay ('added to durations', 'longer than the activity = not available'), the default duration set, and the practical use of stream values like velocity_smooth with distances to get the fastest km.

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 precise verb and resource ('peak efforts of one activity: best average power, HR or speed over durations (s) or distances (m)') and gives concrete examples (peak 5 s to 20 min power, fastest km of a run). It clearly distinguishes itself from siblings compare_best_efforts and get_athlete_power_curves.

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

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

Explicitly routes the agent: 'Use for the peak efforts of one activity', 'Several activities: compare_best_efforts', 'period bests: get_athlete_power_curves', plus a pointer to the method guide. When-to-use and which alternative to pick are both stated, not inferred.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses response size (~2-3k characters), content composition, that small samples are flagged, that missing values are never 0, that a method line states windows/rules, and that no verdict is rendered. These are behavioral traits an agent cannot get from the annotations.

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

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

The directive is front-loaded and the two paragraphs are information-dense rather than padded. The second paragraph is a long run-on inventory of returned sections, but each item carries real content, so little could be cut without losing behavioral detail.

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 complex aggregator with no output schema, the description fully characterizes what comes back, the caveats (flagged small samples, missing values never 0), and the method/guide references, so an agent can call it correctly and interpret results without further discovery.

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 documents each parameter, and the description adds cross-parameter behavior: it explains that when the end date is today the response extends to the next 7 days of planned workouts and the next race. That conditional semantics goes beyond the schema, though threshold_as and detail_level nuances are left entirely to the schema.

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

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

States a specific action (one compact call) and resource (aggregated training review), and enumerates exactly what it aggregates: load, intensity, recovery, durability, plan. It is clearly separable from siblings because it explicitly lists the drill-down tools it summarizes.

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

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

'Use first for a weekly or general training review' gives an explicit entry-point directive, and it names the alternatives (get_training_load, get_intensity_distribution, get_durability, get_recovery_snapshot, get_load_projection) as the sources for further detail. An agent knows both when to pick this tool and where to go for a narrower view.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the '(read-only)' note merely restates the structured data. The description adds useful detail about the shape of the return (JSON content configuration with code, value type, units, options, aggregate), but says nothing about auth, errors, or resolution of the optional athlete default.

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 lines that front-load the purpose before enumerating fields and the id source. Every sentence carries information, though the injected 'Ids: get_custom_items' fragment is slightly telegraphic rather than prose.

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

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

With no output schema, the description carries the return-value burden and does so by listing which fields come back plus the JSON content configuration. Combined with full schema coverage and read-only annotations, an agent has what it needs; only error/empty-result behavior is unaddressed.

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

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

Schema description coverage is 100%, so both item_id and athlete_id are already documented, including the default for athlete_id. The description only echoes the schema's pointer to get_custom_items for ids and adds no new parameter semantics, making the baseline 3 appropriate.

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

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

The description states a specific verb+resource ('full definition of one custom item') and enumerates the fields returned (name, type, description, visibility, index, content configuration). It distinguishes itself from the sibling get_custom_items by noting it retrieves a single item by id, though the plural-vs-singular distinction is conveyed mostly by the tool name.

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

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

'Use for the full definition of one custom item' gives implied usage context, and 'Ids: get_custom_items' routes the agent to the sibling that supplies the required identifier. However, there is no explicit statement of when not to use it or what an alternative would be for related needs.

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

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

Annotations already declare readOnly=true and openWorld=false, so 'read-only' is redundant. The valuable addition is the disclosed side effect: the call 'refreshes the cached definitions the other tools use to label custom fields' – a non-obvious behavioral trait an agent would not infer from the schema or annotations.

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

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

Front-loaded with the primary purpose, followed by the returned-field list and the detail-tool pointer. Two short paragraphs, no filler. The loose '...' enumeration costs a little precision but not much length.

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

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

For a no-output-schema list tool with safety already covered by annotations, the description states the returned fields, discloses the cache-refresh side effect, and points to the detail sibling. An agent has enough to call it correctly; only the absence of any pagination/scope note keeps it from 5.

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

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

Only one parameter (athlete_id) and schema description coverage is 100% ('Default: the configured athlete'), so the schema carries the semantics. The description adds nothing about the parameter, making the baseline 3 correct.

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

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

States a specific verb and resource ('list the athlete's custom items'), enumerates the item categories (charts, activity, interval and wellness fields, streams, zones) and the returned fields (id, name, type, description). It also names the sibling get_custom_item_by_id for the single-item case, so the agent can distinguish the two without opening schemas.

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

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

'Use to list...' gives a clear triggering context, and the closing pointer 'Full definition of one item: get_custom_item_by_id' routes the agent to the right alternative when a single item is needed. It stops short of an explicit when-not, so it lands at 4 rather than 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 only cover readOnlyHint and openWorldHint, and the description adds real behavioral context on top: it states the output is statistics-only with no verdict, that sessions failing the quality filter are counted per exclusion reason, that samples under 8 are flagged, and that mixed indoor/outdoor or mixed equipment are noted. It stops short of describing limits like rate limits or exact return fields, but the disclosure is substantive.

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

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

It is dense and heavily parenthesized, but the primary purpose is front-loaded and the length is justified by 13 parameters and nontrivial filter/output semantics. A few parenthetical clauses could be trimmed, but every block of content is relevant.

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

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

For a 13-parameter analysis tool with no output schema, the description covers the metric, the filter logic, the reported statistics, the small-sample and mixing caveats, and the machine-readable option. Return value shape is left to the output_format/detail_level parameters rather than the description, which is acceptable but leaves some detail implicit.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine meaning about how the parameters operate: the quality-filter semantics (min_minutes, stops, max_vi, max_temp_c, environment), the default 6-week window, and the framing of drift_threshold_pct as the commonly cited 5%. That goes beyond restating 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 names a specific analysis (aerobic decoupling power:HR / pace:HR plus efficiency-factor trend) applied to steady long cycling and running sessions, and it explicitly differentiates itself from get_power_hr_efficiency ('Per interval and bike'). An agent can tell exactly what this computes and how it differs from the neighboring efficiency tool.

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

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

It opens with 'Use for aerobic durability' and routes the agent to get_power_hr_efficiency when per-interval/per-bike granularity is needed and to get_guide for the method. That is clear alternative routing, though it does not spell out explicit when-not conditions (e.g., data prerequisites such as needing HR or long steady sessions).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds return-content context beyond the annotations — category, sport, planned time/load, paired activity, and the full workout document with steps and zone times — which is genuinely useful given there is no output schema. It omits any cost, auth, or size caveats.

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 use case then the return payload, with no filler. Slightly dense return enumeration but 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 no output schema, the description correctly carries the return-value burden by enumerating what comes back. Safety is handled by annotations and all four params by the schema, so the definition is nearly complete for a single-item read tool.

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

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

Schema description coverage is 100%, so event_id, athlete_id, output_format, and resolve_targets are already documented in the schema. The description's mention of 'planned time in zones' loosely relates to resolve_targets but adds no syntax or format guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'read one calendar event completely,' which contrasts with the plural sibling get_events. The 'one ... completely' framing and the workout-document detail make the object of the tool unambiguous, though it never explicitly names the sibling it complements.

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 one concrete scenario ('to read back a workout right after writing it'), which anchors usage. However, it names no alternatives (get_events, get_library_workout) and states no when-not conditions, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the default date window and what each returned event contains (category, sport, planned time/load, paired activity), which goes beyond the structured fields.

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

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

Three sentences, front-loaded with purpose and scope, then return contents, then sibling routing. Every sentence earns its place with no filler.

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

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

No output schema exists, yet the description compensates by describing the event fields returned. With annotations covering safety and full schema coverage for inputs, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including defaults and the categories example. The description restates the default date range and category/sport concepts but adds no syntax or format detail beyond the schema. Baseline 3 is correct.

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

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

States a specific verb and resource ('see the athlete's calendar') and enumerates exactly what it returns (planned workouts, races, notes). It explicitly differentiates from siblings by routing to get_event_by_id for full workout steps and get_training_plan for plan phases.

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?

Clear usage context ('see the athlete's calendar') and named alternatives for adjacent needs. It does not state an explicit when-not condition, but the sibling routing makes the intended scope obvious.

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 readOnlyHint/openWorldHint, it discloses that sport settings are read first, what happens when no kJ thresholds exist (setting explained, suggest_thresholds proposes but never saves), missing vs identical curve reporting, and an API-call budget of 2-5. Rich behavioral 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?

Purpose is front-loaded and every clause is substantive; the dense multi-clause construction is efficient though slightly heavy to parse. Minor room to trim the method-reference tail.

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

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

With no output schema, the description carries the return-value burden and does so fully: watts per duration fresh/after kJ0/kJ1 with change %, missing/identical reporting, and per-activity vs athlete-curve scope. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% so baseline is 3, but the description adds meaning: curves vs activity_id selection (per-activity vs athlete curves, default 42d), and that durations map to watts fresh/after thresholds. It ties parameters to output semantics beyond the schema strings.

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

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

Names a specific analysis (best power fresh vs after kJ0/kJ1 work thresholds) and the exact data source (Intervals.icu fatigued power curves). It also explicitly distinguishes itself from the sibling get_long_ride_fatigue_profile (within one long ride).

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

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

States when to use it, the alternative condition (get_long_ride_fatigue_profile for within-ride analysis), and points to the method guide via intervals://methods/comparisons (get_guide). Alternatives and boundaries are explicit.

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

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

Annotations already cover readOnly, but the description adds substantial interpretive context: estimates vs logged intake, kcal/kJ handling, that correlations need 8+ sessions, and explicit caveats ('Not logged is never 0', 'used minus ingested is no 1:1 energy deficit', 'no targets'). It even points to the method guide via get_guide.

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

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

Front-loaded with the 'Use for' purpose, then computation and caveat details. Dense and mostly earning its place, but some clauses are telegraphic fragments ('used minus ingested is no 1:1 energy deficit') that read run-on rather than trimmed.

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

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

For an 8-parameter tool with no output schema, the description explains what the output contains (g and g/h, share of used, kcal/kJ, per-hour fluid/sodium/sweat loss, correlations with sample sizes) and the method behind them. Missing only a pointer to the closest sibling for differentiation.

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 per-parameter docs already carry baseline meaning. The description goes further by tying parameters together — activity_id selects single-activity mode, omitted triggers period mode with the 90-day default and min_minutes floor — and explains that detail_level omits notes in single-activity mode.

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

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

The opening sentence names the exact resource (carbohydrate, fluid and sodium intake), both operating modes (one activity via activity_id vs period of long sessions), and the default scope. An agent can tell this apart from generic siblings like get_nutrition_summary by the fueling-specific content and the two-mode framing.

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

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

'Use for ... intake of one activity (activity_id) or of the long sessions of a period' gives clear context and the condition that selects each mode. It stops short of naming alternatives (e.g. get_nutrition_summary) or stating when NOT to use it, so no 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 read-only and non-open-world, and the description reinforces this while adding real behavioral context: what fields are returned (distance, time, activity count, dates, notes, reminders, component mileage) and, importantly, the negative disclosure that the recording power meter is not derived from gear. The cache detail lives in the schema rather than here, so it is not double-counted.

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

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

Front-loaded with the use statement and safety profile before the dense enumeration of returned fields and the cross-tool routing. The return-field sentence is long and could be trimmed, but every clause carries information rather than filler.

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

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

With no output schema, the description correctly compensates by enumerating the returned data, including the nested components of a bike. Combined with the sibling routing for activities and power-meter provenance, an agent has enough to call and interpret this tool, though pagination/error behavior is left unaddressed.

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

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

Schema description coverage is 100%, so gear_id, refresh (cache bypass) and athlete_id are already fully documented in the schema. The description adds no parameter-level syntax or default behavior beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific verb and resource ('details of one gear item') with the permitted resource types (bike, shoes, component) and the safety profile (read-only). It also distinguishes itself from the list sibling and from activity-level tools, so the agent can identify it before opening any schema.

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

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

The opening clause ('Use for the details of one gear item') gives a clear use context, and the description routes the agent to alternatives: get_activity_details for the recording power meter and get_activities(gear_id=...) for activities on the gear. It stops short of an explicit 'do not use this for...' exclusion or a stated prerequisite beyond the gear_id hint.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the '(read-only)' note is largely redundant. The description nonetheless adds genuine behavioral context by disclosing the return shape (one row per item with the exact fields), which matters because there is no output schema.

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

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

Front-loads the purpose, then the return shape, then sibling routing, in three tight sentences with no wasted text. Structure is ideal for fast scanning.

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

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

With no output schema, the description compensates by enumerating the returned fields (id, type, name, default-for, activity count, distance, retired flag). Combined with annotation coverage and 100% schema coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so both parameters (refresh and its 30-minute cache behavior, athlete_id default) are already documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('find gear ids and get an overview of the athlete's bikes, shoes and components') and explicitly distinguishes itself from siblings get_gear_details and get_activities. An agent can select this tool without opening either schema.

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

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

Provides explicit routing: use this to find gear ids, use get_gear_details for one item's details, and get_activities(gear_id=...) for activities on a gear. The when-to-use and alternatives are fully named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable context beyond annotations: it is static text with no athlete data, and it mirrors specific MCP resources, which is genuinely useful for an agent deciding between resource and tool access.

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

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

Two tight sentences, front-loaded with the trigger condition, followed by return content. No filler.

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

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

For a single-param read-only doc tool with no output schema, the description covers purpose, trigger, return format, and staticness. Nothing relevant is missing.

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

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

Schema coverage is 100% and the enum values carry per-value descriptions in the schema. The description adds the mapping 'usage = tool overview; workout-syntax = workout format; others = method of that analysis' and ties topics to the corresponding resource URIs, slightly exceeding the baseline.

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

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

States a clear verb+resource: reading documentation on workout syntax or analysis methods. It distinguishes itself from siblings (which are all data/analysis tools) by being the documentation lookup route, but doesn't explicitly name a sibling tool for contrast.

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

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

Explicit when-to-use: before writing a workout when short tool descriptions are insufficient, or to understand how an analysis works. Names the precondition that selects this tool over just reading the schema.

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 readOnlyHint, and the description reinforces 'Read-only, one API call' while adding genuine context: the return shape (bpm per duration per curve, with the setting activity), that missing durations are listed as not available, and the default 90-day window. It does not detail rate limits or auth, but adds meaningful behavior beyond the annotations.

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

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

Front-loads the 'Use for' purpose, then return behavior, then the read-only cost note. Sentences are dense but mostly earn their place, though the 'Method: intervals://methods/comparisons (get_guide)' tail is somewhat internal noise.

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

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

With no output schema, the description carries the return-value burden and does so (bpm per duration, setting activity, not-available handling, default window). Combined with a fully documented 6-param schema, it is nearly complete, lacking only explicit constraint/exclusion guidance.

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 curves, durations, dates, athlete_id and activity_type in detail. The description only reiterates the 90-day default, which the schema also states, so it adds little beyond the structured fields.

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

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

States a specific verb+resource: the highest average heart rate sustained per duration across one or more periods. It distinguishes itself from siblings by cross-referencing get_pace_curves and get_athlete_power_curves, so an agent can identify its unique role in the curve family.

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?

Opens with 'Use for...' and gives a concrete comparison scenario, plus routes to the power-curve sibling. There is no explicit 'do not use when' exclusion, so it falls short of a full 5, but the usage context and alternatives are 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?

Annotations already establish read-only/no-open-world safety, and the description adds real behavioral context on top: missing zone data is never treated as easy, coverage is reported, and the tool is 'statistics only, no verdict'. It also flags that the mapping depends on the athlete's zone basis and zone count — useful caveats not present in structured fields.

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

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

Purpose and default period are front-loaded in the first sentence, with returns and cross-references following in a structured block. Dense and mostly waste-free, though the returns enumeration borders on listing what an output schema would normally carry.

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

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

With no output schema, the description carries the full return-shape burden itself (shares, hours, polarization index, class, per-sport and per-ISO-week breakdown, half-to-half drift), and it notes coverage reporting. An agent has enough to call and interpret the tool across all 8 optional parameters.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds interpretive layer beyond the schema: the three-zone model (below first threshold / between / above second) and the threshold_as behavior ('Z4 counts as moderate (Z2) or high (Z3)'), which clarifies how the power-to-zone decision changes the result.

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

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

States a precise verb+resource: computes training intensity distribution of a period, mapping Intervals.icu time-in-zones to a three-zone model with explicit Z1/Z2/Z3 definitions. The output list (shares, hours, polarization index, class, drift) is specific enough to distinguish it from siblings like get_training_load or get_training_zones without opening any schema.

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

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

'Use for the training intensity distribution of a period' gives a clear trigger, plus defaults (last 4 weeks, read-only). It routes to get_coach_context for the overview and get_guide/intervals://methods/intensity for method detail, but never states when to prefer it over adjacent siblings such as get_training_load or get_training_summary.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses what the read returns (steps, planned time, load, targets), which is meaningful behavioral context given there is no output schema. It does not mention auth or rate limits, but that is minor for a local read.

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

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

Two compact sentences with no waste: purpose and returned contents first, followed by the id source. Everything is front-loaded and nothing is redundant.

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

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

For a read-only, three-parameter tool with full schema coverage and annotations covering the safety profile, the description supplies everything an agent needs: what it fetches, what it contains, and where ids come from. No output schema is needed since the return fields are described.

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

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

Schema description coverage is 100%, so the schema already documents athlete_id, workout_id, and output_format. The description's "Ids: get_workout_library" adds a small hint that overlaps almost entirely with the workout_id schema description, so it earns baseline 3 rather than extra credit.

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

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

States a specific verb+resource ("read one library workout") and enumerates the returned content (steps, planned time, load, targets), which clearly separates it from the sibling get_workout_library that lists workouts. The only gap is it doesn't explicitly contrast with preview_workout, but the singular scope makes intent unambiguous.

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

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

Gives concrete usage context by naming downstream tools ("reuse it with add_or_update_event or validate_workout") and routes id lookup to get_workout_library. Clear when-to-use context, though it offers no explicit when-not or exclusion conditions.

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/openWorld annotations, it discloses meaningful behavior: starting point (CTL/ATL at end of yesterday plus today's completed load), that planned workouts without a load are reported not guessed, and that it is "arithmetic, not a forecast; no verdict." This is exactly the extra context annotations cannot carry.

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

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

Purpose and read-only guarantee are front-loaded, and the dense enumerations (returns list, scenario defaults) each carry information. It is long and packed, but nearly every clause earns its place, with only minor density overhead.

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

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

With no output schema, the description compensates by enumerating the return payload (end values, lowest form, highest ramp, ISO weeks, race days, model check, out-of-range weeks) and the compact/standard/full detail progression. An agent has enough to call and interpret it without further sources.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter semantics the schema does not: target_date defaults to the next RACE_A and is measured at start of day, and target_form triggers a search over taper_days for the load that reaches it. It also routes scenario format details to get_guide.

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

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

States a specific verb/use case ("Use for future fitness") and names the exact outputs (CTL, ATL, form projected over planned workouts) plus the two modes (calendar plan vs. what-if scenario). This cleanly distinguishes it from load-history siblings like get_training_load.

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

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

Clearly frames when to use it (forward-looking projection against the calendar or a scenario) and notes it is read-only with nothing written. It does not explicitly name an alternative tool (e.g., use get_training_load for completed/actual load), so routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, and the description still adds real behavioral context: cost profile (one stream call per ride plus 1-4, one more per id with activity_ids), that results are statistics only with small samples flagged and no verdict, and how phases are compared to the phase before the first threshold. This is exactly the beyond-annotation disclosure the dimension rewards.

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?

Dense but front-loaded: the purpose leads, then phases, scope, aggregation, safety/cost and pointers to alternatives are layered in clearly separated sentences. It is long for a description, but nearly every clause carries distinct operational information rather than filler.

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

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

For a 14-parameter analytic tool with no output schema, the description covers scope, defaults, aggregation behavior, statistical caveats, cost, and pointers to the method guide and sibling tool. Output format is governed by the detail_level/output_format parameters rather than needing prose, so the definition is close to complete.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters, making 3 the baseline. The description restates a few defaults (75-85% FTP, 750/1500 kJ, limit 6 max 12) but adds little parameter meaning the schema does not, beyond the conceptual framing of thresholds and phases.

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

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

Opens with a specific verb and resource: how long rides change at matched power as work accumulates, measured via HR, W/bpm, cadence and stamina before vs after work thresholds. It also explicitly names the sibling it is not (get_fatigue_resistance for fresh-vs-fatigued power curves), so the agent can route without opening either schema.

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

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

Gives clear context (steady segments of a power band, before vs after work thresholds) and points to the alternative (get_fatigue_resistance) plus a method guide (intervals://methods/fatigue via get_guide). It stops short of stating explicit when-not-to-use conditions, but the alternative mapping covers the main disambiguation need.

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 and openWorldHint, and the description adds substantial semantics beyond them: days without logged intake are never treated as 0 kcal, means are computed over logged days only, device burn is an estimate, and calorie balance does not measure fat change. These are non-obvious caveats an agent must know to interpret and present results correctly.

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

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

Front-loads purpose before diving into per-day and per-window output details, then caveats, then a method reference. It is dense and semicolon-heavy, but nearly every clause carries distinct information relevant to a 9-parameter analytics tool; trimming further would lose signal.

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

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

With no output schema, the description carries the full return-value burden and does so explicitly, enumerating the per-day fields (kcal, macros, burn, balance, weight) and per-window aggregates (totals, means, days without intake, weight change/slope in kg/week). It also points to the method guide, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are already documented in structured form. The description reinforces a few points (default 28-day span, configurable custom field codes, balance fallback), but largely restates what the schema already conveys, so it sits at the coverage-driven baseline.

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

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

The description names a precise resource and scope: food intake, calorie balance and weight trend over a period, with per-day and per-window breakdowns. This clearly separates it from the training/wellness siblings by domain. It stops short of naming a sibling alternative (e.g. get_wellness_trends, get_fueling_analysis) to disambiguate, so it falls just under the top mark.

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

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

"Use for food intake, calorie balance and weight trend over a period" is an explicit usage trigger and the default 28-day window and read-only nature set expectations. There is no when-not guidance or named alternative for overlapping tools, which keeps it out of the 5 band.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces with 'Read-only, one API call' while adding real behavioral detail: default 90-day curve, return contents (best time + pace + setting activity), units (min/km, min/100 m for Swim/OpenWaterSwim), and that missing distances are reported as not available.

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

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

Front-loaded with the use case, then dense factual sentences about returns, defaults, and cross-references. No filler; every clause carries information an agent needs.

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

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

With no output schema, the description carries the return-value burden and does so (time, pace, units, missing-distance handling, optional GAP). It also cross-references the HR sibling and the underlying method guide, leaving nothing essential missing for a 7-param, all-optional tool.

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

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

Schema coverage is 100%, so all seven parameters are documented in the schema itself. The description restates the same facts (gradient-adjusted pace, ~90-day default, pace units) without adding syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific noun+scope ('best times per distance over one or more periods') with concrete use cases (PBs, comparing periods, progress). It differentiates toward get_hr_curves for the HR side, but does not address the more ambiguous overlaps with get_best_efforts and compare_best_efforts in the sibling list.

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

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

'Use for...' explicitly frames the scenario, and 'HR side: get_hr_curves' points to the correct alternative when the athlete's heart-rate curves are wanted. No explicit when-not-to-use guidance, but the context is clear enough to route correctly.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the two-API-call cost, the exact pairing mechanism (paired_activity_id / paired_event_id), the one-event-per-activity rule, how missed/unplanned/out-of-range events are classified, the completion formula, and the guide method reference. This is unusually rich operational 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?

Purpose and scope are front-loaded in the first line, followed by dense but relevant edge-case rules. It is long, and the linking/formula detail could be compressed, but nearly every sentence carries information an agent needs to interpret results.

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

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

With no output schema, the description steps in to explain return semantics (planned vs. actual duration/load with deviation %, completion ratio, separate listing of unlinked activities), which is exactly what an agent needs. Only minor gaps remain around result format/pagination.

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

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

Schema coverage is 100% with self-documenting start_date/end_date/athlete_id, so the baseline is 3. The description adds the 'athlete's local date' nuance for upcoming workouts but does not clarify date semantics for the parameters themselves beyond what the schema provides.

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

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

States a specific verb (compare) and two concrete resources (planned workouts vs. activities done) scoped to a date range, which is a distinct deliverable. It does not explicitly name or contrast with potential sibling alternatives like compare_workouts or analyze_workout_execution, so an agent must infer the boundary from the name alone.

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

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

The opener 'Use to compare planned workouts with the activities done in a date range' gives clear intended usage and the read-only caveat. However, it never states when NOT to use it or which sibling to prefer for adjacent needs, leaving the reader to infer the alternative from the sibling list.

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

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

Beyond the readOnlyHint/openWorldHint annotations it discloses cost ('one API call per activity plus 2'), a reliability guard ('at least 3 per group, else not reliable'), and an explicit limitation ('statistics only, no fitness verdict'). These are exactly the traits an agent needs that annotations cannot provide.

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

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

Purpose is front-loaded, then behavior, defaults, and a method pointer follow in a logical order with no filler sentences. The middle paragraph is dense and stacks many clauses, which slightly costs readability but every clause carries information.

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

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

For a 13-parameter analytical tool with no output schema, it describes the returned shape well (per activity and band counts plus time-weighted W, HR, W/bpm, and group comparisons) and states the API cost and reliability threshold. It leaves the exact output field layout to the text/json format flags, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds interpretive context: the band-assignment rule ('puts every WORK interval ... into the power band of its average power'), the trend-group semantics for min_activities_per_group, and the default window/limit, tying the 13 parameters together conceptually.

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

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

States a specific verb and computed resource: 'track power-to-heart-rate efficiency (W per bpm at the same power) over weeks'. This distinguishes it from curve siblings (get_hr_curves, get_athlete_power_curves) and stream comparisons, which do not compute a per-band W/bpm efficiency ratio.

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?

Opens with 'Use to track ... over weeks' and gives concrete operating conditions (last 90 days of rides, band grouping, gear trends). It points to get_guide and intervals://methods/comparisons for methodology but never names a sibling tool it should be preferred over, so a discriminating agent still has to infer the 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 declare readOnlyHint=true and openWorldHint=false, and the description reinforces rather than contradicts this ('read-only, numbers only, no readiness verdict'). Beyond annotations it adds real behavioral context: today's record is flagged preliminary, today_completeness names fields not yet arrived grouped by expected timing, missing values and record update time are surfaced, and small baseline samples are flagged.

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

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

The purpose and mode constraints are front-loaded in the first sentence, followed by a dense but informative inventory of returned content. The prose is long and run-on, but with no output schema most of it earns its place by setting return-value expectations; there is little outright padding.

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

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

For a six-parameter tool with no output schema, the description carries the full burden of explaining the return payload and does so thoroughly: wellness values, load metrics, subjective and custom fields, baselines, activities, planned events, completeness diagnostics, plus a method/guide pointer. Nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description genuinely extends meaning beyond the schema: it explains that days_back extends the window per day, that baseline_metrics drives a baseline block computing 7-day and 42-day mean/median/SD/z-score vs latest value with small-sample flags, and gives a custom-field example (Body Battery). It adds value rather than restating field 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 opening sentence states a specific verb and resource: return the recovery/readiness context of one day in a single call, with concrete scope (default today, read-only, numbers only, no readiness verdict). It also names the sibling it is not — 'Trends: get_wellness_trends' — so an agent can separate this per-day snapshot from the trend tool without opening either schema.

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

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

It gives a clear when-to-use ('Use for the recovery and readiness context of one day in one call') and points to the alternative for trend questions. It stops short of an explicit when-not/exclusion list against other overlapping siblings such as get_wellness_data or get_coach_context, so an agent still has to infer the boundary in those cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it discloses the diagnostic scope and, importantly, that 'the API key is never shown,' which is a useful security assurance for a status tool. It does not mention rate limits or latency, keeping it just below the top score.

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?

It is a single sentence, front-loaded with the trigger condition and followed by a compact colon-list of what it returns. Every clause earns its place; the density is high but there is no filler.

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

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

With no output schema, the description compensates well by enumerating the returned fields (version, permissions, tool sets, reachability, field/stream counts). The only minor gap is that it does not explain the text/json output_format choice, but for a read-only diagnostic tool this is nearly complete.

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

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

Schema description coverage is 100% and the single optional parameter (output_format, an enum with a stated default) is fully documented in the schema. The description adds no parameter-level detail, so the baseline of 3 applies when the schema carries the full burden.

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

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

The description states a specific diagnostic purpose (check the connection when tools are missing or fail) and enumerates exactly what it reports: server version, permission classes, tool set, registered/hidden tools, backend reachability, and athlete field/stream counts. This clearly separates it from the data-fetching siblings, which retrieve training data rather than diagnosing server state.

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 an explicit trigger condition: 'Use to check the connection when tools are missing or fail.' That is a strong context signal for selecting this tool over siblings. It stops short of naming when NOT to use it or a concrete alternative, but the when-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description confirms the read-only contract while adding real context: the snapshot-vs-live distinction versus get_activity_details, and the breadth of returned data. It does not mention the 10-minute cache behavior (only surfaced in the schema) or any auth requirements.

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

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

Purpose and read-only status are front-loaded, followed by returned content and then alternatives. Every clause carries disambiguation value, though the dense enumeration of thresholds and zones makes it longer than strictly necessary.

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

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

With no output schema, the description compensates by enumerating the returned fields (FTP, W', Pmax, LTHR, threshold pace, zones, gear, warm-up/cool-down) and by pointing to the three sibling tools covering adjacent needs. An agent has everything required to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters (refresh, athlete_id, sport_type, output_format) are already documented in the schema. The description adds no parameter-level format or syntax detail beyond noting the per-sport grouping, so the baseline 3 applies.

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

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

States a specific resource (current thresholds and settings per sport) with scope qualifiers (per sport, grouping of activity types like Ride/Run). It plainly identifies the read-only nature and distinguishes itself from siblings that touch overlapping data such as get_training_zones and get_activity_details.

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

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

Explicitly routes the agent: past-activity thresholds live in get_activity_details, zones-only in get_training_zones, and modifications in update_sport_settings. Both when-to-use and when-not-to-use are covered with named alternatives, leaving nothing to inference.

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

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

Annotations give readOnlyHint/openWorldHint, but the description goes well beyond: it quantifies cost (2 API calls plus 2 per power test with check_context), defines the validation rule set that determines what counts as a valid test, discloses the HRRc "not measured is never 0" quirk, and states the output is "statistics only, no verdict." That is rich behavioral context an agent cannot get from the annotations alone.

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

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

The instruction to use it is front-loaded, and each subsequent sentence (validation logic, trending scope, cost, method pointer) adds distinct value. It is dense and parenthetical-heavy, which costs a little readability, but there is no filler.

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

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

Ten optional params with no output schema, so the description must carry return semantics, and it does list the returned fields (target, average, CV, end HR, EF, HRRc), the per-sport-family/per-ISO-week trending, plus the detail_level tiers. Coverage is strong; only the exclusion-reason payload and response shape are left partly implicit, keeping it just under a 5.

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

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

Schema description coverage is 100% with enums for the two enumerated params, so the parameters are already well documented. The description adds only marginal semantics (default 180-day window, the HRRc caveat, the check_context cost) beyond what the schema states; the 3 baseline is appropriate when the schema carries the load.

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

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

States a specific verb+resource with scope: follow submaximal fatigue tests (SFT) that Intervals.icu detects, over weeks, with the questions it answers (which are valid benchmarks, how HR responds). No sibling tool covers SFT trends, so it is clearly differentiated.

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