AI Design Blueprint

Official

Overview Schema Source Related Servers Discussions Admin

spec.validate

Review a written spec, proposal, or task plan against the 8 Spec Quality Laws before coding. Get per-law findings and a readiness grade that flags untestable requirements or irreversible steps as production blockers.

Instructions

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: sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial 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). The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. 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

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.2.1Sep 24, 2026

changedInput schema / properties / private_session / description

Previous value: -"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."New value: +"Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. Default false."

Addedv1.2.0Jul 24, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) are far exceeded by the description's operational disclosures: the 60-180s single-pass runtime, the client-timeout protocol (DO NOT RETRY; capture run_id from the first progress event and fetch via validation_history), persistence semantics via private_session, typed failure envelopes, auth/plan requirements, UK/EU residency and no-training data handling, prompt-injection inertness, and the calibration disclosure that the v1 scorer is not yet tuned. Every claim is actionable.

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 long but well-organized and front-loaded: purpose and sibling differentiation lead, followed by the timeout protocol, return semantics, when-to-call, inputs/auth/failures, and calibration. Some density could be trimmed — the GEP-M2 session detail substantially duplicates the schema's own explanation — but the operational complexity justifies the length overall.

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?

For a tool with 7 params, no enums, a rich output schema, and complex operational behavior, the description covers the full lifecycle: preconditions (auth/plan), invocation (verbatim spec input), failure handling (typed failures plus the timeout recovery flow), and result semantics (spec_classification, not_applicable routing, shared scoring rubric, readiness grade). The output schema covers return values, so the description correctly summarizes rather than repeats them.

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%, so the 3 baseline applies; the description then adds genuine value beyond the schema. It mandates sending implementation_context verbatim with no truncation or '…' placeholders, specifies how to concatenate OpenSpec change bundles, explains that repository groups runs under the 'spec' dimension, and ties the run_id recovery protocol to the persistence behavior controlled by private_session. The no-truncation warning is load-bearing and absent from the schema.

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 states precisely that the tool performs a first-pass specification-quality review of a WRITTEN SPEC against the 8 laws of the Spec Quality Blueprint, with an explicit three-way differentiation from siblings: architect.validate scores built agentic ARCHITECTURE, design.validate scores the rendered SURFACE, and spec.validate scores the written intent. Scope is unambiguous — the what-to-build lens applied before code exists.

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?

Contains explicit WHEN TO CALL and WHEN NOT TO CALL sections: call when the user wants a governance/quality review or readiness grade on a spec; do not call on built code or a rendered surface, which return tier=not_applicable. It also names the alternatives (architect.validate, design.validate) and routes non-spec inputs like source code or UI artefacts to the correct siblings.

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