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

Goes far beyond the annotations: discloses the 60–180s LLM latency, a strict no-retry policy with a run_id recovery path via me.validation_history, persistence/dashboard tagging, private_session side effects, plan/auth requirements, UK data residency with US provider processing, and typed failure codes. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with the described persistence writes (mints run_id, stores a run) and there is no contradiction.

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 opening sentence front-loads purpose well, but the body is a dense wall of all-caps fragments with repeated content — the 60–180s duration appears three times, the no-retry warning is restated, and the verbatim/no-truncation rule is duplicated between the prose and the schema. Almost everything is substantive, but it is not structured for skimming and several sentences could be consolidated.

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 long-running LLM-backed validator with 7 params and an output schema, the definition covers everything an agent needs: latency, timeout recovery, auth/plan gating, failure codes, classification behavior (not_applicable vs failed), return shape, and where the underlying doctrine lives. The calibration disclosure (v1, untuned, directional grade) appropriately tempers reliance on the output.

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 100%, so the baseline is 3; the description still adds operational meaning — that implementation_context must be verbatim with no truncation because compression destroys citable evidence, that huge specs should be split into multiple scoped calls, and that repository groups runs under the 'spec' dimension. It also clarifies the private_session tradeoff (skips persistence and run_id recovery but ownership checks still run), which changes parameter choice rather than merely restating the schema.

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?

States a specific verb+resource (first-pass specification-quality review of a WRITTEN SPEC) and enumerates what it scores (outcome framing, scope boundary, testable acceptance, etc.). It explicitly positions itself in a 'doctrine trio', naming architect.validate (built architecture) and design.validate (rendered surface) as the lenses it is NOT, so an agent can disambiguate without opening schemas.

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?

Contains explicit WHEN TO CALL (user wants a governance/quality review or readiness grade on a spec about to be built from) and WHEN NOT TO CALL (built code or rendered surface → tier=not_applicable, use sibling validators). It also gives a concrete input-shaping rule (concatenate proposal.md + design.md + tasks.md + delta specs) that determines correct invocation.

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