Blocks

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

Annotations already declare a non-destructive, closed-world write. The description adds behavior annotations can't: the line is routed to whichever block holds the given date, and re-reviewing the same week or session REPLACES the existing line (idempotency). It also states no card is created and it saves on return. It stops short of saying what happens if no block exists on that date.

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 action and the write target, then conditions, then parameter notes. Dense but purposeful; there is mild redundancy between the list of review types and the later `date` explanation, and the nested parentheses make it harder to parse than it needs to be.

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 3-parameter mutation with no output schema, the definition covers trigger conditions, what to write, formatting, date resolution, replacement semantics, and persistence ('Saves on return, no card'). An agent has everything needed to invoke it correctly or correctly decline to.

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 baseline is 3, but the description adds real semantics: it ties `date` to the block resolution rule, explains what each `from` value implies, and specifies the expected shape of `text` with a concrete example (number against the goal, athlete's language, no bracketed scales).

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

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

Specific verb and resource: 'Add one line to a training block's PROGRESS — under the block's GOAL on its card in Blocks.' The scope constraint (one line, attached to a goal, on a Blocks card) separates it from the sibling bulk setters like set_training_blocks and from the other 'add_' tools.

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

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

Names the triggering situations explicitly (end of a Review week, Analyze on a session, a block review) and the condition that qualifies content (the reviewed thing moved/held/missed a goal metric). It also gives an explicit exclusion: 'Nothing that bears on the goal → write nothing.'

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 say readOnlyHint=false and destructiveHint=false. The description adds rich behavioral detail: same-title extension (ticks kept, duplicates skipped), single-day, no repeat, saved on return with no card, and the read-back format. It also discloses that the agent cannot tick items for the athlete. No contradiction with annotations.

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

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

The description is longer than minimal, but every sentence adds distinct information: purpose, use cases, extension, constraints, persistence, read-back, and boundaries. It leads with the core action and flows logically, though it could be trimmed slightly without losing value.

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

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

For a write tool with no output schema and modest annotations, the description covers what an agent needs: inputs (date, title, items), behavior (extend vs new), side effects (saved, no card), and how to verify/read back results. It also distinguishes from plan_workouts, so the agent is fully equipped to invoke it correctly.

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

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

Schema coverage is 75%, so the baseline is near 3. The description adds meaning beyond the schema for title (same title/day extends the list) and items (concrete, few words, not advice/training). It does not add color semantics, but the schema already documents color's conditional use.

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-resource pair: 'Put a CHECKLIST on a calendar day, or ADD ITEMS to the one already there.' It also distinguishes from siblings by explicitly naming plan_workouts for training and contrasting 'not advice to read.' The single-day, no-repeat statement further separates it from recurring or copying tools.

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

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

Explicit 'Use it when they want a list to work through, not advice to read' with concrete examples (race kit, evening before a test/race, travel bag). It names the alternative for training (plan_workouts), states the extension behavior, and the 'cannot tick for them' boundary, so agents know when to invoke and what to avoid.

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

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

The annotations declare destructiveHint=false, meaning the tool performs only additive updates, but the description explicitly says `replaces:<id>` retires an existing fact as this one is written. That is a non-additive state change to existing data and contradicts the annotation. The rich behavioral detail about held calls, cards, and horizons cannot overcome the 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 front-loaded with purpose and organized into sections for area, constraints, horizon, dueAction, and duplicate handling. It is very long, but the length is largely justified by the tool's 14-parameter complexity and the absence of an output schema. Some repetition and all-caps rule statements could be tightened.

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

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

Given the tool's complexity, 14 parameters, and no output schema, the description covers the full lifecycle: when to write, what not to write, horizon semantics, area behavior, card versus silent behavior, and how held calls return similar fact ids. Nothing critical for correct invocation appears to be 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?

With 14 parameters and only 64% schema description coverage, the description adds substantial meaning beyond the schema. It explains horizon values (stands, until, recheck, season, pattern), dueDate requirements, dueAction versus mere questioning, tags, area survival rules, and the new/replaces/confirms semantics. This compensates well for the schema's coverage gaps.

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

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

The description states a specific verb and resource: 'Record ONE thing you now know about the athlete, with how long it is true.' It immediately distinguishes this memory tool from the snapshot and training log, and later names sibling tools such as set_activity_notes and confirm_fact. An agent can tell what this tool is for without opening the schema.

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

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

Usage is richly specified: three tests must all pass before writing, computed values should use get_metric_history/get_records/get_activity, and workout verdicts belong in set_activity_notes. The description also explains when to be silent versus when to produce a card, and how to respond when a call is held with similar facts. This is explicit when-to-use, when-not-to-use, and alternative routing.

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

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

Annotations already convey that this is not a read-only operation and is not flagged destructive. The description adds useful behavioral context about the evaluation lifecycle and the meaning of 'dropped', but it does not explain side effects such as whether a commitment can be reopened or whether the status becomes permanently closed.

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

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

The core usage is front-loaded and clearly structured. The final motivational sentence about closing the loop is somewhat extra, but it reinforces why the tool exists without making the description 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?

For a simple three-parameter tool, the description covers what, when, and why. It explains the timing prerequisite, the status options, and the required verdict format. No output schema exists, but return-value documentation is not necessary for this kind of action.

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 67%, and the description adds meaning beyond the schema: it defines the three statuses, clarifies that 'dropped' includes changed-mind or no-longer-relevant, and reinforces the one-line verdict requirement in the athlete's language. The id parameter is already well described in the schema.

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

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

The description says exactly what the tool does: evaluate one of the agent's own earlier instruction/commitment once its day has passed, and record whether it was kept, missed, or dropped. This is a specific verb plus resource that clearly separates it from list/get tools.

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

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

The description gives a concrete condition for when to use the tool: only after the applicable day has passed and the session data is available. It does not explicitly name alternative tools or say when not to use it, but the timing rule is clear and actionable.

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

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

The description reveals concrete behavioral effects: confirmations are incremented, today's date is stamped, ranking is increased, decay after six months is prevented, and the operation is silent with no card. This goes well beyond the sparse annotations (readOnlyHint, openWorldHint, destructiveHint) and 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?

Three sentences with no filler; the trigger is front-loaded and each clause earns its place by explaining a behavioral consequence. The ranking/decay aside is dense but directly relevant to why confirmation matters.

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 two-parameter confirmation tool with no output schema, the description fully covers the situation, side effects, and semantic boundary. The only small gap is that it never states what the function returns, but this is low-stakes for a tool described as 'silent'.

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 50% of the parameters have schema descriptions, and the description does not directly explain the id parameter beyond implying it identifies the pattern/fact. The note parameter is already well described in the schema ('what you saw this time, appended to the fact'), so the description adds no additional parameter value.

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

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

The description opens with the exact trigger, 'You saw a pattern happen again,' and states the core action: record a repeat observation by bumping confirmations and stamping today. It distinguishes confirm_fact from add_fact/update_fact by explicitly telling the agent to use it instead of writing the same pattern twice.

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 when-to-use condition (a pattern is observed again) and an explicit alternative ('instead of writing the same pattern twice'), routing the agent away from creating duplicate facts. The additional note that confirmation is not a claim about the athlete provides a clear exclusion for what the tool is not for.

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 non-read-only, non-destructive, closed-world; the description adds the substantive traits: it ADDS rather than replaces, day notes land only on days that have none, sessions are written two weeks out and beyond that the block target holds instead of a copy. Those are exactly the behaviors an agent would otherwise get wrong, and they are consistent with destructiveHint=false.

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, then constraints, then the replacement caveat — a sensible order and no filler sentences. A few clauses are denser than needed ("and it reproduces the week exactly" restates the weekday-mapping point), but every sentence still carries usable information.

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

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

For a 4-parameter mutation tool with no output schema, it covers source/target semantics, additive behavior, note handling, horizon limits, and the cleanup prerequisite. The only gap is that it never says what the call returns or how the agent can verify the copy (how many sessions landed where).

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, and the description still earns credit by clarifying that `from` and every `to` entry can be ANY date inside the target week and the week is derived from it, plus the note-carry semantics that the schema only partly states. The `why` parameter is left entirely to the schema, so it is not a full 5.

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

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

States a specific verb and resource ("Copy a whole training week onto other weeks, weekday by weekday") and immediately disambiguates scope with the Monday-to-Monday rule. It also distinguishes itself from the nearest siblings by naming plan_workouts and remove_from_plan and describing the different outcomes.

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 when to use it («повтори прошлую неделю», repeating a base week) versus when to use alternatives — "one call instead of a dozen plan_workouts items" — and gives the precise when-not-plus-remediation case: to replace a week, empty it first with remove_from_plan, day by day.

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

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

With annotations only covering the safety profile, the description supplies the crucial operational semantics: copies are independent entries, no series links them, and a copy ADDS to the target day rather than replacing it. It also notes what is carried over (structure, note, tags, key star) and that nothing is invented.

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 the iid behavior, then the usage guidance, then the add-not-replace caveat. It is dense with em-dashes and examples, so it runs slightly long, but every sentence carries actionable 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 mutation tool with no output schema and annotations that only declare the safety profile, the description covers the add-vs-replace behavior, copy independence, what is preserved, and when to choose this over plan_workouts. 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 coverage is 100% and the schema already documents iid, from, to, and why. The description reinforces the key iid distinction (pass it for ONE session from get_plan, omit to copy the whole day), adding a little framing beyond the schema but no new format or syntax detail.

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 (copy planned work from one day to other days) and immediately frames it as the athlete's own Copy/Paste. It differentiates from siblings by naming plan_workouts and remove_from_plan as the alternatives for different intentions.

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 to reach for this instead of re-writing with plan_workouts when the athlete wants the SAME thing again, and gives the replace-vs-add rule (call remove_from_plan first). Concrete scenarios (repeated Tuesday, last week's long ride, gym session) make the selection condition 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?

Goes well beyond the annotations: disclosures that event-day weather is auto-fetched within ~16 days, that GPX cannot be supplied here, and that the tool returns a new event id used by set_event_notes. Lacks any mention of permission/ownership requirements or duplicate-event behavior, so not quite a 5.

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

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

Front-loaded with purpose and trigger, then required fields, then optional groups, then side effects and return value — a sensible priority order. The parenthetical enumeration is dense but each clause carries information; only the mid-sentence detail drop about which fields are optional could be tightened.

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 create tool with no output schema, it covers the essentials: required fields, the return value, automatic weather behavior, and where the GPX step lives. It leaves the athlete-facing intent fields (sport, purpose, priority semantics) to the schema, which documents them well.

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?

At 79% schema coverage the baseline is 3, and the description earns above that by grouping the optional fields and explaining non-obvious effects ('local start time (picks the forecast hours)'). It omits sport, result, and purpose entirely, relying on the schema's own descriptions for those.

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

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

Specific verb + resource + concrete scope: 'Create an event the athlete is preparing for (race, key ride, FTP test) on their Blocks calendar.' The examples and the 'athlete's calendar' framing make it immediately separable from list_events, update_event, and delete_event.

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

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

Gives a clear trigger ('Use when the athlete describes one in chat') and routes a follow-on need explicitly ('pass it to set_event_notes to add detailed prep'). It also pre-empts a foreseeable misuse by stating the GPX route is added in the app, though it never explicitly says to use update_event for existing events.

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

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

Annotations already mark the tool as destructive, but the description adds valuable detail beyond the annotation by revealing exactly what gets destroyed: the event AND its prep notes, and that removal is permanent. It does not contradict the annotations.

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

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

Two tight sentences with no filler. The core action is front-loaded, followed by the critical permanence warning and routing guidance, making every sentence earn 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 one-parameter destructive tool, the description covers what is deleted, that prep notes are removed, that deletion is permanent, and when to use update_event instead. No output schema exists, and the description sufficiently covers what an agent needs to invoke the tool correctly.

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

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

The schema only provides a bare string 'id' with 0% description coverage. The description implies that id refers to the event being deleted from the athlete's calendar, which adds some meaning, but it does not explicitly state the source or format of the id or how it relates to list_events. This is acceptable for a single obvious parameter but not fully specified.

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 ('Delete') and resource ('event from the athlete's calendar'), and it distinguishes itself from update_event by noting when deletion is appropriate versus when updates should be preferred. This is not a tautology and clearly separates the tool from its 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?

The description explicitly gives the conditions for use ('cancelled or added by mistake') and names the alternative ('prefer update_event when only details changed'). This gives an agent clear routing guidance without needing to infer 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?

Annotations give destructiveHint=true/readOnlyHint=false, and the description goes well beyond them: `correct` removes distance records permanently, `merge` hides the later activity and rewrites NP/IF/TSS/charts/intervals, `revert` only unwinds the last merge, and provider syncs will not move a moved activity back. It also states post-edit locking (syncs stop overwriting measured fields) and downstream effects on week/load history/Records. This is the kind of consequence disclosure 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?

Front-loaded one-sentence thesis followed by mode-scoped bullets with consistent trigger→action shape; the athlete quotes earn their place by making mode selection concrete. It is long, and the 'Four modes' miscount plus a couple of parenthetical repeats cost it the top score.

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, but the description states what happens after the call (server recomputes TSS/IF/work/time-in-zone, confirmation card shows before→after) and what persists (edit reason from `ask`, corrected flag in week/load/Records). For a destructive 10-param mutation tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 80%, but the description supplies the missing semantics for the highest-risk parameter — mode — by defining each enum value's meaning and required companions (withId only for merge, date/time only for move, absolute totals never deltas). It also constrains withId ('same sport, second starts after first ends, at most 3 h apart, from list_activities'). Slight gap: elevation and elapsedTime are never tied to a mode, and elevation's relationship to extend is unstated.

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 concrete verb+resource+scope: correct ONE completed activity when the recording (measured numbers or filed day) is wrong, and enumerates the modes that do it. This is clearly distinguishable from rename_activity, set_activity_notes and tag_activity, which touch labels rather than measurements. Minor internal slip: it says 'Four modes' while five (extend/correct/move/merge/revert) are listed and in the enum — the enumeration itself still rescues clarity.

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?

Each mode is gated on a concrete real-world condition with the athlete's own phrasing ('первые полчаса не записались', 'Страва посчитала 42 км'), which is exactly the when-to-use signal an agent needs. It also specifies ordering (merge first, then extend), a guard against guessing ('ask for whatever you're missing'), and a mandatory prerequisite ('get_activity first').

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 destructiveHint=false, but the description adds substantive caveats beyond them: wind is unknown, group riding biases the value low, tagged rides are excluded, and the output is explicitly an estimate rather than a measurement. It also states the return content (estimate, spread, ride count), covering the missing 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?

Purpose and method are front-loaded and every clause carries information. It is a dense single paragraph, so a sentence break between method, caveats, and race usage would improve scanability, 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?

With no output schema, the description fully specifies what comes back (estimate plus spread plus number of rides). It also covers the statistical approach, the caveats, and the required follow-up workflow, so an agent has everything needed to call and act on 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?

There is a single optional parameter with 100% schema coverage, including its bounds and default (120 days), so the schema already carries the meaning. The description adds nothing about the lookback window, which is acceptable given full coverage but leaves no extra value.

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 (estimate the athlete's effective drag area, CdA in m²) and explains the derivation, distinguishing it clearly from siblings like estimate_thresholds. An agent can tell exactly what this produces 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 downstream guidance: to use the result for a race, propose setting it on the event via update_event cda and only after the athlete agrees. It also names the data conditions that select this tool (athlete's own outdoor rides with power) and exclusions (race/group/indoor-tagged rides).

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/safe, so the bar is for added context, and this delivers: it discloses the return shape (recommended, CP range, W', fade estimate, confidence with reasons, hrZones with bounds), and critically warns that estimates are FLOORS and that confidence gates whether an update may be proposed, plus that a howToRead block must be read first.

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?

Long but front-loaded: the purpose and method come first, then usage, then scope, then a return-contract warning. Since there is no output schema, much of the length is load-bearing, though some density (CP range, W', fade, hrZones, howToRead all in one paragraph) could be 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?

With no output schema, the description fully carries the return-value burden by enumerating the fields and the howToRead/confidence contract, and it closes the scope gap for running. An agent has everything needed to call it and to interpret and report 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 schema already documents both parameters including the 'running returns guidance, not numbers' enum behavior and the default window. The description reinforces the 90-day default and cycling scope but adds no syntax or semantics 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 verb+resource with method detail: estimates FTP/LTHR/max HR from ACTUAL synced rides via a mean-maximal power curve and Critical Power fit. It distinguishes itself from siblings by naming the scope (CYCLING ONLY) and explicitly ruling out running threshold pace, which separates it from estimate_cda and running-oriented tools.

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

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

Gives explicit triggering conditions ('when heart rate sits under or over its zone on rides that felt right', 'when they ask whether their heart-rate zones are correct') and an anti-pattern correction ('that request is what the tool is for, not a reason to send them to a test'). It also names the correct alternative for out-of-scope cases (a recent race result or 30-min field test for runners).

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 a safe read, yet the description discloses rich behavior: how structure_read_by changes which structure to trust, the rule to grade on laps when laps and detection disagree, decoupling naming and its <5% line, cadence/terrain attribution, tss_basis and np_caveat preconditions, and zone-basis caveats. This is far beyond what annotations provide.

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

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

Front-loaded with the core purpose, and most sentences carry substantive field semantics, but the body is an extremely dense run-on that packs many concepts into single sentences. Useful content is present, yet the sprawl works against quick scanning and some clause repetition could be 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?

With no output schema, the description assumes the full burden of explaining the return shape and does so exhaustively — stats, decoupling fields, work_reps sub-fields, structure variants, zone splits with basis and ref, and the description field. Nothing needed to interpret the response 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 0% and the single id param is undocumented in the schema, but the description states where the id comes from ('Use the id from list_activities'), supplying the missing semantics. It adds no further constraints on the value, so it is strong but not exhaustive.

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 completed activity in full detail') and enumerates the returned content (stats, HR drift, work_reps, interval/lap structure, notes, zone splits). It clearly distinguishes the single-activity read from list_activities and get_activity_series.

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 for use ('how you analyze how a session was actually executed ... before writing a coach read or adjusting the plan') and routes the agent to list_activities for the id. It does not explicitly delimit when to prefer get_activity_series over this tool, so it stops short of full when/when-not 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 destructiveHint=false, so no contradiction. The description adds rich behavioral detail beyond annotations: default bucket selection yields ~150 rows, fine buckets over the whole ride are widened to ~300 rows and the header notes it, and the 'moving clock' semantics tie to get_activity blocks and lactate sample t. It also states the output is CSV, which is not in the schema. This fully discloses expected behavior.

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. It opens with the core purpose, then usage rationale, then parameter semantics, then a practical anti-pattern. It is front-loaded and well-organized, with no filler or redundant statements. Length is justified by the complexity of the zoom behavior.

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 data-retrieval tool with 4 parameters (1 required) and no output schema, the description is complete. It explains the return format (CSV), the columns, default row counts, the zoom mechanism, and the clock reference. It also covers when to use it and how it differs from related tools. Nothing an agent needs to invoke it correctly is missing.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema. It explains that fromSec/toSec use the same clock as a block's start and a lactate sample's t, and that bucketSec interacts with them to zoom into a rep or climb. It also explains the default row-count behavior and the widening fallback. These semantics are not in the schema and are essential for correct parameter usage.

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

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

The description states a precise verb-resource pair: returns the activity's own chart as a time-bucketed CSV of average power, heart rate, cadence, and altitude. It distinguishes itself from siblings by explicitly positioning it as the 'SEE the session' tool versus a summary, and even contrasts it with get_activity by referencing the same clock. An agent can tell exactly what this does and how it differs from get_activity or other data tools.

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

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

Provides explicit when-to-use guidance: 'Call it when a summary is not enough and you need to SEE the session.' It also gives a concrete anti-pattern: 'Prefer this over asking the athlete for a screenshot.' For zooming, it explains exactly when to pass fromSec/toSec with a small bucketSec. This is model-level guidance with clear alternatives and 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?

Annotations already declare readOnlyHint=true, so no repetition is needed; the description adds that the document mirrors the athlete's Profile page and that the grade block is machine-read and scopes every knowledge-base search. This goes beyond the annotation's binary safety flags and clarifies content semantics.

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

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

Three sentences, each with a distinct purpose: state the output, position it against `list_facts`, and flag the machine-read grade block. No wasted words, and the main function 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 no-parameter, read-only tool, the description covers its purpose, relationship to the structured alternative, and a key behavioral detail (grade-block scoping). The absence of an explicit output format is a minor gap, but the term 'document' and the reference to the Profile page convey the essential return nature.

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

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

The tool has zero parameters, so the baseline for this dimension is 4; the description adds no parameter-specific meaning because none exist, but clarifies that the `grade` block (sport/level/populations) is machine-readable, which is output context rather than parameter semantics.

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

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

States the tool's function as rendering everything known about an athlete as a single document, and explicitly contrasts it with `list_facts`, distinguishing the two. The mention of the grade block scoping knowledge-base searches adds precision.

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?

Directly instructs when to use this tool ('Kept for readers that want it in one piece') and names `list_facts` as the alternative for structured needs (ids, states, single area). It also warns that the grade block scopes knowledge-base search, helping an agent decide based on query intent.

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 that this is a read-only, non-destructive, closed-world operation. The description adds valuable behavioral context by explaining that `effective` contains resolved app bounds and targets while `raw` contains the stored profile and auto/manual flags.

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

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

The description is front-loaded with the core action and then details the returned blocks. It is dense but mostly earns its length because there is no output schema; however, the long single-sentence style could be structured more readably.

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, so the description carries the burden of explaining return values. It does so thoroughly: named profile metrics, athlete block fields, intake state, and the `effective` vs `raw` distinction with their practical meaning.

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, so there are no parameter semantics to explain; baseline 4 is appropriate. The description correctly focuses on return structure rather than inventing parameter guidance.

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 the athlete's profile. It enumerates the concrete contents (FTP, thresholds, HR, zone model, athlete block, intake, effective/raw), so the agent can distinguish it from update_athlete_profile and from other get_* tools.

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

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

Gives clear usage context: use the profile data to right-size volume, ramps, and fuelling. It does not explicitly say when to use this versus siblings like get_context or get_athlete_file, and its mention of update_athlete_profile is about passing flags rather than an alternative selection 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 already declare readOnlyHint and destructiveHint, so safety is covered. The description adds meaningful behavioral context by specifying it returns the 'full block structure' and the source domains, which goes beyond the schema and 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, front-loaded sentence with no filler. The action, resource, scope, and purpose are all packed efficiently.

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

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

For a one-parameter read tool with annotations covering safety, the description is sufficient. It explains what it returns (block structure), the scope, and the intended use. Without an output schema, mentioning the block structure is enough guidance, though it could specify 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?

With schema coverage at 0%, the description must compensate. It identifies the parameter as 'by id' but does not elaborate on the id type or format. However, the single parameter is simple and the tool name clarifies it is a workout id, making this adequate for the minimal schema.

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

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

The description clearly states the verb (read), the resource (workout by id), and explicitly scopes to catalog, collection, or the athlete's own library. It also conveys the purpose ('to inspect before scheduling or adapting'), which distinguishes it from plan-specific retrievals like get_plan_workout.

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

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

It provides a concrete use case ('inspect before scheduling or adapting') but does not name alternatives or explicitly state when not to use it. The scope (catalog/collection/library) implies it's not for plan workouts, but that differentiation is not stated directly.

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

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

Annotations already cover the read-only safety profile, yet the description adds substantial behavioral detail: it enumerates exactly what is returned (date/weekday, plan with precomputed done/NOT-done verdicts, readiness, thresholds, activities with notes, 14-day comparison, 12-week load, upcoming events, response profile, facts, recent plan changes, and Blocks assistant exchanges). It also explains the side effect of the `question` parameter—that it triggers a knowledge base search but does not answer the question—and confirms 'Read-only: it writes nothing,' which is consistent with annotations.

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

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

The description is long and dense, but it is front-loaded with the core purpose and uses clear section markers ('WHEN TO CALL') to aid scanning. For a tool that returns so many different data points, most sentences earn their place, though some list items could be tightened. It is appropriately sized for the complexity, with no major structural flaws.

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

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

Given the tool's complexity, the lack of an output schema, and the rich but safety-focused annotations, the description covers everything an agent needs: when to call, what data is returned, how the optional `question` behaves, and which siblings to use for focused retrieval. Nothing essential is missing.

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

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

Schema coverage is 100% for the single `question` parameter, so the schema already documents its format and basic effect. The description adds meaning beyond the schema by clarifying that the search is for evidence retrieval only and that 'it does not answer the question, it only decides what to retrieve,' which helps an agent understand the parameter's purpose. Minor additional value, but not enough to reach 5 given the schema already carries the essential details.

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 (get_context) and immediately defines its scope as 'THE WHOLE PICTURE IN ONE CALL'. It distinguishes itself from siblings by naming get_today, get_plan, list_activities, get_readiness_today, list_facts, and search_knowledge as more targeted alternatives, so an agent can tell exactly when this tool is the right pick.

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 to call it as the first tool of a conversation, and again only after a long gap or when the athlete reports a change. It also warns that a second call in the same conversation 'almost always returns what you are already holding' and directs the agent to specific alternatives for uncovered data. This is a complete when/when-not/alternatives guide.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: the result is computed in code from the athlete's FTP, weight and the event's CdA, and it requires an existing GPX on the event. It does not, however, mention rate limits or handling of missing GPX/FTP.

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, then the output enumeration and prerequisites. The long output list is on the verbose side but earns its place since there is no output schema to document the return values. No filler sentences.

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

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

For a read-only tool with no output schema, the description usefully enumerates the return contents and states the prerequisites (event id, GPX on event). Annotations cover the safety profile. It is close to complete, though it does not say what happens when the GPX is absent or the event is a non-race.

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 50%: ifTarget is documented in the schema (IF, 0.55–1, default 0.80) but the required id is not. The description partially compensates by stating the id comes from list_events, but adds nothing about ifTarget and gives no format detail for id, so this sits at 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 specific verb (Read) and resource (an event's race course), and enumerates the concrete outputs it produces (finish time, NP/TSS, power plan per climb, surface split, key moments). No sibling tool does anything comparable, so an agent can distinguish it immediately.

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

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

Provides explicit use cases ('разбери трассу', pacing a race, which climb decides it) and a prerequisite (needs the event id from list_events and a GPX on the event). It also cautions 'use ITS numbers — do not redo the physics', but names no alternative tool or when-not-to-use condition, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it explains the fallback to a suggested load when no test exists, that hand-written answers are merged with auto-detected ones, and points to howToRead for interpretation. It does not describe pagination or ordering, keeping it short of a 5.

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

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

It leads with the resource and folds parameters into the end, which is good front-loading, but the middle is overstuffed with jargon and parenthetical references (profile fatigueTest / fatigueTestRun, log_sft_answers, howToRead) that make it hard to parse in one read. Some clauses could be trimmed without losing meaning.

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

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

With no output schema, the description compensates by enumerating what each test entry contains (load, HR vs baseline, HR drop, answers, check-in) and how lower HR can signal fatigue. This is close to complete; a note on ordering or result limits would make it fully sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `sport` picks the bike (watts) vs run (pace) test, `weeks` looks back with default 12, and `suggest` is for deriving watts from their own riding. These go beyond the schema's literal text and clarify intent.

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 concrete verb and resource — retrieves the athlete's SFT (fatigue test) log — and specifies the source (auto-detected tests plus hand-written log_sft_answers entries). It is dense with domain jargon (SFT, profile fatigueTest, howToRead), which slightly obscures the plain purpose, but the resource is unambiguous and distinguishes it from generic activity/readiness tools.

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

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

Implies when behavior changes (proposes the protocol's load when no test is set up or when suggest:true, and suggest is for 'what watts should my test be' or a new season). However, it never explicitly says when to call this versus siblings like get_readiness or get_metric_history, leaving the routing 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/destructiveHint, so the safety profile is covered; the description adds substantial extra context — ordering ('newest first'), what each row contains (reps × watts, % threshold, HR drift a→b, sRPE, lactate, notes), and the HR-family exclusion rule. The fitness-interpretation caveats (4+ min reps, 8+ min bike threshold) are useful behavioral framing, though the prose is hard to parse.

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 concept reasonably, but the body is a dense, jargon-laden run-on mixing return-value details, interpretation heuristics, and parameter notes without clear separation. Much of it earns its place, but the structure makes it costly to extract the actionable parts.

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 does the work of explaining the returned structure (per-session rows, HR drift, sRPE, lactate, notes), and adds interpretation caveats. It is nearly complete for an analytical read tool; only the 'sessions' parameter and default-8 behavior are left unexplained.

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 ~75%, and the description reinforces semantics: 'family' is a substring of the label, 'zone' filters, 'weeks' looks back (default 12, max 52). It adds the substring-matching behavior beyond the schema's example, but never mentions the 'sessions' parameter, leaving one gap.

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 the resource — 'the same rep family across sessions — the interval ledger' — and the word 'get' in the name plus the ledger framing make the read intent clear. It also distinguishes itself from the snapshot variant ('this for the longer arc and every family'), though the phrasing is idiosyncratic rather than plainly stated.

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

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

Explicitly states when to use it: 'THIS IS WHERE A TARGET COMES FROM: before writing watts, a pace or a % into a rep session, read interval_progression in the snapshot ... or this for the longer arc and every family.' It routes between the two modes, though it does not name a discrete sibling tool to prefer 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond that: the default returns a COMPACT DIGEST with key findings, practical application, and limitations, and section returns one sub-section. It also discloses citation behavior, which helps the agent use 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?

The description is dense but every sentence earns its place: it states the action, the default return format, the optional parameter behavior, and when not to call. The key guidance is front-loaded in the first sentence.

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

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

With only two simple parameters, read-only annotations, and no output schema, the description covers everything an agent needs: the refId format, the default digest contents, the section option, and the calling policy relative to search. There are no significant missing behavioral details.

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

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

Schema description coverage is 100%, so the schema already documents refId and section. The description adds value by explaining the default vs. section tradeoff and providing concrete refId and section examples, making the conditional meaning of the parameters clearer than 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?

The description states a specific verb and resource: 'Read an entry by refId'. It clearly distinguishes itself from knowledge search by saying 'Prefer answering from the search card first; only call this when the card is insufficient.' The REF-001 / SYNTH-04 examples make the target resource concrete.

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 guidance is present: use the search card first, call this only when the card is insufficient. It also explains when to pass `section` for depth versus relying on the default digest. This fully routes an agent between the default and parameterized behavior.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds meaningful behavioral context: only activities with sRPE logged are included, and results are aggregated per day and ISO week. It does not describe empty-result behavior or output format, but this is minor for a read-only summary 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 concise sentences, with the formula and aggregation logic front-loaded and the use case in the second sentence. No wasted words.

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

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

Given no output schema, the description sufficiently explains the computation, data source, aggregation granularity, and intended use. It would be more complete with a brief note on what the returned summary contains, but the current description is adequate 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 0%, so the description must compensate. It adds the 'date range' meaning for from/to and the ISO-week aggregation granularity, but it does not clarify inclusivity, boundary handling, or other parameter semantics beyond what the property names and regex already imply.

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 computes sRPE training load (Foster AU = sRPE × minutes) summed per day and per ISO week over a date range, using only activities with sRPE logged. It does not explicitly name a sibling tool to differentiate from, but the 'Complements TSS' note helps position it relative to TSS-based load reasoning.

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?

'Complements TSS: use it to reason about total load including non-metered sports, monotony and ramp' gives explicit when-to-use guidance. It lacks an explicit exclusion or named alternative tool, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: rows carry a `source` discriminator (profile | lab | field-test | estimate | self-report) and the profile is overwritten in place, which explains why history is the only way to see movement.

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 and front-loaded: the core purpose leads, then the contrast with the profile, then the source caveat. It is somewhat long-winded with em-dash chains, but each sentence carries usable 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?

There is no output schema, so the description partially compensates by describing row structure via the `source` field. Pagination is left to the schema's limit parameter. Adequate for a read-only historical query, though return shape could be fuller.

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 to/from/kinds/limit are already documented, including 'newest first' and date patterns. The description adds no syntax or semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('the HISTORY of a measured number') and enumerates the exact kinds it covers (FTP, LTHR, weight, ferritin, etc.). It explicitly contrasts itself with the profile, which carries only the CURRENT value, so an agent can tell it apart from get_athlete_profile 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 an explicit trigger ('call it when the question is about a trend, not about today'), notes it is 'Deliberately not in the turn snapshot', and warns to say which source is being compared since a lab number and a field estimate are not the same measurement twice. This is unambiguous when/when-not 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 establish readOnly/destructive/openWorld, and the description adds substantial behavioral context beyond them: omitted dates are unbounded so a bare call returns the whole past and future calendar, days returned are only those with a session or note, `key:true` marks a KEY session declared in advance, and structure:true changes the payload shape. This is exactly the kind of cost/semantics disclosure 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 scope are front-loaded, and with no output schema the dense return-value enumeration earns its space. However, the middle is a single run-on sentence with heavy parenthetical nesting that could be broken up for faster scanning, so it is informative but not maximally clean.

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 full burden of documenting the return payload, and it does: `days` contents, per-workout fields (iid, title, sport, zone, duration+TSS, goal, fuel, target, targetDefault, judge_by), day notes, monthlyTss, and the structure flag. Nothing an agent needs to call or interpret the result 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 meaning the schema does not: both dates are inclusive, and omitting either makes that bound unbounded, with the extreme case spelled out. It also explains what structure:true actually produces (compact interval string) with a concrete example, exceeding the schema's terse 'include each workout's compact interval structure'.

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 what is already scheduled on the athlete's calendar') plus the scope ('in a date range'), and explicitly distinguishes itself from get_plan_workout ('for raw blocks of ONE entry use get_plan_workout'). An agent can route between get_plan, get_plan_workout and plan_workouts without opening any schema.

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

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

Gives a clear purpose rationale ('so you don't double-book and can balance weekly load') and names one alternative with the condition that selects it (structure:true vs get_plan_workout). It lacks an explicit when-not statement or guidance on bounding the range for large calendars, so it falls just short of full routing 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 establish read-only, non-destructive, closed-world, so the bar is lower, yet the description still adds meaningful domain context: the fuel field's computation ('grams for the WHOLE session... raised when hard work follows, or your own number'), the distinction between target and targetDefault, and a pointer to control_signal. It stops short of describing pagination or failure behavior, so not a 5.

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

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

The opening clause is well front-loaded, but the middle is a dense run-on with nested parentheticals (the fuel explanation spans multiple clauses and asides). Information density is high, yet the structure impedes scanning and some clauses could be split or 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?

With no output schema, the description must characterize the return, and it does so thoroughly: interval structure, raw blocks, totals, notes, target/targetDefault, control, and fuel composition. The main remaining gap is characterization of the 'date' input, but for a single-read tool this is largely complete.

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

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

Schema description coverage is 0%, so the description carries the burden. It helpfully explains where iid comes from (get_plan / athlete snapshot) but adds nothing about what the required 'date' parameter means (scheduled date vs. day to read) or its interplay with iid. Half the parameters get meaning, so a middling 3.

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

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

States a specific verb and resource ('Read ONE scheduled workout in full detail') and enumerates the payload scope (intervals, blocks, totals, target, control, fuel). An agent can immediately tell this apart from list-level siblings like get_plan or plan_workouts, and it names get_plan / the athlete snapshot as the source of the identifying iid.

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: 'Use the iid from get_plan / the athlete snapshot' and 'This is how you inspect exactly what the athlete is supposed to do before advising on or editing a session.' That is a concrete trigger. It stops short of explicit when-not or naming an alternative tool for other cases (e.g. catalog templates), so not 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 destructiveHint=false, so the tool is clearly a safe read. The description adds substantial behavioral detail beyond annotations: it computes arithmetic over the plan (no citations), reads both plan and executed activities, reports them separately, is silent under three weeks, and deliberately omits easy families (repeating endurance is correct). These are non-obvious behaviors essential for correct interpretation and are not present in the annotations.

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

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

The description is dense and multi-sentence, but every sentence carries unique information: core purpose, per-family scope, plan-vs-execution split, edge cases (target-only climb, plan grew but work didn't, athlete outrunning plan), and limitations (silence below 3 weeks, no easy families). It is front-loaded with the primary purpose. It could be slightly tighter, but the complexity justifies the 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 sophisticated analysis tool with no output schema, the description is exceptionally complete. It covers what it evaluates (block progression per family), what data it reads (prescription and executed time), how it reports (two separate views), edge cases (plan grew, athlete outrunning flat plan), and limitations (silent below 3 weeks, excludes easy families). An agent has everything needed to decide when to call it and to interpret its results.

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 is empty (0 parameters, 100% coverage), so there are no formal parameters to document. The description compensates by clarifying the implicit inputs: the athlete's calendar, the weekly prescribed shape, working minutes, synced activities, and the plan. This adds meaning beyond the empty schema by telling the agent what data sources the tool relies on, which is exactly what a parameterless tool needs.

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, non-tautological purpose: determining whether an athlete's block is progressing or repeating across quality families (tempo/threshold/vo2/sprint). It distinguishes this tool from siblings like get_interval_progression and get_strength_progression by scope (block-level, per quality family) and by separating plan vs. executed work. No other sibling covers this exact combination.

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

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

The description implies clear usage context: you ask this tool when you need block-level progression analysis per quality family, reading both prescription and executed time. It also notes an explicit condition (silent below three weeks of history). However, it does not explicitly name alternatives or state when not to use it (e.g., for single workouts or strength). This is close to a 5 but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: it specifies the content (subjective + confounders + manual objective values) and that aggregates are anchored at the range end. It does not mention response format or size limits, but it adds value beyond the annotations.

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

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

The description is two sentences with no fluff. The first sentence states exactly what the tool returns, and the second gives the primary use cases. It is front-loaded and every word 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 read-only tool with two date parameters, the description sufficiently explains the output (raw entries plus aggregates) and gives usage context. It could clarify whether both endpoints are inclusive, but given the simple parameter set and no output schema, it is adequately 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?

The schema has zero descriptions for the two parameters. The description only refers to 'a date range' without explaining inclusivity, timezone, or defaults. It does not compensate for the lack of schema coverage, leaving parameters semantically under-specified.

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 raw readiness entries and per-metric aggregates for a date range. It explicitly distinguishes from siblings by naming the use cases 'trend review', 'before/after a training block', and mentions log_readiness for backfilling, which differentiates it from get_readiness_today and get_readiness_baseline.

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 usage scenarios: trend review, before/after a training block, and checking history before backfilling. It names log_readiness as the tool to use for backfilling, providing guidance on when not to use this tool. However, it does not explicitly exclude other siblings like get_readiness_today, though the context implies historical vs. current.

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

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

Annotations already indicate read-only and non-destructive behavior, so the bar for additional disclosure is lower. The description adds valuable context by specifying exactly what the baseline contains (7d/28d mean, 28d SD, rolling-3d, sample size), which helps the agent interpret results. It does not describe output structure or potential edge cases, but for a zero-parameter read-only tool this is sufficient.

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

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

The description is two sentences with no filler. The first sentence front-loads the core factual definition of the baseline, and the second sentence adds a practical usage note. Every phrase earns its place, and the formatting is easy to scan.

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-parameter, read-only tool with clear annotations, the description provides enough context for an agent to call and interpret the tool correctly. It defines the data contents and the intended comparison target. No output schema exists, but the description enumerates the key return fields, so no critical information 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?

There are no parameters, and schema coverage is 100%, so nothing needs to be documented about inputs. The baseline score for zero-parameter tools is 4, and the description does not need to compensate for parameter ambiguity. No further parameter semantics are required.

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: the athlete's current per-metric readiness baselines, including specific summary statistics like 7d/28d mean, 28d SD, and sample size. It communicates that this is the athlete's 'personal normal,' which is a clear and meaningful purpose. However, it does not explicitly name or contrast sibling tools like get_readiness_today or get_readiness, so sibling differentiation is only implicit.

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

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

The description provides clear usage context: compare today's readiness values against these baselines and never against population absolutes. This gives the agent actionable guidance on how to use the returned data. It does not explicitly name alternative tools or state when not to use this tool, but the population-vs-personal contrast effectively steers 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?

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, but the description adds substantial context: it enumerates the returned fields (today's entry, PRS, confounder flags, baseline7d/28d, sd28d, zToday, rolling3d, n28), states 'Blocks computes NO verdict', and documents the house threshold rule (|zToday| ≥ 0.9, n28 ≥ 7). This is meaningfully more than the annotations provide.

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

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

The description is a dense wall of run-on sentences and unexplained domain jargon (PRS, RHR, zToday, persist3d, h = round(baseline28d)) delivered in a single breathless block. It is over-stuffed and hard to parse rather than front-loaded and scannable.

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

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

With no output schema, the description carries the burden of describing return values, and it does so thoroughly by enumerating the entry fields and aggregates plus the scoring rules. An agent would know what comes back, even if the terminology is opaque.

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

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

With 100% schema description coverage and a single parameter, the schema already documents `date` fully, and the description merely restates the default ('`date` defaults to the athlete's today'). No added syntax or format value 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 resource ('the athlete's readiness picture for one morning') and scopes it to a single entry plus per-metric history aggregates, which separates it from a broad multi-day view. However, it never names the sibling tools (get_readiness, get_readiness_baseline) it most resembles, so the agent must infer the boundary between them.

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

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

The description explains how to interpret output ('One morning is a reading; a shift that persists... is what moves a plan') but gives no explicit guidance on when to call this versus get_readiness or get_readiness_baseline. No prerequisites, no exclusions, no alternatives 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 this as a safe read, but the description goes well beyond them: data provenance (bests derived from the full-resolution import stream, matching the head unit), the meaning of the `pending` counter and how to phrase results that aren't final, and the fact that it also returns the threshold/battery/fade readings shown on the athlete's Records page.

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

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

The core purpose and the two-window mechanics are front-loaded, and each paragraph carries distinct information. It is longer than needed in places (e.g., the aside about never quoting different numbers than the page), which slightly dilutes scannability but does not bury the key points.

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, so the description carries the full burden of describing return values, and it does: row contents, session provenance, the 90-day gap marker, the threshold/battery/fade readings, and the pending state. Nothing essential for calling or interpreting the result 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?

There is only one parameter, and the 100%-covered enum schema already documents it. The description adds real meaning by explaining what each enum branch yields (cycling: best average watts over 18 windows; running: fastest time over 12 distances with pace), though it does not add any parameter syntax 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+resource and the exact scope: the athlete's bests for one sport across the last-90-day and all-time windows, with per-sport peak definitions (18 power windows vs 12 run distances). It is clearly distinguishable from siblings like estimate_thresholds or get_metric_history without opening any schema.

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

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

Gives concrete when-to-use scenarios (anchor threshold estimates, spot a decayed top end, size interval targets, distinguish a true PR from a good day) and explains how to read the 90-day-vs-all-time gap. It also flags the `pending` > 0 caveat and routes the agent to the shared `howToRead` block used by estimate_thresholds.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely new behavior: traversal depth is exactly one hop, and an unknown refId returns the literal string 'No entry'. It omits ordering/completeness guarantees, so it falls short of a 5.

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

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

Two sentences, front-loaded with what is returned, followed immediately by the traversal scope and the follow-up tool. Every clause carries information; no filler.

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

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

With no output schema, the description usefully enumerates the projected fields (refId, title, evidence level, section), plus traversal depth and error behavior for a read-only one-parameter tool. Minor gaps remain around result ordering or empty-relationship cases.

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

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

Schema description coverage is 100% and the single refId parameter is documented with an example ('REF-001 or SYNTH-04'). The description reinforces that an exact refId is required and notes the unknown-id outcome, but adds no format or syntax detail 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?

States a specific verb and resource ('List the entries one knowledge-base entry cross-references') and pins the scope precisely as 'one hop in the citation graph'. It also names the returned fields, so an agent can distinguish it from get_knowledge 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 an explicit when-to-use scenario ('walk from a nearly-right search card to its neighbours') and names the follow-up alternative ('read the one you need with get_knowledge'). Nothing about routing 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?

The annotations already establish read-only, non-destructive, closed-world behavior, and the description adds substantial behavioral detail beyond that: the 12-week computation window, the specific analyses performed, the decision to stay silent on small samples, and the meaning of an empty answer. This gives the agent a clear model of what the tool will and will not do.

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

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

The description is three sentences, front-loads the core purpose, and each clause adds meaningful information: computation source, evaluated patterns, scope boundary, and empty-result semantics. No filler or repetition is present.

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

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

For a parameterless read-only tool, this is complete. It gives the computation window, the exact patterns being evaluated, the source data boundary ('no literature'), and a clear interpretation of empty output. Nothing needed to invoke or trust the 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter burden for the description to carry. The baseline of 4 applies because nothing is underdocumented.

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 resource—this athlete's response profile—and explains exactly what it computes: whether quality sessions land as aimed, whether sRPE separates hard/easy days, whether low readiness predicts poor sessions, and which weekday leaks occur. This clearly distinguishes it from sibling read tools like get_readiness or get_load_summary.

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

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

It clearly frames when this tool is appropriate: when you need evidence specific to this athlete from their own last 12 weeks, as opposed to literature or generalized knowledge. It also tells the agent that an empty answer means there is genuinely no usable sample yet. It does not explicitly name alternatives or exclusions, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description adds substantive disclosure beyond that by enumerating exactly what is returned (per-week letters, done vs planned hours, done/missed/ahead sessions, race, overlaid blocks with stimulus and lever). Only gap is nothing about size/volume of a full year's payload.

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 resource definition, then the operational guidance. Dense but each clause carries information; the parenthetical doc reference and the somewhat run-on planning sentence cost it a point.

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, so the description must carry the return-value burden and it does so thoroughly, plus it covers the planning workflow the tool feeds into. Slightly incomplete on result size and on the year parameter's behavior, but otherwise sufficient 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% with a single optional 'year' parameter already documented ('default this year'). The description never mentions the year parameter, so it adds nothing 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 resource and its scope precisely: 'The athlete's YEAR, by weeks — what the calendar's Season view shows', then enumerates the payload (weeks, letters, hours, key sessions, races, training blocks). An agent can tell this is the season-level aggregate, distinct from week-level or plan-level tools, though no sibling is named as a contrast for the read itself.

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 trigger conditions: 'Read it before you plan beyond the next two weeks or when they ask how their season looks'. It then names the alternative (set_training_blocks) and describes the correct workflow split — blocks first, sessions only into the next two weeks, targets beyond that.

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 and non-destructive annotations, the description explains the two layers of data: amendments made before the session versus actual set-by-set execution. It also documents important behavioral context: no TSS, no duration, actual RPE, load/reps, and the athlete's reason for divergence. This gives the agent a strong mental model of what the tool returns.

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

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

The description is long but dense, with the core purpose front-loaded and no fluff. Some sentences around 'opposite advice' and 'the calendar alone cannot tell you' are explanatory rather than strictly necessary, but they reinforce usage rather than waste space.

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 semantic content is thoroughly covered, especially the distinction between amended decisions and executed sets. However, the description does not address date-range behavior, return format, or empty results. Since there is no output schema, a bit more detail about what the agent receives would make this 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?

The schema has 0% description coverage and the tool description never mentions the to/from date-range parameters. The parameter names and date pattern provide some self-evident meaning, but the description does not compensate for the missing schema semantics, so an agent gets no guidance about how the date range filters the log.

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 concrete resource: what the athlete actually did in a planned gym session, set by set, plus what they changed in the plan before starting. It clearly explains why this tool exists and distinguishes it from calendar or plan data by noting that strength sessions have no TSS or duration.

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

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

The description explicitly tells the agent when to use this tool: before prescribing the next gym session and before judging whether the last one was completed. It also warns that the calendar alone cannot answer those questions. It does not name sibling alternatives explicitly, but it provides clear context and the different questions each data layer answers.

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 cover only the read-only safety profile, and the description adds a lot beyond that: newest-first ordering, per-line structure (kg×reps, s/m for timed/distance, bw, sets done/planned, RPE vs target), the days-since-previous marker, header frequency stats, and the 14-day BREAK rule that reframes the next load as a return rather than a step up. This is exactly the extra context the annotations do not 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?

It is front-loaded with what the tool returns, but it degenerates into a run-on paragraph mixing return format, coaching heuristics ('one axis moved and named; over target or unfinished = the same load'), and prose like 'Arithmetic over the log, nothing to cite.' It is dense and hard to scan, and the house-practice sentences are arguably guidance rather than tool semantics.

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 must carry the return format itself, and it does: per-exercise lines, their fields, the header aggregate, and the BREAK annotation. An agent can predict the shape and interpret the numbers without a 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 real meaning to `exercise`: it is a substring match against the athlete's own names, with a concrete example ('присед' finds both squats), which the schema only partly conveys. The sessions cap and 4/12-week windows are mentioned, though the default of 8 sessions is left 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 verb and resource: the per-exercise lift history across sessions, with ordering (newest first). It also differentiates itself from a near-sibling by noting 'the snapshot's strength_progression has the last three for exercises in view; this has a year', so the agent can tell it apart from the other progression tools.

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

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

Gives explicit usage: 'A WEIGHT COMES FROM HERE: read it before writing a kg' and, for ambiguous exercise names, 'ask, then link_exercises', which routes to a specific sibling. It does not, however, explain when to choose get_strength_log or get_progression instead, so the alternative routing is only partial.

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, non-destructive, closed-world behavior, so the bar is lower. The description adds real context beyond them: the returned fields and the `zone` semantics, including the instruction to flag and confirm when the zone reports UTC and the athlete may already be on a different calendar day.

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 fact, then the call-to-action, then the caveat — a sensible order with no filler. The em-dash-heavy sentences are dense and slightly over-packed, but every clause carries distinct 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 carries the return-value burden and does so by naming the ISO date, weekday, ISO week, and zone. Combined with the UTC caveat, an agent has everything needed to call it and interpret the result 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?

Zero input parameters, so the baseline is 4. The description's discussion of `zone` concerns a returned field rather than an input, which adds useful meaning without misrepresenting 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 names a specific resource and scope: today's date on the athlete's Blocks account, in their own time zone, and even enumerates the returned components (ISO date, weekday, ISO week). It is clearly distinguishable from siblings like get_context or get_readiness_today.

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 explicitly when to call it — to anchor relative reasoning ('today', 'tomorrow', 'this week', 'in 3 days') and to supply the correct `date` to other tools. This is direct routing guidance, not implied 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?

Annotations already cover the read-only/no-destruction profile, so the description's added value is the semantics: how grading works (four axes, self-referential intensity baseline, floor/ceiling as forbidden-to-exceed bounds), and the open:false behavior for unfinished weeks. That is substantive behavioral context beyond the annotations, though return shape/pagination specifics are not addressed.

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 carries information, but the opening sentence is very long and hyphen-heavy, burying the output anatomy inside it. It is dense rather than wasteful, though it could be split for faster 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?

No output schema exists, so the description must carry the return contract, and it does: four graded axes, a letter grade, floor/ceiling bounds with rationale, and the open:false flag for unfinished weeks. Combined with annotations and the fully documented parameter, 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% and the single date parameter is fully documented in the schema. The description only restates the default ('the last one that ended, today's on a Sunday'), which slightly clarifies the schema's 'default the last finished week' but adds little new syntax or edge-case meaning.

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

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

States a specific verb (grade) and resource (one finished training week) and enumerates exactly what the grade is composed of: four axes, a base letter A–D, and the floor/ceiling bounds. No sibling in the list produces a week grade, so an agent can identify this tool unambiguously from its name plus description.

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 ('Call it when the athlete asks to review a week') plus a when-not boundary: an unfinished week returns open:false rather than an error, and grading starts from the week's Sunday. It also states the default (last finished week). No alternative sibling is named, but the routing condition 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?

Annotations already declare it is a write (readOnlyHint=false) that is non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: rename semantics (a rename starts a history over), the confirmation requirement, the "Saves on return" persistence behavior, and the inverse "unlink separates" 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?

Three dense sentences, zero filler, with the purpose front-loaded before the precondition and parameter notes. 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?

No output schema exists and the annotations cover the safety profile, so the description need not explain return values. It covers purpose, precondition, behavior, and all three params; only edge details (e.g., what happens when names overlap an existing history, or the effect beyond "saves") are left unstated.

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 0%, so the description must carry the burden, and it does: "`names` continue `as`" documents the direction of the merge for the two required params, and "`unlink` separates" documents the third. This meaningfully compensates for the undocumented schema, though it stops short of noting array limits (maxItems 6) or the return/error shape.

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 ("Join the lift histories of one movement logged under two names") and immediately clarifies the rename-causes-split semantics that motivate the tool. This distinguishes it from siblings like rename_activity or edit_activity, which do not merge history.

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 hard precondition: "ONLY after the athlete confirmed it is the same exercise," which is exactly the gating an agent needs before merging histories. It does not name an explicit alternative tool or spell out a when-not case, but the confirmation gate is a strong, actionable usage 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?

Goes well beyond the read-only annotations by disclosing sync deduplication, provider coverage, completed-only scope, the row-count vs date-window default, local-clock date interpretation, and note truncation behavior. No annotation contradictions.

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

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

Front-loads the core list of fields and usage context, and nearly every sentence adds actionable information. It is dense and unformatted, but not padded with irrelevant 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?

With no output schema, the description fully enumerates the row fields and explains the two note columns, their truncation, and how to retrieve full text via get_activity. An agent has enough to call and interpret the tool correctly.

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

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

With 0% schema description coverage, the description compensates by explaining the semantic purpose of from/to and the default row-count behavior of limit. It does not explicitly name the limit parameter or its maximum, but the schema supplies structure and bounds.

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 completed activities) and enumerates the returned fields, scope (completed, synced, deduplicated), and providers. It also distinguishes this list tool from get_activity by noting that coachNote is an excerpt here but returned whole there.

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 to use this to find an activity id before calling set_activity_notes and to base summaries on real numbers. It also names the condition for passing explicit from/to and explains the default 30-row behavior, with get_activity implied for full note retrieval.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that open commitments already ride in the snapshot, implying the tool can return closed ones. It doesn't contradict annotations and gives useful scoping 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?

Three sentences: the first states the core purpose, the second adds context about the snapshot, and the third gives usage guidance. No redundant words, and key information is front-loaded.

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

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

For a simple read-only listing tool with two optional parameters, the description covers scope and usage well. It mentions returning ids and filtering by status, but it doesn't describe pagination or the exact return structure (no output schema exists). Still, the essential information for calling the tool correctly is present.

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

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

Schema description coverage is only 50% (status has a description, limit does not). The tool description mentions status usage indirectly ('to see closed ones') but completely ignores the 'limit' parameter. Given the low coverage, the description should compensate, but it fails to explain limit's purpose or behavior.

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

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

The description clearly states the tool lists commitments (instructions given to this athlete) with ids, and specifies the scope as 'your own instructions from earlier turns.' It distinguishes from siblings like close_commitment by focusing on listing rather than modifying.

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

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

The description provides context for when to call: 'to see closed ones too, or to check what you told them about a specific date before you say it again.' This implies when to use it over relying on the snapshot, though it doesn't explicitly name alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: the types of events included, the default to upcoming events, and the exact fields returned. It does not contradict annotations and provides value beyond them.

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

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

Three sentences, each purposeful: the first lists content, the second gives usage, the third states the default. No fluff or repetition. Information is front-loaded 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?

With only one optional parameter and no output schema, the description fully covers what an agent needs: the fields returned, the use case, and the default behavior. Nothing critical is missing for a read-only list 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% and the schema describes includePast as 'also return events whose date has passed.' The description adds the default value ('Defaults to upcoming events'), which clarifies the parameter's behavior without redundancy. This exceeds the baseline for full schema coverage.

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

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

The description clearly states it lists the athlete's events with specific types (races, key rides, FTP tests, camps) and enumerates the fields returned (id, date, name, location, URLs, route stats, notes). This is a specific verb+resource and distinguishes it from sibling tools like list_activities or create_event.

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

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

It explicitly says 'Use this to find an event id before writing fueling/pacing guidance with set_event_notes,' giving a clear when-to-use context. It also mentions the default behavior of upcoming events. It does not explicitly name alternatives or exclusions, but the purpose is distinct enough that this is a minor gap.

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 indicate readOnly and non-destructive hints. The description goes far beyond by defining the five states (live, lapsed, stale, asleep, retired) and their implications, including cautions about lapsed facts ('ask before taking the freed space') and the status of stale facts. This is rich behavioral context not visible in 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?

The description is dense but front-loaded with the core purpose and when-to-use guidance in the first two sentences. The state breakdown follows logically and every clause adds value—no filler. Despite length, it earns its space by clarifying a complex state model.

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

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

Covers usage, state semantics, and differentiation from the snapshot. It does not explicitly describe the response format (e.g., array of fact objects), but given that the tool is a listing endpoint and the description references facts carrying a 'state', it is reasonably complete for a read-only operation. A minor gap is the absence of explicit return shape, but not critical.

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%, giving baseline 3. However, the description adds nuanced meaning to the 'state' parameter by explaining each state's semantics and the default behavior (everything except retired). It does not add extra meaning for 'tag' or 'area' beyond schema descriptions, but the state definitions are a meaningful augmentation.

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

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

Clearly states the tool lists all facts about the athlete, specifically distinguishing active facts (already in snapshots) from inactive ones (lapsed, asleep, retired). This differentiates it from any sibling that returns the current snapshot, and the verb 'call this' implies a listing action.

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 directs when to use: 'call this when you need the rest' and enumerates the specific cases (lapsed, asleep out of season, retired history, or a specific area in full). Also implicitly says not to use it for active facts since they are already in the snapshot, providing clear contextual 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 destructiveHint=false, so the safety profile is established. The description adds the useful behavioral detail that the result includes entry counts and frames the tool as a topic map, but it does not describe return structure or pagination. This is acceptable but not rich.

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

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

The entire description is one front-loaded sentence with no filler. It states the action, the resource, and the key output characteristic efficiently.

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

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

For a simple parameterless list tool with read-only annotations, the description conveys enough to be called correctly: no inputs, sections are returned, and entry counts are included. The lack of an output schema is partially mitigated by the explicit mention of entry counts, though exact response formatting is unspecified.

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 schema description coverage is 100%, so there is no parameter information the description needs to supply. The baseline for a parameterless tool applies here.

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 ('List') and resource ('knowledge-base sections') and adds the distinguishing output detail 'with entry counts (the topic map)'. It is clearly scoped and can be differentiated from siblings like list_facts or search_knowledge.

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 purpose is specific enough that an agent can infer when to use it: when needing an overview of knowledge-base sections and their sizes. However, there is no explicit guidance on when not to use it or which siblings to prefer, leaving some 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?

Beyond the annotations (readOnlyHint=false), the description discloses that samples are appended by default, replace:true overwrites the entire set, and samples become visible as markers retrievable via get_activity. This gives the agent a concrete model of side effects and resulting state.

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 distinct functional information: scope, parameter semantics, append/overwrite behavior, and downstream effects. It is dense but not bloated; no filler or restatement of schema constraints.

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 3-parameter logging tool with no output schema, it covers input semantics, mode of operation, downstream retrieval, and scope limitations. An agent can confidently construct a correct call without needing additional tools; activity_id is self-explanatory.

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 has no property descriptions (0% coverage), so the description carries full weight. It defines t as seconds on the MOVING clock with estimation guidance, mmol as the reading, and explains the replace flag's default behavior. This is meaningful semantic coverage for all three 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 a specific verb ('Record') and a precise resource ('athlete's blood-lactate samples on a completed activity'), reinforced with a concrete example. It clearly distinguishes log_lactate from sibling log_* tools by naming blood-lactate as the metric and 'completed activity' as the target.

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 context: use on completed activities, append by default vs replace:true, and a clear when-not instruction ('put your interpretation in set_activity_notes, not here'). It does not explicitly contrast with log_metric or log_session_rpe, but the boundary is clear enough for correct 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 declare it is a non-read-only, non-destructive write; the description supplies the substantive behavior: batching (a whole lab report as one card), and the retroactive rescoring of every power ride from an FTP row's date to the next FTP row (IF, TSS, zones, calendar repaint). That is exactly the kind of side effect an agent cannot infer from annotations. It stops short of saying what happens on duplicate dates, invalid kinds, or beyond the 20-row cap.

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 the batch behavior, then the profile distinction, then the FTP side effect — a sensible ordering where each sentence carries operational content. It is dense and leans on caps, backticks, and a long run-on clause ("never today-because-that-is-when-they-told-you"), which makes it slower to parse than it needs to be.

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 write tool with no output schema, the description covers purpose, dating, provenance, batching, and the main side effect, so an agent can call it correctly on the happy path. Gaps remain around the `kind` enum (19 values with no per-kind unit or valid-range guidance), the 20-item cap, and what the tool returns or does on partial failure.

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

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

The description adds meaning the schema does not: `note` is provenance ("Trisystems СПб, step test to exhaustion"), never athlete interpretation, and `date` is the measurement date rather than the reporting date, reinforced with the FTP backdating rule. It does not compensate for the absence of enum/unit guidance for `kind` or the unit table for `value`, which remain only in the schema.

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

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

"Record a MEASUREMENT with its date" is a specific verb+resource, and the examples (lab test, blood panel, weigh-in, field-test) plus explicit enum-like kinds make the scope unmistakable. It also draws a hard line against profile mutation by naming update_athlete_profile. It loses a point for not distinguishing itself from the sibling log_lactate, despite listing "a lactate draw" as an example of what this tool takes.

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-not guidance: "This is history, not the profile: it does NOT change what the app plans against — if the test says the threshold moved, propose update_athlete_profile as well." It also prescribes the correct date semantics via a concrete case (backfilled FTP should be dated to when it was measured, source self-report) and warns against defaulting to today.

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

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

Beyond annotations that only say it is non-read-only and non-destructive, the description discloses idempotent MERGE-upsert behavior, partial-update semantics where existing fields survive, a 90-item batch cap, and range-checking to protect baselines. These are exactly the behavioral details an agent needs before writing readiness data.

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

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

The description is a single dense paragraph but is front-loaded with the core operation and idempotency contract, then moves through batch behavior, field categories, and confounder semantics. Every clause carries useful information for correct 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 complex nested write tool with no output schema and no property descriptions, the description is largely complete: it covers idempotency, batching, field semantics, and confounders. It leaves minor gaps around return shape and a few fields like note and other_confounder.

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 0%, so the description carries the burden and does so well: it defines McLean 1-5 scales, prs 0-10, optional objective fields with units, confounder flags, and an example range check. It does not document every minor field such as note or other_confounder, but it adds substantial meaning beyond the schema.

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

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

The description states a specific verb and resource: record the athlete's daily readiness, one entry per date, via an idempotent MERGE-upsert. This clearly distinguishes it from the sibling read tools such as get_readiness and get_readiness_today.

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

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

It gives clear usage context, including one-entry-per-date semantics and batch backfill from an export. However, it does not explicitly name get_readiness/get_readiness_today as alternatives or state when not to use this tool.

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

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

Annotations only declare the write/no-open-world profile; the description goes well beyond them by disclosing that replace:true must carry the WHOLE corrected set to change or remove a mark, that otherwise marks are appended, that the athlete can edit the same marks in the RPE tab, and that changes persist ('Saves on return'). Minor tension with destructiveHint=false exists since replace can remove a mark, but the removal is small and reversible, not truly destructive.

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 every clause carries information (clock semantics, replace rule, sibling disambiguation, persistence). It is dense and runs long with several parenthetical quotes, which costs a little readability, 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?

For a mutation tool with no output schema and no annotations beyond the safety profile, this covers the necessary ground: input clock conventions, the add-vs-replace choice, sibling routing, and return behavior ('Saves on return'). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: t is defined as seconds on the MOVING clock (aligned to get_activity's blocks/effort_marks), v is the RPE, step is the context label, and replace's whole-set semantics are spelled out. This is meaning the schema's bare types cannot convey.

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

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

Specific verb (Write) plus precise resource (EFFORT MARKS for an activity), and it explicitly distinguishes itself from the two nearest siblings, log_session_rpe and log_sft_answers. An agent can tell exactly what this does 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?

States when to use it, names the alternatives it is NOT ('Not the session RPE (that is log_session_rpe) and not the fatigue test's answers (log_sft_answers)'), and gives the replace:true vs default add semantics as an explicit decision 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 already declare this is a non-read-only, non-destructive write. The description adds real value beyond them by disclosing the downstream effect (load_au = sRPE × duration_min, Foster method) and that the data feeds the same load currency as TSS. It does not state whether re-logging overwrites an existing sRPE or what the response contains.

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 scale definition, then the derived-metric consequence. Dense but every clause carries information; mild jargon stacking (sRPE, load_au, TSS) is offset by the parenthetical explanations.

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 2-parameter mutation with no output schema, the description covers scale, timing, prerequisite, and the computed side effect, which is what an agent needs to call it correctly. Missing only the overwrite/duplicate behavior and return-value 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?

Schema coverage is 0%, so the description must compensate, and it largely does: it pins srpe to the app's 1-10 scale, identifies it as Foster's session-RPE, and specifies the ~30 min post-session timing. It also clarifies that activity_id must reference a completed activity from list_activities. Exact ID format is still unspecified.

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 ('Attach the athlete's session RPE ... to a completed activity') and names the upstream tool (list_activities) that supplies activity_id. It does not explicitly differentiate from the near-sibling log_rpe_marks, so it stops short of full disambiguation.

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 when-to-use context: ~30 minutes post-session, applies to any sport including gym/tennis where no power meter exists. The prerequisite of a completed activity is stated. There is no explicit exclusion telling the agent when to prefer a different sibling tool.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds real behavior beyond that: writes are 'merged with what is there' (non-destructive upsert), manually entered `hr` 'wins over the file's' (precedence rule), and 'Saves on return, no card' (no confirmation interaction). It doesn't cover auth or failure behavior, but the added context is substantive.

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

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

Front-loads the core action and resource, then layers the conditional hr rule and the naming rule in short, information-dense sentences. Telegraphic style ('no card') costs a little clarity but nothing is 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 an 8-param, no-required-param mutation with no output schema, the description covers the essential write semantics (merge, precedence, session identification, save timing). The gaps are minor since the schema already describes hrr, rpe, and minutesLeft, and no return value needs explaining.

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 50%: hr, hrr, rpe, and minutesLeft have descriptions, while date, note, sport, and activity_id do not. The description partially compensates by explaining hr's manual-entry precedence and the activity_id vs date+sport session-naming rule, but leaves note and the hrr/rpe semantics 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 verb ('Write to') and resource ('athlete's fatigue-test (SFT) log'), and explicitly names the sibling that reads it back: 'read by get_fatigue_tests'. An agent can distinguish this from log_readiness, log_lactate, and log_session_rpe 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 a clear conditional: 'When the app did not find the test (treadmill, another device), pass `hr` as they read it', plus naming conventions via activity_id or date+sport. It names the read-side sibling but does not spell out when NOT to use this versus the other log_* tools, so it falls short of a full when/when-not/alternatives treatment.

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 annotations by disclosing return shape ('per-item result with the new iid, duration and TSS'), persistence behavior ('sessions are written two weeks out'), server-side validation, and that custom workouts are saved to the athlete's library. It also explains operational limits: the 40-item cap is a ceiling, a call too long to finish saves nothing, and the agent's key-session cap differs from the athlete's. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

The description is front-loaded with purpose and a per-day workflow, and most sentences carry operational guidance that earns its place. It is dense but appropriate for a high-complexity scheduling tool; a few parenthetical clauses could be trimmed, but nothing is seriously 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?

For a complex tool with a large nested schema and no output schema, the description covers the essential workflow, batching limits, long-horizon alternative, and return values. The remaining parameter details, such as why and noteEdits, are fully documented in the schema, so an agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning. The description still adds useful selection semantics by clarifying when to use workoutId versus a custom workout, and by specifying that key sessions should be declared first and filled around, which is not obvious from the field definitions alone.

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

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

States a specific verb and resource: 'Add one or more workouts to the athlete's training calendar (the days appear in Blocks).' It distinguishes the tool from catalog search and custom creation by prescribing workoutId from the catalog or search_catalog first, so an agent can tell what this tool does 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?

Provides an explicit workflow: prefer an existing workout by id, use search_catalog when no catalog map is present, and only create a custom workout when nothing suitable exists. It also names the alternative for longer horizons (set_training_blocks) and gives batching guidance ('Batch this week and the next in one call'), covering both when to use this tool and when to use a sibling 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it discloses that there is no undo, precisely what survives the operation (completed activities, day notes), and what the call reports back ('how many entries were removed, or says nothing was planned that day'). That is exactly the destructive-scope and outcome context an agent needs.

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 tight sentences with the scope decision front-loaded, then the preservation boundary, then the irreversibility and return behavior. No filler and no repetition of the name or title.

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 supplies the return semantics and the no-undo warning. It is complete for calling the tool, though it says nothing about permission or authorization requirements for a destructive operation, which would be the last missing piece.

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 baseline is 3, but the description adds real meaning by stating that `iid` comes from get_plan and that omitting it is a bulk clear for the day. It adds nothing about `why` or `noteEdits`, which rely entirely on their 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 precise verb+resource (remove planned work from the calendar) and disambiguates the two modes in one breath: a single entry by `iid`, or the whole day when `iid` is omitted. It distinguishes itself cleanly from siblings like delete_event, plan_workouts and copy_workouts by scoping itself to *planned* entries only.

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: pass `iid` to drop one scheduled workout, omit it to clear the day. It also names the recovery path ('putting a session back is plan_workouts or copy_workouts') and states the exclusion boundary ('completed activities and the day's notes stay'), so the agent knows when NOT to reach for this tool.

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

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

Adds genuine behavior beyond the annotations: the provider's native name is kept separately and rewritten on every sync, so the rename survives 'Sync now', and an empty string reverts to it. It also scopes the mutation ('does NOT touch the source'), which usefully clarifies why destructiveHint=true is limited to the local title. It stops short of stating what happens if the activity id is unknown or if an existing custom title is overwritten.

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 action, then the empty-string behavior, then the sync semantics, then the usage trigger. Dense and largely waste-free, though the trailing 'a session you merely read as something else keeps its name' is a second pass at the same exclusion already implied earlier.

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 two-parameter mutation with annotations covering safety and no output schema, the description supplies the non-obvious context an agent needs (sync survival, provider-name preservation, clearing semantics, usage trigger). The only real gap is that the 'id' parameter's expected value/reference is left entirely to inference.

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 0%, so the description must carry both parameters. It handles 'title' well (empty string clears, examples given, and the schema supplies maxLength), but 'id' is never explained beyond being required, leaving half the surface undocumented.

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 (give one completed activity the athlete's own title) with a concrete example, and implicitly distinguishes itself from sibling mutators like set_activity_notes, edit_activity and tag_activity by confining the action to the title field. An agent can tell what it does 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?

Explicitly names the trigger conditions ('when the athlete asks for a rename, or tells you what a generically named session actually was') and an exclusion ('a session you merely read as something else keeps its name'). This is exactly the when/when-not routing an agent needs versus get_activity or edit_activity.

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

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

Beyond the destructiveHint annotation, the description discloses the key behavioral nuance: the fact is kept and marked retired rather than deleted, it leaves the agent's context, and it remains visible to the athlete. The lapsed-fact distinction adds important behavioral context that annotations alone do not provide, and nothing contradicts the annotations.

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

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

The description is compact and front-loaded with the core condition, but the phrase 'Always a card' is unexplained domain jargon that may confuse an agent. Overall, every sentence contributes meaning, though the conceptual framing is denser 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?

For a two-parameter state-change tool with no output schema, the description explains the lasting effect, athlete visibility, and the lapsed exception. It does not describe the expected response or error handling, but those are partially covered by annotations and the simplicity of the call.

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

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

Schema coverage is 50%, so reason has a description but id does not. The description reinforces what a valid reason means by defining 'no longer true, or never was' and contrasting it with lapsed, but it adds no direct guidance on how to format or obtain id. This is adequate for a simple two-parameter tool, but not rich.

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

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

The description clearly identifies the operation as retiring a fact: removing an athlete's statement from the active context while marking it as no longer believed. It distinguishes this from deletion and from lapsed facts, so an agent can differentiate retire_fact from update_fact and confirm_fact 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?

It gives explicit when-to-use conditions: retire a fact when it is no longer true or never was. It also gives an explicit when-not-to-use condition: a LAPSED fact is not automatically retired, and the agent should ask first. This is clear usage guidance even without naming sibling tools.

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

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

Annotations only declare the generic write-capable profile (readOnlyHint=false, destructiveHint=false), so the description carries the real burden – and it does: it discloses the connection prerequisite, that attaching is equivalent to an upload and becomes visible via get_event_course, and that an existing GPX is only overwritten under an explicit replace flag plus athlete consent. That is exactly the kind of side-effect and safeguard context annotations cannot express.

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

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

Four dense sentences with no filler, front-loaded with the resource and then the two mode conditions. The final consent/replace sentence is long but is a genuine safety instruction, not padding; the enumeration of returned fields (id, name, km, climbing, last edited) earns its place since there is no 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-required-param, dual-mode tool with no output schema, the description covers prerequisites, mode selection, side effects, and safety constraints, and explicitly documents the list-mode return fields. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 25% (just 'query'), so the description must compensate, and it does for three of four params: routeId as the route selector that also switches modes, eventId as sourced from list_events, and replace as the overwrite gate. It adds nothing about the query name filter beyond the schema's own 'part of a route name', leaving a small gap, but overall the semantics are strong.

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 (the athlete's saved Ride with GPS routes) and cleanly splits the tool into its two real behaviors: listing when routeId is absent, and attaching a course when routeId + eventId are given. An agent can tell it apart from get_event_course and list_events, which are named as the counterpart tools.

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

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

Gives explicit mode-selection rules keyed on parameters ('Without routeId: lists them', 'With routeId + eventId (from list_events): puts that route on the event'), names the prerequisite (athlete must have connected Ride with GPS in Connections), and adds a when-not constraint ('Attach only the route the athlete picked; an event that already has a GPX is replaced only with replace:true after they agree').

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to re-establish safety. It adds real behavioral context beyond that: the workout is not placed on the calendar, it produces a library card the athlete applies, and it persists even if later removed from the calendar. It doesn't address auth/permissions or how duplicates/overwrites are handled.

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 the calendar exclusion, and the body is dense with actionable detail. Slightly long, with plan_workouts referenced twice and a mildly tangled final sentence, but almost nothing is 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, and the description compensates by describing what is produced (a library card) and how it can later be scheduled via plan_workouts + workoutId. For a two-parameter write tool this is close to sufficient; only error/overwrite behavior is unstated.

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 genuine meaning: the workout object is 'the same object as plan_workouts' custom items[].workout', and notes are 'the workout's own notes: intent, cues'. It also explains the read-then-resubmit pattern for copying, which the schema alone cannot convey.

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

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

The description states a specific verb and resource ('Save a workout to the athlete's library') and immediately contrasts it with the sibling plan_workouts by scope ('WITHOUT putting it on the calendar'). An agent can distinguish this from plan_workouts 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 explicit when-to-use cases ('a variation of a session for later, a template they asked to keep'), an explicit exclusion with routing ('For a session on a day use plan_workouts'), and even a workflow for the copy-with-a-change case. Alternatives are named rather than implied.

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 safety profile is covered. The description adds contextual behavior beyond that: it explains that the athlete's saved workouts are deliberately not in the catalog map and enumerates the returned fields (id, title, zone, duration, TSS, IF, source).

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 scope and followed by usage guidance and output details. The middle sentence is a bit long and repeats the point about saved workouts, but every sentence contributes useful information.

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

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

For a read-only search tool, the description covers the search scope, when to use it, filtering options, return fields, and downstream integration via plan_workouts. There is no output schema, but the return fields are explicitly listed. No critical calling detail is missing.

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

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

Schema description coverage is 83%, so the baseline is 3. The description maps 'sport, target zone, and a duration window' to the relevant schema parameters, but adds little beyond what the schema already states for those fields. Query and limit are not described in prose, though the schema covers them well.

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 ('Search') and names three distinct resources: the Blocks catalog, coach collections, and the athlete's saved workouts. It distinguishes itself from siblings by noting the 'mine' source and by saying returned ids can be passed to plan_workouts.

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

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

It explicitly tells the agent to reuse an existing workout before inventing one, and positions this tool as the mechanism for that lookup. It gives concrete search angles (keyword, rep interior, saved workouts) but does not name alternative search tools or state 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?

Annotations already establish readOnly/non-destructive, and the description goes well beyond them by disclosing the actual return shape (compact cards with refId, title, evidence level, tier, sport, DOI, actionable bottom-line, finding, and decision on frameworks) and how complete that payload typically is for answering and citing. This is behaviorally rich for a read 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?

Front-loaded with purpose and return format, and every clause carries information (return fields, escalation trigger, citation rules). It is dense rather than bloated, though the citation-etiquette sentences push it toward the long side for a search 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?

With no output schema, the description carries the burden of explaining return values and does so concretely, including which fields appear on ordinary entries versus frameworks. Combined with the sibling escalation path, an agent has everything needed to call this correctly and interpret results.

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 schema already documents tag, limit, query, sport, section, and minLevel with examples. The description adds little parameter-level meaning beyond noting the refId/section pattern for the sibling tool, so it does not exceed the schema 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 specific verb (Search) and resource (curated endurance-science knowledge base) plus the domain scope, and distinguishes itself from the sibling get_knowledge by contrast ('Call get_knowledge(refId) only when...'). An agent can tell this is the discovery/ranking entry point versus the single-entry detail 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?

Explicitly routes between this tool and get_knowledge with a stated condition ('only when you need the full protocol/mechanism/limitations'), and gives follow-on guidance on citing (refId + level, DOI only when the reader asks). When-to-use and when-to-escalate are both covered.

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