create_structured_workout

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

Beyond the annotation readOnlyHint=false, the description explains that the tool creates a workout and can optionally schedule it on a COROS calendar date, which is important behavioral context for a state-changing tool. It does not go into detail about external synchronization, validation, or persistence, but the annotations already signal write 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?

Two compact sentences rapidly deliver the core purpose and the optional scheduling side effect. No filler or redundant details; high information density.

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 tool with nested arrays and 20% schema coverage, the description is decent but would benefit from a note that 'steps' is an ordered list of step objects or repeat groups, how targets are attached (e.g., intensityMin/intensityMax), and whether authentication is required. However, the high-level purpose is clear enough for an AI agent to select, if not fully specify, the correct payload.

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 only 20%, the description compensates by paraphrasing key enums: 'time/ms/distance/open steps' maps to targetType, 'HR/pace/power/cadence/speed targets' maps to intensityType, and 'repeat groups' maps to the nested repeat object. It does not fully describe step kinds or edge-case semantics, but it does add meaningful 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?

The description clearly identifies the action ('Create'), the exact resource ('a structured running or cycling workout'), and lists concrete features (time/distance/open steps, HR/pace/power/cadence/speed targets, repeat groups, optional scheduling). It is specific enough to distinguish from generic workout-creation tools, though it does not explicitly name sibling tools or contrast 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 implies usage context: creating structured run/bike workouts with optional scheduling. It gives no explicit when-to-use versus alternatives such as create_workout, assign_workout_to_calendar, or validate_structured_workout, and does not mention exclusions or prerequisites (e.g., prior authentication).

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