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?

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 of behavioral disclosure. It reveals that the tool is 'rule-based and conservative' and that it 'flags stale data explicitly,' which are useful traits for interpreting outputs. It does not discuss errors, latency, or edge cases, but for a 0-parameter informational tool this is solid coverage.

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

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

Three sentences with no filler. The opening sentence delivers the verdict and signal list, the second adds the algorithmic tone, and the third gives usage guidance and data-freshness behavior. Every sentence earns its place and the most important information is front-loaded.

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

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

The tool has no parameters and an output schema exists, so return values are structurally covered. The description provides purpose, decision context, behavioral traits, and staleness handling, making it complete for an agent to select and call this tool correctly.

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

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

The tool has zero parameters, and the input schema is empty, so there is nothing for the description to explain about parameters. The baseline of 4 applies because parameter semantics are trivially covered by the schema.

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

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

The description states a clear purpose: provide a GO/EASY/REST readiness verdict for today, with the key signals behind it. This differentiates it from siblings like get_recovery_summary and get_daily_metrics, and the 'START HERE' phrasing reinforces its role as the primary readiness decision tool.

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

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

The description explicitly directs usage with 'START HERE for "should I train today?"' giving a strong contextual signal about when to use the tool. It stops short of naming alternatives or stating when not to use it, but the usage context 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?

With no annotations, the description carries the full behavioral burden, and it succeeds: it states the tool writes nothing, returns a preview and one proposal id, and that apply_workout is needed for the actual Garmin sync. It also clarifies that existing calendar content is listed and the package adds to 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?

The description is dense but every sentence earns its place: purpose, structure, defaults, usage trigger, output behavior, and side-effect disclosure. It is slightly long but justifiably so given the absence of annotations and the tool's complexity.

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 no annotations and three optional parameters, the description covers what the tool builds, what the response contains, what happens next via apply_workout, and what side effects are absent. An agent has enough context 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?

Schema coverage is 100%, so the schema already fully documents start_day, long_run_day, and days_per_week including defaults and constraints. The description adds useful context like default session sizes (50/55/45/90 min), but does not need to carry parameter meaning, making 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 opens with a specific verb and resource — 'Build a polarised training week and file it as ONE proposal' — and enumerates the week's structure in concrete terms. It also distinguishes itself from apply_workout by explaining that this tool only creates the proposal and does not push to Garmin.

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

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

It explicitly states when to use the tool: when the athlete asks for their week, with example phrasings like 'plan my week'. However, it does not explicitly name when not to use it or name the closest sibling alternative, so it stops at clear context without exclusions.

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

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

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.