smartgym_update_exercise

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.