AI Design Blueprint

Server Details

AI Design Blueprint is a doctrine and runtime standard for agentic AI: 10 principles, 16 laws, and Pro/Teams validators your coding agent calls over MCP.

Ownership verified

Status: Healthy
Uptime: 99.4% over 39 days
Last Tested: 2026-09-25 08:26
Transport: Streamable HTTP · MCP 2025-11-25
URL

TDQS

A4.2/5.0

Scored 2026-09-24 18:46 across 29 tools

Disambiguation4/5

Tools are largely distinct, with clear separation between content retrieval (principles, clusters, guides, examples), validation lenses (architect, design, spec), and side-effecting handoffs. Some ambiguity exists between the me.* session tools (me.sessions, me.session_event, me.await_steer) and between the search variants (principles.search vs guides.search vs examples.search), but the descriptions mitigate most confusion.

Naming Consistency3/5

Naming is a mixed bag: content tools follow a consistent verb_noun pattern (principles.list, guides.search, examples.get), but other namespaces vary arbitrarily — me.await_steer vs me.session_event vs me.validation_history mix verbs and nouns, handoffs use noun suffixes, and architect.certify has no explicit object. The dotted namespaces impose order, but the internal verb styles are inconsistent.

Tool Count2/5

At 29 tools this server exceeds the well-scoped band, even accounting for its wide scope. It bundles several distinct concerns — doctrine retrieval, three validation lenses, session management, learning progress, handoffs, and telemetry — into one surface, which would strain an agent's tool selection and client payload size. The count feels like several smaller servers merged together.

Completeness4/5

The core lifecycle is well covered: validate → consensus → certify → history across all three lenses, with session grouping and evidence tracking. Notable gaps include no tool to cancel or delete a validation run, no way to publish/unpublish a run despite public_review URLs being mentioned, and no create/update/delete for sessions — leaving a few dead ends around the persistence model.

Available Tools

29 tools

architect.certifyCertify Production-Ready ArchitectureAInspect

Pro/Teams — second-pass adversarial certification of an architect.validate run that scored production_ready (A or B first-pass tier). ON CLIENT TIMEOUT — DO NOT RETRY THIS TOOL. RECOVERY FIRST: the run_id is emitted in the FIRST notifications/progress event at t=0s (BEFORE the LLM call begins). Capture it. On timeout, call me.validation_history(run_id='<that-id>') to fetch the persisted cert verdict; the server-side run completes independently within a 6-minute budget. This is the canonical recovery path. Use it before considering any retry. Long-running LLM call (60-180s typical; exceeds Claude Code's ~60s idle budget); MCP clients commonly close the call before the server returns. Retrying re-runs the LLM call AND burns one of your 3 cert retry-budget attempts. Mints the certified production_ready badge when both reviewers sign off; caps the run to C/emerging when the second pass surfaces a missed production_blocker. MANDATORY DOCTRINE RULE (load-bearing): the badge certifies the EXACT code that produced the validate run_id, NOT 'this codebase' in general. If you modify, fix, or iterate the code between architect.validate and architect.certify — even a single character — cert rejects with code_fingerprint_mismatch. Fixing the code voids the run. The recovery path is always: edit code → architect.validate → fresh run_id → architect.certify on the fresh run. Do NOT cert from a stale run_id after iteration; ask the user to re-validate first. WHEN TO CALL: only after architect.validate returned tier=production_ready AND the user wants the certified badge AND the code has not been touched since the validate run. NOT for tier=draft/emerging/not_applicable runs (typed rejections fire — see below). NOT idempotent across attempts: each call is one of the 3 attempts in the retry budget. BEHAVIOR: atomic one-shot single LLM call, ~60-180s server-side at high reasoning effort (small payloads finish faster; observed p99 ~250s; server-side budget is 6 min, above the observed range). Exceeds typical MCP-client tool-call idle budget (~60s in Claude Code), so the FIRST notifications/progress event fires at t=0 carrying the run_id. The run is atomic by contract — no in_progress lifecycle, no cancellation, no resume. Updates the persisted run's result_json (public review URL + me.validation_history(run_id=...) reflect the cert outcome). ELIGIBILITY GATE (typed rejection enum on failure): caller must own the run, tier=production_ready, less than 24h old, not already certified, within cert retry budget (max 3 attempts), no other cert call in flight for the same run_id, code fingerprint must match the validated code, AND the submitted payload must be cert-payload-complete (see Payload Completeness below — cert rejects pre-LLM with payload_incomplete when an imported module's surface isn't visible in the validate payload that produced this run_id). Rejection reasons (typed Literal): auth_required, paid_plan_required, run_not_found, not_run_owner, not_eligible_tier, not_agentic_component (tier=not_applicable runs), already_certified, certification_age_exceeded, retry_budget_exhausted, code_fingerprint_mismatch, code_fingerprint_missing, code_not_on_file (caller omitted code argument AND the 24h cert-retry hold for this run has expired or was never written. Recovery: re-run architect.certify from the same MCP session that ran architect.validate, passing the code explicitly — the server never persists code by design), payload_incomplete (submitted/validated payload imports modules whose contents aren't visible — cert refuses pre-LLM to prevent a false-precision downgrade. Recovery: re-validate with verbatim public-surface stubs for every imported module, then re-cert on the fresh run_id. Empirically validated: PR #157 iter8/iter9 cert rejections were exactly this class — code on disk was correct, the submitted payload merely omitted module visibility), cert_consensus_score_below_threshold (consensus_median<75 — consensus runs only), cert_consensus_unstable_blocker (any principle mode_stability<80% — consensus runs only), run_state_corrupt, cert_persistence_failed, cert_in_flight (a prior architect.certify call on this run_id is still running. Poll me.validation_history for the verdict; do not retry until it resolves). PAYLOAD COMPLETENESS (load-bearing for cert eligibility): the cert reviewer reads the EXACT payload that produced the validate run_id. Imported modules whose surface isn't present in the payload cause pre-LLM payload_incomplete refusal. Avoidance — when validating with intent to cert, bundle public-surface stubs for every imported module: from sqlalchemy.exc import SQLAlchemyError → include a stub class; from app.db import models → include a class models: namespace stub with the columns/methods you reference; module-level imports of dataclass, Literal, json, datetime, timezone MUST also be in the payload (cert correctly catches when they're omitted — code would NameError on import). 'Submit Like Production': the payload should be the code as it would actually run, not a compressed sketch. The stubs cover IMPORTED dependencies only; the certified code's own enforcement branches (approval gates, policy checks, recovery paths) must be present in full. A # ... placeholder reads as an ABSENT control and is graded against you, not as shorthand for one that exists. PRE-LLM REJECTION AUDIT TRAIL: when cert rejects before the LLM call (payload_incomplete, code_fingerprint_mismatch, etc.), certification_attempts=[] on the response — no attempt landed in the retry budget, no LLM hop occurred. The rejection envelope's rejection_reason + guidance are the actionable surface. (Audit-trail UI surfacing of pre-LLM rejections is tracked in the platform self-audit set as anomaly #5; out of scope for the cert tool itself.) INPUTS: re-send the SAME code that produced the run_id (the architect persists findings + recommendations, never code, by design — privacy-preserving). Server compares the submitted code's SHA-256 fingerprint to the stored fingerprint and rejects mismatches. Auth: Bearer , Pro or Teams plan required. UK/EU data residency (Cloud Run europe-west2). Code processed transiently by OpenAI (no-training-on-API-data) and dropped; payloads JSON-escaped + delimited as inert untrusted data — prompt-injection inside code is ignored. If the cert call fails outright (provider error, persistence error), a fresh architect.certify is the recovery path; the eligibility gate enforces the 3-attempt retry budget. For long-running cert workflows the answer is to re-validate, not to make this tool stateful. OUTCOMES: certification_status ∈ {confirmed_production_ready (badge mints), downgraded_to_emerging (cert review surfaced a missed production_blocker, tier capped at C/emerging), unavailable_provider_error (LLM call failed, retry within budget)}. Cert findings + summary + attempt history surfaced on the persisted run for full inspectability.

ParametersJSON Schema

Name	Required	Description	Default
`code`	No	The same code that was sent to architect.validate to produce this run_id. Sent verbatim — the cert reviewer needs the actual code to surface production_blockers the first pass missed. May be omitted (empty string) when the prior validate stored the code under the 24h cert-retry hold; in that case the server reuses the stored code automatically. Sent under the same enterprise-safety envelope as architect.validate (transient processing, no training, JSON-escaped + delimited).
`run_id`	Yes	The run_id from a prior architect.validate call. Returned in the validate response when persistence_status='saved'. Must be owned by the caller (per-user authorisation, same gate as me.validation_history).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

Annotations indicate readOnly=false, idempotent=false, destructive=false, but the description goes far beyond: it details non-idempotency, side effects (badge mintage, run persistence), potential rejections, retry budget, long execution time with idle-timeout risk, and recovery processes. 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 extremely dense and content-rich, but it runs as a large block of text. Every sentence provides critical operational information (retry budget, risks, rejection reasons), but formatting improvements like headings and bullet lists would enhance scannability. Despite length, no redundancy is present.

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?

The description covers the complete call context: prerequisites, side effects (badge mint, persisted state change), non-idempotency, timeout behavior, payload requirements, rejection reasons with recovery options, and the retry budget. Nothing an agent needs to know before invoking is missing.

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

Parameters5/5

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

Even though the schema has 100% coverage, the description adds crucial semantics beyond basic types: run_id must be persisted from a prior validate, code is optional only if a 24-hour hold applies, and the payload must exactly match the one used for validation. It also explains the implications of omitting code, which is not obvious 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 title and description make the tool's purpose explicit: certifying a previously validated architect run as production-ready. It clearly distinguishes itself from sibling tools by referencing architect.validate as its input and by specifying it is not for other tiers.

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?

The description provides a dedicated 'WHEN TO CALL' section stating it must be used only after architect.validate returns tier=production_readyats and when the user wants the badge Apa it lists explicit exclusions (draft/emerging tiers). It also warns about the retry budget and the need for fresh code, so the agent knows exactly when to invoke this tool.

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

architect.validateValidate Agent ArchitectureAInspect

Pro/Teams — first-pass doctrine review of agentic code/workflow against the 10-principle AI Design Blueprint doctrine. ON CLIENT TIMEOUT — DO NOT RETRY THIS TOOL. Long-running LLM call (60-180s typical); MCP clients commonly close the call before the server returns. Retrying re-runs the 60-180s LLM call from scratch and burns compute. RECOVERY: the run_id is emitted in the FIRST notifications/progress event at t=0s (before the LLM call begins) — capture it. On timeout, call me.validation_history(run_id='<that-id>') to fetch the persisted result; the server-side run completes independently within a 6-minute budget. Edge case: if the transport dropped before the first progress notification (very rare; sub-second window), call me.validation_history(repository='<same value you passed here>') to find your most recent run. TASK-AUGMENTED INVOCATION (MCP 2025-11-25, SEP-1686): clients that advertise the tasks capability can task-augment this call by including task: {ttl: <ms>} inside the JSON-RPC request's params (NOT as a tool argument; alongside arguments, _meta, etc.). The server returns a CreateTaskResult immediately (taskId equals the run_id above) and runs the validation in the background. Spec-correct long-running pattern: poll via tasks/get for state, fetch the terminal payload via tasks/result, listen for notifications/tasks/status for push updates, and cancel via tasks/cancel. _meta.progressToken from the original request stays valid for the entire task lifetime. Sync (non-augmented) calls behave exactly as before, backwards-compatible by construction. The me.validation_history(run_id=...) recovery path remains the canonical recovery handle for clients that don't yet advertise the tasks capability. Returns code_classification (autonomous_agentic_workflow vs non_agentic_component), per-principle findings (verdict, severity_score 0-100, severity_class, code-cited evidence, recommendation), severity-weighted readiness (score|null, grade|null, tier ∈ {production_ready, emerging, draft, not_applicable}), recommended examples, reproducibility envelope (model, seed, doctrine_fingerprint, prompt_template_fingerprint), persistence_status with shareable run_id/badge_url/review_url. Those two URLs 404 until the run's owner publishes it: runs are private by default. Read public_review in the response before embedding either one. WHEN TO CALL: the user wants a governance audit, readiness score, or production_ready badge on an agent/workflow they just built or changed. WHEN NOT TO CALL: non-agentic plumbing (math utilities, type aliases, event-loop helpers, single-shot request/response handlers) returns tier=not_applicable with score=null/grade=null — that's not a failure, the doctrine simply doesn't grade non-agentic code, and architect.certify will refuse with not_agentic_component. Submit the OWNING agentic workflow instead. BEHAVIOR: long-running LLM call (~60-180s typical at high reasoning effort, single-pass; server-side budget 6 min). Mints run_id at t=0; first notifications/progress event carries run_id as recovery handle; keepalive every 30s. Persists ValidationRun + UserValidationRun + AIValidationRunLog + LLMUsageLog atomically; on rollback, badge/review URLs are stripped. 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 in code is inert. INPUTS: send FULL file contents verbatim as implementation_context (NO truncation, NO ... placeholders, NO comment removal — the architect treats your ... as literal code and hallucinates bugs that don't exist). If too large, split into MULTIPLE calls scoped by file/module; never truncate one call. Pass repository="" to group runs into a project trend. Pass private_session=true to skip the stored run (persistence + recovery disabled); operational security + cost logs are still kept. focus_area narrows scope; unmatched focus_area fails explicitly rather than silently widening. PAYLOAD COMPLETENESS (load-bearing if you intend to architect.certify this run): the validate first-pass is permissive — it scores on doctrine alignment + structural patterns visible in the submitted code. Cert's adversarial second-pass is rigorous — it scores on cert-payload-completeness as well as code correctness. A run that scores 100/A at validate can cert-reject pre-LLM with payload_incomplete when imported modules' surfaces aren't visible. To validate with INTENT TO CERT, also bundle verbatim public-surface stubs for every imported module: from sqlalchemy.exc import SQLAlchemyError → include a stub class; from app.db import models → include a class models: namespace stub with the columns/methods the code references; module-level imports of dataclass, Literal, json, datetime, timezone MUST also be in the payload (cert correctly catches when they're omitted — the module would NameError on import as submitted). 'Submit Like Production': the payload should be the code as it would actually run. TWO COMPLETENESS AXES. (1) IMPORTS: stub the public surface of every dependency (above). (2) ENFORCEMENT BRANCHES: the code under cert itself (approval gates, policy checks, recovery paths) must be the REAL logic, fully written. A placeholder body (# ... execute approved action ..., pass # TODO, a bare ...) is graded as a MISSING control, not shorthand; cert scores what would actually run. Never sketch the agent you are certifying. Empirically reconfirmed PR #157 iter8 → iter9 cert downgrades. SCORE VARIANCE DISCLOSURE (anomaly #10 — empirically documented): validate scores are POINT ESTIMATES with an observed empirical variance band of ~20-67 pts on BYTE-IDENTICAL input. Runs against the same repository, same code, same deterministic seed (the seed is derived from input — same input → same seed) can produce materially different scores AND different top-blocker rankings, because OpenAI's reasoning models at reasoning_effort=high are not strictly deterministic even with the seed parameter pinned. The reproducibility_mode='best_effort' field on every response is the platform's honest disclosure of this property. For decisions where stability matters more than speed, call architect.validate_consensus (N=3-5 aggregated, median verdict + per-principle stability metrics) instead — collapses the variance, surfaces unstable principles explicitly. A single validate run is a single roll; consensus is the right tool when one score isn't enough. ITERATION LOOP — repository keying. Pass the SAME repository value across calls to chain iteration rounds; the validator auto-resolves the most recent prior run on (user, repository, scope) as prior_run_baseline and the LLM grades the new submission with iteration context (per-principle severity deltas surface in the response). Changing the repository string between calls — even subtly with an iter-2 suffix — silently severs the chain and yields a fresh blind first-shot. Round numbering belongs in task or commit messages, never in repository. See the architect-validation-orchestration skill in the agent-asset pack for the full validate → consensus → certify sequence. VERIFICATION LAYERS (the two-layer doctrine this platform practices on itself): validate verifies DOCTRINE ALIGNMENT against the 10-principle Blueprint — design patterns, hand-off explicitness, operational-state inspectability, race/blocker handling at the architectural level. validate does NOT guarantee runtime correctness. cert verifies PAYLOAD COMPLETENESS and runs an adversarial second pass over the submitted code — catches production_blockers the first pass missed, name-errors on import, missing module surfaces, etc. cert does NOT verify runtime correctness either. Passing validate is a NECESSARY condition for production_ready, not a sufficient one. Runtime correctness (does this actually execute and behave?) is verified at the THIRD layer — your tests, types, walks. The platform's own recursive-integrity practice: every PR runs validate against its own primitives, then cert. Real bugs surfaced via this practice in PR #157 — NULL-UUID false-positive (iter3) and tie-breaker mismatch (iter5) — that 25 unit tests had missed. Two-layer verification is the discipline, not 'either/or'. TYPED FAILURES: timed_out, rate_limited, dependency_unavailable, schema_mismatch (each carries retryable + next_action). NEXT STEP: if tier=production_ready (A or B grade), the response carries certification_status='not_evaluated' — call architect.certify(run_id, code) to mint the certified production_ready badge (separate ~60-150s adversarial review, eligibility-gated). See Payload Completeness above for the common pre-cert pitfall.

ParametersJSON Schema

Name	Required	Description
`task`	No	What the agent or workflow is trying to accomplish. Adds evaluation context.
`files`	No	List of file paths relevant to the implementation context.
`goals`	No	Specific safety or quality goals to evaluate against (e.g. 'prevent irreversible actions', 'explicit approvals').
`language`	No	Programming language of the code being evaluated (e.g. 'python', 'typescript').
`focus_area`	No	Narrow the evaluation to a specific principle cluster or slug (e.g. 'delegation', 'visibility', 'establish-trust-through-inspectability').
`repository`	No	Iteration key. SAME value across calls auto-resolves the most recent prior run as `prior_run_baseline` for iteration-aware grading (per-principle severity deltas, regressions/improvements). CHANGING the value (even subtly with an `iter-2` suffix) silently severs the chain and yields a fresh blind first-shot. Round numbering belongs in `task`, not here. Empirical evidence of why anchoring matters: PR #157 iter1 33/F vs iter2 100/A on byte-identical baseline-race primitives (+67 spread); invoice-payment-manager #158 38/F vs #159 74/C (+36 spread) — same code, score variance from non-deterministic LLM at reasoning_effort=high; the baseline anchor collapses this onto a stable arc.
`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.
`example_limit`	No	Maximum number of curated examples to include in recommendations.
`private_session`	No	Set to true to skip the stored run AND prior-run anchoring AND run_id recovery for this call. Operational security and cost logs are still kept, per the Privacy Policy. The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. Use for private one-shots that don't participate in the iteration arc. Default false.
`implementation_context`	Yes	The artifact under review. SEND FULL FILE CONTENTS VERBATIM — the architect cites per-line evidence (identifiers, branch ordering, structural choices); any compression destroys evidence and produces hallucinated findings on code that isn't there. CONCRETE DON'TS: do NOT replace docstrings/comments with `...`; do NOT condense multi-line statements; do NOT replace dict/set comprehensions with `{...}`; do NOT remove explanatory comments to save tokens. If the file is large, split into MULTIPLE architect.validate calls scoped by file/module — never truncate one call. Architecture summaries (high-level prose) accepted ONLY for greenfield (no code yet); never as a substitute for code that already exists.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations, the description discloses that this is a long-running LLM call (60-180s typical, 6-minute server budget), that retrying on client timeout re-runs the call from scratch, that the run_id is emitted in the first progress event, and that runs are private by default with URLs that 404 until published. It also discloses persistence atomicity, auth/plan requirements, residency, score variance (~20-67 points), and the fact that validate does not verify runtime correctness. The annotations are consistent: readOnlyHint=false and idempotentHint=false align with creating persisted runs and warning against retries.

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

Conciseness2/5

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

The description is genuinely front-loaded, opening with the core purpose, timeout warning, and recovery path. However, it is extremely long and contains substantial redundancy and low-signal detail, such as repeated PR-number score anecdotes, the recursive-integrity narrative about the platform's own CI practice, and extended certification-payload examples. While section headings help navigation, the overall size and repetition hurt parseability; many sentences could be cut without losing essential guidance.

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 high-complexity, long-running, stateful tool, the description covers nearly everything an agent needs: timeout behavior, recovery handles, task-augmentation protocol, iteration semantics, typed failure modes, privacy/persistence behavior, return-field meaning, and the validate→consensus→certify orchestration sequence. The presence of an output schema covers structured return values, while the description adds the temporal and operational context the schema cannot express. Nothing critical is missing.

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

Parameters5/5

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

Even though schema coverage is 100%, the description adds substantial operational meaning beyond the schema's field names. It explains that implementation_context must be sent verbatim with no truncation, no `...` placeholders, and no comment removal; that repository must stay stable across calls to preserve the iteration chain; that changing repository silently severs prior-run anchoring; and that private_session disables persistence and recovery. It also clarifies the special task parameter semantics for MCP task-augmented invocation, which the schema alone would not convey.

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: a first-pass doctrine review of agentic code/workflow against the 10-principle AI Design Blueprint. It clearly distinguishes itself from siblings like architect.certify (second-pass adversarial review) and architect.validate_consensus (N=3-5 aggregated stability-focused validation), and from spec.validate/design.validate by targeting agentic workflows. This is far beyond a tautology or vague purpose statement.

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?

The description provides an explicit WHEN TO CALL (governance audit, readiness score, production_ready badge) and WHEN NOT TO CALL (non-agentic plumbing, which returns tier=not_applicable). It also names alternatives with concrete conditions: use architect.validate_consensus when stability matters more than speed, use architect.certify to mint the badge after production_ready, and use me.validation_history for timeout recovery. An agent can reliably select this tool versus its siblings from the description alone.

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

architect.validate_consensusValidate Agent Architecture (Consensus Mode)AInspect

Pro/Teams — N-shot CONSENSUS doctrine review of agentic code. ON CLIENT TIMEOUT — DO NOT RETRY THIS TOOL. Long-running (~80-120s for N=3 parallel LLM calls); MCP clients often close the call before the server returns. Retrying re-runs N × 60-180s LLM calls from scratch and burns N× compute. RECOVERY: same heartbeat pattern as architect.validate — the run_id is emitted in the FIRST progress event at t=0s (before LLM children fire); on timeout, call me.validation_history(run_id='<that-id>') to fetch the persisted consensus envelope. Runs N parallel architect.validate calls with private_session=True, then aggregates them to a per-principle MODE verdict + median severity + per-principle stability + score range/stdev. Returns one ConsensusValidationResponse with the headline median score, the honest variance band, and a representative full ValidationResponse (the child whose score is closest to the median). WHEN TO CALL: the user wants an HONEST first-pass score on agentic code, with the architect's variance surfaced. The single-shot architect.validate re-asserts the prior persisted run's verdict via baseline-anchor injection — same code can score 60/C anchored vs 98/A unanchored. Consensus mode is the unanchored honest read. WHEN NOT TO CALL: when you NEED the iteration delta against a prior run (regressions/improvements panel) — for that, call architect.validate which keeps baseline injection on. CHAIN RESUME: each child runs with private_session=True (no anchor) on purpose, but the CONSOLIDATED outer row IS persisted with lifecycle_status='completed' — the next single-shot architect.validate on the same repository auto-resolves it as prior_run_baseline. Consensus checkpoint becomes the new anchor. See the architect-validation-orchestration skill in the agent-asset pack for the full validate → consensus → certify sequence. BEHAVIOR: N (default 3, max 5) parallel LLM calls run concurrently; wallclock ~80-120s for N=3 (max child latency, not sum). Cost = N × LLM bill. Each child runs with private_session=True so the doctrine prompt's prior-run baseline injection is suppressed (no anchor bias). One CONSOLIDATED UserValidationRun row is written carrying the consensus envelope; the N children themselves do NOT persist (private_session contract). AUTH: sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial plan. Same paid-plan gate as architect.validate. INPUTS: same shape as architect.validate. n is the only extra arg (range 2..5). private_session is implicit (always true for children); the OUTER consolidated row IS persisted unless the tool itself is called inside another private context — but no such wrapper exists today. OUTPUT: response carries score_consensus_median (headline), score_stdev (honest uncertainty), score_range (min, max), mode_stability_min_pct (the cert-eligibility gate's input — ≥ 80% means the consensus is stable), per_principle (mode + distribution + severity median per principle), and representative_response (the closest-to-median child's full ValidationResponse so existing UI components render unchanged). TYPED FAILURES: same as architect.validate (timed_out, rate_limited, dependency_unavailable). Plus consensus-specific: consensus_quorum_failed when fewer than 2 child runs succeeded (≥ 2 required to compute a meaningful median).

ParametersJSON Schema

Name	Required	Description
`n`	No	Number of parallel child runs. Default 3 (the variance signal is visible at N=3; cost = 3× LLM bill). Capped server-side by Settings.consensus_n_max (default 5).
`task`	No	What the agent or workflow is trying to accomplish.
`files`	No	List of file paths relevant to the implementation.
`goals`	No	Specific safety or quality goals to evaluate against.
`language`	No	Programming language of the code (e.g. 'python').
`focus_area`	No	Optional: narrow the review to a principle cluster or slug.
`repository`	No	Iteration key. Consensus children all run unanchored (`private_session=True`), but the consolidated row IS persisted under this key — discoverable as prior baseline for the next single-shot `architect.validate`. Same value across calls keeps the iteration arc inspectable.
`example_limit`	No	Max curated examples per child run.
`implementation_context`	Yes	The artifact under review. SEND FULL FILE CONTENTS VERBATIM — same constraint as architect.validate. Truncation produces hallucinated findings on code that isn't there.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only carry generic flags, so the description carries the full burden and delivers: long-running execution (~80-120s), N parallel LLM calls with Nx cost, a DO NOT RETRY timeout warning, private_session child isolation versus a persisted consolidated row, and consensus-specific typed failures. There is no contradiction with the annotations.

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

Conciseness5/5

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

The description is long but appropriately structured, with the most critical operational warning front-loaded and clearly labeled sections for behavior, auth, inputs, outputs, and failures. Every section earns its place given the tool's cost, timeout behavior, and persistence semantics.

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 complex, expensive, state-persisting tool, the description covers prerequisites, input mapping, output fields, failure modes, sibling routing, persistence semantics, and recovery after client timeout. An agent has everything needed to decide whether to call it, how to call it safely, and what to do when it times out.

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

Parameters3/5

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

Schema description coverage is 100% and every parameter is already richly documented, including the verbatim implementation_context constraint, n's server-side cap, and repository's iteration-key behavior. The tool description mostly restates these points rather than adding substantially new parameter semantics, so it stays at the high-coverage 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 opens by defining the tool as an N-shot CONSENSUS doctrine review of agentic code and specifies that it returns a ConsensusValidationResponse with a median score and variance band. It explicitly contrasts consensus mode with the single-shot architect.validate, so an agent can tell the siblings apart.

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?

It provides dedicated WHEN TO CALL and WHEN NOT TO CALL sections, directing agents to consensus mode for honest unanchored first-pass scores and to architect.validate for iteration-delta regressions. It also gives concrete timeout recovery steps via run_id and validation_history, making invocation context unambiguous.

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

assets.listList Agent AssetsA

Read-onlyIdempotent

Inspect

Public — list downloadable doctrine and agent asset artifacts (skill packs, rule packs, MCP setup snippets) the user can drop into their AI coding tool to import the Blueprint as native skill/rule files. Returns a list of assets with name, format (one of: zip / md / markdown / mdc / json / toml / text — the full vocabulary), pack_version, download_url, and platform target (Claude Code, Cursor, Codex, Gemini, Qwen). The response also carries count (length of assets) for symmetry with principles.list / clusters.list / guides.list. WHEN TO CALL: the user asks how to bring the Blueprint into their coding agent, or wants to install it as a local skill/rule file. WHEN NOT TO CALL: for the live MCP tools themselves — those are already available through this server. For doctrine content, prefer principles.list/get and guides.list/get. BEHAVIOR: read-only, idempotent, no auth required. Asset artefacts are regenerated on every deploy from the canonical doctrine.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the existing annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that no auth is required and that asset artifacts are regenerated on every deploy from the canonical doctrine, giving insight into potential variability. 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.

Conciseness5/5

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

The description is well-structured with a front-loaded purpose, followed by detailed but relevant output information, usage guidance, and behavioral notes. Each sentence adds value, and the use of WHITE sections aids readability.

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 simple zero-parameter read-only tool, the description is exceptionally complete. It covers output fields, format vocabulary, platform targets, usage boundaries, and behavior. No gaps remain even without relying on the output schema.

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?

The tool has zero parameters, so schema coverage is trivially 100%. The description correctly implies an unfiltered list of all assets, which is sufficient for the empty input schema. Baseline for 0 params is 4.

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 the tool lists downloadable doctrine and agent asset artifacts (skill packs, rule packs, MCP setup snippets) for importing the Blueprint into AI coding tools. It distinguishes itself from sibling tools like principles.list and guides.list by explicitly contrasting with them.

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?

The description includes explicit WHEN TO CALL and WHEN NOT TO CALL sections, naming specific alternative tools (principles.list/get, guides.list/get) and explaining when not to use this tool (for live MCP tools or doctrine content). This provides clear guidance for tool selection.

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

clusters.getGet ClusterA

Read-onlyIdempotent

Inspect

Get one principle cluster by stable slug. Returns the cluster definition, shared rationale, and the full set of member principles (slug + title) so the caller can pivot into principles.get without a second list call. WHEN TO CALL: the user has already named a specific cluster (e.g. 'delegation', 'visibility', 'trust', 'orchestration') OR you have a slug from a prior clusters.list / principles.list response and need its full definition + member principles. The response embeds member principle slugs + titles already, so DO NOT loop principles.get over each member to get a cluster overview — read the response. WHEN NOT TO CALL: the user is describing a topic, failure mode, or keyword in natural language (call principles.search instead); the user wants to discover which clusters exist (call clusters.list); the user wants the definition of one specific principle (call principles.get directly). Idempotent + cacheable per slug. Returns 404-shaped error_payload on unknown slug — the slug must match exactly the value emitted by clusters.list, with no normalization.

ParametersJSON Schema

Name	Required	Description	Default
`slug`	Yes	Stable slug of the principle cluster (e.g. 'delegation', 'visibility', 'trust', 'orchestration').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: idempotent and cacheable per slug, returns a 404-shaped error_payload on unknown slug, and requires exact slug matching with no normalization. This provides actionable knowledge about edge cases without contradicting annotations.

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

Conciseness5/5

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

The description is structured with clear sections (purpose, WHEN TO CALL, WHEN NOT TO CALL, behavior notes) that make it scannable. Every sentence contributes new information; the length is justified by the decision logic and edge-case guidance, and the core purpose is front-loaded.

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?

With a single parameter, a rich output schema, and comprehensive annotations, the description fully covers all contextual needs: what the tool returns, when to use it, when not to use it, error handling, caching, and parameter matching rules. No gaps remain for this tool's complexity.

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

Parameters5/5

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

Schema description coverage is 100% for the single slug parameter, but the description adds extra meaning by explaining the origin of slugs (from clusters.list/principles.list), the requirement for exact matching with no normalization, and the error behavior on unknown slugs. This goes beyond the schema's basic type and examples.

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 opens with 'Get one principle cluster by stable slug', which is a specific verb+resource+scope statement. It clearly distinguishes from siblings by explicitly naming alternatives (clusters.list, principles.get, principles.search) and by stating the return contents (cluster definition, shared rationale, member principle slugs + titles).

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?

Provides explicit WHEN TO CALL and WHEN NOT TO CALL sections with named alternative tools for each exclusion case. It also gives a performance guideline advising not to loop principles.get over members because the response already embeds member slugs/titles, which goes beyond typical tool descriptions.

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

clusters.listList ClustersA

Read-onlyIdempotent

Inspect

List all principle clusters with their stable slugs and linked principle titles. Use this to discover which clusters exist before drilling in with clusters.get or filtering principles.list by cluster. Prefer clusters.get when you already know the cluster slug and need full detail.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior3/5

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful content expectations (stable slugs, linked principle titles) but no additional behavioral traits like pagination, rate limits, or auth needs. It does not contradict annotations, but the added behavioral context is minimal.

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

Conciseness5/5

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

The description is two short sentences, front-loaded with the primary action. The second sentence adds necessary guidance on when to use alternatives. No redundant information or wasted words.

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?

Given the tool's simplicity (no parameters), the presence of an output schema, and strong annotations, the description fully covers the use case, including context for when to use this list tool versus related tools. It is complete and self-sufficient.

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?

The tool has zero parameters, and the schema's property map is empty. Per the baseline for 0 params, a score of 4 is appropriate — the description isn't required to explain parameters, and it doesn't attempt to, which is correct.

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 'List all principle clusters with their stable slugs and linked principle titles' — a specific verb and resource. It distinguishes from siblings by naming clusters.get and principles.list as alternatives, 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?

Explicitly provides when to use: 'Use this to discover which clusters exist before drilling in with clusters.get or filtering principles.list by cluster.' Also states a clear exclusion: 'Prefer clusters.get when you already know the cluster slug and need full detail.' This meets the highest standard for usage guidance.

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

design.validateValidate Experience DesignAInspect

Pro/Teams — first-pass surface-craft review of a FRONTEND artefact (component, screen, or flow) against the 8 laws of the Experience Design Blueprint. The surface-craft companion to architect.validate: where architect.validate scores agentic ARCHITECTURE against the 10 agentic principles, design.validate scores the PERCEPTIBLE SURFACE — what the user sees, taps, scans, and remembers (Jakob's familiarity, Hick's choice load, Fitts's targets + the accessibility floor, Miller's working-memory budget, Aesthetic-Usability, Peak-End, Tesler's irreducible complexity, the Mental-Model gap). 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 'surface' dimension, distinct from the 'architecture' and 'spec' 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 surface_classification (ui_surface vs non_ui — non-visual code is marked not_applicable, NOT failed), 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 architect.validate uses, so all three lenses grade on one rubric. ACCESSIBILITY IS THE FLOOR: a breach of the Fitts's-Law floor (interactive target below the WCAG 2.2 24×24 minimum, missing focus visibility, an unreachable destructive confirmation) is a production_blocker, not polish. WHEN TO CALL: the user wants a craft/UX/accessibility review or a readiness grade on a frontend artefact they just built or changed. WHEN NOT TO CALL: non-visual code (backend, config, type aliases) returns tier=not_applicable — submit the actual UI surface instead. INPUTS: send the FULL artefact source verbatim as implementation_context (no truncation, no '…' placeholders — they are read as literal code). 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 artefact 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 craft signal, not a certified verdict. DOCTRINE: the eight laws — each law's evidence, craft-surface application, anti-patterns, and the validator questions this tool scores against — live in the experience-design-blueprint skill and docs/business/EXPERIENCE_DESIGN_BLUEPRINT.md (the surface-craft companion to the architect-validation-orchestration skill that orchestrates the agentic validators).

ParametersJSON Schema

Name	Required	Description
`task`	No	What this surface is for (e.g. 'the closed-beta apply form'). Adds evaluation context.
`files`	No	File paths relevant to the artefact, for context.
`goals`	No	Specific craft/UX goals to weight (e.g. 'WCAG 2.2 AA', 'one primary action per screen').
`repository`	No	Project/repository key. Groups this run with prior design.validate runs on the same project in your validation-history dashboard (the same grouping architect.validate uses), under the 'surface' 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 frontend artefact under review. SEND FULL SOURCE VERBATIM — the reviewer cites specific elements, values, and structure; any compression destroys evidence and produces findings on code that isn't there. Do NOT replace markup/styles with '…'; do NOT condense multi-line JSX/CSS. If large, split into MULTIPLE calls scoped by component — never truncate one call.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

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

Annotations exist (readOnlyHint=false, idempotentHint=false, destructiveHint=false), lowering the bar, and the description still adds substantial non-obvious behavior: 'ON CLIENT TIMEOUT — DO NOT RETRY... the server mints a run_id... capture that run_id and call me.validation_history(run_id='<that-id>') instead of retrying (a retry re-runs the full 60-180s call).' It also discloses persistence toggles (private_session skips stored run but 'operational security + cost logs are still kept'), the accessibility floor being a 'production_blocker, not polish', and a calibration caveat that the grade is 'directional craft signal, not a certified verdict'. None of this is derivable from the annotations.

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

Conciseness3/5

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

The description is front-loaded well — purpose, sibling differentiation, and the critical timeout/run_id protocol come early. However, it is a dense wall of prose (~600+ words) with multiple long run-on sentences, and it repeats content already in the schema (the verbatim-source instruction on implementation_context, the return-format description duplicating what the output schema covers). List-able details like auth requirements and typed failures are buried in paragraphs rather than structured, so trimming and structuring would improve parseability.

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 7-parameter tool with a validation-family context and critical run-recovery semantics, nothing the agent needs to invoke it correctly is missing: when/why to call, what happens on timeout, how to recover the result, side-effect semantics, auth preconditions, failure envelope types (timed_out, rate_limited, dependency_unavailable, schema_mismatch with retryable + next_action), and the non-visual-code not_applicable path. The output schema already carries return values, and the description's byte-for-byte guidance on input handling is exhaustive.

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 description coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema: it flags a concrete gotcha on implementation_context ('no truncation, no '…' placeholders — they are read as literal code'), clarifies private_session's residual logging ('operational security + cost logs are still kept'), and explains repository grouping semantics under the 'surface' dimension. The additions are modest because the schema is already rich, but they meaningfully justify a tick 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 opens with a specific verb and resource: 'first-pass surface-craft review of a FRONTEND artefact (component, screen, or flow) against the 8 laws of the Experience Design Blueprint.' It draws an explicit line against architect.validate ('where architect.validate scores agentic ARCHITECTURE... design.validate scores the PERCEPTIBLE SURFACE') and notes v1 is single-pass with 'no certification or consensus mode yet (those stay architect.validate-only).' An agent can distinguish this from spec.validate, architect.certify, and architect.validate_consensus 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.

Usage Guidelines5/5

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

The description has explicit WHEN TO CALL ('the user wants a craft/UX/accessibility review or a readiness grade on a frontend artefact they just built or changed') and WHEN NOT TO CALL sections ('non-visual code (backend, config, type aliases) returns tier=not_applicable — submit the actual UI surface instead'). It also names the sibling counterpart architect.validate and the spec lens, so the selection context across the validation family is fully specified.

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

examples.getGet ExampleA

Read-onlyIdempotent

Inspect

Get one curated example by stable slug. Returns title, summary, source-code links, principle coverage (the principle slugs the example demonstrates), difficulty, library/framework, and implementation notes. Use this when you already have the slug from examples.search, a principles.get response, or a guide cross-link; prefer examples.search when filtering by topic / principle / difficulty / library; prefer guides.get when the caller wants a full walkthrough rather than a single reference example. Returns error_payload on unknown slug. Some entries are first-party agentic patterns (entry_kind='pattern') rather than upstream cookbook examples: those additionally return pattern_slug, pattern_family, when_to_use, doctrine_relations (each {principle_id, relation, note, code_ref} where relation is one of structural / default_gap / depends), prior_art, and doctrine_binding_basis. Every other row omits those seven keys.

ParametersJSON Schema

Name	Required	Description	Default
`slug`	Yes	Stable slug of the curated example (e.g. 'agents-building-blocks-5-control').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses error behavior ('Returns error_payload on unknown slug') and explains the two possible entry kinds, including the conditional additional fields for pattern entries. This adds significant context not captured in annotations.

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

Conciseness5/5

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

The description is front-loaded with the core action and return types, then uses conditional clauses to explain variants. Despite length, every sentence contributes necessary information; no fluff or repetition.

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 one parameter and an output schema, the description thoroughly explains return values, error handling, and edge-case entry variants. It also positions the tool within the broader toolset, making it complete for an agent deciding whether to invoke it.

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

Parameters3/5

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

The only parameter, 'slug', is fully described in the input schema (100% coverage). The tool description does not add new semantic details beyond using the term 'stable slug', which already appears in the schema. Baseline 3 is appropriate since schema handles the parameter meaning.

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?

Purpose is explicitly stated: 'Get one curated example by stable slug.' It names the verb and resource, and distinguishes from siblings by contrasting with examples.search and guides.get (e.g., 'prefer examples.search when filtering ... prefer guides.get when the caller wants a full walkthrough').

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?

Provides explicit when-to-use guidance: 'Use this when you already have the slug from examples.search, a principles.get response, or a guide cross-link', and names alternatives with conditions: 'prefer examples.search when filtering by topic / principle / difficulty / library; prefer guides.get when the caller wants a full walkthrough'.

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

examples.searchSearch ExamplesA

Read-onlyIdempotent

Inspect

Search curated examples by free-text query, ranked by relevance, with optional filters: principle_ids (only examples covering those principles), difficulty (beginner/intermediate/advanced), library (e.g. 'langgraph', 'openai'). Returns each match's slug, title, summary, principle coverage, difficulty, library, and source-code link — slug is the handle examples.get hydrates. Default limit 5, capped server-side. Use this when the user describes a use case, technique, or library and wants matching examples; prefer examples.get when you already have the slug; prefer guides.search when the user wants a full walkthrough; prefer principles.search when the user wants doctrine guidance, not an implementation. Results may include first-party agentic patterns (entry_kind='pattern') carrying an explicit doctrine binding, see examples.get. Filter to one family with pattern_family, which implies patterns only. Patterns take a small relevance preference over generic examples when otherwise equally relevant; that preference never outranks a genuine failing-principle match, and a pattern whose only relation to a failing principle is 'depends' receives no such match at all.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of results to return. Capped at server maximum.
`query`	Yes	Free-text search query matched against example title, summary, and metadata.
`library`	No	Filter by library or framework name (e.g. 'langgraph', 'openai', 'anthropic').
`difficulty`	No	Filter by difficulty level.
`principle_ids`	No	Filter to examples that cover these principle IDs.
`pattern_family`	No	Filter to one agentic-pattern family. Implies patterns only, since no upstream cookbook example carries a family.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds substantial behavioral context beyond that: ranking by relevance, default limit 5 capped server-side, results may include first-party agentic patterns, and the nuanced relevance preference rule ('never outranks a genuine failing-principle match; a pattern whose only relation to a failing principle is 'depends' receives no such match at all'). This gives the agent a true sense of what the tool does behaviorally.

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 fairly long but tightly packed with essential information. It front-loads the core action and then logically builds: filters, return payload, default limit, usage guidance, and pattern-specific nuances. No filler sentences; each clause adds meaning, though a slightly more compact structure would be ideal.

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?

With 6 parameters, an output schema present, and complex ranking/filter behavior, the description is remarkably complete. It covers return payload fields (slug, title, summary, etc.), default and cap behavior, usage alternatives, and the tricky pattern-inclusion rules. The output schema handles return structure details, so the description's job is done well.

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 description coverage is 100%, so baseline is 3. The description adds semantic value beyond the schema: it clarifies principle_ids as 'only examples covering those principles', explains pattern_family implies patterns only, and gives concrete library examples ('langgraph', 'openai'). It also explains the overall search+filters behavior, going beyond bare parameter names.

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?

Opens with a specific verb+resource: 'Search curated examples by free-text query, ranked by relevance.' It clearly distinguishes itself from siblings by naming alternatives in usage guidance: 'prefer examples.get when you already have the slug; prefer guides.search when the user wants a full walkthrough; prefer principles.search when the user wants doctrine guidance.'

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?

Explicitly states when to use this tool: 'Use this when the user describes a use case, technique, or library and wants matching examples.' It also gives explicit exclusions and alternatives: 'prefer examples.get when you already have the slug; prefer guides.search when the user wants a full walkthrough; prefer principles.search when the user wants doctrine guidance, not an implementation.' This is textbook usage guidance.

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

guides.getGet Application GuideA

Read-onlyIdempotent

Inspect

Get a full application guide by its stable slug (e.g. 'security-application', 'observable-evaluation'). Returns sections, action items, and linked principles. Use this when you already have the guide slug from guides.list or guides.search. Prefer guides.search when the user describes a topic in natural language; prefer guides.list when you need the full inventory.

ParametersJSON Schema

Name	Required	Description	Default
`slug`	Yes	Stable slug of the application guide (e.g. 'security-application', 'observable-evaluation').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context about the return structure (sections, action items, linked principles) and the stability of the slug, going beyond what annotations provide.

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

Conciseness5/5

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

Three sentences, front-loaded with the core action, then return contents, then usage guidance. No wasted words.

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 simple one-parameter tool with full annotations and output schema, the description covers the purpose, return contents, and usage alternatives comprehensively. No gaps identified.

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

Parameters3/5

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

Schema coverage is 100% for the single slug parameter, which already includes examples. The description repeats the examples and adds that the slug comes from guides.list or guides.search, but this is marginal beyond 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 clearly states the tool gets a full application guide by stable slug, with examples. It distinguishes itself from siblings by focusing on slug-based retrieval and listing return contents.

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?

Explicitly says when to use this tool (when you already have the slug) and when to prefer alternatives (guides.search for natural language, guides.list for full inventory).

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

guides.listList Application GuidesA

Read-onlyIdempotent

Inspect

List application guides that show how Blueprint principles apply to engineering challenges (security, evaluation, observability, etc.). Use this to discover which guides exist before drilling in. Prefer guides.search when the user describes a topic or failure mode in natural language. Prefer guides.get when you already know the guide slug and need full detail.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the discovery context but does not disclose additional behavioral traits such as pagination or output size. With annotations present, this is adequate but not rich.

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

Conciseness5/5

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

Three sentences, each adding value: what it does, when to use it, and how to choose alternatives. No redundancy, front-loaded with the core purpose.

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 simple list tool with no parameters, an output schema, and strong annotations, the description fully covers its role, usage context, and sibling differentiations. Nothing is missing.

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?

The tool has zero parameters, so the baseline is 4. The description needs no parameter explanation and adds no confusion. The schema is trivially complete.

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 uses a specific verb and resource ('List application guides') and clarifies the scope ('show how Blueprint principles apply to engineering challenges'). It also distinguishes from siblings by framing this tool as the discovery entry point before drilling in.

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?

Explicitly names when to use this tool versus alternatives: 'Use this to discover which guides exist before drilling in. Prefer guides.search when the user describes a topic or failure mode in natural language. Prefer guides.get when you already know the guide slug and need full detail.' This gives clear, actionable guidance.

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

guides.searchSearch Application GuidesA

Read-onlyIdempotent

Inspect

Search application guides by free-text query, matched against section answers and action items. Use this when the user describes an engineering challenge (security review, evaluation harness, observability) and wants matching guides. Prefer guides.get when you already have the guide slug; prefer guides.list when you need the full inventory.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of results to return. Capped at server maximum.
`query`	Yes	Free-text search query matched against all guide content including section answers and action items.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context by specifying that the search matches against 'section answers and action items', which goes beyond the schema and clarifies the search's scope and semantics. It does not mention pagination or result ordering, but the output schema likely covers return format, and the bar is lower given annotation coverage.

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

Conciseness5/5

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

The description is three sentences, each earning its place: first defines the action, second gives the use case, third provides sibling alternatives. No redundant or vague wording. It is front-loaded with the primary purpose and is highly scannable.

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 simple search tool with comprehensive annotations, full schema coverage, and an output schema present, the description covers all necessary context: purpose, use case, and alternatives. It doesn't need to explain return values because the output schema exists. The description is complete for the tool's complexity.

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

Parameters3/5

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

Schema coverage is 100% with clear descriptions for both 'query' and 'limit'. The description reinforces that query is free-text and matched against content, but it doesn't add significant new meaning beyond the schema. Baseline of 3 is appropriate when the schema carries the parameter documentation.

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 the tool's function: 'Search application guides by free-text query' with specific scope ('matched against section answers and action items'). It also distinguishes from siblings by explicitly naming alternatives (guides.get, guides.list), providing clear differentiation.

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?

The description gives explicit guidance on when to use this tool ('Use this when the user describes an engineering challenge... and wants matching guides') and when to prefer alternatives ('Prefer guides.get when you already have the guide slug; prefer guides.list when you need the full inventory'). This satisfies both when-to-use and when-not-to-use criteria.

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

handoffs.agencyRequest Agency HandoffAInspect

Authenticated — submit an agency engagement enquiry on behalf of the caller for a founder-led discovery call. Persists an AgencyHandoff row routed to the agency inbox; the user is contacted by the team for a scoped proposal. Engagement scopes: workflow sprint (rapid agentic workflow implementation), proof-of-concept (validate a specific agent design in a bounded timeframe), pilot support (co-design and validate a production-ready pilot), advisory (ongoing architectural guidance across a product team). WHEN TO CALL: the user has identified a paid hands-on expert engagement need beyond self-service learning, and explicitly asks to talk to the team or book a discovery call. ALWAYS confirm with the user before firing — this creates a sales-visible record. WHEN NOT TO CALL: for free training / partnerships discussion (use handoffs.partnership); for support / billing / access (use handoffs.operator); proactively or as a sales push. BEHAVIOR: write-only, single insert, side-effecting. Auth: Bearer (Firebase ID token, any plan). UK/EU residency. Response confirms the ticket id + scope so the user can reference it.

ParametersJSON Schema

Name	Required	Description	Default
`role`	No	Role or title of the person submitting the agency inquiry.
`locale`	No	Response locale for the acknowledgment.	en
`reason`	Yes	Description of the engagement need: workflow sprint, proof-of-concept, pilot support, or advisory.
`company`	No	Company or team name submitting the agency inquiry.
`website`	No	Website or relevant URL for the team or project.
`agent_name`	No	Name of the agent or client triggering the handoff.	mcp-client
`support_type`	No	Type of support needed.
`trace_summary`	No	Optional agent trace summary for operator context.
`agent_platform`	No	Platform or runtime the agent is running on.
`workflow_stage`	No	Current workflow stage.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already indicate a write operation (readOnlyHint=false), but the description goes further by disclosing 'write-only, single insert, side-effecting', persistence details, auth requirements ('Bearer <token> (Firebase ID token)'), residency constraint ('UK/EU residency'), and the confirmation warning about creating a 'sales-visible record'. This adds significant behavioral context beyond the 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 longer than ideal but well-organized with labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR). It front-loads the core purpose and uses clear signposting. However, there is some redundancy (e.g., 'Authenticated' at the beginning and 'Auth: Bearer <token>' later), so it is not maximally concise.

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?

The description covers purpose, scope, when to use (with exclusions), behavioral traits, authentication, residency, confirmation requirement, and response contents. Given that an output schema exists, the description does not need to detail return values, and it provides a complete operational picture for an agent.

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 descriptions already cover 100% of parameters, providing a baseline of 3. The description adds value by elaborating on the engagement scopes for the 'reason' parameter (workflow sprint, proof-of-concept, pilot support, advisory) with brief explanations, and clarifies that the request is made 'on behalf of the caller' and returns a ticket id + scope. This is meaningful but not extensive, as the schema already lists the scopes.

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 opens with a specific verb and resource: 'submit an agency engagement enquiry on behalf of the caller for a founder-led discovery call.' It clearly distinguishes itself from siblings by explicitly naming alternatives (handoffs.partnership, handoffs.operator) in the WHEN NOT TO CALL section, and by describing the exact engagement scopes.

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?

The description provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including specific conditions ('user has identified a paid hands-on expert engagement need... explicitly asks to talk to the team'), a mandatory confirmation step, and named alternatives for other use cases. This is exemplary guidance for an AI agent.

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

handoffs.operatorRequest Operator HandoffAInspect

Authenticated — creates a support handoff record when an agent needs human review, account-specific escalation, or operator follow-up that cannot be resolved with the read-only doctrine tools. Persists a SupportHandoff row (reason, topic, page_url, agent_name, agent_platform, trace_summary, user_email) routed to the support inbox; user is contacted by the team. WHEN TO CALL: user explicitly asks for human help, hits a billing/access issue, or the agent has tried the doctrine tools and the user still needs a human. ALWAYS confirm with the user before firing — this creates a human-visible ticket. WHEN NOT TO CALL: proactively, silently, or to log debugging traces (use diagnostic logs instead); for partnerships/agency enquiries (use handoffs.partnership / handoffs.agency); for content questions answerable by principles.search / guides.search. BEHAVIOR: write-only, single insert, side-effecting (creates a ticket the team will see). Auth: Bearer (any plan). UK/EU residency. Response confirms ticket id + topic so the user can reference it.

ParametersJSON Schema

Name	Required	Description	Default
`topic`	No	Topic category for routing (e.g. 'agent', 'billing', 'access', 'general').	agent
`locale`	No	Response locale for the handoff acknowledgment.	en
`reason`	Yes	Clear description of why a human operator review is needed.
`page_url`	No	URL of the page or context where the handoff was triggered.
`agent_name`	No	Name of the agent or client triggering the handoff.	mcp-client
`trace_summary`	No	Optional summary of the agent's recent actions or trace for operator context.
`agent_platform`	No	Platform or runtime the agent is running on (e.g. 'claude-code', 'cursor', 'copilot').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

Goes beyond the annotations by disclosing side effects ('write-only, single insert, side-effecting'), the requirement to confirm with the user before firing, auth specifics (Bearer token, any plan), residency (UK/EU), and response content (ticket id + topic). Also notes the record is routed to the support inbox and that the user is contacted. 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.

Conciseness5/5

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

The description is long but well-structured with CAPS-labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) that are easy to parse. Every sentence provides actionable information, with no redundant wording.

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?

Given the tool's complexity (7 params, annotations, output schema), the description covers invocation rationale, exclusions, side effects, auth requirements, user confirmation, and response details. It is comprehensive enough for an agent to confidently decide when and how to invoke it.

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 baseline is 3. The description adds meaning by listing the persisted SupportHandoff fields (reason, topic, page_url, agent_name, agent_platform, trace_summary, user_email) and explaining routing, which helps the agent understand how parameters map to the record. One minor issue: user_email is mentioned but not present in the schema, causing slight ambiguity.

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 it 'creates a support handoff record' for specific scenarios (human review, escalation, operator follow-up) that cannot be resolved via read-only doctrine tools. It also explicitly names sibling tools to distinguish from them in the WHEN NOT TO CALL section.

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?

Provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, listing triggers (user request, billing/access issues, doctrine tools failing) and exclusions (proactive/silent use, logging traces, partnerships/agency, content questions). Each exclusion names the correct alternative tool, giving clear decision guidance.

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

handoffs.partnershipRequest Partnership HandoffAInspect

Authenticated — creates a partnerships handoff record for design-partner, ecosystem, training, or advisory conversations needing human review. Persists a PartnershipHandoff row routed to the partnerships inbox; the user is contacted by the team. WHEN TO CALL: user explicitly wants to engage as a design partner, co-marketing/training partner, or evaluate the Blueprint for their org's training programme. ALWAYS confirm with the user before firing — this creates a human-visible partnerships ticket. WHEN NOT TO CALL: for general support / billing / access issues (use handoffs.operator); for paid-engagement enquiries (use handoffs.agency); proactively or as a sales prompt — only when the user has explicitly asked. BEHAVIOR: write-only, single insert, side-effecting (creates a ticket). Auth: Bearer (any plan). UK/EU residency. Response confirms the ticket id + audience so the user can reference it.

ParametersJSON Schema

Name	Required	Description	Default
`role`	No	Role or title of the person submitting the partnership inquiry.
`topic`	No	Partnership topic category.	ecosystem
`locale`	No	Response locale for the handoff acknowledgment.	en
`reason`	Yes	Clear description of the partnership opportunity or inquiry.
`website`	No	Website of the organization for additional context.
`agent_name`	No	Name of the agent or client triggering the handoff.	mcp-client
`organization`	No	Name of the organization or company making the partnership inquiry.
`trace_summary`	No	Optional agent trace summary for operator context.
`agent_platform`	No	Platform or runtime the agent is running on.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that the tool is write-only, single-insert, side-effecting (creates a ticket), requires Bearer token auth, has UK/EU residency constraints, and returns a confirmation with ticket id and audience. This adds significant context not available from annotations alone.

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 fairly long but well-structured with labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) that make it scannable. While every sentence adds value, it could be slightly tightened without losing meaning.

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?

The description covers purpose, use cases, exclusions, behavioral effects, auth, geography, and expected response. With 100% schema description coverage and an output schema available, no critical information is missing for a human-review handoff tool.

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

Parameters3/5

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

Schema description coverage is 100%, with all 9 parameters individually described in the schema. The description does not add parameter-level semantics beyond the schema, which is acceptable per baseline. No contradiction or hidden parameter behavior is introduced.

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 the tool creates a partnerships handoff record for specific conversation types (design-partner, ecosystem, training, advisory) and explicitly distinguishes it from siblings by pointing to alternative tools for other use cases. The verb 'creates' and resource 'partnerships handoff record' provide precise purpose.

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?

The description provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, naming concrete alternatives (handoffs.operator for general support, handoffs.agency for paid engagements) and warning against proactive/sales use. It also instructs to always confirm with the user before firing, giving clear operational guidance.

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

me.add_evidenceAdd Evidence NoteAInspect

Authenticated — append a free-text evidence note to a specific stage in the caller's active course. Notes record concrete implementation observations, decisions, or artefacts that demonstrate progress through a Blueprint principle (e.g. how a delegation boundary was implemented, what approval flow was chosen and why). Persisted as UserStageEvidence rows scoped to (user_id, course_slug, stage_slug). WHEN TO CALL: AFTER the user has articulated something concrete they have built, observed, or decided — not to capture intent or speculation. Pair with me.coaching_context to close evidence gaps. WHEN NOT TO CALL: to log every conversation turn; to record planning, ideas, or todos; on behalf of another user; without the user's awareness (they should know their progress is being recorded). BEHAVIOR: write-only, single insert. Auth: Bearer (Firebase ID token, any plan). UK/EU residency. Notes are visible only to the owning user and are surfaced on me.learning_path / me.coaching_context. Confirms the stage_slug + course_slug pair in the response so the user can see which stage was credited.

ParametersJSON Schema

Name	Required	Description
`note`	Yes	Evidence note to append to the delegation boundary notes for this stage.
`stage_id`	Yes	ID of the stage to append the evidence note to.
`course_slug`	Yes	Slug of the course the stage belongs to (e.g. 'agentic-fundamentals').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

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

The description discloses key behavioral traits beyond annotations: write-only single insert, authentication method, UK/EU residency, visibility rules, and response behavior. This goes well beyond the generic readOnlyHint=false annotation and provides critical operational context.

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-structured with labeled sections (behavior, when to call, when not, auth, visibility). It earns its length given the tool's complexity, though there is slight redundancy (e.g., 'Authenticated' at the start and 'Auth: Bearer' in behavior).

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?

Given the tool's moderate complexity and existing output schema, the description covers all necessary context: purpose, usage, behavior, auth, residency, visibility, and response. An agent can correctly select and invoke this tool without additional information.

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 parameters already have descriptions. The tool description adds semantic depth by explaining what constitutes a good note (concrete evidence vs. speculation), how course_slug and stage_id relate to persistence scoping, and that the response confirms the stage/credit pair. Minor inconsistency (stage_slug vs stage_id) does not undermine clarity.

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 specifies the action ('append a free-text evidence note'), the target ('a specific stage in the caller's active course'), and the purpose (recording concrete observations, decisions, or artefacts). This distinguishes it from sibling tools like me.coaching_context and me.learning_path, which are read-oriented.

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 WHEN TO CALL and WHEN NOT TO CALL sections are provided, including concrete positive and negative examples. It also recommends pairing with me.coaching_context, making the usage context unambiguous and actionable.

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

me.await_steerWait for the Next Cockpit Steer (long-poll)A

Read-onlyIdempotent

Inspect

Pro/Teams. BLOCK until the session owner posts the next steer event to a Governed Session from the AIDB Studio cockpit, then return it. DELIVERY GUARANTEE: the durable cursor read against the session log is authoritative (at-least-once: a lost response is safely re-issuable with the same cursor, and timed_out is only returned after a final confirming read). The in-between wake-up is a best-effort in-process push: usually sub-second, but a steer is never lost if a wake-up is missed; the confirming read catches it. See the after_event_id and timeout_s parameter descriptions for the semantics. THE LOOP: finish a task -> post me.session_event handoff -> call me.await_steer -> on a steer, FIRST post me.session_event event_type=ack ('Started: '), then execute, then handoff, then call me.await_steer again; on timed_out, call again with the returned after_event_id. REQUIRES team mode on the session (toggled by the owner in the web app); owner-scoped, so foreign session ids read as not found. Read-only: this tool never writes events. REJECTION CODES (invalid_request): 'Session not found.' (not yours, or no such id); 'Team mode is off for this session.' (owner enables it on the session page). Auth: sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial plan.

ParametersJSON Schema

Name	Required	Description
`timeout_s`	No	Seconds to wait before returning timed_out. Clamped to 5-240, DEFAULT 45: safe under Claude Code's 60-second first-response-byte timer for HTTP servers. Longer waits require the per-server timeout raised in the MCP client config (e.g. "timeout": 300000 in .mcp.json).
`session_id`	Yes	The Governed Session to watch. Must be YOURS and have team_agents enabled; list sessions via me.sessions.
`after_event_id`	No	Cursor: highest session-event id you have already seen (0 = deliver any existing steer). Pass the value from your previous await_steer result or me.sessions read. Non-destructive at-least-once delivery: re-calling with the same cursor returns the same steers again, so a lost response never loses a steer.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description confirms and extends this: 'Read-only: this tool never writes events.' It adds substantial behavioral context: at-least-once delivery, the durable cursor guarantee, best-effort in-process wake-up, timeout semantics, rejection codes, auth/plan requirements, and owner/team-mode constraints. There is no contradiction with the 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 long but well-structured with capitalized section labels (DELIVERY GUARANTEE, THE LOOP, REJECTION CODES) that make it scannable, and the core blocking behavior is front-loaded in the first sentence. Some redundancy exists: the at-least-once guarantee, safe re-issuance with the same cursor, and timed_out behavior appear both in the delivery-guarantee paragraph and again in the after_event_id parameter description. It earns its length overall, but slightly tighter wording would improve it.

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?

Given the tool's complexity — long-polling, cursors, delivery guarantees, team-mode authorization, and loop integration — the description covers everything an agent needs: when to call, how to handle timeouts, what rejection codes to expect, auth/plan requirements, and the exact handoff/ack pattern. An output schema exists, so return-value details need not be repeated in the description. No material gap remains.

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

Parameters5/5

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

With 100% schema description coverage, the schema already documents all three parameters, but the description materially deepens their meaning. timeout_s is tied to Claude Code's 60-second first-response-byte timer and the need to raise the MCP client timeout in .mcp.json for longer waits. after_event_id is explained as a non-destructive, at-least-once cursor where re-calling with the same cursor returns the same steers again — semantics the schema alone does not convey.

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: 'BLOCK until the session owner posts the next steer event ... then return it.' It clearly identifies this as a long-poll read against a Governed Session, distinguishing it from siblings like me.session_event (which posts handoffs) and me.sessions (which lists sessions). The title 'Wait for the Next Cockpit Steer (long-poll)' reinforces the purpose unambiguously.

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?

The description gives an explicit usage loop: finish task -> post me.session_event handoff -> call me.await_steer -> ack, execute, handoff, then call again. It also says to call again on timed_out with the returned after_event_id, and refers readers to parameter descriptions for semantics. It names related siblings (me.session_event, me.sessions) and explains when they fit into the flow, leaving no ambiguity about how to use this tool versus alternatives.

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

me.coaching_contextGet My Coaching ContextA

Read-onlyIdempotent

Inspect

Authenticated — returns stages in the caller's active course where recorded evidence is thin relative to the stage's principle requirements. Each thin stage carries the missing principle slugs + a short diagnostic so the caller can suggest the user record concrete evidence. WHEN TO CALL: when the user asks 'what should I work on next' or 'what's weak in my Blueprint progress'; before suggesting which guide/example to consult. Pair with me.add_evidence to close gaps. WHEN NOT TO CALL: to lecture the user on principles they have already satisfied; on every conversation turn (state changes only when evidence is added). BEHAVIOR: read-only, idempotent. Auth: Bearer (any plan). Returns thin_stages list with stage slug, course slug, missing principles, evidence_count, and a coaching_note.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

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

The description discloses behavior beyond annotations: 'BEHAVIOR: read-only, idempotent. Auth: Bearer <token> (any plan).' It also explains state-changing semantics ('state changes only when evidence is added'). This complements the readOnlyHint and idempotentHint annotations without contradicting them.

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 longer than average but well-structured with clear sections (main purpose, WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR, Auth, Returns). Every sentence adds value, though the auth and behavior details could be slightly condensed without losing meaning.

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?

Given the tool's complexity (zero parameters, read-only, clear output), the description is complete: it explains the output shape ('thin_stages list with stage slug, course slug, missing principles, evidence_count, and coaching_note'), auth requirements, usage triggers, and when to avoid calling. No critical information is missing.

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?

The tool has zero parameters, so there are no parameter semantics to explain. The description correctly omits parameter details, and the schema trivially covers 100% of parameters. The baseline score of 4 is appropriate for a no-parameter tool.

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 the tool's function: 'returns stages in the caller's active course where recorded evidence is thin relative to the stage's principle requirements.' It uses a specific verb ('returns'), identifies the resource ('stages in the caller's active course'), and differentiates from siblings like me.add_evidence and me.learning_path by focusing on evidence thinness.

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 WHEN TO CALL and WHEN NOT TO CALL sections are provided, including example user queries ('what should I work on next'). It also explicitly names an alternative/complementary tool: 'Pair with me.add_evidence to close gaps.' This is exemplary usage guidance.

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

me.learning_pathGet My Learning PathA

Read-onlyIdempotent

Inspect

Authenticated — returns the caller's Blueprint learning-path state: current course slug, stage progress, certification status (Foundation, Practitioner, Capstone), Capstone track eligibility flags, and the next recommended stage. WHEN TO CALL: the user asks 'where am I', 'what's next', or 'am I Capstone-eligible'; before suggesting next-step coaching content. WHEN NOT TO CALL: as a heartbeat (state changes only when the user completes a stage); to read another user's progress. BEHAVIOR: read-only, idempotent. Auth: Bearer (any plan, including basic). Returns user_email, course_slug, stages list with completion timestamps, certification block, and a next_stage hint.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

The description adds significant behavioral context beyond annotations: it specifies authentication requirements, plan inclusiveness, the condition that state changes only when a stage is completed, and the exact return fields. Annotations already declare read-only and idempotent, but the description enriches with operational details.

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

Conciseness5/5

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

The description is well-organized into labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR, Auth, Returns), each sentence adding distinct value. It is longer than average but every part serves a purpose, and key information is front-loaded in the first sentence.

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?

Given the tool has zero parameters, an output schema, and strong annotations, the description provides complete guidance: purpose, use cases, exclusions, behavior, auth, and output summary. Nothing essential is missing for an agent to invoke it 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?

With zero parameters, the schema is complete (100% coverage) and no parameter descriptions are needed. The description explains the tool's output and invocation context, which is sufficient for a no-argument call.

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 the tool returns the caller's Blueprint learning-path state, listing specific components like current course slug, stage progress, certification status, and next recommended stage. It uses a specific verb ('returns') and a specific resource, distinguishing it from sibling tools like me.sessions or me.coaching_context.

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 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections provide clear usage context, including user intents like 'where am I' and 'am I Capstone-eligible', and exclusions like 'as a heartbeat' and 'to read another user's progress'. This gives the agent actionable guidance on when to select 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.

me.session_eventPost a Team Event to a Governed SessionAInspect

Pro/Teams — append a TYPED TEAM EVENT to a Governed Session's timeline (GEP-M6). This is how the user's own harness makes trio work inspectable: handoffs between role lenses, pushbacks, plan previews, gates, and acks land as structured events next to the validation runs, so the session reads as a system, not a transcript. CHANNEL PROVENANCE: this MCP channel posts the AGENT-SIDE vocabulary only. steer events and actor human are cockpit-originated by contract (the owner posts them from the AIDB Studio session surface) and are REFUSED here, so a timeline entry can never impersonate the human side of the loop. Every event posted here is durably stamped with its channel. REQUIRES team mode: the session must have team_agents enabled (toggled in the web app on the session page); posting to a standalone session is refused so non-team sessions stay byte-identical. Owner-scoped: foreign session ids read as not found. event_type: handoff | pushback | plan_preview | gate | ack. actor: pm | engineer | designer | system. Read events back via me.sessions(session_id=...). WHEN TO CALL: at every role handoff (who -> who, what was passed), when a role pushes back on another's output, when the PM's plan is previewed for the co-planning gate, and when a hard gate blocks on an irreversible side-effect. ack: the IDE agent confirms it STARTED working on a steer. Post it FIRST on receiving a steer (summary like 'Started: '), then execute, then post handoff with the result. WHEN NOT TO CALL: not a chat log: post decisions and transitions, not every message; never to record a steer (steers arrive FROM the cockpit via me.await_steer). REJECTION CODES (invalid_request): 'Session not found.' (not yours, or no such id); 'Team mode is off for this session.' (owner enables it on the session page); 'This session has reached its event limit (500).' (the shared volume brake: start a new session for further team events); 'summary must not be blank.' (empty summaries are refused); steer/human posts are refused with a pointer to the cockpit channel. Auth: sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial plan.

ParametersJSON Schema

Name	Required	Description
`actor`	Yes	Who acted: pm \| engineer \| designer \| system (`human` is reserved for the cockpit channel)
`summary`	Yes	One-to-two sentence event summary (truncated to 500 chars) — a decision or transition, not a chat message.
`event_type`	Yes	handoff \| pushback \| plan_preview \| gate \| ack (ack = started working on a steer; `steer` itself is cockpit-only and refused on this channel)
`session_id`	Yes	The Governed Session to post to. Must be YOURS and have team_agents enabled; list sessions via me.sessions.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

The annotations are all false and convey little, so the description carries the full burden — and delivers extensively: exact rejection messages, refusal of steer/human posts for channel provenance, team-mode requirement, owner-scoping (foreign ids read as not found), the 500-event limit, durable channel stamping, and auth plan requirements. No contradiction with annotations: readOnlyHint=false correctly matches this append-style write operation and destructiveHint=false likewise.

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 dense and long, but section headers (CHANNEL PROVENANCE, REQUIRES team mode, WHEN TO CALL, WHEN NOT TO CALL, REJECTION CODES) make it scannable and the core purpose is front-loaded. It loses a point for restating the event_type and actor enums that already exist in the schema, and the prose could be tightened.

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 write tool with four required parameters, multiple refusal modes, and workflow-integration nuances, nothing an agent needs to invoke it correctly is missing: triggering conditions, ordering with me.await_steer, rejection semantics, read-back via me.sessions, and auth requirements. An output schema exists, so the absence of return-value detail is not a gap.

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

Parameters5/5

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

Though schema coverage is 100%, the description adds operational meaning beyond each field: what makes a valid summary (a decision or transition, not a chat message), what ack specifically means (started working on a steer), why `human` is excluded from actor, and the ownership/team-mode constraints on session_id. The rejection-code section maps each failure to its root cause in the parameters, going well beyond the baseline for high coverage.

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 opens with a precise verb+resource pairing — 'append a TYPED TEAM EVENT to a Governed Session's timeline' — and enumerates the exact event types and actors. It distinguishes itself from siblings by naming me.await_steer as the cockpit source of steers and me.sessions as the read-back channel, so an agent can tell it apart without opening other schemas.

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 WHEN TO CALL and WHEN NOT TO CALL sections spell out triggering situations (role handoffs, pushbacks, plan previews, hard gates, ack on steer receipt) and exclusions (not a chat log; never to record steers, which arrive via me.await_steer). It even sequences the workflow: post ack first, execute, then post handoff with the result.

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

me.sessionsMy Governed SessionsA

Read-onlyIdempotent

Inspect

Pro/Teams — list or inspect the authenticated user's Governed Sessions (GEP-M2): durable, owner-scoped containers that group validation runs across lenses (architect.validate → 'architecture', design.validate → 'surface', spec.validate → 'spec') into one timeline for one piece of work. Two modes: (1) No arguments returns every session (id, title, status, repo_url, spec_ref, team_agents, run_count, validators = the lenses seen), newest first. (2) session_id=<id> returns that session plus its run timeline (light rows; fetch full results per run via me.validation_history(run_id=...)) and, for team sessions, events = the typed team-event log posted via me.session_event. Attach new runs by passing session_id to architect.validate, design.validate, or spec.validate. Sessions are created and managed in the web app at /app/sessions. Read-only. Auth: Bearer . Pro or Teams plan required.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	No	Session id to inspect (returns the session + its run timeline). Owner-scoped: ids you don't own answer 'Session not found.'. Omit to list all your sessions.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds owner-scoping behavior ('ids you don't own answer Session not found'), auth requirements (Bearer token), plan restrictions (Pro/Teams), return shapes for both modes, and events for team sessions. This is substantive behavioral context beyond the annotations, with no contradictions.

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

Conciseness5/5

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

The description is dense but well-structured: it front-loads the purpose with 'Pro/Teams — list or inspect', then uses two numbered modes, field lists, cross-references, and auth/plan requirements. Every sentence contributes to understanding, with no filler except a harmless redundant 'Read-only' phrase.

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?

The description covers modes, returned fields, run timeline details, linking to related tools (validation_history, session_event, validate tools), where sessions are created, authentication, and plan requirements. With an output schema present, it does not need to enumerate return values further; it is complete for a list/inspect tool of this complexity.

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

Parameters3/5

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

The input schema already provides 100% coverage with a detailed description of session_id, including the owner-scoping and 'Session not found' behavior. The tool description repeats this almost verbatim, so it adds no meaningful semantic value beyond the schema. Baseline 3 is appropriate given high schema coverage.

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?

Description explicitly states 'list or inspect the authenticated user's Governed Sessions' with a specific verb and resource, and distinguishes from siblings by defining sessions as durable containers grouping validation runs across lenses (architect.validate, design.validate, spec.validate). It clearly separates itself from me.validation_history, which is referenced for full run results.

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?

Two modes are clearly described: no arguments lists all sessions, while session_id=<id> inspects a specific session with its timeline. It explicitly directs users to me.validation_history for full run results and to the validate tools for attaching new runs, and notes sessions are created/managed in the web app. This provides clear when-to-use and alternative context.

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

me.validation_historyMy Validation History (architecture + design + spec)A

Read-onlyIdempotent

Inspect

Pro/Teams — return the authenticated user's validation run history for all three lenses (architect.validate → validator='architecture', design.validate → validator='surface', spec.validate → validator='spec') with the Blueprint Readiness Score (0-100), letter grade (A-F), and tier (draft, emerging, production_ready). Each run carries a validator field naming its lens. Three lookup modes: (1) run_id=<id> returns a SINGLE run with the full persisted result_json — use this to RECOVER a result when your MCP client tool-call timed out before architect.validate, design.validate, or spec.validate returned. The run completes server-side and persists; the run_id is surfaced in the first progress notification of every validate call so you have the recovery handle even when your client gives up early. (2) repository=<name> returns the full per-run trend for that repository plus a regression diff between the latest two runs. (3) No arguments returns one summary per repository the user has validated, sorted by most recent. Use modes (2) or (3) BEFORE re-validating the same repository on either lens — they tell you which principles or laws regressed since the last run, so you can focus the new review on what is actually changing. Auth: Bearer . Pro or Teams plan required.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of runs to return when scoped to a single repository. Capped at 50. Ignored when `run_id` is provided.
`run_id`	No	Single-run lookup by run_id (UUID). Returns the persisted result_json verbatim — the same payload architect.validate would have returned if your client hadn't timed out. Use this to recover a result when your MCP tool-call closed before the server returned. Per-run authorisation: returns only runs owned by the calling user.
`repository`	No	Repository name or path to scope the history to. Pass the same value you would pass to architect.validate. Omit to get one summary per repository. Mutually exclusive with `run_id` — if both are passed, `run_id` wins.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

The description adds significant behavioral detail beyond annotations: runs complete server-side, run_id is surfaced in the first progress notification, per-run authorization limits to owned runs, regression diff behavior, and sorting. No contradiction with the readOnly/idempotent hints.

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

Conciseness5/5

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

The description is length justified given the tool's three modes and use cases. It is front-loaded with a clear purpose statement, then structures the modes with numbered lists for easy scanning. No redundant or filler sentences.

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?

The description fully covers a complex tool: all modes, recovery workflow, regression analysis, auth, and plan requirements. Since an output schema exists, return-value details are not needed. This is complete for an agent to select and invoke 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% with descriptive parameter texts, so baseline is 3. The description adds value by contextualizing parameters into the three lookup modes and linking run_id to timeout recovery and repository to regression diffs, going beyond mere schema restatement.

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 the tool returns the authenticated user's validation run history for all three lenses, with a specific verb ('return') and resource. It distinguishes itself from sibling validate tools by specifying it is a history/retrieval tool, including the exact validator values for each lens.

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 is provided: use run_id to recover results after a client timeout, and use repository/no-arg modes before re-validating to identify regressions. It also notes Auth requirements and plan limitations, giving clear conditions for appropriate use.

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

principles.getGet PrincipleA

Read-onlyIdempotent

Inspect

Get one doctrine entry by stable slug. The lens selects the doctrine: 'architecture' = one of the 10 agentic principles (default); 'surface' = one of the 8 experience-design laws; 'spec' = one of the 8 spec-quality laws. Returns id, title, cluster, definition, rationale, implications, and risk-if-violated (laws also carry their eponym and validator_questions). Use this when you already have the exact slug from principles.list; prefer principles.search when the user describes a topic or failure mode in natural language; prefer principles.list when you need every entry or every entry within a cluster. Returns error_payload on unknown slug for the lens.

ParametersJSON Schema

Name	Required	Description	Default
`lens`	No	Which public doctrine the slug belongs to: 'architecture' (10 principles, default), 'surface' (8 design laws), or 'spec' (8 spec laws).	architecture
`slug`	Yes	Stable slug of the principle (e.g. 'establish-trust-through-inspectability').

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the safe-read nature is known. The description adds valuable behavioral context by enumerating the return fields (id, title, cluster, definition, rationale, implications, risk-if-violated), noting that laws also carry eponym and validator_questions, and specifying that unknown slugs return an error_payload. This goes beyond the annotation baseline and informs edge-case handling.

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

Conciseness5/5

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

The description is compact and front-loaded with the core purpose, then packs lens semantics, return fields, usage alternatives, and error behavior into three sentences. Every sentence contributes unique value without redundancy, achieving high informational density.

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 simple get-by-slug tool with two parameters, the description covers all necessary context: what the tool returns, how the lens parameter alters selection, when to use it versus alternatives, and how errors are handled. The presence of an output schema further reduces ambiguity, and the description still goes beyond by detailing the content of the response.

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% with descriptive parameter entries, so baseline is 3. The description enriches this by explaining the semantic meaning of each lens value ('architecture' = 10 agentic principles, 'surface' = 8 design laws, 'spec' = 8 spec laws) and by advising users to obtain slugs from principles.list, which is not explicit in the schema. This compensates well for the schema's bare listing.

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 opens with 'Get one doctrine entry by stable slug', clearly stating the verb and resource. It further distinguishes the lens values by naming exactly what each selects (10 agentic principles, 8 experience-design laws, 8 spec-quality laws), and explicitly contrasts with principles.list and principles.search, making it easy to identify the tool's unique role.

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?

The description gives explicit usage instructions: 'Use this when you already have the exact slug from principles.list', and names alternatives: 'prefer principles.search when the user describes a topic or failure mode in natural language; prefer principles.list when you need every entry or every entry within a cluster.' This is textbook when/when-not guidance with specific alternatives.

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

principles.listList PrinciplesA

Read-onlyIdempotent

Inspect

List Blueprint doctrine with stable slugs, titles, and clusters. The lens selects which of the three public doctrines: 'architecture' = the 10 agentic principles (default, the architect.validate rubric); 'surface' = the 8 experience-design laws (the design.validate rubric); 'spec' = the 8 spec-quality laws (the spec.validate rubric). Use this when you need the full inventory or want every entry in one cluster (pass cluster slug to filter). Prefer principles.search when the user describes a topic, failure mode, or keyword in natural language. Prefer principles.get when you already know the exact slug and need full detail.

ParametersJSON Schema

Name	Required	Description	Default
`lens`	No	Which public doctrine: 'architecture' = the 10 agentic principles (default), 'surface' = the 8 experience-design laws, 'spec' = the 8 spec-quality laws.	architecture
`cluster`	No	Cluster slug to filter by (e.g. 'delegation', 'visibility', 'trust', 'orchestration'). Omit to return all principles.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context about lens selection (three doctrines), default behavior (architecture), and the ability to filter by cluster, going beyond structured fields. It doesn't contradict annotations.

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

Conciseness5/5

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

Four sentences, no filler. Front-loaded with the core purpose, then concise details on lens and guidance on alternatives. Every sentence earns its place.

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 simple list tool with rich annotations, output schema, and sibling alternatives, the description fully covers purpose, usage, parameter semantics, and alternatives. No significant gaps.

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 baseline is 3. The description enriches both parameters: explains the lens enum values and maps them to validator rubrics (architect.validate, design.validate, spec.validate), and provides example cluster slugs, thereby adding meaning beyond 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 clearly states 'List Blueprint doctrine with stable slugs, titles, and clusters' with a specific verb and resource. It distinguishes itself from siblings by explicitly naming principles.search and principles.get and describing when each should be used instead.

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?

Provides explicit usage guidance: 'Use this when you need the full inventory or want every entry in one cluster' and explicitly recommends alternatives: 'Prefer principles.search when...' and 'Prefer principles.get when...'.

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

principles.searchSearch PrinciplesA

Read-onlyIdempotent

Inspect

Search Blueprint principles by free-text query and return the closest matches ranked by relevance. Use this to find principles related to a specific design challenge, failure mode, or keyword (e.g. 'reversibility', 'approval flow', 'delegation boundary'). Returns principle title, cluster, definition, rationale, and implementation heuristics. Prefer this over principles.list when you have a specific topic in mind rather than wanting all principles. The lens picks the doctrine searched: 'architecture' = the 10 agentic principles (default), 'surface' = the 8 experience-design laws, 'spec' = the 8 spec-quality laws, 'all' = all 26 (each result then names its lens). Laws also match on their eponym (e.g. 'Hick', 'Fitts').

ParametersJSON Schema

Name	Required	Description	Default
`lens`	No	Which public doctrine to search: 'architecture' = the 10 agentic principles (default), 'surface' = the 8 experience-design laws, 'spec' = the 8 spec-quality laws, 'all' = all three.	architecture
`limit`	No	Maximum number of results to return. Capped at server maximum.
`query`	Yes	Free-text search query matched against principle title, definition, rationale, and cluster.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds useful behavioral context: the results are 'ranked by relevance', it returns specific fields (title, cluster, definition, rationale, implementation heuristics), and for the 'all' lens each result 'names its lens'. This goes beyond annotations without contradicting them.

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 a single paragraph that front-loads the core purpose, then adds usage guidance, return details, and lens semantics. It's slightly long but every sentence adds information an agent needs. No fluff or repetition of schema details. The structure is logical and scannable.

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?

Given the tool's moderate complexity, the presence of a full input schema, output schema, and annotations, the description is complete. It covers what the tool does, when to use it, how the lens works, what the results include, and the eponym matching behavior. Nothing an agent needs to call it correctly is missing.

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 schema already documents all three parameters. The description adds value by clarifying the lens semantics (e.g., 'architecture' = the 10 agentic principles, default) and by noting that queries also match on eponyms ('Hick', 'Fitts'). This enriches the meaning of the query parameter beyond the schema's generic description.

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 ('Search'), a specific resource ('Blueprint principles'), and the action ('by free-text query and return the closest matches ranked by relevance'). It explicitly distinguishes itself from the sibling 'principles.list' by stating when to prefer it, making it easy for an agent to tell them apart 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.

Usage Guidelines5/5

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

The description gives explicit guidance: 'Prefer this over principles.list when you have a specific topic in mind rather than wanting all principles.' It also explains how the 'lens' parameter selects the doctrine, provides example queries, and notes that laws match on eponyms. This is clear, actionable usage context with no ambiguity.

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

signals.feedbackSubmit FeedbackAInspect

Public — records explicit free-text user feedback about the Blueprint, this tool surface, or a specific principle/example. Captures category (bug, doctrine_critique, missing_example, ergonomics, other), free-text body, and optional contact_email when permission_to_follow_up is true. WHEN TO CALL: ONLY when the user explicitly says they want to give feedback (e.g. 'can you log this as feedback', 'file this critique', 'send a bug report'). Use signals.report instead for value-moment metrics (rating validate's output 1-5). WHEN NOT TO CALL: proactively, silently, or to substitute for signals.report. Never harvest contact info without explicit permission_to_follow_up=true. BEHAVIOR: write-only, no auth required (open to all callers). Stores one feedback record, at rest under UK/EU residency. contact_email is stored ONLY when permission_to_follow_up=true, and that fact is confirmed back in the response so the user can see the privacy boundary. When permission_to_follow_up=true AND a valid contact_email is given, and only then, it also opens a support inbox item so a human can reply, and the free-text fields are sent to OpenAI for triage (severity and a short summary). The contact_email field is never part of that request, so keep personal data out of the free text. In every other case nothing leaves the server.

ParametersJSON Schema

Name	Required	Description
`surface`	No	Which Blueprint surface the feedback is about. Use 'mcp' if the session was via Claude Code or another MCP client. Use 'principles', 'examples', 'guides', 'coaching', or 'validation' based on what the user interacted with.
`task_type`	No	What the user was doing when they decided to give feedback. Use plain English — e.g. 'code-review', 'architecture-design', 'agent-setup', 'onboarding', 'validation'. Infer from context.
`what_helped`	No	Ask the user: 'What was most helpful?' Record their answer verbatim or paraphrased in plain English. Max 1000 chars. No code snippets, no proprietary content.
`what_missing`	No	Ask the user: 'What was missing or could be improved?' Record their answer verbatim or paraphrased. Max 1000 chars.
`contact_email`	No	Only ask for this if the user explicitly says they want a follow-up response. Never prompt for email unprompted. Only stored when permission_to_follow_up=true.
`rating_clarity`	No	Ask the user: 'How clear was the Blueprint guidance? Rate 1–5.' 1 = very unclear, 5 = very clear. Only set if the user gives an explicit number.
`would_use_again`	No	Ask the user: 'Would you use the Blueprint again for a similar task?' Set true/false based on their answer. Only set if they answer explicitly.
`rating_usefulness`	No	Ask the user: 'How useful was the Blueprint for this task? Rate 1–5.' 1 = not useful, 5 = very useful. Only set if the user gives an explicit number.
`permission_to_follow_up`	No	Set to true only if the user explicitly said they want a follow-up. Must be confirmed before storing contact_email.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.8/5.0

Behavior5/5

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

The description adds rich behavioral disclosure beyond the sparse annotations: write-only, no auth required, single feedback record stored under UK/EU residency, contact_email stored only with explicit permission and confirmed back to the user, support inbox creation and OpenAI triage only when permission plus a valid email are present, and personal data excluded from the OpenAI request. This aligns with readOnlyHint=false and idempotentHint=false and gives the agent a clear safety profile.

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 well-structured with labeled WHEN/BEHAVIOR sections and front-loads the core purpose. It is fairly long and repeats the permission_to_follow_up condition multiple times, and the 'category (bug, doctrine_critique, ...)' list does not correspond to any input-schema field, adding noise. Still, most sentences carry useful guidance for an agent.

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?

Given nine optional parameters, an output schema, and the sensitive data-handling behavior, the description is complete: it covers when to call, when not to call, auth, storage residency, follow-up workflow, privacy boundaries, and the sibling to prefer instead. The category/free-text mismatch is a terminology issue rather than a missing capability, and the output schema covers return-value details.

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 meaningful semantics: the conditional relationship between permission_to_follow_up and contact_email, the rule that contact_email never leaves with the OpenAI triage request, and the instruction to keep personal data out of the free-text fields. It doesn't enumerate each parameter, but it clarifies the privacy-sensitive interactions that the schema alone states more tersely.

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 opens with a specific verb and resource: 'records explicit free-text user feedback about the Blueprint, this tool surface, or a specific principle/example.' It also explicitly contrasts this tool with signals.report by distinguishing feedback capture from value-moment metrics, so an agent can tell the siblings apart without inspecting schemas. The only minor wrinkle is the mention of a 'category' and 'free-text body' that don't map cleanly to the schema's actual fields, but the overall purpose is unambiguous.

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?

The 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections are explicit: call only when the user explicitly requests feedback capture, use signals.report for 1-5 value-moment ratings, and never call proactively, silently, or as a substitute for the sibling. It also states a hard privacy rule about permission_to_follow_up before collecting contact info, which is exactly the kind of conditional an agent needs.

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

signals.reportReport Value EventAInspect

Pro/Teams — records a value moment (e.g. review_confidence, runtime_risk_found, workflow_clarity) after a successful validate run on any lens — architect.validate, design.validate, or spec.validate — or a doctrine session. Each event captures event_type, surface_used (mcp/web/cli), perceived_value (1-5), and an optional brief_context — structured fields only, NO prompts or code stored. WHEN TO CALL: after architect.validate, design.validate, or spec.validate returns a clearly useful result AND the user has acknowledged the value (or you ask them "would you rate this 1-5?"). Each validator's response carries an explicit next_step instruction telling the agent to OFFER this call — surface that offer to the user. WHEN NOT TO CALL: silently or without the user's awareness; on every validate (only after a clear value moment); to capture intent or speculative value. If the user declines, do not retry within the same session. BEHAVIOR: write-only, single insert into ValueEvent. Auth: Bearer , Pro or Teams plan required. UK/EU residency. Do NOT include proprietary code, prompt content, or PII in brief_context — it surfaces in admin AI-visibility dashboards. Expect a 1-line acknowledgment in the response; the structured feedback is then aggregated server-side.

ParametersJSON Schema

Name	Required	Description
`team_size`	No	If the user mentions their team size during the session, record it here. Do not ask for it explicitly — only capture if volunteered.
`event_type`	Yes	Pick the type that best matches what just happened: 'review_confidence' — a validator lens (architect.validate / design.validate / spec.validate) returned aligned; 'runtime_risk_found' — a validate run found violations; 'workflow_clarity' — principles/examples clarified a design decision; 'agent_setup_success' — user successfully wired up an agent or MCP tool; 'onboarding_helped' — user understood how to start using the Blueprint; 'research_time_saved' — user found relevant doctrine faster than expected; 'team_alignment' — Blueprint helped align a team on agentic design; 'other' — use only if none of the above fit.
`surface_used`	No	Where the value was experienced. Use 'mcp' when called from Claude Code, Cursor, Windsurf, or any MCP client. Use 'principles' if the user was browsing or searching principles. Use 'examples' if the user was reading implementation examples. Use 'for-agents' if the user came via the /for-agents page. Use 'learn' or 'certification' for course-related sessions.
`brief_context`	No	1–2 plain-English sentences summarising what was helpful. Example: 'Validation identified a missing approval gate before email send.' No code snippets, no proprietary content, no user PII. Max 500 chars.
`workflow_stage`	No	Infer from what the user was doing: 'exploring' — reading doctrine, browsing principles; 'designing' — planning architecture or agent flows; 'implementing' — writing or refactoring code; 'reviewing' — running a validator lens on existing code, a surface, or a spec; 'shipping' — preparing for production or deployment.
`perceived_value`	No	Ask the user: 'On a scale of 1–5, how valuable was this session?' Map their answer directly: 1=low, 5=high. Do not guess — only set this if the user gave an explicit score.
`would_recommend`	No	Ask the user: 'Would you recommend the Blueprint to a colleague?' Set true/false based on their answer. Only set if asked — do not assume.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.9/5.0

Behavior5/5

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

The description goes far beyond the sparse annotations (all false). It discloses the write-only, single-insert behavior, auth requirements (Bearer token, Pro/Teams plan), UK/EU residency, the exclusion of code/PII from brief_context, and the exact response format (1-line acknowledgment). This fully informs the agent of side effects and constraints.

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

Conciseness5/5

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

The description is lengthy but tightly organized into labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loaded with the core purpose. Every sentence conveys a distinct requirement or constraint; there is no filler or repetition. The structure improves scannability despite the length.

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?

Given the tool's complexity (7 optional parameters, sensitive data restrictions, multiple call contexts) and the existence of an output schema, the description is complete. It covers auth, data handling, response behavior, and privacy rules, leaving no critical gap for an agent to misuse the tool.

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?

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra semantics for key parameters, such as interpreting event_type examples, clarifying that perceived_value must be explicitly requested and not guessed, and mapping surface_used to contexts like 'mcp' for MCP clients. It does not cover every parameter, but the schema does, and the added value is meaningful.

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 the tool records a value moment after a successful validate run or doctrine session, with explicit examples of event types. It distinguishes itself from sibling tools like signals.feedback by specifying the exact triggering conditions (after architect.validate, design.validate, spec.validate) and the optional nature of the capture.

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?

Provides explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, including the requirement to offer the call after a validator's next_step instruction, not to call silently, not to call on every validate, and not to retry if declined. This leaves no ambiguity about appropriate usage.

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

spec.validateValidate Specification QualityAInspect

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).

ParametersJSON 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

ParametersJSON Schema

Name	Required	Description
No output parameters

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.

team.summarizeSummarize Team UsageA

Read-onlyIdempotent

Inspect

Pro/Teams — summarises the caller's tool-usage patterns and value signals over a configurable window (default 30 days). Returns tool_call_counts, top principles cited in validate runs, value_event_counts by event_type, and an aggregate readiness trend. WHEN TO CALL: the user asks 'how is the Blueprint helping me/my team', 'what should I explore next', or 'show me my Blueprint usage'. WHEN NOT TO CALL: proactively or on every conversation turn (the summary is an explicit retrospective, not telemetry); to compare users (returns only the caller's own data). BEHAVIOR: read-only, idempotent over the same window. Aggregates from AIToolCallLog + ValueEvent + AIValidationRunLog. Pass private_session=true to bypass server-side logging for this summary call (the underlying historical data still exists; only this read is untracked). Auth: Bearer , Teams plan only; Pro and beta plans are refused. UK/EU residency.

ParametersJSON Schema

Name	Required	Description	Default
`days_back`	No	Number of days of usage history to include in the summary.
`private_session`	No	Set to true to skip logging this summary call.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description goes beyond these by revealing data sources (AIToolCallLog, ValueEvent, AIValidationRunLog), the private_session logging bypass behavior, authentication requirements, plan restrictions (Teams only, Pro/beta refused), and residency constraints (UK/EU). No contradictions 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 longer than average but well-structured with clear section headers (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR). It is front-loaded with the core purpose and each sentence provides distinct value. Slightly verbose, but every part serves a purpose; the structure earns a 4.

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 this complexity — aggregation from multiple logs, auth, plan gating, residency, and a private_session flag — the description covers every aspect an agent needs to call it correctly. An output schema exists for return values, so those are covered. Nothing is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters are fully documented in the schema itself. The description adds marginal context (e.g., that private_session doesn't delete underlying data), but it largely repeats what the schema already provides. Per calibration, a 3 is appropriate when the schema carries the burden.

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 ('summarises') and a clear resource ('the caller's tool-usage patterns and value signals over a configurable window'). It enumerates the exact return fields and explicitly differentiates itself from any sibling by noting it returns only the caller's own data, which rules out comparison use cases.

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?

The description includes explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, providing concrete example user queries ('how is the Blueprint helping me/my team') and clear exclusions (proactive calls, every turn, comparing users). This is textbook usage guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updateSep 23, 2026

Changedprinciples.search1 field changed

addedInput schema / properties / lens

Added value: +{
+  "default": "architecture",
+  "description": "Which public doctrine to search: 'architecture' = the 10 agentic principles (default), 'surface' = the 8 experience-design laws, 'spec' = the 8 spec-quality laws, 'all' = all three.",
+  "enum": [
+    "architecture",
+    "surface",
+    "spec",
+    "all"
+  ],
+  "title": "Lens",
+  "type": "string"
+}

3 tool updatesSep 20, 2026

Changedarchitect.validate1 field changed

changedInput schema / properties / private_session / description

Previous value: -"Set to true to disable logging AND prior-run anchoring AND run_id recovery for this call. Use for private one-shots that don't participate in the iteration arc. Default false."New value: +"Set to true to skip the stored run AND prior-run anchoring AND run_id recovery for this call. Operational security and cost logs are still kept, per the Privacy Policy. The request is also not persisted in the model provider's response store; the provider's abuse-monitoring retention still applies. Use for private one-shots that don't participate in the iteration arc. Default false."

Changeddesign.validate1 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."

Changedspec.validate1 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."

1 tool updateJul 28, 2026

Changedexamples.search1 field changed

addedInput schema / properties / pattern_family

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "tools-actions",
+        "reasoning-reflection",
+        "retrieval",
+        "memory",
+        "sampling-search",
+        "multi-agent",
+        "safety-routing",
+        "specialty"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Filter to one agentic-pattern family. Implies patterns only, since no upstream cookbook example carries a family.",
+  "title": "Pattern Family"
+}

2 tool updatesJul 24, 2026

Changedprinciples.get1 field changed

addedInput schema / properties / lens

Added value: +{
+  "default": "architecture",
+  "description": "Which public doctrine the slug belongs to: 'architecture' (10 principles, default), 'surface' (8 design laws), or 'spec' (8 spec laws).",
+  "enum": [
+    "architecture",
+    "surface",
+    "spec"
+  ],
+  "title": "Lens",
+  "type": "string"
+}

Changedprinciples.list1 field changed

addedInput schema / properties / lens

Added value: +{
+  "default": "architecture",
+  "description": "Which public doctrine: 'architecture' = the 10 agentic principles (default), 'surface' = the 8 experience-design laws, 'spec' = the 8 spec-quality laws.",
+  "enum": [
+    "architecture",
+    "surface",
+    "spec"
+  ],
+  "title": "Lens",
+  "type": "string"
+}

7 tool updatesJul 19, 2026

Changedarchitect.validate1 field changed

addedInput schema / properties / session_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "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.",
+  "title": "Session Id"
+}

Addeddesign.validate
Addedme.await_steer
Addedme.session_event
Addedme.sessions

Changedsignals.report2 fields changed

changedInput schema / properties / event_type / description

Previous value: -"Pick the type that best matches what just happened: 'review_confidence' — architect.validate returned aligned; 'runtime_risk_found' — architect.validate found violations; 'workflow_clarity' — principles/examples clarified a design decision; 'agent_setup_success' — user successfully wired up an agent or MCP tool; 'onboarding_helped' — user understood how to start using the Blueprint; 'research_time_saved' — user found relevant doctrine faster than expected; 'team_alignment' — Blueprint helped align a team on agentic design; 'other' — use only if none of the above fit."New value: +"Pick the type that best matches what just happened: 'review_confidence' — a validator lens (architect.validate / design.validate / spec.validate) returned aligned; 'runtime_risk_found' — a validate run found violations; 'workflow_clarity' — principles/examples clarified a design decision; 'agent_setup_success' — user successfully wired up an agent or MCP tool; 'onboarding_helped' — user understood how to start using the Blueprint; 'research_time_saved' — user found relevant doctrine faster than expected; 'team_alignment' — Blueprint helped align a team on agentic design; 'other' — use only if none of the above fit."

changedInput schema / properties / workflow_stage / description

Previous value: -"Infer from what the user was doing: 'exploring' — reading doctrine, browsing principles; 'designing' — planning architecture or agent flows; 'implementing' — writing or refactoring code; 'reviewing' — running architect.validate on existing code; 'shipping' — preparing for production or deployment."New value: +"Infer from what the user was doing: 'exploring' — reading doctrine, browsing principles; 'designing' — planning architecture or agent flows; 'implementing' — writing or refactoring code; 'reviewing' — running a validator lens on existing code, a surface, or a spec; 'shipping' — preparing for production or deployment."

Addedspec.validate

2 tool updatesMay 22, 2026

Changedarchitect.validate2 fields changed

changedInput schema / properties / private_session / description

Previous value: -"Set to true to disable all logging for this validation call."New value: +"Set to true to disable logging AND prior-run anchoring AND run_id recovery for this call. Use for private one-shots that don't participate in the iteration arc. Default false."

changedInput schema / properties / repository / description

Previous value: -"Repository name or path for additional context."New value: +"Iteration key. SAME value across calls auto-resolves the most recent prior run as `prior_run_baseline` for iteration-aware grading (per-principle severity deltas, regressions/improvements). CHANGING the value (even subtly with an `iter-2` suffix) silently severs the chain and yields a fresh blind first-shot. Round numbering belongs in `task`, not here. Empirical evidence of why anchoring matters: PR #157 iter1 33/F vs iter2 100/A on byte-identical baseline-race primitives (+67 spread); invoice-payment-manager #158 38/F vs #159 74/C (+36 spread) — same code, score variance from non-deterministic LLM at reasoning_effort=high; the baseline anchor collapses this onto a stable arc."

Changedarchitect.validate_consensus1 field changed

changedInput schema / properties / repository / description

Previous value: -"Repository name or path. Lets the consensus row group into the per-project history view alongside single-shot validate runs."New value: +"Iteration key. Consensus children all run unanchored (`private_session=True`), but the consolidated row IS persisted under this key — discoverable as prior baseline for the next single-shot `architect.validate`. Same value across calls keeps the iteration arc inspectable."

24 tool updatesMay 9, 2026

Changedarchitect.certify1 field changed