delete_workout

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

No annotations are provided, so the description carries the full burden, and it delivers. It discloses that the preview call 'deletes nothing', that the operation is a WRITE and irreversible, and the cross-cutting side effect 'Deleting from the library also removes the workout from the watch on its next sync.' The dev-only semantics of the confirm flag are also surfaced. This is exactly the critical behavioral disclosure a delete operation 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?

The description is front-loaded with the single most important fact (WRITE, irreversible), followed by a tight narrative of the handshake, then the side effect, then the constraint. The three-sentence body is efficient and every clause earns its place. It drops to a 4 only because the closing Args block makes the whole thing slightly longer than the leanest possible version, though the zero schema coverage justifies that 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 mutation with a destructive edge, the description covers the safety mechanism (token handshake), the failure mode it prevents (accidental deletion without review), the side effect on the watch sync, and the environment constraint (dev/stdio only). An output schema exists, so return values don't need documenting. There is no material gap in state, effects, or prerequisites.

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. The Args section maps each parameter to its origin: 'workout_id' from list_workouts, 'confirmation_token' from the preview call bound to 'this same id', and 'confirm' qualified as a dev/stdio-only flag. This adds meaning well beyond the bare schema and prevents the classic bug of the agent passing a token as a workout_id.

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

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

Opens with a specific verb+resource+scope: 'Delete ONE workout from your Garmin Connect library (a WRITE, irreversible).' The qualifier 'ONE' combined with 'no bulk delete' directly distinguishes it from any batch-style sibling and from the schedule/unschedule pair. The irreversibility cue adds important grading context in the first sentence.

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 clearly explains the two-call preview-then-confirm protocol, when the token is needed, and the 'no bulk delete' constraint that tells the agent it must loop. It explicitly cautions 'confirm each workout individually.' However, it never explicitly contrasts with the sibling unschedule_workout, so the 4 reflects 'clear context, no named alternative'.

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