validate_spec

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses behavior: what kinds of problems are detected, that unknown keys are reported as warnings, and that the tool returns valid/errors/warnings plus a summary. This goes well beyond minimal coverage.

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 with a one-sentence purpose, followed by a focused list of concrete error categories and a clear statement of return values. Every sentence adds value; there is no fluff or redundancy.

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?

Given the tool's complexity and the sparse input schema, the description is remarkably complete. It explains the return shape, enumerates specific validation checks, and notes the warning behavior for unknown keys. The presence of an output schema also helps, but the description alone provides enough context for effective use.

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 schema only defines 'spec' as an object with additionalProperties, providing no semantic detail. The description compensates by enumerating the kinds of content in the spec (durations, power, FTP, ramps, repeats, unit forms) and explaining how certain values are interpreted. It does not provide a full structural breakdown, but the added context is substantial.

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 with a specific verb+resource: 'Check a workout spec and report every problem found.' It clearly distinguishes validation from sibling tools like describe_spec or render_zwo by focusing on error detection rather than description or rendering.

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 clearly implies when to use the tool: before relying on a spec, to catch mistakes that would cause problems downstream. It does not explicitly name alternatives or state when not to use it, but the context and error-focused language make the intended usage clear.

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