Skip to main content
Glama

AI Design Blueprint

by com.aidesignblueprint
OverviewDiscussionsAdmin

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: 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
NameRequiredDescriptionDefault
taskNoWhat this spec is for (e.g. 'the closed-beta apply flow rework'). Adds evaluation context.
filesNoFile paths relevant to the spec, for context.
goalsNoSpecific quality goals to weight (e.g. 'ready for an agent to build unattended', 'tight scope').
repositoryNoProject/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_idNoOptional 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_sessionNoSet 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_contextYesThe 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
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only carry a basic safety profile, so the description carries the full burden—and it delivers. It discloses long-running behavior (~60-180s), run_id emission and persistence, private_session effects, auth/plan requirements, UK/EU residency, transient OpenAI processing, prompt-injection treatment as inert data, typed failure envelopes, and calibration limitations. This is exemplary behavioral disclosure.

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 justifies its length with high information density; every block covers a distinct concern (scope, timeout, inputs, auth, failures, calibration). It front-loads the most decision-relevant information (what it reviews and how it differs from siblings). It loses a point for some repetition of schema-provided param details, but remains well-organized and readable.

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 parameters, an output schema, and complex operational behavior, the description covers every critical angle: when to call, when not to call, input preparation, timeout recovery, auth, data handling, failure typing, output semantics, and calibration caveats. An agent has everything needed to invoke this tool correctly.

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 baseline is 3, but the description adds operational meaning beyond the schema: full verbatim concatenation rules for implementation_context, repository grouping under the 'spec' dimension, session_id ownership checks, and private_session's persistence/recovery implications. There is slight redundancy with the schema, but the added context pushes it above baseline.

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 a specific verb and resource: it 'scores' a 'WRITTEN SPEC' against the 8 laws of the Spec Quality Blueprint. It explicitly differentiates itself from architect.validate (architecture) and design.validate (rendered surface), leaving no ambiguity about which sibling to choose.

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?

Usage guidance is explicit and thorough: 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections name exact conditions and alternatives (architect.validate/design.validate). It also provides critical operational guidance like 'ON CLIENT TIMEOUT — DO NOT RETRY' and how to recover via me.validation_history, which is far beyond minimal usage guidance.

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 toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources