create_garmin_workout

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

Annotations carry only a title (no readOnly/destructive/idempotence hints), so the description bears the full behavioral burden. It discloses the return payload (workoutId and a Connect link) and a distinctive error mode (re-auth message rather than an exception for missing sessions). It does not cover idempotency or name-uniqueness behavior, but for a create action the mutating side effect is self-evident.

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: purpose, then routing, then return value, then error behavior, then example. Every sentence earns its place and there is no filler. The example makes it moderately long, but that length is justified by the nested complexity of the steps parameter.

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 supplies return values and auth-failure behavior, and the schema covers all parameters at 100%. The only notable gap is not pointing the agent to the authenticate_garmin sibling when the re-auth message is received; otherwise the definition is complete for a complex, write-side tool with minimal annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema through a concrete step/repeat-block example and a summarizing list of target types, which materially helps an agent construct the deeply nested 'steps' parameter correctly.

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 verb and resource ('Create a new structured workout in Garmin Connect') and enumerates the content scope: durations, pace/HR/power/cadence targets, repeat blocks, and swim-specific fields. It explicitly names the sibling it is not, update_garmin_workout, so an agent can route correctly without inspecting 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?

'Use to add a workout; to change one that exists, use update_garmin_workout instead' is explicit when-to-use and when-not-to-use with a named alternative. The create-vs-update decision is the key routing ambiguity among the siblings, and it is resolved directly.

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