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

With no annotations, the description carries the behavioral burden and does meaningful work: it discloses reliance on Garmin's auto-detected interval structure and provides a fallback rule that the athlete's stated structure wins. It does not cover side effects, auth, or failure modes, but the tool is a read-only analysis and an output schema exists.

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

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

Three sentences front-load the purpose, compactly list the outputs, and close with an important caveat. There is no filler or redundancy.

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

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

An output schema exists, so return values do not need describing. The description covers the operation, default selection, and an interpretation rule; minor gaps remain around what 'rule-based notes' contain and when activity_id is necessary beyond 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 baseline is 3. The description reinforces the default latest-run behavior and the single-run focus, but it does not add semantics beyond what the schema already provides for 'day' and 'activity_id'.

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

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

The description states a specific task, 'Deep dive into ONE run', and enumerates concrete outputs: HR zones, interval structure, weather, performance condition, and rule-based notes. It is distinguishable from siblings like get_trend or get_intensity_distribution by its single-run scope, though it does not explicitly name alternatives.

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 'Default: the latest run with detail' gives a clear default invocation, and the wording implies this is for granular single-run analysis. However, it does not state when to prefer this tool over siblings such as get_recent_activities or get_intensity_distribution, nor any 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?

With no annotations, the description carries full burden and delivers: it discloses that this is a write operation with side effects, that it pushes to the watch and then verifies, possible warnings (offline watch, mismatch), single-use semantics, and the response content. No contradictions or unsupported claims.

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?

Every sentence earns its place: purpose, consent gate, card-run exception, return value, and id behavior. The purpose is front-loaded with 'WRITE', and the structure is dense without being bloated.

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

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

The description covers when to call, what it does, what can go wrong, error outputs, and return value, and an output schema covers the structured result. Nothing required for correct invocation is missing, even without annotations.

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

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

The sole parameter proposal_id is already well documented in the schema (pattern + 'returned by propose_workout'), so the baseline is 3. The description adds valuable lifecycle semantics: the proposal can be applied once, and unknown/used ids produce an explanatory response listing open proposals.

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

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

The description opens with 'WRITE a proposed session to the athlete's Garmin account' and specifies the full sequence: upload, schedule, push, read back, verify. This clearly distinguishes it as the mutation counterpart to read-only siblings like get_* and propose_workout, while naming the artifact it operates on.

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

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

It states an explicit gate: call only after the athlete has seen the preview and explicitly agreed, and gives concrete examples of what counts and what does not. It also declares a when-not case ('Not available to the app's own card runs; there the athlete clicks').

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

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

With no annotations, the description carries the burden and does disclose key traits: no arguments, no Garmin call, no athlete data read, and a once-per-conversation cadence. It could say more about caching or whether the text changes over time, but the safety and side-effect profile is clear.

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, though the itemized content list is long and slightly leans on breadth over brevity. No filler or restatement of the tool name.

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

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

An output schema exists, so return-format detail is unnecessary; the description still characterizes payload content well. For a zero-param fetch tool, the invocation rules and side-effect statement make the definition 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?

Zero parameters gives a baseline of 4, and the description reinforces this with 'No arguments, no Garmin call'. There is no additional semantic depth to add beyond that.

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

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

States a specific verb and resource (coaching reference / full rule set) and enumerates its contents, so the agent knows exactly what comes back. It is clearly distinguished from every sibling, which fetch athlete data, by saying it 'reads nothing of the athlete'.

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

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

Gives an explicit trigger and an explicit limit: 'Call it ONCE per conversation, before the first training advice, and follow it.' That is when-to-use plus a when-not-to-repeat rule, with no inference required.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that all recorded recovery values for one day are returned, that the default is the latest day with data, and that trends are out of scope. It does not mention what happens when no data exists for the requested day, but the output schema likely covers return structure.

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

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

Two short sentences front-load the core behavior and then provide the usage rule. Every word contributes meaning and there is no fluff or repetition of schema content.

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

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

This is a simple tool with one optional parameter, no nested objects, and an output schema, so the description does not need to explain return values. It covers purpose, default behavior, and scope. The main gap is that it does not explicitly mention sibling tools like get_recovery_summary or get_trend, though 'not for trends' handles the most important distinction.

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

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

The schema already documents the 'day' parameter fully, including ISO format and the omit-for-latest behavior. The description adds semantic value by clarifying that the default is the latest day with data, not merely the latest calendar day, and by framing the selection as a single night/day. This goes beyond the schema's own parameter description.

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

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

The description clearly states that the tool returns every recorded recovery value for exactly one day, defaulting to the latest day with data. It also distinguishes itself from trend tools with 'not for trends.' It lacks an explicit verb in the description, but the tool name 'get' supplies the action, making the purpose unambiguous.

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

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

The description explicitly says to use it when a single night/day is in question and not for trends, providing a clear when/when-not rule. However, it does not name specific sibling alternatives such as get_trend or get_recovery_summary, so it stops short of fully explicit alternative guidance.

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

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

With no annotations provided, the description carries the disclosure burden. It explains that the tool returns time in heart-rate zones grouped by intensity buckets, includes percentages, and reveals a non-obvious data-quality behavior: it states how many runs have zone detail so an incomplete picture is visible. It does not mention period filtering in prose, but the schema documents the period_days parameter without contradiction.

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

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

The description is two compact sentences with no wasted words. It front-loads the core output and follows with a useful caveat. Every sentence contributes meaningful information.

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

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

With an output schema present and only one optional parameter, the description covers the tool's purpose, aggregation scope, and a data-completeness caveat. The only minor gap is not explicitly connecting the result to the period_days window in prose, but the schema handles that detail, making the description 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?

There is only one optional parameter, and schema description coverage is 100%, so the schema already documents period_days with default, minimum, and maximum. The description adds no additional parameter semantics; 'across all runs' could even slightly obscure the period-window behavior, though the schema clarifies it. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource (heart-rate zone time across all runs), the output form (percentages), and the organizing question (80/20 polarisation). This is specific enough to distinguish it from siblings like analyze_workout, which targets a single workout, and get_training_load, which is about load rather than zone distribution.

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

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

The description explicitly names the use case: it is the basis for the 80/20 polarisation question. This gives an agent a clear trigger for when to use the tool. It does not mention alternatives or exclusion conditions, but the context is strong 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?

With no annotations, the description carries the behavioral burden. It signals a read-only digest ('Use to see') and discloses non-obvious classification logic ('Quality / Long Run / Easy, from training effect and duration'), which is genuinely useful. It doesn't address auth or side effects, but none are suggested by the tool.

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

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

Two tight sentences: the first packs the output shape and classification rule, the second gives the use case. Every phrase earns its place and there is no redundant or generic 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 one-parameter read tool with an output schema, the description covers the essential return content, the classification behavior, and the intended use context. It could be slightly stronger by tying period_days to 'recent' or noting any limit on how many workouts are returned, but these are minor gaps.

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

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

Schema coverage is 100%, and the single parameter's meaning ('Window length in days') plus min/default/max is fully documented in the schema. The description adds no extra parameter-level information, so the baseline 3 is appropriate.

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

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

The description clearly states what the tool returns: 'totals per sport plus the latest workouts' with runs classified into Quality / Long Run / Easy. It stops short of a 5 because it uses a noun-phrase ('Workout digest') rather than an explicit verb, and it doesn't name sibling tools to sharpen differentiation.

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

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

'Use to see what was actually trained before recommending the next session' gives a clear, practical when-to-use context. It does not explicitly mention alternatives or when-not-to-use, so it earns a 4 rather than a 5.

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

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

No annotations are provided, so the description carries the behavioral burden. It clearly discloses the aggregation behavior, the inclusion of a latest-day snapshot, and the explicit absence of day-by-day output. It does not discuss data-source assumptions or edge cases, but the core non-obvious behavior is stated.

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 deliver the result shape, the intended use case, and the critical scope exclusion. There is no filler or redundancy, and the most important information appears first.

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

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

For a single-parameter tool with an output schema and no annotations, the description is sufficient to select and invoke the tool correctly. It explains the aggregate result, the window, and the non-aggregate exclusion. Naming sibling alternatives or caveats such as timezone handling would improve it further.

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

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

Schema coverage is 100% and the schema already describes period_days as 'Window length in days.' The description adds only the semantic link that N controls the aggregation window and latest snapshot, which is marginal value beyond the schema. Thus the baseline of 3 is appropriate.

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

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

The description states the exact metrics covered (sleep, HRV, resting HR, stress, Body Battery, steps) and the precise output form: averages over N days plus a latest-day snapshot. It also explicitly contrasts itself with a day-by-day list, which distinguishes it from sibling tools like get_daily_metrics or get_trend.

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

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

It provides a clear trigger phrase ('how has my recovery been?') and a clear exclusion ('never a day-by-day list'). However, it does not name any sibling tool explicitly as the alternative for day-level detail, so an agent must infer which sibling to use instead.

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

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

With no annotations, the description carries the behavioral burden, and it adds real value by disclosing that the ACWR source may be Garmin's EWMA or a less-reliable self-computed fallback and that VO2max change is only reported when the value actually varied. It does not explicitly state read-only behavior, but 'picture' and the absence of any mutation language make that clear enough.

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 tightly written sentences, with the core scope front-loaded and the source/fallback caveats kept in a separate short note. Every sentence adds information; there is no repetition of schema content.

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

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

For a one-parameter read tool with an output schema, the description covers the meaningful behavioral caveats (source reliability and conditional VO2max reporting). It stops short of being fully complete because it doesn't explain when period_days should be customized, though the schema's default and range largely compensate.

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 single period_days parameter is already documented with range and default. The description adds no parameter-specific semantics beyond the implicit weekly granularity, which matches the baseline for schema-covered parameters.

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

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

The description opens with 'Training-load picture' and lists exactly what is included (ACWR with source, Garmin training status, VO2max with change, weekly load buckets), so an agent can tell what it returns. It does not explicitly contrast itself with siblings like get_vo2max_history or get_training_readiness, so it misses the top bar for sibling differentiation.

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

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

The content list gives a strong implied use case: any request for a training-load overview or ACWR. It offers no explicit when/when-not guidance or mention of alternatives, so an agent still has to infer the boundary against get_training_readiness, get_recovery_summary, or get_vo2max_history.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the rule-based/conservative logic, that stale data is flagged explicitly, and that a >30-minute-old sync triggers an automatic 10-40 s Garmin sync reported in the response. That auto-sync side effect and its latency are exactly the kind of behavior an agent needs before calling.

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

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

Front-loaded with the verdict, then the signals, then usage routing, then behavioral caveats. Every sentence adds distinct information; nothing is restated from the schema.

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

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

An output schema exists so return values need not be described, and the description covers side effects, staleness, and latency. It does not state behavior when data is entirely absent or how missing signals are represented, a minor remaining gap for a diagnostic 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?

The tool takes zero parameters, which is the baseline-4 case since there is nothing to disambiguate. The description correctly implies a parameterless call and spends its space on behavior instead.

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

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

The description opens with a specific verb-and-resource pairing ('Today's readiness verdict GO / EASY / REST') and then enumerates the exact signals it aggregates (HRV, sleep, Body Battery, RHR vs 27-day baseline, ACWR, days since hard workout). This is clearly distinguished from siblings like get_recovery_summary or get_training_load, which cover single domains.

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

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

It explicitly routes the agent: 'START HERE for "should I train today?"', which is a strong when-to-use signal. It does not name an alternative or a when-not condition, so it falls short of full 5-level routing guidance, but the entry-point declaration is clear.

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

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

With no annotations, the description carries the behavioral burden and does disclose the core behavior: one metric, weekly averaging, trailing N days. However, it is silent on how trend direction is determined, missing-data handling, and whether weeks are calendar-aligned — details an agent might need.

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

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

One sentence conveys the computation, scope, and motivating use case with concrete examples. Every clause earns its place and the key constraint ('ONE') is front-loaded.

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

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

For a low-complexity, two-parameter tool with an output schema, the description plus schema is sufficient for an agent to invoke it correctly. It lacks explicit guidance on which sibling to choose instead, but the stated use case makes the selection path reasonably clear.

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?

period_days is already explained in the schema, and metric's enum values are largely self-explanatory; the description reinforces that exactly one metric is selected. This adds some meaning but does not materially compensate for the metric parameter lacking its own schema description.

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

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

The description names a concrete computation — weekly averages of a single recovery metric over a trailing window — and frames it around a clear question ('trending up or down?'). It distinguishes itself from broader summary/daily sibling tools without being a tautology.

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 use context: answering whether HRV, resting HR, or sleep is trending over time. It does not name sibling tools or state when not to use it, so it stops 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job: it explains the data shape (STEPS, only changed days, Garmin carry-forward), the time windows (8 weeks, 28 days vs 28 before), and the specific metrics included (distance, Z5 minutes, easy share, temperature). It also explicitly states the tool is descriptive, not causal, which is a key behavioral trait. The only minor gap is that it doesn't describe the output format or whether the comparison is computed server-side, but the output schema exists and the description is already quite rich.

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

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

The description is two sentences, tightly packed with useful information. It front-loads the core purpose (VO2max over last 8 weeks as STEPS), then adds the comparison detail, and ends with the use case and a caveat. Every sentence earns its place; there is no fluff or repetition of schema information.

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

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

Given the tool has 0 parameters and an output schema exists, the description is complete for an agent to decide whether to call it and what to expect. It covers the data granularity, time windows, metrics, and the descriptive-not-causal nature. The sibling context (get_trend, get_training_load) makes the use-case sentence particularly valuable for routing. Nothing essential is missing.

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

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

The tool has 0 parameters, so the schema provides no parameter semantics. The description compensates by explaining what data the tool returns and the time windows involved. Since there are no parameters to document, the description's role is to clarify the tool's scope and output, which it does well. A 4 is appropriate because the description fully covers the tool's behavior despite having no parameters to describe.

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

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

The description clearly states the tool returns VO2max history over the last 8 weeks as STEPS, with a specific data format (only days where the value changed, because Garmin carries it forward). It also includes a descriptive comparison of the last 28 days versus the 28 before, covering specific metrics. The final sentence explicitly ties it to the use case 'why is my VO2max moving?', which distinguishes it from sibling tools like get_trend or 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?

The description explicitly states when to use this tool: 'Use for "why is my VO2max moving?".' It also clarifies what the tool is not: 'Descriptive, not causal.' This gives an agent clear guidance on when to select this tool over siblings like get_trend or get_training_load, and sets expectations that it won't provide causal analysis.

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?

No annotations are supplied, so the description carries the full burden and does so: 'The calendar wins' with the rule that occupied days get nothing, downgrades are surfaced as `calendar:` lines, and 'Nothing is written here' makes the non-mutating nature explicit. Sizing (+10% over the last four weeks) and target sourcing (the athlete's own zones) are disclosed behavioral traits an agent could not infer.

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

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

It is dense at roughly 140 words, but it is front-loaded with purpose, then usage trigger, then conflict-resolution behavior, then what is returned. Nearly every clause carries information; only the return-value sentence is arguably redundant given the output schema.

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

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

For a zero-annotation, zero-required-parameter tool this covers the essentials: what is produced, the scheduling constraints applied, how calendar conflicts are resolved and reported, that nothing is persisted, and the id needed for apply_workout. An agent can invoke it and hand off correctly without further information.

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

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

Schema description coverage is 100%, so start_day, long_run_day and days_per_week are already fully documented with defaults and formats. The description references the long run weekday and week framing but adds no parameter-level syntax or edge-case meaning beyond the schema, so baseline 3 applies.

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

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

Opens with a specific verb+resource: 'Build a polarised training week and file it as ONE proposal', then enumerates the concrete composition rules (VO2max + threshold 48h apart, long run on its weekday, easy runs, one rest day). This is clearly distinguishable from propose_workout (single session) and apply_workout (which it names as the downstream step).

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

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

Gives an explicit trigger with quoted user phrasings ('plan my week', 'what should next week look like') and states the follow-up path via apply_workout with the returned proposal id. It does not explicitly say when NOT to use it or name propose_workout as the alternative for a single session, 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?

With no annotations, the description carries full weight and delivers: NOTHING is written to Garmin, only a preview plus proposal id is returned, day defaults to today, impossible requests return a reason rather than a session, and targets derive from the athlete's Garmin zones with unmeasured items listed as assumptions. This is exceptional transparency for an unannotated tool.

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

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

Every sentence earns its place: purpose, target source, usage triggers, kind definitions, default, return value, safety guarantee, and failure mode. The structure front-loads the core action and then layers behavioral context without redundancy. It is compact despite conveying a large amount of decision-relevant 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 6-parameter tool with an output schema, the description covers the full lifecycle (proposal, preview, apply, failure mode, zone assumptions, readiness swap). The only notable gap: both distance_km and duration_min are optional, and the description does not state what happens if neither is provided. This is minor but prevents a perfect score.

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 high at 83%, so baseline is 3. The description adds real value for the one undocumented parameter, kind, by defining easy/long, threshold (Z4 reps), vo2max (Z5 reps), and steady (>=12 min at threshold, the only shape Garmin measures VO2max from). It also clarifies the day default. This pushes it above baseline.

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

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

The description opens by naming a specific verb ('Build') and resource ('a structured session ... file it as a PROPOSAL'), and then situates it against the sibling workflow by saying nothing is written to Garmin and apply_workout is the follow-up. This strongly differentiates it from apply_workout, propose_week, and analyze_workout without opening the schema.

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

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

Gives explicit trigger conditions: 'Use when the athlete asks for a workout' with concrete examples, plus the readiness-verdict swap scenario. It also routes to apply_workout only after athlete approval. It does not explicitly say 'don't use this for weekly planning (propose_week)' or other exclusions, but the alternative is clearly identified.

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

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

With no annotations provided, the description carries the full burden. It discloses the key behavioral traits: duration (10-40 s), read-only behavior toward Garmin, and the only side effect (writes to local database). It does not mention failure modes or repeated-call safety, but the side-effect boundary is well communicated.

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

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

The description is compact and front-loaded with the core action. Each sentence adds useful information, though the capitalized 'NOW' is minor filler. Overall it is appropriately sized and easy to parse.

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

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

For a tool with one optional parameter and an output schema, the description covers what it does, when to call it, how long it takes, and its side effects. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The input schema fully describes the single optional 'days' parameter, including range and default. The description adds minimal parameter nuance, but the 100% schema coverage means the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Pull'), names the resource ('Garmin Connect'), and specifies the data scope ('latest days and workouts'). It is clearly distinguishable from the sibling get_* tools, which read local data, while this tool performs a sync.

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

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

The description gives explicit when-to-use guidance ('Call this first when today's run or last night's sleep is missing') and adds timing expectations. It does not explicitly name alternatives or say when not to use it, but the sibling context and 'call this first' phrasing make the intended usage 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?

No annotations are provided, so the description carries the full burden and does so thoroughly: it discloses that only the calendar entry is removed (workout stays in the library), that only app-uploaded entries are touched, that changed-hands entries are skipped and reported, that explicit athlete consent is required, and that card runs cannot invoke it.

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

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

Front-loaded with the core action, and each sentence carries distinct value (behavior, reversal semantics, safety scope, consent). It is slightly dense but nearly 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?

For a mutation tool with an output schema present, the description covers what an agent needs: what it does, reversal behavior, consent requirement, and edge-case handling (reported skips). Return values are handled by the output schema.

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

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

Schema coverage is 100% and the schema already describes proposal_id. The description adds nuance by noting the tool handles 'a whole applied week' as well as a single session, clarifying the scope of proposal_id beyond the schema's terse 'id of a proposal that was applied.'

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 ('Take a session... back OFF the athlete's Garmin calendar') and explicitly frames itself as 'the counterpart of apply_workout.' An agent can immediately distinguish it from apply_workout and the read-only get_* siblings.

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

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

Gives concrete trigger conditions: 'when the athlete says the session should not be there after all, or after trying the write path out.' It also names the alternative (apply_workout) and the inverse relationship, 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.