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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds value beyond this by detailing the response structure (errors + warnings with location and message), which accurately sets expectations about multi-finding validation results rather than a simple pass/fail. No contradiction exists between the 'WITHOUT creating' phrasing and the readOnlyHint annotation. Minor deduction because the description doesn't mention scaling, rate-limit, or size constraints on the spec being validated, which could matter for very large drafts.

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 sentences achieve complete clarity with zero wasted words. The first sentence front-loads the core behavior and return type; the second provides the usage loop (validate → fix → re-validate → commit). Every clause in the description contributes distinct information: behavior, return shape, workflow, and the alternative tool. This is an exemplary balance of brevity and informativeness.

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 tool has an output schema, so the description appropriately avoids re-explaining return types, focusing instead on the validation workflow context. Given the annotations cover the safety profile (read-only, idempotent) and the output schema covers the response shape, the description ties everything together with the draft-iteration use case. Small gap: it doesn't hint at performance expectations for large specs or note edge cases like validation timeouts, but these are niche concerns for a validation utility.

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 description coverage is 100%, so with a single 'spec' parameter documented as 'The ModelSpec to validate', the schema carries all the weight. The description itself adds no parameter-level guidance about what constitutes a valid ModelSpec or how deeply it validates (e.g., does it validate nested tests/effects/constraints?). Per calibration, when schema coverage is high the baseline is 3, and the description doesn't need to restate parameter structure — though it could have added insight on validation semantics without bloating the text.

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 and resource ('Validate a ModelSpec') and immediately differentiates the tool from its sibling create_model with the emphatic 'WITHOUT creating it'. It then specifies the exact return shape (a 'valid' flag plus structured findings with location and message), leaving zero ambiguity about what the tool does. The contrast with create_model makes the resource scope unmistakable.

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 second sentence explicitly frames the intended workflow: 'Use this to iterate on a draft — fix the reported errors, re-validate — before committing with create_model.' This gives the model a clear when-to-use instruction and names the main alternative tool (create_model). It loses a point because it doesn't discuss related non-mutating siblings like dry_run, test_spec, or evolve_spec where the boundary is less obvious, and there's no explicit 'when not to use' statement.

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