AI Design Blueprint

Validate Specification Quality

spec.validate

Pro/Teams — first-pass specification-quality review of a WRITTEN SPEC (proposal, design doc, task breakdown, or an OpenSpec-style change bundle) against the 8 laws of the Spec Quality Blueprint. The what-to-build lens of the doctrine trio, applied BEFORE code exists: where architect.validate scores built agentic ARCHITECTURE and design.validate scores the rendered SURFACE, spec.validate scores the written intent the team will build from (outcome framing, scope boundary, testable acceptance, decision trail, handoff completeness, doctrine-upfront, task traceability, risk and reversibility). ON CLIENT TIMEOUT — DO NOT RETRY. Long-running LLM call (~60-180s at high reasoning effort, single-pass). The server mints a run_id, emits it in the FIRST progress event at t=0s (before the LLM call), and persists the run — so on a client timeout, capture that run_id and call me.validation_history(run_id='') to fetch the persisted result instead of retrying (a retry re-runs the full 60-180s call). Runs appear in your validation-history dashboard tagged as the 'spec' dimension, distinct from the 'architecture' and 'surface' runs; pass repository to group them per project. Pass private_session=true to skip the stored run (persistence + recovery disabled); operational security + cost logs are still kept. v1 is single-pass: no certification or consensus mode yet (those stay architect.validate-only). Returns spec_classification (spec_document vs non_spec — source code or UI artefacts are marked not_applicable, NOT failed; submit those to architect.validate or design.validate instead), per-law findings (verdict, severity_score 0-100, severity_class, cited evidence, recommendation), and severity-weighted readiness (score, grade, tier) computed by the SAME scorer the other two lenses use, so all three grade on one rubric. TESTABILITY IS THE FLOOR: a load-bearing requirement with no observable acceptance signal, or an irreversible step with no named human gate, is a production_blocker, not polish. WHEN TO CALL: the user wants a governance/quality review or a readiness grade on a spec they are about to build from (proposal, requirements, task plan). WHEN NOT TO CALL: built code or a rendered surface — those return tier=not_applicable; use the sibling validators instead. INPUTS: send the FULL spec text verbatim as implementation_context (for an OpenSpec change, concatenate proposal.md + design.md + tasks.md + delta specs; no truncation, no '…' placeholders — they are read as literal content). Auth: Bearer , Pro/Teams plan. UK/EU residency; transient OpenAI processing (no-training); prompt-injection text inside the spec is treated as inert untrusted data. TYPED FAILURES: same as architect.validate (timed_out, rate_limited, dependency_unavailable, schema_mismatch — each carries retryable + next_action); the services raise the identical typed envelopes on this lens. CALIBRATION DISCLOSURE: the scoring prompt is a v1 first-cut mirroring the architect's contract structure; its score calibration is not yet tuned against a corpus of real runs the way architect.validate was. Treat the grade as directional quality signal, not a certified verdict. DOCTRINE: the eight laws — each law's definition, rationale, anti-patterns, and the validator questions this tool scores against — live in content/spec-quality-laws.json (the what-to-build companion to the experience-design laws).

Input Schema

TableJSON Schema

Name	Required	Description
`task`	No	What this spec is for (e.g. 'the closed-beta apply flow rework'). Adds evaluation context.
`files`	No	File paths relevant to the spec, for context.
`goals`	No	Specific quality goals to weight (e.g. 'ready for an agent to build unattended', 'tight scope').
`repository`	No	Project/repository key. Groups this run with prior spec.validate runs on the same project in your validation-history dashboard (the same grouping the other lenses use), under the 'spec' dimension.
`session_id`	No	Optional Governed Session to attach this run to (GEP-M2). Must reference a session YOU own (list via me.sessions; sessions are created in the web app at /app/sessions) — foreign ids are refused before any model call. The run then appears on the session's timeline alongside the other lenses. With private_session=true no run is stored so nothing attaches, but the ownership check still runs FIRST: a session id you don't own fails the call either way.
`private_session`	No	Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). Default false.
`implementation_context`	Yes	The specification under review. SEND FULL TEXT VERBATIM — the reviewer cites specific requirements, decisions, and tasks; any compression destroys evidence and produces findings on content that isn't there. For an OpenSpec change, concatenate proposal.md + design.md + tasks.md + delta specs. Do NOT truncate; if very large, split into MULTIPLE calls scoped by document.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A4.8/5.0

Behavior5/5

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

Far exceeds annotation coverage: discloses long-running behavior (60-180s), timeout recovery protocol, persistence and private_session semantics, single-pass limitation, output classification behavior (non_spec → not_applicable), calibration caveat, auth/residency requirements, and prompt-injection treatment. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long, but every major section (purpose, timeout recovery, when-to-call, input requirements, caveats) serves a distinct and critical purpose for a high-risk, long-running tool. It is dense and information-rich, though not optimally scannable—a few headings or bullet points would improve access. It earns a 4 for being appropriately sized for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description provides comprehensive coverage: it explains what the tool returns (spec_classification, findings, readiness score), identifies failure modes with retry semantics, and provides doctrine references. Together with the schema and annotations, an agent has all context needed to select and invoke the tool correctly, handle timeouts, and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, setting a baseline of 3. The description adds crucial context on implementation_context: 'send the FULL text verbatim,' no truncation, and splitting large inputs into multiple calls. It also clarifies repository grouping and private_session behavior. This extra guidance pushes the score above baseline, though not every parameter gets equivalent treatment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific function: 'first-pass specification-quality review of a WRITTEN SPEC' against the '8 laws of the Spec Quality Blueprint.' It distinguishes itself from siblings by explicitly contrasting with architect.validate (architecture) and design.validate (surface), making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'WHEN TO CALL' if the user wants a governance/quality review on a spec; 'WHEN NOT TO CALL' for built code or rendered surfaces, directing to sibling validators. Also explains how to handle timeouts (do not retry, use me.validation_history) and provides a concrete example of when to use this tool over alternatives.

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

All AI Design Blueprint tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose within its domain: the validators are differentiated by lens (architect/design/spec), content tools are split by entity (principles/clusters/guides/examples/assets) with list/get/search variants, and even the me.* and handoffs.* tools have non-overlapping functions. The only near-overlap (architect.validate vs architect.validate_consensus) is explicitly disambiguated by the consensus variant's description.

Naming Consistency4/5

Tool names consistently use a domain prefix (architect., principles., me., etc.) and snake_case throughout. While most are action-oriented (validate, list, get, search, add, await, report, summarize), some me.* and handoffs.* names are noun phrases (me.learning_path, handoffs.agency) that don't signal the action as clearly, creating minor deviation from a pure verb_noun or action pattern.

Tool Count3/5

At 29 tools, the set is heavy but justified by the server's broad multi-domain scope (doctrine, validation, learning, support, and team analytics). Each tool has a distinct role, but the number exceeds the typical well-scoped range, and some content types (e.g., examples) could have been consolidated without losing function.

Completeness4/5

The server covers its apparent domains thoroughly: doctrine content has list/get/search for most entity types, validation covers architecture/design/spec with consensus and certification, and user learning/support have appropriate tools. Minor gaps exist—e.g., examples have no list-all endpoint, and session management is web-only—but none are blocking for core workflows.

Resources

Need Help?