Public agentic AI doctrine tools plus authenticated architecture, design, and spec validators.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.8/5 across 29 of 29 tools scored.
Each tool has a clearly distinct purpose within its domain: the validators are differentiated by lens (architect/design/spec), content tools are split by entity (principles/clusters/guides/examples/assets) with list/get/search variants, and even the me.* and handoffs.* tools have non-overlapping functions. The only near-overlap (architect.validate vs architect.validate_consensus) is explicitly disambiguated by the consensus variant's description.
Tool names consistently use a domain prefix (architect., principles., me., etc.) and snake_case throughout. While most are action-oriented (validate, list, get, search, add, await, report, summarize), some me.* and handoffs.* names are noun phrases (me.learning_path, handoffs.agency) that don't signal the action as clearly, creating minor deviation from a pure verb_noun or action pattern.
At 29 tools, the set is heavy but justified by the server's broad multi-domain scope (doctrine, validation, learning, support, and team analytics). Each tool has a distinct role, but the number exceeds the typical well-scoped range, and some content types (e.g., examples) could have been consolidated without losing function.
The server covers its apparent domains thoroughly: doctrine content has list/get/search for most entity types, validation covers architecture/design/spec with consensus and certification, and user learning/support have appropriate tools. Minor gaps exist—e.g., examples have no list-all endpoint, and session management is web-only—but none are blocking for core workflows.
architect.certifyCertify Production-Ready ArchitectureAInspectPro/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 20-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 20 min, ~5× observed max). 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.
| 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). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-idempotent, non-read-only behavior, and the description massively expands on this: atomic one-shot execution, 60-180s runtime, client-timeout risk, retry-budget consumption, fingerprint-mismatch rejection, and side effects like badge minting or downgrade. No annotation contradiction exists; idempotentHint=false matches 'NOT idempotent across attempts.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded section headers and front-loads the most critical timeout/recovery warning. However, it is extremely long and contains some redundancy (repeated recovery-path guidance) and tangental audit-trail context that could be trimmed without losing essential usage information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity, non-idempotent behavior, retry budget, and failure modes, the description is remarkably complete: it enumerates typed rejection reasons, eligibility gates, payload-completeness rules, outcome enum values, recovery paths, and data-residency/transient-processing notes. The output schema exists, and the description still explains the returned certification_status variants, so an agent has full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (run_id, code), but the description adds critical parameter semantics: code must be the exact code that produced the run_id, may be omitted under the 24h cert-retry hold, and must be payload-complete with stubs for imported modules. It also clarifies run_id provenance and ownership requirements, going well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'second-pass adversarial certification of an architect.validate run that scored production_ready.' It further distinguishes itself by naming the sibling flow and the badge outcome, so an agent can immediately tell this is not validate or validate_consensus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit 'WHEN TO CALL' section with precise preconditions ('only after architect.validate returned tier=production_ready AND...') and explicit non-conditions ('NOT for tier=draft/emerging/not_applicable runs'). It also provides a canonical recovery path for timeouts and alternatives via me.validation_history, making usage boundaries clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
architect.validateValidate Agent ArchitectureAInspectPro/Teams — first-pass doctrine review of agentic code/workflow against the 10-principle Agentic AI Blueprint. 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 20-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 20 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: Bearer , Pro/Teams 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations: it discloses 60-180s latency, retry hazards, server-side 20-min budget, keepalive/run_id behavior, persistence/rollback effects, score variance (~20-67 pts), privacy defaults, and auth/residency constraints. It even explains the MCP task-augmented execution path and timeout recovery. No annotation contradiction; additions are consistent with the side-effectful, non-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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally long, but it is front-loaded with purpose and the most safety-critical warning (timeout/retry), uses labeled sections, and nearly every sentence carries operational content. It is not concise in word count, but it is well-structured and dense enough that the length is largely earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers invocation, recovery, output fields, failure types, iteration semantics, verification layers, and next steps; the presence of an output schema means return-value detail is not required. This is as complete as a tool description can reasonably be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds critical parameter semantics: implementation_context must be verbatim full code (no ellipses), repository is an iteration key that must remain stable, private_session disables recovery, and the MCP tasks capability is distinguished from the tool argument. This meaningfully exceeds the baseline schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific action ('first-pass doctrine review') on a specific resource ('agentic code/workflow') against the 10-principle Agentic AI Blueprint, and explicitly contrasts itself with architect.certify's second pass. This clearly distinguishes the tool from siblings like architect.validate_consensus and architect.certify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, directs non-agentic code away from this tool, and names alternatives: validate_consensus for stability, certify for the next step, and validation_history for timeout recovery. This is textbook usage guidance with exclusions and alternatives.
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)AInspectPro/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: Bearer , Pro/Teams 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).
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations: it discloses the ~80-120s wallclock time, warns against retrying on client timeout, explains the recovery path via `me.validation_history`, details `private_session=True` behavior (children do not persist; the consolidated row does), notes cost and auth requirements, and lists typed failures including the consensus-specific `consensus_quorum_failed`. This is exceptionally transparent behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely packed and well-sectioned, with each sentence adding operational value: timeout recovery, invocation criteria, chain resume, behavior, auth, inputs, outputs, and failures. It is front-loaded with the most urgent caveat (do not retry on timeout), and the structured sections make navigation easy despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (N parallel LLM calls, persistence, aggregation, failure modes), the description is exceptionally complete. It covers inputs, outputs (including specific fields like `score_consensus_median` and `representative_response`), recovery, cost, and integration with sibling tools. The existence of an output schema reduces the need to describe return values, but the description still enriches it with the semantics of each field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 100% coverage, the description adds critical semantics: it explains that `n` is capped server-side (default 5) despite the schema's max of 10, clarifies that `private_session` is implicit for children, and explains `repository` as the iteration key that makes the consolidated row discoverable as a future baseline. It also reinforces the `implementation_context` requirement to send file contents verbatim. This adds meaning well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: 'N-shot CONSENSUS doctrine review of agentic code' and explicitly contrasts with the sibling `architect.validate`: single-shot re-asserts prior persisted runs via baseline-anchor injection, while consensus mode is the unanchored honest read. It clearly indicates the tool runs N parallel `architect.validate` calls and aggregates them into a structured consensus verdict, making its purpose and scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, naming the exact alternative (`architect.validate`) and the conditions that favor each. It even explains the chain-resume behavior and how the next single-shot call uses the consensus result as a baseline, providing concrete, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
assets.listList Agent AssetsAPublic — 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 ClusterAGet 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.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the principle cluster (e.g. 'delegation', 'visibility', 'trust', 'orchestration'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 ClustersAList 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 DesignAInspectPro/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: Bearer , Pro/Teams 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).
| Name | Required | Description | Default |
|---|---|---|---|
| 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). 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses long-running LLM call (~60-180s), timeout retry behavior with run_id recovery, persistence/private_session tradeoffs, typed failure envelopes, accessibility floor as production_blocker, and calibration limitations. These details go well beyond the annotations, which are only false/true flags; no contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is substantial but organized with labeled sections and front-loaded with the core purpose and sibling distinction. Some operational details (auth, residency) could be trimmed, but the structure keeps it navigable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity — 7 params, long-running behavior, output semantics, and edge cases — the description covers returns (surface_classification, per-law findings, readiness), non-UI handling (not_applicable not failed), typed failures, and even scorer alignment with architect.validate. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial semantics: implementation_context must be full verbatim source, repository groups runs under the 'surface' dimension, private_session disables persistence/recovery, and session_id must reference an owned session (foreign ids refused). This meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool performs 'first-pass surface-craft review of a FRONTEND artefact ... against the 8 laws of the Experience Design Blueprint', clearly distinguishing from architect.validate by contrasting 'PERCEPTIBLE SURFACE' vs 'agentic ARCHITECTURE'. Verb and resource are specific, and the scope is defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections tell the agent when to use the tool (craft/UX/accessibility review of frontend) and when not (non-visual code). It also names architect.validate as the architecture lens, guiding selection between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
examples.getGet ExampleAGet 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.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the curated example (e.g. 'agents-building-blocks-5-control'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 ExamplesASearch 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 GuideAGet 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.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the application guide (e.g. 'security-application', 'observable-evaluation'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 GuidesAList 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 GuidesASearch 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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 HandoffAInspectAuthenticated — 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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 HandoffAInspectAuthenticated — 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.
| 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'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 HandoffAInspectAuthenticated — 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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 NoteAInspectAuthenticated — 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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)APro/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: Bearer , Pro/Teams plan.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by explaining the durable cursor read, at-least-once delivery, the confirming read for timed_out, and the best-effort in-process wake-up. It also discloses rejection codes, auth requirements, and the read-only nature, all of which align with readOnlyHint=true and idempotentHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections (overview, delivery guarantee, loop, requirements, rejection codes). Every sentence provides essential operational context for a complex long-poll tool, so it earns its place. It is slightly dense but appropriately sized for the behavior it documents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (long-poll, delivery guarantees, session ownership, plan requirements), the description is exceptionally complete. It covers the purpose, usage loop, prerequisites, error codes, auth, and timeout semantics. An output schema exists, so return-value details are not the description's responsibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The tool description adds further value by integrating after_event_id and timeout_s into the usage loop, explaining the cursor semantics, and directing the agent to the schema for full details. This incremental context justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'BLOCK until the session owner posts the next `steer` event to a Governed Session from the AIDB Studio cockpit, then return it.' It clearly distinguishes itself from sibling tools by highlighting its read-only, long-poll nature and explicitly stating it never writes events, unlike me.session_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit 'THE LOOP' workflow that tells the agent exactly when to call this tool and how to sequence it with me.session_event. It also covers exclusions (e.g., owner-scoped, foreign session ids read as not found) and gives handling instructions for timed_out responses, including an alternative action (call again with the returned after_event_id).
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 ContextAAuthenticated — 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 PathAAuthenticated — 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 SessionAInspectPro/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: Bearer , Pro/Teams plan.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false, openWorld=false, idempotent=false, destructive=false. The description goes far beyond this: it discloses that steer/human posts are refused, that team mode must be enabled, that foreign session ids read as not found, that there's a 500-event limit, that blank summaries are refused, and that auth requires Pro/Teams. It also explains the channel provenance (agent-side vocabulary only). No contradiction with annotations; the description enriches the safety/behavioral profile enormously.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but clearly structured with sections (purpose, channel provenance, requirements, when to call, when not to call, rejection codes). It front-loads the core purpose first. However, some parts are verbose (e.g., repeating 'the owner posts them from the AIDB Studio session surface' could be shorter) and there's a slight over-explanation of mechanics. Still, for a tool with this complexity, the length is mostly justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-complexity tool with a rich schema, output schema, and annotations, and the description leaves nothing unclear. It covers the full context: why to use it (making trio work inspectable), lifecycle (post ack first, then handoff), error handling (rejection codes with conditions), auth requirements, team mode requirement, and relationship to cockpit/await_steer. Taking the output schema into account, the description is complete for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that `actor` 'human' is reserved for the cockpit channel, `event_type` 'ack' means 'started working on a steer', the `summary` should be a decision/transition (not chat) and is truncated to 500 chars, and `session_id` must be yours and team-enabled. This extra context pushes it above baseline, though a few details are already embodied in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'append a TYPED TEAM EVENT to a Governed Session's timeline'. It clearly defines what the tool does (posting structured handoffs, pushbacks, gates, etc.), lists allowed event types and actors, and distinguishes this agent-side channel from cockpit-originated `steer` events by naming `me.await_steer` as the source. This fully differentiates it from sibling tools like handoffs.* and me.sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'WHEN TO CALL' (every role handoff, pushback, plan preview, gate, ack on steer) and 'WHEN NOT TO CALL' (not a chat log, never record steers). It also gives direct alternatives: 'Read events back via me.sessions' and 'steers arrive FROM the cockpit via me.await_steer'. This is textbook usage guidance with exclusions and alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
me.sessionsMy Governed SessionsAPro/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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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)APro/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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 PrincipleAGet 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.
| 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'). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 PrinciplesAList 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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 PrinciplesASearch 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. NOTE: search currently covers the 10 agentic principles only; for the 8 experience-design laws or the 8 spec-quality laws use principles.list(lens='surface') / principles.list(lens='spec') until search spans all three lenses.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only and idempotent behavior; the description adds crucial behavioral context: the current scope limitation to 10 agentic principles and the exact alternative calls for the other lenses. It also discloses the return fields and ranking behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, front-loaded with the main purpose, and every sentence contributes value: function, examples, alternative guidance, and a scope note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, output schema, and annotations, the description is complete: it explains what the tool does, when to use it, what it returns, and its current limitations. It fully equips an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters, including descriptions of what the query matches and limit behavior. The description reinforces the query semantics with examples but does not add essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('search'), resource ('Blueprint principles'), and behavior ('return the closest matches ranked by relevance'). It also explicitly distinguishes itself from principles.list, making the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Prefer this over principles.list when you have a specific topic in mind', and also gives a when-not-to-use with specific alternatives for other lenses. Concrete examples of queries enrich the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
signals.feedbackSubmit FeedbackAInspectPublic — 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), single insert into UserFeedback. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses write-only behavior, no auth required, a single insert into UserFeedback, UK/EU residency, and the privacy boundary for contact_email. These traits go beyond the sparse annotations (all false hints) and inform the agent about 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loaded purpose. It is longer than necessary and repeats the contact_email privacy condition twice, but every section carries useful guidance, so minor redundancy prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 9 optional parameters and an output schema, the description covers when to call, behavior, privacy, and regulatory context. It does not need to explain return values because an output schema exists. This is a complete and appropriately rich description for a feedback tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 9 parameters at 100% coverage, so baseline is 3. However, the description references 'category' and 'free-text body' which do not match any schema field, creating potential confusion. It repeats the contact_email privacy rule already present in the schema, adding no new parameter value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it records explicit free-text user feedback about the Blueprint, tool surface, or a principle/example. It uses a specific verb and resource, and immediately distinguishes itself from signals.report, a sibling tool for metrics. The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO CALL' section is explicit with examples, and the 'WHEN NOT TO CALL' section clearly prohibits proactive or silent invocation and substituting for signals.report. It names the alternative tool and provides concrete guidance, which is exactly what an agent needs to select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
signals.reportReport Value EventAInspectPro/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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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 QualityAInspectPro/Teams — first-pass specification-quality review of a WRITTEN SPEC (proposal, design doc, task breakdown, or an OpenSpec-style change bundle) against the 8 laws of the Spec Quality Blueprint. The what-to-build lens of the doctrine trio, applied BEFORE code exists: where architect.validate scores built agentic ARCHITECTURE and design.validate scores the rendered SURFACE, spec.validate scores the written intent the team will build from (outcome framing, scope boundary, testable acceptance, decision trail, handoff completeness, doctrine-upfront, task traceability, risk and reversibility). ON CLIENT TIMEOUT — DO NOT RETRY. Long-running LLM call (~60-180s at high reasoning effort, single-pass). The server mints a run_id, emits it in the FIRST progress event at t=0s (before the LLM call), and persists the run — so on a client timeout, capture that run_id and call me.validation_history(run_id='') to fetch the persisted result instead of retrying (a retry re-runs the full 60-180s call). Runs appear in your validation-history dashboard tagged as the 'spec' dimension, distinct from the 'architecture' and 'surface' runs; pass repository to group them per project. Pass private_session=true to skip the stored run (persistence + recovery disabled); operational security + cost logs are still kept. v1 is single-pass: no certification or consensus mode yet (those stay architect.validate-only). Returns spec_classification (spec_document vs non_spec — source code or UI artefacts are marked not_applicable, NOT failed; submit those to architect.validate or design.validate instead), per-law findings (verdict, severity_score 0-100, severity_class, cited evidence, recommendation), and severity-weighted readiness (score, grade, tier) computed by the SAME scorer the other two lenses use, so all three grade on one rubric. TESTABILITY IS THE FLOOR: a load-bearing requirement with no observable acceptance signal, or an irreversible step with no named human gate, is a production_blocker, not polish. WHEN TO CALL: the user wants a governance/quality review or a readiness grade on a spec they are about to build from (proposal, requirements, task plan). WHEN NOT TO CALL: built code or a rendered surface — those return tier=not_applicable; use the sibling validators instead. INPUTS: send the FULL spec text verbatim as implementation_context (for an OpenSpec change, concatenate proposal.md + design.md + tasks.md + delta specs; no truncation, no '…' placeholders — they are read as literal content). Auth: Bearer , Pro/Teams plan. UK/EU residency; transient OpenAI processing (no-training); prompt-injection text inside the spec is treated as inert untrusted data. TYPED FAILURES: same as architect.validate (timed_out, rate_limited, dependency_unavailable, schema_mismatch — each carries retryable + next_action); the services raise the identical typed envelopes on this lens. CALIBRATION DISCLOSURE: the scoring prompt is a v1 first-cut mirroring the architect's contract structure; its score calibration is not yet tuned against a corpus of real runs the way architect.validate was. Treat the grade as directional quality signal, not a certified verdict. DOCTRINE: the eight laws — each law's definition, rationale, anti-patterns, and the validator questions this tool scores against — live in content/spec-quality-laws.json (the what-to-build companion to the experience-design laws).
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | What this spec is for (e.g. 'the closed-beta apply flow rework'). Adds evaluation context. | |
| files | No | File paths relevant to the spec, for context. | |
| goals | No | Specific quality goals to weight (e.g. 'ready for an agent to build unattended', 'tight scope'). | |
| repository | No | Project/repository key. Groups this run with prior spec.validate runs on the same project in your validation-history dashboard (the same grouping the other lenses use), under the 'spec' dimension. | |
| session_id | No | Optional Governed Session to attach this run to (GEP-M2). Must reference a session YOU own (list via me.sessions; sessions are created in the web app at /app/sessions) — foreign ids are refused before any model call. The run then appears on the session's timeline alongside the other lenses. With private_session=true no run is stored so nothing attaches, but the ownership check still runs FIRST: a session id you don't own fails the call either way. | |
| private_session | No | Set true to disable persistence AND run_id recovery for this call (a private one-shot that does not appear in the dashboard). Default false. | |
| implementation_context | Yes | The specification under review. SEND FULL TEXT VERBATIM — the reviewer cites specific requirements, decisions, and tasks; any compression destroys evidence and produces findings on content that isn't there. For an OpenSpec change, concatenate proposal.md + design.md + tasks.md + delta specs. Do NOT truncate; if very large, split into MULTIPLE calls scoped by document. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds annotation coverage: discloses long-running behavior (60-180s), timeout recovery protocol, persistence and private_session semantics, single-pass limitation, output classification behavior (non_spec → not_applicable), calibration caveat, auth/residency requirements, and prompt-injection treatment. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long, but every major section (purpose, timeout recovery, when-to-call, input requirements, caveats) serves a distinct and critical purpose for a high-risk, long-running tool. It is dense and information-rich, though not optimally scannable—a few headings or bullet points would improve access. It earns a 4 for being appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description provides comprehensive coverage: it explains what the tool returns (spec_classification, findings, readiness score), identifies failure modes with retry semantics, and provides doctrine references. Together with the schema and annotations, an agent has all context needed to select and invoke the tool correctly, handle timeouts, and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, setting a baseline of 3. The description adds crucial context on implementation_context: 'send the FULL text verbatim,' no truncation, and splitting large inputs into multiple calls. It also clarifies repository grouping and private_session behavior. This extra guidance pushes the score above baseline, though not every parameter gets equivalent treatment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific function: 'first-pass specification-quality review of a WRITTEN SPEC' against the '8 laws of the Spec Quality Blueprint.' It distinguishes itself from siblings by explicitly contrasting with architect.validate (architecture) and design.validate (surface), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'WHEN TO CALL' if the user wants a governance/quality review on a spec; 'WHEN NOT TO CALL' for built code or rendered surfaces, directing to sibling validators. Also explains how to handle timeouts (do not retry, use me.validation_history) and provides a concrete example of when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
team.summarizeSummarize Team UsageAPro/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 , Pro or Teams plan. UK/EU residency.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 aligns without contradiction. It adds valuable context: data sources (AIToolCallLog, ValueEvent, AIValidationRunLog), private_session behavior (bypasses logging but historical data remains), auth requirements (Bearer token, Pro/Teams), and residency (UK/EU). This depth exceeds what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and every sentence serves a purpose. It is information-dense without fluff, front-loading the core purpose before diving into usage and behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, return values, usage conditions, exclusions, behavior, data sources, privacy, auth, and residency. An output schema exists so detailed return structures are understandably omitted, but the description gives a high-level overview of what is returned, making it complete for an agent to decide when and how to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described, but the description enriches meaning: it explains the configurable window defaults to 30 days and clarifies that private_session=true bypasses server-side logging while historical data persists. This adds behavioral nuance beyond the schema's concise descriptions, though much is redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'summarises the caller's tool-usage patterns and value signals over a configurable window' and lists specific return fields (tool_call_counts, top principles, value_event_counts, readiness trend). This specific verb+resource+scope distinguishes it from sibling tools focused on architecture, validation, or personal guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including example user queries ('how is the Blueprint helping me/my team') and clear exclusions (proactive calls, cross-user comparison). This goes beyond typical usage guidance and effectively prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!