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

Beyond the annotations (non-read-only, idempotent, non-destructive) it discloses the crucial behavioral truth: nothing is delivered to the Watch, first delivery requires a manual permission grant in the iPhone app, later auto-delivery is opt-in and opportunistic. It also warns that device capability validation can reject activities/goals/alerts before scheduling and forbids claiming the Watch received the plan.

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?

It is dense and front-loaded with the most important fact (pending plan, not delivered) in the second clause, and most sentences carry unique constraints. It runs long as a single unbroken paragraph and repeats the pool_length_m display-only point that also appears in the schema, costing some concision.

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 deeply nested workout-definition tool with an output schema and full safety annotations, it covers the operational facts an agent needs: delivery model, permission flow, validation failure and retry semantics, platform requirement (watchOS 11+ for pool custom workouts), and where to verify outcomes.

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 only 67%, and the description fills the gap with meaning the schema cannot express: units are seconds/meters, scheduled_at must carry an explicit local UTC offset, step names describing reps/weights are instructions rather than native repetition goals, pool swimming must use activity=swimming with location=indoor, and pool_length_m is display-only because WorkoutKit has no setter. It also explains that pool_distance_with_time advances only when BOTH distance and time are satisfied.

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?

"Create one structured workout requested by the user, scheduled within the next 7 days" states a specific verb, resource and scope. It immediately distinguishes this from delivery/inspection siblings by saying it stores a pending plan rather than starting anything on the Watch, and it explicitly points to workout_plans for checking results.

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?

It states the triggering condition (user-requested workout, within 7 days), the alternative for verification (read workout_plans), how to handle rejection (retry with the SAME idempotency_key and payload), and the fallback path when background scheduling does not fire (review each plan manually).

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