AI Design Blueprint Doctrine
Server Details
The industry standard reference for safe, observable, and steerable AI agent UX. Browse and search the 10 Blueprint principles, principle clusters, curated implementation examples, and application guides. 13 public tools require no credentials. Tools for learning path, coaching context, and handoffs require a Firebase Bearer token. Validation and usage summary tools require a Pro or Teams membership.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
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.
Tool Definition Quality
Average 4/5 across 22 of 22 tools scored. Lowest: 3.3/5.
Each tool has a clearly distinct purpose within its category. Descriptions explicitly contrast related tools (e.g., 'Prefer clusters.list when you need to discover which clusters exist' vs. 'Use clusters.get when you already know the exact cluster slug'), eliminating ambiguity.
All tool names follow the consistent pattern `<category>.<action>` using lowercase snake_case (e.g., `architect.validate`, `clusters.list`, `guides.search`). No mixing of styles or unpredictable verbs.
22 tools is slightly above the typical 10-15 range but still well-scoped for the domain's complexity. Each category (validation, discovery, handoffs, personal progress, signals) earns its tool count.
The tool set covers the full lifecycle: discovery (principles, clusters, examples, guides), validation (architect.validate, validation_history), personal tracking (me.*), human handoffs (handoffs.*), feedback (signals.*), and team features (team.summarize). No obvious gaps.
Available Tools
23 toolsarchitect.certifyCertify Production-Ready ArchitectureAInspect
Pro/Teams — second-pass adversarial certification of an architect.validate run that scored production_ready (A or B first-pass tier). 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. ATOMIC ONE-SHOT, RECOVERABLE: single LLM call typically runs 60-150s server-side (empirical, on real third-party code at high reasoning effort — small payloads finish faster). This exceeds the standard MCP-client tool-call idle budget (~60s in Claude Code), so the FIRST notifications/progress event fires at t=0 and carries the same run_id you passed in. If your client closes the tool-call early, recover the cert verdict via me.validation_history(run_id=<that-id>) once the server-side LLM call lands — same pattern as architect.validate. The run is atomic by contract — no in_progress lifecycle, no cancellation, no resume. If the cert call fails outright (provider error, persistence error), a fresh architect.certify is the recovery path (eligibility gate enforces the retry budget). For long-running cert workflows the answer is to re-validate, not to make this tool stateful. Eligibility gate (typed rejection enum on failure): caller must own the run, run must be tier=production_ready, less than 24h old, not already certified, and within the cert retry budget (max 3 attempts per run). Reads first-pass findings from the persisted run; the caller must re-send the code (the architect persists findings + recommendations, never code, by design — privacy-preserving). The cert outcome updates the persisted run's result_json so the public review URL + me.validation_history(run_id=...) reflect it. ENTERPRISE-SAFE: code is processed transiently by the LLM provider (OpenAI, no-training-on-API-data) and dropped; JSON-escaped + delimited as inert untrusted data so prompt-injection inside payloads is ignored. UK/EU data residency (Cloud Run europe-west2). Auth: Bearer .
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 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. Running cert against findings alone (no code) cannot catch what the first pass didn't evidence. 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). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description reveals key behavioral traits: it is a synchronous one-shot call (~20-40s), atomic with no lifecycle, no cancellation, and fail recovery requires a fresh call. It also discloses enterprise-safety handling, data residency, and auth mechanism, fully informing the agent.
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 front-loaded with the core purpose and outcome. Every sentence adds value, covering eligibility, behavioral constraints, safety, and recovery. While slightly verbose, it is well-structured and efficient for the amount of necessary detail.
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 (certification workflow, eligibility, safety, no output schema), the description is remarkably complete. It covers failure recovery, retry budget, privacy-preserving design, data residency, and auth. An agent has all information needed to decide when and how to invoke this 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% coverate with descriptions for both parameters (run_id and code). The tool description adds some extra context (e.g., code must be verbatim, run_id ownership), but the schema descriptions are already adequate. Therefore, the description adds marginal value beyond the schema, justifying a baseline score of 3.
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 ('certify') and resource ('architect.validate run with production_ready tier'), distinguishing it clearly from the sibling tool architect.validate. It details the outcome (minting badge or capping to C/emerging), leaving no ambiguity about the tool's 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 explicitly states when to use this tool: after a first-pass architect.validate that scored production_ready. It provides eligibility criteria (ownership, tier, age, not already certified, retry budget) and explains that long-running workflows should re-validate instead. However, it does not explicitly compare to other tools like handoffs or assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
architect.validateValidate Agent ArchitectureAInspect
Pro/Teams — single-pass doctrine review of agent code, workflow, or architecture against the 10-principle Agentic AI Blueprint. Returns a structured assessment with code_classification (autonomous_agentic_workflow vs non_agentic_component), per-principle findings (verdict, severity_score 0-100, confidence, evidence_quality, code-cited evidence, recommendation), a severity-weighted readiness block (score, grade A-F, tier), recommended examples, processing latency, reproducibility fingerprints (model, seed, system_fingerprint, doctrine_fingerprint, prompt_template_fingerprint), and a persistence_status with shareable run_id / badge_url / review_url when saved. Typed failures: timed_out, rate_limited, dependency_unavailable, schema_mismatch (each carries retryable + next_action). Returns in ~30-50s; fits the ~60s MCP-client tool budget. TWO-STEP CERTIFY: when first-pass scores production_ready (A or B tier) the response carries certification_status='not_evaluated'. To mint the certified production_ready badge, call architect.certify(run_id, code) next — a separate Pro/Teams tool with its own eligibility gate (caller-owned, tier=production_ready, less than 24h old, not already certified, retry budget). Cert is kept off the validate hot path so first-pass review always returns inside the tool budget; cert itself runs as a single LLM call (~20-40s) and also fits cleanly. Call when the user wants a governance audit, a readiness score, or a public badge for an agent or workflow they have just built or changed. Pass repository="" to group runs into a project trend. INPUT FIDELITY: when reviewing existing code, send the FULL file contents verbatim as implementation_context. Do NOT truncate, compress, summarise, or paraphrase the code; the architect's verdict relies on per-line evidence (variable names, structural choices, exact branch ordering). If the file is large, split into multiple architect.validate calls scoped by file rather than condensing one call. Architecture summaries are valid ONLY when no code exists yet (greenfield review). ENTERPRISE-SAFE: payloads are processed transiently by the LLM provider (OpenAI, no-training-on-API-data) and dropped; user code + context are JSON-escaped and delimited as inert untrusted data so prompt-injection inside payloads is ignored. Pass private_session=true to bypass server-side logging — enforced in code. TIMEOUT RECOVERY: this tool typically returns within the client tool budget. If your MCP client closes the tool-call early (transport reset, etc.), the run still completes server-side — the first notifications/progress event fires at t=0 carrying the run_id, and you can recover the result via me.validation_history(run_id=...) once the run completes. Recovery requires the same Bearer token (per-run authorisation) and is unavailable when private_session=true (nothing persists). UK/EU data residency (Cloud Run europe-west2). Auth: Bearer .
| 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-and-scope'). | |
| repository | No | Repository name or path for additional context. | |
| example_limit | No | Maximum number of curated examples to include in recommendations. | |
| private_session | No | Set to true to disable all logging for this validation call. | |
| implementation_context | Yes | The artifact under review. When reviewing existing code, pass the FULL file contents verbatim — no truncation, no whitespace compression, no condensing of multi-line statements, no summarisation. The architect's findings cite specific identifiers, branch ordering, and structural choices that get destroyed by compression, so a summarised submission produces a degraded verdict that does not reflect the actual code. If a single file is too large, split into multiple architect.validate calls scoped by file/module rather than condensing one call. Architecture summaries (high-level prose) are accepted ONLY when no code exists yet (greenfield review); never as a substitute for code that already exists. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that data is sent to Anthropic and only structured results are stored, and that private_session disables logging. Annotations already indicate mutability (readOnlyHint=false), so the description adds valuable privacy 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 three sentences, each serving a purpose: purpose and outputs, data handling, and authentication. No fluff, highly focused.
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 an output schema present and 9 parameters, the description covers the core functionality, privacy implications, and auth requirement. It is sufficient for an agent to understand when and how to use 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 description coverage is 100%, so the baseline is 3. The description does not add significant parameter semantics beyond what the schema already provides, though it clarifies the private_session behavior.
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 explicitly states the tool evaluates code, workflows, or architecture against Blueprint doctrine and returns principle coverage, findings, and recommendations. This is specific and distinct from sibling tools like assets.list or clusters.get.
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 implies usage for architecture validation but does not explicitly state when to use versus alternatives or provide conditions for non-use. It mentions 'Pro/Teams' which hints at plan restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
assets.listList Agent AssetsARead-onlyIdempotentInspect
List downloadable doctrine and agent asset artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent behavior. The description adds the 'downloadable' qualifier, hinting at the nature of the artifacts but no further behavioral traits. No contradiction.
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?
Single sentence that is perfectly concise with no wasted words. All content is front-loaded and 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 zero parameters, annotations present, and an output schema existing, the description is mostly complete. However, it does not clarify what fields or format the list includes, which would be helpful 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?
There are zero parameters, so schema coverage is 100% by default. The description does not need to add parameter info; 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 uses a specific verb 'List' and clearly identifies the resource as 'downloadable doctrine and agent asset artifacts', distinguishing it from sibling list tools like clusters.list, guides.list, and principles.list.
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?
No guidance is provided on when to use this tool versus alternatives such as clusters.list, guides.list, or principles.list. The description does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clusters.getGet ClusterARead-onlyIdempotentInspect
Get full detail for one cluster: description, member principles, and shared rationale. Use this when you already know the exact cluster slug. Prefer clusters.list when you need to discover which clusters exist.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the principle cluster (e.g. 'delegation-and-scope'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint as true, so the description does not need to repeat. However, it adds no further behavioral context beyond stating the action, which is adequate given 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 a single, concise sentence with no unnecessary words or repetition, efficiently conveying the tool's 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 retrieval with one parameter and full annotations, the description is mostly complete. It could optionally mention that the response contains full cluster details, but the output schema handles that.
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 covers the single parameter fully (100% coverage), and the description only provides an example value ('delegation-and-scope') without adding new semantic meaning beyond what the schema already provides.
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 action ('Get'), the resource ('principle cluster'), and the identifier ('stable slug'). It distinguishes itself from sibling tools like 'clusters.list' and 'principles.get' by specifying a single cluster retrieval by slug.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., 'clusters.list'). While the purpose is clear, an agent would benefit from knowing not to use this for listing or filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clusters.listList ClustersARead-onlyIdempotentInspect
List all principle clusters with their stable slugs and linked principle titles. Use this to discover which clusters exist before drilling in with clusters.get or filtering principles.list by cluster. Prefer clusters.get when you already know the cluster slug and need full detail.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, which the description does not contradict. The description adds that clusters have 'stable slugs and linked principle titles,' but it does not disclose additional behavioral traits (e.g., sorting, pagination, rate limits). The description is consistent 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 a single sentence that is directly relevant and front-loaded. Every word earns its place, with no extraneous content. It is appropriately sized for the tool's simplicity.
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, has output schema), the description is complete. It tells the agent what the tool returns and the type of information included. Sibling tools exist but the description suffices for an agent to select and invoke this 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 has zero parameters (100% schema coverage). The description does not describe parameters because none exist. It adds value by clarifying the output content (stable slugs and linked principle titles). Baseline 3 is appropriate, and since no param info is needed, a score of 4 reflects sufficient context.
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 purpose: listing principle clusters. It specifies what information is included (stable slugs, linked principle titles) and distinguishes it from sibling tools like clusters.get (which retrieves a single cluster) and principles.list (which lists principles).
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?
Description lacks any guidance on when to use this tool versus alternatives. For example, it does not mention that this tool returns all clusters without filtering, or when one might prefer to use clusters.get for a specific cluster. No usage context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
examples.getGet ExampleARead-onlyIdempotentInspect
Get full detail for one curated example: code links, principle coverage, difficulty, library, and notes. Use this when you already have the slug from examples.search or a guide cross-link. Prefer examples.search to find examples by topic, principle ID, difficulty, or library.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the curated example (e.g. 'agents-building-blocks-5-control'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds no further behavioral context. The description is consistent with annotations, but does not disclose additional traits like caching or error 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?
Single sentence that is front-loaded with the action and resource, containing no wasted words. Efficient and direct.
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 tool is simple with one required parameter and an output schema. The description is adequate for a get-by-identifier tool, though it could briefly mention that the returned object includes example content. Still, it is complete enough for effective use.
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 the slug parameter already documented. The description adds 'stable slug' and a concrete example, but this adds minimal value beyond what the schema provides.
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 verb 'Get' and the resource 'curated example', specifying the lookup method by 'stable slug'. This distinguishes it from sibling tools like 'examples.search' or 'examples.list'.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., 'examples.search' for query-based retrieval). However, the description implies usage for direct slug-based access, which is adequate for a simple get-by-identifier tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
examples.searchSearch ExamplesARead-onlyIdempotentInspect
Search curated examples ranked by relevance, with optional filters for principle coverage, difficulty, and library. Use this when the user describes a use case, technique, or library and wants matching examples. Prefer examples.get when you already have the example slug and need full detail.
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to reiterate safety. It adds 'curated examples' but no further behavioral details (e.g., pagination, server caps). Not contradictory.
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?
A single, front-loaded sentence with no filler. Every word adds value: verb, resource, and filtering dimensions. Perfectly 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?
Given the presence of an output schema, return values are covered. The description omits default limit (5) and query behavior, but these are in the schema. For a search tool with 5 parameters, the context is mostly sufficient; a minor addition about result ordering or cap could elevate 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 description coverage is 100%, so the description does not need to explain parameters. It mentions three parameter categories (principle coverage, difficulty, library) which align with schema fields, but adds no extra meaning or constraints 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 action ('Search') and the resource ('curated examples'), listing filtering dimensions (text, principle coverage, difficulty, library). It distinguishes from sibling tools like 'examples.get' and 'guides.search' which retrieve specific items or search guides.
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 implies usage via the verb 'Search' and filtering fields, but lacks explicit guidance on when to use this tool versus siblings like 'examples.get' or 'guides.search'. No exclusion or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
guides.getGet Application GuideARead-onlyIdempotentInspect
Get a full application guide by its stable slug (e.g. 'security-application', 'observable-evaluation'). Returns sections, action items, and linked principles. Use this when you already have the guide slug from guides.list or guides.search. Prefer guides.search when the user describes a topic in natural language; prefer guides.list when you need the full inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the application guide (e.g. 'security-application', 'observable-evaluation'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so the description adds context by stating it returns a 'full application guide', which is consistent. However, it does not elaborate on any additional behavioral traits 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?
The description is a single, concise sentence that front-loads the purpose and provides an example. Every word is necessary and there is no superfluous 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 simplicity (one parameter, output schema exists), the description is complete. It covers what the tool does, how to use it, and the expected input format. No gaps are evident.
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 repeats the example slug format already in the schema's description, adding no new semantic value beyond the schema itself.
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 action 'Get', the resource 'full application guide', and the identifier 'stable slug'. It distinguishes from sibling tools like guides.list or guides.search by specifying that it retrieves a single guide by its unique slug.
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 implies when to use the tool (when you have a stable slug) but does not explicitly state when not to use it or mention alternatives. Given the presence of sibling tools, more guidance on choice would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
guides.listList Application GuidesARead-onlyIdempotentInspect
List application guides that show how Blueprint principles apply to engineering challenges (security, evaluation, observability, etc.). Use this to discover which guides exist before drilling in. Prefer guides.search when the user describes a topic or failure mode in natural language. Prefer guides.get when you already know the guide slug and need full detail.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds behavioral context by specifying that the guides are about applying blueprint principles to specific challenges (security, evaluation), which provides useful semantic 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 a single, action-initial sentence with no extraneous words. It directly states the verb and resource, making it highly efficient.
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 zero parameters and an existing output schema, the description sufficiently explains what the tool returns (list of guides related to blueprint principles applied to engineering challenges). No further details are necessary for a simple list operation.
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 100% and the description cannot add parameter-specific information. Baseline score of 4 is appropriate per guidelines.
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 action (list) and resource (application guides), and distinguishes it from siblings like guides.get and guides.search by specifying the content focus (blueprint principles applied to engineering challenges).
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 implies usage when one needs to list guides, but does not explicitly state when to use this tool versus alternatives like guides.get or guides.search, nor does it provide exclusions or prerequisites. Given the presence of siblings, some guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
guides.searchSearch Application GuidesARead-onlyIdempotentInspect
Search application guides by free-text query, matched against section answers and action items. Use this when the user describes an engineering challenge (security review, evaluation harness, observability) and wants matching guides. Prefer guides.get when you already have the guide slug; prefer guides.list when you need the full inventory.
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint true. The description adds value by specifying what content is searched (section answers, action items), which goes beyond 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?
Two concise sentences, front-loaded with purpose and scope. No wasted words; every sentence adds value.
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 presence of an output schema, the description adequately covers input semantics and search behavior. It is complete for a search tool with no missing critical 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 baseline is 3. The description adds meaning about the query searching against specific guide content, which is not in the schema, thus providing additional semantic 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 searches application guides by text query, and specifies it matches against all content including section answers and action items. This distinguishes it from sibling tools like guides.get (by ID) and guides.list (list all).
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 implies usage for free-text searching without explicit when-not or alternatives, but the context of sibling tools makes the use case clear. Lacks explicit exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
handoffs.agencyRequest Agency HandoffBInspect
Submit an agency engagement enquiry on behalf of the authenticated user for a founder-led discovery call. Agency engagements cover four 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), and advisory (ongoing architectural guidance across a product team). Use this when the user has identified a need for hands-on expert support beyond self-service learning. Requires a Firebase Bearer token.
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false). The description adds authentication requirement ('Auth: Bearer <token>') but lacks details on side effects, confirmation, or error conditions.
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?
Two sentences, front-loaded with purpose and essential auth info. No redundant 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 an output schema exists (signal true), the description adequately covers the action. It could briefly note that trace_summary provides operator context, but schema handles that.
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?
All parameters have descriptions in the schema (100% coverage), so the description adds no new meaning beyond listing engagement types which are already in the parameter 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 clearly states the tool submits an agency engagement enquiry for founder-led discovery calls, listing specific engagement types. However, it does not differentiate from sibling tools handoffs.operator and handoffs.partnership.
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?
No guidance on when to use this tool versus alternatives. The description only states what it does without any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
handoffs.operatorRequest Operator HandoffAInspect
Creates a support handoff when an agent needs human review, escalation, or account-specific follow-up. Auth: Bearer .
| 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'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-idempotent, and open-world behavior. The description adds value by specifying the auth requirement (Bearer token), which is not present in annotations. This helps the agent understand the tool's invocation 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 a single sentence stating the purpose, followed by one sentence on auth. It is front-loaded and every word earns its place. No unnecessary 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?
With an output schema present, return values are covered. The description conveys the core purpose and auth requirement. However, given 7 parameters and no mention of side effects (e.g., notifications, processing details), some nuance is missing. Adequate but not fully comprehensive.
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 the schema itself documents all 7 parameters. The description does not add additional semantics beyond the schema, meeting the baseline expectation but not surpassing it.
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 support handoff and specifies three scenarios: human review, escalation, account-specific follow-up. The verb and resource are distinct. However, it does not explicitly differentiate from sibling handoff tools like handoffs.agency or handoffs.partnership, which limits clarity slightly.
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 clear context when to use (human review, escalation, account-specific follow-up) but lacks explicit guidance on when not to use or how to choose among sibling handoff tools. No exclusion criteria or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
handoffs.partnershipRequest Partnership HandoffAInspect
Creates a partnerships handoff for design partner, ecosystem, training, or advisory conversations needing human review. Auth: Bearer .
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and idempotentHint=false, which align with a write operation. The description adds an auth requirement ('Auth: Bearer <token>') not present in annotations, providing useful behavioral 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 concise (one sentence plus auth instruction) with no wasted words. It is front-loaded with the main purpose, though it could benefit from slightly more detail.
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 the basic purpose and auth, but given the tool has 9 parameters (1 required) and a presumed output schema, it lacks details on what the handoff entails or the response structure. The schema and annotations carry most of the burden.
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 the baseline is 3. The description does not add any additional meaning beyond what the schema provides for parameters. The brief auth note is separate.
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 specifies the action (Creates), resource (partnerships handoff), and context (design partner, ecosystem, training, or advisory conversations needing human review). It clearly differentiates from sibling tools like handoffs.agency and handoffs.operator by listing specific topics.
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 phrase 'needing human review' provides clear context for when to use this tool. However, it does not explicitly mention when not to use it or compare with sibling tools (handoffs.agency, handoffs.operator), which would be helpful.
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 NoteBInspect
Append a free-text evidence note to a specific stage in the authenticated user's active course. Evidence notes record concrete implementation observations, decisions, or artefacts that demonstrate progress through a Blueprint principle — for example, describing how a delegation boundary was implemented or what approval flow was chosen and why. Call this after the user has articulated something they have built or observed, not to capture intent. Requires a Firebase Bearer token.
| 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'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation (readOnlyHint=false). The description adds the auth requirement (Bearer token). It does not contradict annotations, but it does not elaborate on side effects or other behavioral traits beyond what annotations convey.
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 consists of two brief, front-loaded sentences with no redundant information. It is optimally concise for the given 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?
The description covers the basic operation but lacks context such as constraints, error conditions, or size limits on the note. While an output schema exists, the description does not fully compensate for the missing behavioral context, making it minimally adequate.
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% and each parameter has a clear description. The main description adds no additional semantic value beyond the schema, so it meets the baseline without exceeding it.
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 action (appends a note) and the resource (delegation boundary notes for a course stage), which distinguishes it from sibling tools. However, the term 'delegation boundary notes' may be domain-specific and slightly ambiguous without further 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?
No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned. The description is purely functional.
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 ContextARead-onlyIdempotentInspect
Returns stages where evidence is thin relative to principle requirements. Auth: Bearer .
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds the auth requirement ('Bearer <token>') which is not in annotations, and clarifies the output nature (stages with thin evidence). 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?
Two short sentences: first states core functionality, second adds auth context. No redundant words or 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?
For a parameterless tool with an output schema, the description is largely complete. It explains the return type and auth. However, it could clarify the definition of 'thin evidence' or link to principles, though not strictly necessary given 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?
No parameters exist, so schema description coverage is trivially 100%. The description does not need to add parameter info and instead focuses on tool output, which is appropriate.
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 clearly states the tool returns stages where evidence is thin relative to principle requirements. This specific verb-noun combination distinguishes it from siblings like 'me.add_evidence' and 'me.learning_path'.
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?
No guidance on when to use this tool versus alternatives. The description does not specify when not to use it or mention any preconditions beyond auth.
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 PathARead-onlyIdempotentInspect
Returns your learning path state: course progress, certification status, and Capstone track eligibility. Auth: Bearer .
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds authentication requirement ('Auth: Bearer <token>') and lists returned data (course progress, certification status, eligibility). Annotations already indicate read-only and idempotent. No contradiction.
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?
Single sentence plus auth note. No superfluous words. Front-loaded with core functionality.
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 output schema exists, description provides sufficient overview of return data. Auth note covers access. Missing error conditions or rate limits, but not critical for a simple read 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?
No parameters in schema; schema coverage 100%. Baseline 4 for 0 parameters. Description does not need to add parameter details, but enumeration of returned data is helpful.
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?
Title 'Get My Learning Path' and description 'Returns your learning path state: course progress, certification status, and Capstone track eligibility' clearly specify the action (return), resource (learning path), and data provided. It distinguishes from sibling tools like 'me.coaching_context' or 'assets.list'.
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?
No explicit guidance on when to use this tool vs alternatives (e.g., 'me.coaching_context' for coaching, 'guides.get' for guides). No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
me.validation_historyMy Architect Agent Validation HistoryARead-onlyIdempotentInspect
Pro/Teams — return the authenticated user's architect.validate run history with the Blueprint Readiness Score (0-100), letter grade (A-F), and tier (draft, emerging, production_ready). 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 returned. The run completes server-side and persists; the run_id is surfaced in the first progress notification of every architect.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 calling architect.validate again on the same repository — they tell you which principles 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint and idempotentHint annotations, including auth requirements, return format, and regression diff logic. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core purpose, and every sentence adds essential information. No superfluous 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?
Despite no output schema, the description fully explains the return data (score, grade, tier) and the regression diff for single-repository queries. It covers both usage modes, auth, and plan requirements, making it complete for agent decision-making.
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 descriptions for both parameters. The description enriches them with usage context: for repository, it says to pass the same value as architect.validate; for limit, it mentions capping at 50. This adds value over the schema alone.
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 returns the authenticated user's architect.validate run history with specific data (score, grade, tier). It distinguishes between behavior with and without a repository argument, and implicitly differentiates from sibling tools like architect.validate.
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 advises using this before calling architect.validate again, explaining how it helps focus reviews on regressions. It also mentions the required Pro/Teams plan, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
principles.getGet PrincipleARead-onlyIdempotentInspect
Get full detail for one principle: definition, rationale, risk, heuristics, and linked example slugs. Use this when you already have the exact slug from principles.list or principles.search. Prefer principles.search when the user describes a topic or failure mode in natural language. Prefer principles.list when you need every principle or every principle within a cluster.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Stable slug of the principle (e.g. 'establish-trust-through-inspectability'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that the slug is stable, but does not disclose other behaviors like error handling or permissions.
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?
Single sentence, front-loaded, no extra words. Perfectly 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?
Given the low complexity, good annotations, and presence of an output schema, the description is adequate. It covers the core purpose, but could optionally mention what happens if slug is invalid.
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 already describes the slug parameter with example and note of stability. Description adds no new meaning; schema coverage is 100%, so baseline 3 applies.
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 single doctrine principle by its stable slug. It distinguishes from sibling tools like principles.list and principles.search.
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 implies usage: when you know the stable slug, use this tool. However, it does not explicitly mention alternatives or when-not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
principles.listList PrinciplesARead-onlyIdempotentInspect
List all 12 Blueprint principles with stable slugs, titles, and clusters. Use this when you need the full inventory or want every principle 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 |
|---|---|---|---|
| cluster | No | Cluster slug to filter by (e.g. 'delegation-and-scope'). Omit to return all principles. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds minimal behavioral context (stable slugs), but no further traits like pagination or auth needs.
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 a single short sentence that is front-loaded with the purpose, containing no extraneous 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 output schema exists and the tool is simple (list with one optional filter), the description covers all necessary context, including the notion of stable slugs.
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%, and the description paraphrases the schema's description for the 'cluster' parameter, adding no new meaning beyond what the schema already states.
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 specific verb 'List' and resource 'doctrine principles', and mentions 'stable slugs' which distinguishes it from siblings like 'principles.get' or 'principles.search' that likely retrieve single or search with complex queries.
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 implies usage for listing all principles optionally filtered by cluster, but does not explicitly state when to use this vs alternatives like 'principles.get' or 'principles.search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
principles.searchSearch PrinciplesBRead-onlyIdempotentInspect
Search Blueprint principles by free-text query and return the closest matches ranked by relevance. Use this to find principles related to a specific design challenge, failure mode, or keyword (e.g. 'reversibility', 'approval flow', 'delegation boundary'). Returns principle title, cluster, definition, rationale, and implementation heuristics. Prefer this over principles.list when you have a specific topic in mind rather than wanting all principles.
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description carries minimal burden. It adds that matching occurs against title, definition, rationale, and cluster, but does not disclose other behaviors like ranking, case sensitivity, or result ordering. 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?
The description is a single, efficient sentence that conveys the purpose and matching fields with no unnecessary words. It is front-loaded and 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?
Given the simple search nature, the description adequately covers what the tool does. The output schema exists separately, and annotations cover safety. Minor gaps: it could mention that it is read-only (already in annotations) or describe return structure, but overall 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?
Schema description coverage is 100%, so the baseline is 3. The description repeats the schema's info about matching fields without adding new semantics about parameter formatting or constraints. No extra value 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 it searches doctrine principles by text query and specifies the matching fields. It distinguishes the tool's purpose from siblings by focusing on 'principles', but does not explicitly differentiate from other search tools like examples.search or guides.search.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., examples.search, guides.search). The description lacks 'use this when' or 'instead of' statements, leaving the agent to infer appropriate usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
signals.feedbackSubmit FeedbackAInspect
Records explicit user feedback — open to all callers, no auth required. Call ONLY when the user explicitly says they want to give feedback; never proactively. contact_email stored only when permission_to_follow_up is true — confirmed in response.
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint: false). Description adds that contact_email is only stored when permission_to_follow_up is true, and this is confirmed in the response. Also emphasizes never proactive, adding behavioral safety 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?
Three sentences convey purpose, a behavioral caveat, and usage guideline. No wasted words, highly efficient.
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?
Description covers when to use, data handling, and caller anonymity. With 9 optional parameters fully described in schema and an output schema present, the description provides adequate context. Could mention outcome confirmation but not necessary.
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%. Description adds minimal extra meaning beyond confirming the conditional storage of contact_email and mentioning a response confirmation. Baseline 3 is appropriate.
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?
States 'Records explicit user feedback' clearly. Distinguishes usage with 'only when user explicitly requests; never proactively', but does not explicitly differentiate from sibling tools like signals.report.
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 call ('only when user explicitly requests; never proactively') and notes anonymous callers are welcome. No mention of alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
signals.reportReport Value EventAInspect
Pro/Teams — records a value moment after a successful validation or design session. Only structured fields stored — no prompts or code. Do not include proprietary content in brief_context. Offer once per session after a clear success signal; never silently. Requires active Pro or Teams Bearer token. Auth: Bearer .
| 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' — architect.validate returned aligned; 'runtime_risk_found' — architect.validate found violations; 'workflow_clarity' — principles/examples clarified a design decision; 'agent_setup_success' — user successfully wired up an agent or MCP tool; 'onboarding_helped' — user understood how to start using the Blueprint; 'research_time_saved' — user found relevant doctrine faster than expected; 'team_alignment' — Blueprint helped align a team on agentic design; 'other' — use only if none of the above fit. | |
| 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 architect.validate on existing code; '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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false). Description adds detail: only structured fields stored, no prompts/code, and a constraint on brief_context. 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?
Three sentences, front-loaded with purpose, each sentence adds value. No redundant 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?
Covers usage, data storage constraints, and anonymity. Output schema exists so return values don't need explanation. Could benefit from mentioning when not to use.
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 descriptions for all parameters. The description adds no extra meaning beyond the schema fields, so baseline 3 is appropriate.
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 action ('Records a value moment') and resource, but does not explicitly differentiate from sibling 'signals.feedback', which could be similar.
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 guidance: offer once per session after a clear success signal, never silently. Includes that anonymous callers are welcome, but no exclusions or 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 UsageARead-onlyIdempotentInspect
Pro/Teams — summarises your tool usage patterns and value signals from log data. Offer when user asks how the Blueprint is helping or what to explore next; not proactively. ENTERPRISE-SAFE: pass private_session=true to bypass all server-side logging for this summary call. UK/EU data residency (Cloud Run europe-west2). Auth: Bearer .
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds value by explaining it uses log data, mentions auth requirement ('Auth: Bearer <token>'), and discloses that setting private_session skips logging, providing behavioral context beyond 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?
Two sentences, no wasted words. First sentence defines purpose and data source. Second sentence gives usage guideline and a parameter hint. Front-loaded and efficient.
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?
Tool has output schema (not shown but in context), so return value description is unnecessary. The description covers purpose, usage context, authentication, and a special parameter. Complete for the 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?
Input schema has 100% coverage with descriptions for both parameters. The description adds only 'private_session=True skips logging', which is redundant with schema. Baseline 3 is appropriate as schema does the heavy lifting.
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 summarizes tool usage patterns and value signals from log data, with specific verb 'summarises' and resource 'team usage'. It distinguishes from siblings like 'guides.get' or 'assets.list' by focusing on usage patterns.
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 'Offer when user asks how the Blueprint is helping or what to explore next; not proactively', giving clear when-to-use and when-not-to-use guidance. No explicit alternative is named, but context is sufficient.
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.
Discussions
No comments yet. Be the first to start the discussion!