preview_workout

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: it produces output but publishes nothing, so there are no side effects. It also characterizes the return value as the exact payload HoodaRun would receive. It omits validation/error behavior and whether the spec is checked against constraints before compilation.

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?

One sentence, front-loaded with the action and the return value, ending with the key safety clause. There is no filler and nothing that could be cut without losing meaning.

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?

The description covers the output concept (WorkoutKit-shaped JSON), which partly compensates for the absent output schema. But for a tool whose only parameter is an opaque nested object, leaving the spec structure entirely undocumented leaves a critical gap in an otherwise self-contained definition.

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?

The single `spec` parameter is a free-form object with additionalProperties:true and 0% schema description coverage, and the description adds nothing about its expected fields, nesting, or required keys. An agent is told it may be a 'workout or strength spec' but must guess the entire structure, which is the tool's core input.

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 uses a specific verb ('Compile') and names the resource ('a workout or strength spec') plus the concrete return form ('exact WorkoutKit-shaped JSON'). It implicitly covers both create_workout and create_strength_workout by accepting 'workout or strength spec', but it never names those siblings, so differentiation is by inference rather than explicit routing.

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?

'without publishing anything' implies a dry-run use case, letting an agent infer it should preview before calling create_workout or create_strength_workout. However, the description never states that context explicitly, nor does it give any when-not condition (e.g., skip preview for trivial specs).

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