propose_workout

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

With no annotations, the description carries full weight and delivers: NOTHING is written to Garmin, only a preview plus proposal id is returned, day defaults to today, impossible requests return a reason rather than a session, and targets derive from the athlete's Garmin zones with unmeasured items listed as assumptions. This is exceptional transparency for an unannotated tool.

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?

Every sentence earns its place: purpose, target source, usage triggers, kind definitions, default, return value, safety guarantee, and failure mode. The structure front-loads the core action and then layers behavioral context without redundancy. It is compact despite conveying a large amount of decision-relevant information.

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 6-parameter tool with an output schema, the description covers the full lifecycle (proposal, preview, apply, failure mode, zone assumptions, readiness swap). The only notable gap: both distance_km and duration_min are optional, and the description does not state what happens if neither is provided. This is minor but prevents a perfect score.

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 high at 83%, so baseline is 3. The description adds real value for the one undocumented parameter, kind, by defining easy/long, threshold (Z4 reps), vo2max (Z5 reps), and steady (>=12 min at threshold, the only shape Garmin measures VO2max from). It also clarifies the day default. This pushes it above baseline.

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 opens by naming a specific verb ('Build') and resource ('a structured session ... file it as a PROPOSAL'), and then situates it against the sibling workflow by saying nothing is written to Garmin and apply_workout is the follow-up. This strongly differentiates it from apply_workout, propose_week, and analyze_workout 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?

Gives explicit trigger conditions: 'Use when the athlete asks for a workout' with concrete examples, plus the readiness-verdict swap scenario. It also routes to apply_workout only after athlete approval. It does not explicitly say 'don't use this for weekly planning (propose_week)' or other exclusions, but the alternative is clearly identified.

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