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

Adds material behavior beyond the annotations: dry_run defaults to true and 'sends NOTHING', and omitting sets silently produces one flagged 1x10 set. Those are exactly the side effects an agent must know, though 'flagged' is undefined and nothing is said about error/permission 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?

Three short lines, front-loaded with the core action, then the two operational facts (position indexing and the dry_run default). No filler; the only weak spot is the unexplained word 'flagged'.

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

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

For an 8-parameter destructive mutation with 0% schema coverage, the description covers the highest-risk items (dry_run, defaults) but leaves required-but-undefined parameters and the meaning of 'flagged' unexplained. An output schema exists, so return values need not be described.

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

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

Schema description coverage is 0%, so the description carries the burden and only partially meets it: it explains position counting, the section values, and defaults for sets/rest/note, but says nothing about reps, weight_kg, routine, or exercise, and 'optional rest' has no unit or range.

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 a catalog exercise to a routine section', and names the section enum values inline. It is separable from siblings like remove_exercise or update_exercise by the verb, but never explicitly contrasts itself with 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?

Usage is implied rather than stated: the section/position semantics and the dry_run safety default tell the agent how to invoke it, but there is no when-to-use vs when-to-use-an-alternative guidance (e.g. update_exercise for modifying an existing entry).

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=true and idempotentHint=false, and the description goes well beyond that by spelling out exactly what destruction occurs: an exercise left out of a passed section is removed, an exercise listed under another section is moved, and omitted sections are untouched. It also explains that dry_run=true previews the plan and sends NOTHING, which is the key safety behavior 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 paragraphs, front-loaded with the purpose and then the destructive semantics. The only waste is the `days` sentence, which restates the schema field description almost verbatim.

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

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

For a 9-parameter destructive tool with an output schema (so return values need no prose), the description covers the highest-risk semantics thoroughly: removals, moves, omitted sections, and dry-run preview. The remaining gap is the unexplained `routine`/`name`/`goal`/`note` parameters and the lack of routing versus update_routine.

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

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

With schema description coverage at 11%, the description must carry the load, and it partially does: it defines the section lists (warmup/main/cooldown), the exercise_id vs catalog-name distinction, the optional rest/note/sets overrides, and the days format. But the required `routine` identifier and the `name`, `goal`, and `note` parameters are never explained in either place.

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

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

States a specific verb+resource+scope: 'Rewrite a routine in one go,' which distinguishes it as a bulk-replace operation rather than a single-field edit. However, it never names or contrasts the sibling smartgym_update_routine, so the boundary between the two is left for the agent to infer.

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

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

The example ('week 2 of FB-A') and the section-rewrite semantics imply usage, and dry_run's default preview is documented. But there is no explicit when-to-use statement and no exclusion or alternative named, which matters given smartgym_update_routine exists as a sibling.

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, so the description doesn't need to re-warn. It adds genuinely new behavior: the operation is reversible via smartgym_unarchive_routine, and the default dry_run=true performs no mutation at all. Minor gap: it doesn't say what 'archived' means to downstream reads.

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

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

Three short lines, front-loaded with the action and scope, followed by the reversal path and the dry-run default. 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?

An output schema exists so return values need no explanation, and the key behaviors (scope, reversibility, safe default) are covered. Slight incompleteness around what archiving does to the routine's visibility and how partial failures are handled.

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 carry the load. It clarifies that routines may be passed as names or ids (schema only says array of strings) and explains the dry_run semantics and default. It doesn't cover edge cases like duplicate or unknown identifiers.

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 (Archive) and resource (routines), clarifies accepted identifier forms (names or ids), and scopes the effect to 'every device'. It also names the sibling tool that reverses it, so an agent can distinguish it from unarchive_routine and the other routine 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 context: archiving is reversible via smartgym_unarchive_routine, and dry_run=true is the default and sends nothing, which tells the agent the safe path. It stops short of explicitly stating when to prefer this over siblings like update_routine or apply_routine.

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, idempotentHint=false, and openWorldHint=true, but the description adds substantial context beyond them: all-or-nothing validation, the dry-run-first safety workflow, deterministic fuzzy matching of exercise names, and the flagged default set when sets are omitted. This is exactly the kind of behavioral disclosure that reduces accidental destructive calls.

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 outcome, then proceeds into parameter detail in a logical order. It is dense and somewhat long, but nearly every clause carries payload (validation mode, day encoding, default-set flagging) rather than filler. Minor tightening could still help, so not a full 5.

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

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

With an output schema present, the description need not document return values, and it correctly focuses on inputs and behavior. For a nested, multi-routine mutation tool with rich annotations, it covers validation, dry-run semantics, name-uniqueness, and section ordering fully — 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?

Top-level schema coverage is effectively 0% (dry_run and routines carry no inline descriptions), so the description must carry the burden and does: it explains dry_run semantics, the routines structure, required name uniqueness, the optional days/goal/note fields, and the weekday numbering scheme (1=Sunday…7=Saturday). It adds real semantic meaning for nested specs (exercise fuzzy-match, rest_seconds, sets defaults) beyond what the schema offers.

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 ('Create one or more routines (a program) on the SmartGym server') and immediately distinguishes scope ('all devices get them'), which separates it cleanly from update_routine, add_exercise, and the other routine-mutating siblings. An agent can identify the create-vs-update boundary 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?

The description gives strong operational guidance: dry_run=true is the default and 'sends NOTHING', while dry_run=false actually creates and verifies on the server, and validation is all-or-nothing. It stops short of naming sibling alternatives (e.g. when to use update_routine instead), so it is clear context without 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 openWorldHint=true, so the safety profile is covered. The description adds useful scope about owned_only=true meaning 'only what you selected' and notes that weights are included, but it does not discuss external/open-world implications, auth needs, or edge cases.

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 a parenthetical that explains the parameter inline. There is no wasted wording, and the most important information comes first.

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

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

An output schema exists, so return values need not be explained, and annotations cover read-only/open-world behavior. For a one-parameter listing tool, the description is nearly complete, though it could clarify the owned_only=false case.

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 parameter meaning. It explains that owned_only=true limits results to selected equipment, which is the key semantic for the only parameter. It does not explicitly describe owned_only=false, but the default and boolean nature make that inferable.

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: list equipment and dumbbell/kettlebell weights. It is immediately clear what the tool returns, and no sibling tool covers equipment listing.

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 implied by 'List equipment', but the description does not explicitly state when to use this tool, when not to use it, or what alternatives exist. Given the unrelated sibling set, the risk of confusion is low, but guidance is minimal.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes further by disclosing the sectioned return shape, the meaning of history_depth, and the encoding convention 0.0 = bodyweight, which are genuine behavioral details 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 purpose is front-loaded in the first sentence and parameter semantics follow compactly. It is slightly dense in the final clause listing returned fields, but no sentence 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 an output schema present, the description need not restate the full return structure, yet it supplies the parameter semantics and the bodyweight/history_depth conventions that the schema leaves undocumented. Nothing needed 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 description coverage is 0%, so the description must carry both parameters, and it does: `routine` is explained as a case-insensitive, partial-match name or an id, and `history_depth` is tied to how many recent sessions are returned. Both parameters get meaning the bare schema lacks.

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 ('Get a routine') and immediately scopes the output as a warmup/main/cooldown split, which distinguishes it from the sibling smartgym_list_routines. An agent can tell this is the single-routine detail tool 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 implied: it accepts a name or id and returns detail, so it is clearly the fetch-detail call. However, no explicit when-to-use versus smartgym_list_routines or the edit tools is given, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds non-obvious behavioral detail beyond the annotations: sort order, the default/override date logic, local-timezone inclusivity, and the pagination envelope fields.

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

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

Front-loads what the tool returns, then the date-window rules, then the filter and pagination. Three tight sentences with no filler; every clause carries operational meaning.

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

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

For a read-only list tool with 6 optional params, no required inputs, and an existing output schema, the description covers the windowing defaults, override semantics, filter, and pagination shape. 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 0%, so the description carries the full burden and mostly does: it gives the enum values for `days`, the YYYY-MM-DD inclusive local-time semantics for `date_from`/`date_to` with their override relationship, and the `routine` filter accepting name or id. Only `limit` and `offset` are left undocumented, though pagination is acknowledged via total/has_more/next_offset.

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 ('List past workouts') and adds scope (newest first) plus the returned fields (duration, calories, heart rate). No sibling tool covers workout history, so it is unambiguous among the given set.

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?

Explains the default window (last 7 days), how to change it via `days` (14/30), and that explicit `date_from`/`date_to` override the default — clear context for choosing inputs. It does not name alternatives or exclusions, but none of the sibling tools are plausible substitutes.

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, openWorldHint=true). Beyond that, the description discloses failure and warning semantics: ok=true means the server returned account data, `problem` describes what to fix, and `warning` signals a version mismatch against the version the MCP was verified against. It does not mention auth requirements or any rate/latency characteristics, so it is strong but not exhaustive.

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 what is checked, then output semantics in two short, disciplined sentences with no filler. Slight redundancy in explaining `ok`, `problem`, and `warning` when an output schema already exists, but it is compact enough that this does not hurt readability.

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 parameters, an existing output schema, and annotations covering read safety, the description supplies exactly the remaining information: what is inspected, what success means, and how to interpret the problem/warning fields. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4. The description correctly spends no space on argument semantics and instead invests in output interpretation.

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 ('Check') plus three named resources it inspects: the credentials file, the SmartGym server, and the installed app version. It is immediately distinguishable from all siblings, which are routine/exercise mutation and listing 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?

Usage is implied by the tool's nature — a diagnostic check — and there is no sibling alternative to route away from, so no explicit exclusions are needed. However, the description never says when to call it (e.g. before first use, after auth failures, to troubleshoot), leaving timing 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 establish readOnlyHint=true and openWorldHint=true. The description adds the important behavioral detail that archived routines are excluded by default and only included when include_archived=true, which goes beyond the annotation data. It does not discuss pagination or ordering, but for a simple list tool this is a useful addition.

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 short and front-loaded, starting with what is listed and the returned fields. Each subsequent sentence handles archived behavior and usage guidance without redundancy. No sentence 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?

An output schema exists, so return-value structure need not be repeated. The description still covers the key input behavior and how to use the results downstream. It could be slightly more complete by explicitly contrasting with get_routine, but it is otherwise sufficient for this low-complexity 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 description coverage is 0%, so the description must compensate, and it does: it explains exactly how include_archived affects the result. The implied default (exclude archived unless true) aligns with the schema default of false. With only one parameter, this is nearly complete for invocation purposes.

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, 'List routines', and immediately enumerates the returned fields (id, name, days, exercise counts by section). This distinguishes it from sibling retrieval tools such as get_routine, which would fetch a single routine rather than a list.

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

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

It clearly explains the archived-routines condition: archived routines are listed only when include_archived=true. It also advises using the returned id or name in other tools, giving practical follow-up guidance. It does not explicitly compare against get_routine, but the usage context is nevertheless 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 declare destructiveHint=true and idempotentHint=false, so the mutation risk is already known. The description adds genuinely new behavioral information: dry_run defaults to true and sends NOTHING, which materially changes the safety profile of the default call. It does not clarify reversibility or auth requirements.

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

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

Two tight sentences with the primary action front-loaded, followed by the parameter clarifications. Every clause adds operational value and there is no filler.

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

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

An output schema exists, so return values need not be described. The description covers the key non-obvious behaviors for a 4-param mutation tool. It could note whether position is 0-indexed or what happens to the source section's ordering, but the essentials are 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?

With 0% schema description coverage, the description must carry the burden, and it does for three of four params: exercise_id provenance, position semantics (counted within target section, omitted = last), and dry_run behavior. Only 'section' is left to its enum values, which are self-explanatory.

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 (move) and resource (exercise), plus the two distinct scopes of the move: cross-section and intra-section repositioning. This cleanly separates it from siblings like smartgym_reorder_routine, smartgym_add_exercise, and smartgym_remove_exercise.

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 preconditions: exercise_id must come from smartgym_get_routine, and position counts within the target section with omission meaning 'last'. It stops short of naming when to prefer a sibling tool (e.g. reorder_routine vs this) or any when-not condition.

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 destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: logged history is retained (partial rather than full destruction) and dry_run defaults to true so nothing is sent unless explicitly overridden. It stops short of describing reversibility or permissions.

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

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

Three short clauses, front-loaded with the core action and the non-destructive caveat, then the parameter sourcing and the dry-run warning. 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 an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the key operational facts (history retention, dry-run default, ID provenance), leaving only minor gaps like error/permission behavior.

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 load, and it does: it names smartgym_get_routine as the source of exercise_id and explains that dry_run=true (the default) sends nothing. Both parameters get meaningful semantics beyond their bare types.

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 (Remove) and resource (exercise from its routine) with a scoping detail that logged history is preserved. It does not explicitly name a sibling alternative (e.g., archive_routines, move_exercise), so differentiation is implicit rather than 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?

The removal use case is clear from the verb, and the dry_run note tells the agent it must set dry_run=false to actually act. However, there is no explicit when-to-use/when-not guidance or reference to an alternative tool for related operations.

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 flag destructive/non-idempotent/open-world. The description adds real behavioral context on top: dry_run=true (the default) sends NOTHING, omitted sections are left untouched, and every list must contain exactly that section's current ids — an important precondition that prevents partial or invalid rewrites.

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

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

Three short sentences, front-loaded with the core action, then the constraint, then the dry-run safety note. No filler; every clause adds operational 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?

An output schema exists, so return formatting need not be described. With 5 params at 0% schema coverage and destructive annotations, the description covers the risky behavior and the id-list precondition well, though naming the section parameters explicitly would close the last gap.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it explains that the array parameters are per-section ordered id lists, constrains their contents, and defines the dry_run default and effect. It doesn't name main/warmup/cooldown explicitly or explain the routine identifier, so not fully compensating.

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 (reorder exercises within routine sections) and seeds the distinction from siblings by naming smartgym_move_exercise for section changes. It never explicitly ties 'sections' to the main/warmup/cooldown parameters, so the mapping requires a small inference.

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

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

Gives a clear when-to-use-this vs when-to-use-something-else: reorder here, use smartgym_move_exercise to change an exercise's section. It also explains that omitted sections stay unchanged and that dry_run defaults to true, but it doesn't state prerequisites like needing the routine to already exist or requiring the exact current ids to be known 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is partially covered. The description adds genuinely useful context that 'dry_run=true sends NOTHING', which matters a lot for a destructive tool — but it omits that dry_run defaults to true and says nothing about reversibility or failure modes.

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 very short sentences with the purpose front-loaded and zero padding. The 'dry_run=true sends NOTHING' phrasing is terse to the point of being slightly cryptic, but it is efficient.

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

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

An output schema exists, so return values need not be explained. However, for a destructive, non-idempotent operation whose dry_run flag defaults to true, the description should state the default and the effect of a real run; it does not.

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 parameter burden. It explains dry_run's effect ('sends NOTHING') but gives no meaning at all for the required 'routine' parameter (id? name? format?), leaving half the parameters 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 ('Bring an archived routine back to the active list') that is immediately distinguishable from the inverse sibling smartgym_archive_routines. The scope (archived -> active) is unambiguous.

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

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

Usage is implied by the state transition described, but there is no explicit when-to-use guidance, no prerequisite (e.g. routine must currently be archived), and no pointer to alternatives. Adequate but with clear gaps.

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 adds genuinely non-obvious behavior on top: `sets` is a full replacement list (extra sets added, unlisted sets removed), logged history is never touched, and dry_run=true sends nothing to the server. That is exactly the extra context an agent needs before a destructive call.

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 mutation scope, then the subtle set-replacement rule, then the safety valve (dry_run). Four tight lines with zero filler and inline code formatting for the key identifiers.

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

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

An output schema exists so return values need not be explained, and the description covers the destructive/replacement semantics and the dry-run safeguard. It would be fully complete with a note on exercise_id requirement or rest_seconds units, but nothing essential to a correct call 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?

Top-level schema description coverage is 0%, so the description must carry the load, and it does for three of five parameters: it defines the `sets` shape ([{reps, weight_kg}]) and its replace-all semantics, the note clearing convention ("" clears), and dry_run's default. exercise_id and rest_seconds are only obliquely covered via the wording 'rest time' and the required-id 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 (change) plus the exact mutable fields of a specific resource (an exercise's rest time, note, template sets), so the agent can distinguish it from sibling mutators like smartgym_update_routine or smartgym_move_exercise 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?

Usage is only implied: this is the tool for editing an existing exercise's template fields, and dry_run=true is flagged as the safe default. There is no explicit when-to-use vs. when-not guidance and no pointer to alternatives for other kinds of edits (e.g. reordering or moving exercises).

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 flag destructiveHint=true and idempotentHint=false, and the description adds genuinely new behavior: the two-phase dry-run default that previews old → new without sending, versus dry_run=false which snapshots, sends, and verifies server-side, plus the name-collision constraint.

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 edit scope, then grouped into the days format and the dry-run contract. Every sentence carries information; the only slight redundancy is repeating the weekday mapping already in the schema.

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

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

An output schema exists, so return values need no explanation, and the dry-run workflow is fully covered. The remaining gap is how the required `routine` argument is identified and how errors surface on a name collision.

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 17% (only `days` is documented), so the description must compensate. It does: it explains the 1=Sunday…7=Saturday numbering, the comma-separated format, the "" clear semantics, and the dry_run default/toggle. It still leaves the `routine` identifier format and name/goal/note semantics to inference.

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 (Edit) plus the resource (a routine) and enumerates the editable fields (name, days, goal, note), which cleanly separates it from siblings like smartgym_update_exercise or smartgym_reorder_routine.

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 operating context: only passed fields change, empty string clears, and dry_run=true is the default and sends nothing. It does not explicitly name sibling alternatives, but the field-scoped framing makes the boundary with update_exercise implicit and safe.

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