AI Design Blueprint Doctrine
Server Details
Doctrine and examples for the Agentic AI Blueprint. 13 public tools, no credentials required.
- 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.1/5 across 23 of 23 tools scored. Lowest: 3.4/5.
Each tool has a clearly distinct purpose: resource retrieval (principles, guides, examples, clusters, assets) uses separate list/search/get verbs; validation and certification are separate tools; handoffs are split by type; user and signal tools have unique roles. No overlap or ambiguity.
All tools follow a consistent dot-separated namespace pattern with lowercase snake_case verb_noun names (e.g., clusters.list, examples.search, architect.validate). The pattern is uniform across all tool groups, making it easy to predict tool names.
At 23 tools, the count is on the higher side but still justified by the broad domain coverage: validation, certification, knowledge base (principles, guides, examples, clusters, assets), user management, handoffs, signals, and team summary. Each tool serves a distinct need, though a few (e.g., assets.list) may be seldom used.
The tool set covers core workflows: validating code against the blueprint, certifying results, retrieving all knowledge objects, managing user progress and history, handling handoffs, and collecting feedback/signals. Minor gaps like lack of administrative tools for updating doctrine content are acceptable given the user-facing scope.
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?
The description fully discloses the tool's behavior: atomic, no lifecycle, no cancellation, failure recovery path. It explains privacy-preserving design (code not stored, sent again), enterprise safety (transient processing, no training, data residency), and outcome persistence. No contradiction with annotations (readOnlyHint=false, idempotentHint=false).
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 and informative but could be more structured (e.g., bullet points). However, every sentence adds value, and it is not overly verbose for the amount of content. Minor deduction for lack of formatting.
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 tool's behavior, inputs, eligibility, and outcomes. It lacks explicit output format details (e.g., exact response fields), but given the tool's simplicity (badge or downgrade) and no output schema, the description is largely sufficient. Slightly incomplete for an agent expecting a structured 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%, and the description adds significant value beyond the schema. For 'code', it explains why it is needed and the safety envelope. For 'run_id', it clarifies ownership and authorization. This helps the agent understand the purpose and constraints of each parameter.
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 that this is a second-pass adversarial certification for a prior architect.validate run that scored production_ready (A or B). It specifies the outcomes: minting a badge or downgrading to C. This distinguishes it from siblings like architect.validate (first-pass) and other tools.
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 guidance on when to use this tool: after architect.validate returns production_ready. It details the eligibility gate (owner, tier, age, not already certified, retry budget) and explains that it is a synchronous one-shot call, with recovery via re-submission. It also states that for long-running workflows, one should re-validate, not use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
architect.validateValidate Agent ArchitectureAInspect
Pro/Teams — 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 adds significant behavioral context beyond annotations: it discloses that data is sent to Anthropic for processing (privacy impact), only structured results are stored, requires Bearer token auth, and offers a private session to disable logging. This aligns with and supplements the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false).
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 and front-loads the core purpose immediately. Every sentence adds value (purpose, privacy, auth, private session option). No fluff or redundancy.
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 9 parameters (1 required), an output schema, and is a validation tool, the description covers the essential behavioral aspects: evaluation subject, output type, data handling, auth, and privacy option. The output schema covers return values, so description need not detail them.
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 already documents all parameters. The description mentions private_session and its effect, but this is redundant with the schema description. It does not add significant new meaning beyond what's in the schema, 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 tool evaluates code, workflow, or architecture against the Blueprint doctrine and returns structured results. It uniquely distinguishes itself from sibling tools (none are validation-focused) and uses specific verbs ('evaluate' and 'returns').
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 context on when to use (e.g., for Blueprint doctrine evaluation) and includes important usage notes like data being sent to Anthropic and the private_session option. However, it does not explicitly state when not to use the tool or list alternatives, though given the unique purpose, this is a minor gap.
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 readOnlyHint and idempotentHint, so description adds minimal extra behavioral context beyond 'downloadable' artifacts. 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?
Single sentence is concise and front-loaded with the verb and resource. No unnecessary 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 no parameters and existence of output schema, the description fully covers what the tool does without needing additional details.
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; description adds no param info but baseline is 4. Schema coverage is 100% with zero params, so no gap.
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 action 'List' and specific resource 'downloadable doctrine and agent asset artifacts', distinguishing it from sibling tools like clusters.list or guides.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?
While no explicit when-not-to-use or alternatives are given, the context is clear for a simple list-all operation with no parameters. The tool's name and sibling set imply its scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
clusters.getGet ClusterBRead-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: true' and 'idempotentHint: true', so the safety profile is clear. However, the description adds no additional behavioral context, such as what happens if the slug does not exist or any error conditions. For a read operation, more detail on what is returned could be helpful.
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. It is front-loaded and easy to parse.
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 present), the description adequately covers its core purpose. However, it could briefly mention that the slug is a unique identifier and that the return value is a cluster object (though output schema likely 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?
The input schema has 100% coverage for its single parameter 'slug', which already includes a useful example. The tool description does not add any further semantics beyond what the schema provides, so the baseline of 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 'Get a principle cluster by its stable slug' clearly specifies the verb 'Get', the resource 'principle cluster', and the unique key 'slug'. It distinguishes from sibling tools like 'clusters.list' (which lists clusters) and 'principles.get' (which gets a principle, not a cluster).
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 does not provide any guidance on when to use this tool versus alternatives (e.g., 'clusters.list' for listing all clusters). No explicit when-to-use or when-not-to-use context is given.
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, so the description's addition of return fields is helpful but not critical for behavioral transparency. 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?
Single sentence, front-loaded with verb and resource, no redundant words. Economical and clear.
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 0 parameters, output schema existence, and simplicity, the description provides enough context about return values (slugs, linked titles) for agent invocation.
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 0 parameters, so description need not add param info. Schema coverage is 100%, making the description's mention of return values sufficient.
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 verb 'list' and resource 'principle clusters', and specifies return fields (stable slugs, linked principle titles). Distinguishes from sibling tools like clusters.get 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 on when to use this tool versus alternatives like clusters.get or principles.list. No explicit when-not or context for selection.
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 provide readOnlyHint and idempotentHint, so the description does not need to add safety info. It adds context about 'curated' and 'stable slug', which is useful but not critical 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?
A single, efficient sentence that front-loads the action and resource. No wasted 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 tool's simplicity (one parameter, output schema, and comprehensive annotations), the description fully covers the necessary information 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?
Schema description coverage is 100% and the schema already describes the 'slug' parameter well. The description adds no additional meaning beyond reiterating 'by its stable slug', 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 verb 'Get' and the resource 'curated example' with the identification method 'by its stable slug'. It distinguishes itself from siblings like 'examples.search' which is a search tool.
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 use for retrieving a specific curated example by slug, but does not explicitly contrast with siblings like 'examples.search' or state when not to use. The context is clear enough for an agent to infer.
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 indicate readOnlyHint and idempotentHint. The description adds 'curated' but no further behavioral traits (e.g., ordering, pagination, result completeness). 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?
One concise sentence with no wasted words. Front-loaded with the core action and resource.
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 that an output schema exists, the description is adequate for a search tool. However, it omits mention of result ordering or that results are scored, which could be useful.
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 parameters are fully described in the schema. The description merely lists the filter categories without adding new 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?
The description uses a specific verb 'search' and resource 'curated examples', listing key dimensions (text, principle coverage, difficulty, library). It clearly distinguishes from sibling tools like examples.get and 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?
The description implies usage for searching examples, but provides no explicit guidance on when to use this tool versus alternatives (e.g., guides.search, principles.search) or when not to use it.
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 declare readOnlyHint and idempotentHint, so the description carries less burden. It adds that the guide is 'full', implying complete content, but doesn't disclose other behavioral traits like error responses or caching. 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?
The description is a single, front-loaded sentence with no unnecessary words. Every part serves a clear 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?
Given the simplicity of the tool (single required parameter), the description is sufficient. The presence of an output schema means return values don't need explicit description. However, it could briefly mention that the output is the full guide object.
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 100% coverage with a clear description for the 'slug' parameter. The description repeats the schema info and adds examples, providing minimal added 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 the action ('get'), the resource ('full application guide'), and the identifier ('stable slug'), with concrete examples. It distinguishes from sibling tools like guides.list and guides.search by specifying 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?
Usage context is implied (when you have a slug), but there is no explicit guidance on when to use this tool versus alternatives like guides.list or guides.search. The description assumes the agent understands the differentiation.
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 indicate readOnly and idempotent behaviors. Description adds valuable context about the content (security, evaluation challenges), going beyond structured fields.
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, front-loaded sentence with no redundant information. Every word contributes to 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?
Tool is simple with no parameters and an output schema. Description sufficiently explains what is listed, though absence of sorting/filtering details is acceptable given lack of params.
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 baseline 4 applies. Description does not need to add parameter info, as schema coverage is 100%.
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 verb 'list' and resource 'application guides', specifying they relate to blueprint principles and engineering challenges. This distinguishes it from siblings like guides.get (single) and guides.search (query-based).
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 such as guides.get or guides.search. Missing explicit context for selection.
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, so the behavioral baseline is covered. The description adds value by stating that the search matches against 'all guide content including section answers and action items,' which provides useful 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 just two sentences, with no wasted words. It is front-loaded with the purpose, making it efficient and easy to parse.
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 (2 parameters, output schema present, annotations present), the description is mostly complete. It could be improved by briefly mentioning return format or pagination behavior, but it adequately covers the core search function.
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 description coverage is 100%, with both parameters having detailed descriptions. The tool description adds no additional parameter-level information beyond what is already in the schema, so it meets the baseline 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 clearly states the verb 'Search' and the resource 'application guides', and specifies what content is matched ('all guide content including section answers and action items'). This distinguishes it from siblings like guides.get (retrieve specific guide) and guides.list (list all 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 lacks any guidance on when to use this tool versus alternatives such as guides.get or examples.search. It only describes the function, leaving the agent without explicit context for choosing between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
handoffs.agencyRequest Agency HandoffAInspect
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 provide readOnlyHint=false and idempotentHint=false. The description adds important behavioral context: 'Auth: Bearer <token>', which is not in annotations. 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 a single concise sentence plus an auth note, with no filler. All information is front-loaded and essential.
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 10 parameters, 1 required, 100% schema coverage, and an output schema, the description is sufficient. It covers purpose and authentication. Could mention the output, but 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 description coverage is 100%, so baseline is 3. The description adds value by listing the engagement types (workflow sprint, proof-of-concept, etc.) that correspond to the 'reason' and 'support_type' parameters, providing a cohesive summary beyond individual field 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's action ('submits an agency engagement enquiry'), specifies the type of engagements (workflow sprint, proof-of-concept, pilot support, advisory), and differentiates from siblings like 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?
The description implies usage for agency handoffs by naming the tool 'handoffs.agency' and listing engagement types, but does not explicitly state when to use this versus sibling tools (handoffs.operator, handoffs.partnership). No direct guidance on prerequisites or exclusions.
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 a write operation (readOnlyHint false). The description adds authentication requirements beyond annotations, but no other behavioral traits (e.g., side effects, response format) are disclosed.
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 extremely concise—two sentences that front-load the purpose and authentication requirement. 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?
While the description covers the core purpose and auth, it lacks differentiation from sibling handoff tools and does not guide parameter selection (e.g., topic routing). The output schema exists, so return value detail is less critical, but overall context for agent decision-making is incomplete.
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 covers all 7 parameters with descriptions (100% coverage). The tool description adds no additional parameter information, so the schema carries the full burden.
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 for specific scenarios (human review, escalation, follow-up). However, it does not differentiate from sibling tools like handoffs.agency or handoffs.partnership, which would help an agent select the correct tool.
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 lists when to use the tool but lacks guidance on when not to use it or how it compares to alternatives. No exclusions or alternative suggestions are provided.
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 confirm it is not read-only (readOnlyHint=false), aligning with 'Creates'. The description adds the authentication requirement ('Auth: Bearer <token>'), which is valuable beyond annotations. 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 extremely concise: one sentence plus an auth note. It is front-loaded with the core purpose and contains no unnecessary 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 handoff creation tool with 9 parameters (1 required) and an output schema, the description is sufficient. It explains the purpose and auth, though it could mention the response or side effects. However, the output schema likely covers return values.
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 add parameter details. The description does not provide extra meaning beyond the schema, meeting the baseline expectation.
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 (creates a partnerships handoff) and specifies the contexts (design partner, ecosystem, training, advisory) needing human review. It distinguishes itself from siblings like handoffs.agency and handoffs.operator by naming specific partnership categories.
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 indicates when to use ('needing human review') but does not explicitly state when not to use or recommend alternatives. With sibling tools for agency and operator handoffs, more precise guidance would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
me.add_evidenceAdd Evidence NoteAInspect
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 indicate readOnlyHint=false and idempotentHint=false, consistent with the description's 'appends' action. The description adds the critical authentication requirement, which is not provided by 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. The first sentence states the purpose, the second adds authentication info. Efficient and 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?
For a simple append tool with an output schema, the description covers the core function and authentication. It lacks potential limitations (e.g., character limits) but is largely complete given the tool's simplicity and schema richness.
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 parameter descriptions. The description adds minimal value beyond the schema, simply restating the action's purpose without detailing parameter syntax or format.
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 ('appends') and identifies the resource ('delegation boundary notes for a course stage'). It clearly distinguishes from sibling tools, none of which have a similar function.
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 mentions authentication ('Auth: Bearer <token>'), which is a usage requirement, but does not specify when to use or avoid this tool versus alternatives. Usage context is implied but not explicitly stated.
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?
Beyond annotations (readOnlyHint, idempotentHint), the description adds that it returns stages with thin evidence and requires Bearer token auth. 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 sentences, no waste. Purpose is front-loaded, auth requirement is appended efficiently.
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 annotations and an output schema, the description sufficiently covers behavior and auth. No 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?
No parameters exist, so baseline is 4. Description does not need to add parameter details.
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 and resource ('Returns stages where evidence is thin relative to principle requirements'), clearly distinguishing it from siblings like 'me.learning_path' or 'me.add_evidence'.
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 implicitly suggests use for identifying evidence gaps but does not explicitly state when to use vs alternatives or provide when-not-to-use 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 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?
Annotations already indicate read-only and idempotent behavior. The description adds the authentication requirement ('Auth: Bearer <token>'), providing useful behavioral context beyond annotations. 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 consists of two concise sentences that front-load the main purpose and add auth context. No unnecessary words 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?
Given the tool has no parameters and an output schema exists, the description sufficiently covers what the tool returns (course progress, certification status, eligibility) and auth requirements. No 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?
The input schema has zero parameters with 100% schema description coverage. The description adds no parameter information, but the baseline for 0 parameters is 4, as 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 purpose (returning learning path state) and specifies the resources: course progress, certification status, and Capstone track eligibility. It effectively distinguishes itself from sibling tools, none of which deal with learning paths.
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 does not provide explicit guidance on when to use this tool versus alternatives or when to avoid it. It only implies it's for the current user via 'Your learning path', but no exclusions or context for alternative tools are given.
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?
Annotations declare readOnlyHint and idempotentHint. Description adds valuable details: per-repository summary vs full trend with regression diff, sorting by recency, and that it reveals regressed principles. 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?
Description is efficient, front-loading purpose and usage. It could be slightly more concise (e.g., combining auth/plan note) but is well-structured and 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?
No output schema, but description fully covers return fields (scores, grades, tiers), explains both invocation modes, regression diff, auth/plan requirements. Complete 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 covers 100% of parameters with descriptions. The description adds critical behavioral semantics: when omitted, returns one summary per repository; when provided, returns trend and regression diff. This greatly enhances understanding beyond 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?
Description specifies returning validation history with scores, grades, and tiers. It explicitly contrasts with sibling tool architect.validate ('Use this BEFORE calling architect.validate again'), distinguishing its purpose clearly.
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 clear when-to-use guidance (before re-validating), and explains behavior for with/without repository argument. Auth and plan requirements are stated. Does not explicitly exclude alternatives 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.
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?
The description adds no behavioral details beyond what the annotations already provide (readOnlyHint, idempotentHint). It is consistent with annotations but does not disclose additional traits like error behavior or authentication 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, concise sentence that conveys the essential purpose without extraneous 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 low complexity, complete schema coverage, and existence of an output schema, the description is sufficient for an agent to understand the tool's function. No additional context is needed.
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 adds no additional meaning to the parameter beyond the schema's own description. The baseline of 3 is appropriate as the description meets the minimum but does not enhance understanding.
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', the resource 'doctrine principle', and the method 'by its stable slug', which distinguishes it 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 have a specific slug, but does not explicitly state when to use this tool over alternatives like 'principles.list' or 'principles.search', nor does it mention when not to use it.
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 declare readOnlyHint and idempotentHint, so the description's job is easier. It adds value by noting that results include stable slugs, providing useful behavioral context. 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?
Two sentences, no unnecessary words. The first sentence states the core purpose, the second adds the optional filter. Information is 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?
Given the presence of an output schema, the description does not need to detail return values. It mentions stable slugs, which aligns. For a listing tool, it could mention ordering or pagination, but with structured output, this is acceptable.
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 coverage is 100%, and the schema description for 'cluster' is detailed with an example. The tool description adds little beyond what the schema provides ('filter by cluster slug'), but the mention of 'stable slugs' in the return value is not directly about parameters. 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 tool lists doctrine principles with stable slugs, which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'principles.get' (single item retrieval) and 'principles.search' (likely full-text search) by focusing on listing all or filtered 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?
The description mentions optional filtering by cluster slug, implying when to use it (list all or filter by cluster). However, it does not explicitly state when to prefer this over siblings like 'principles.search' or 'clusters.list', leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
principles.searchSearch PrinciplesARead-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 true, covering safety. Description adds which fields are matched but no further behavioral details (e.g., pagination, ordering). 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?
Single sentence, 10 words, front-loaded with purpose. No redundancy, every word 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?
Tool is simple with 2 params and output schema. Description sufficiently covers what it does and what it matches. Lacks detail on return format but output schema covers 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 description coverage is 100%, so baseline is 3. Description adds value by stating search targets (title, definition, rationale, cluster), which is not in schema. Provides useful context for parameter usage.
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?
Clearly states verb 'Search' and resource 'doctrine principles', and specifies matched fields (title, definition, rationale, cluster). Distinct from sibling search tools for examples and 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?
Implies use for searching principles via text query, which distinguishes it from other search tools. However, lacks explicit when-not or alternative tool recommendations.
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?
Discloses conditional storage of contact_email and that anonymous callers are welcome. Adds value beyond annotations by explaining behavior that is not inferable from schema 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?
Three concise front-loaded sentences with no redundant information. Every sentence serves a distinct 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?
Covers purpose, usage constraints, and key behavioral nuances. With output schema present and full parameter descriptions, the description is sufficiently complete for a feedback submission 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 already describes all 9 parameters thoroughly (100% coverage). Description adds cross-parameter constraint about contact_email storage and response confirmation, providing extra 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?
Clearly states 'Records explicit user feedback' with specific verb and resource. Distinguishes from sibling 'signals.report' by emphasizing explicit user request and anonymous callers.
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 instructs 'Call only when user explicitly requests; never proactively.' Provides clear context but does not mention alternatives or when not to use beyond that.
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?
Discloses that only structured fields are stored and warns against including proprietary content in brief_context. Annotations indicate it is not readonly (modifies state) and not idempotent, which aligns with the description's 'Records' verb. 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?
Three sentences, each serving a distinct purpose: purpose, storage constraint, and usage guideline. No unnecessary 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?
Given that an output schema exists, the description covers the essential aspects: what, constraints, and when to use. Could add more about expected side effects, but annotations partially cover this. Overall 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%, so baseline is 3. The description adds little beyond schema—only a reminder about the brief_context max length which is already documented. It does not explain parameter semantics further.
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 a value moment and emphasizes structured storage only. It distinguishes from siblings like signals.feedback by specifying 'no prompts or code', though it does not explicitly contrast with other sibling tools.
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 to offer once per session after a clear success signal and never silently. Also notes anonymous callers are welcome, clarifying when and by whom the tool should be invoked.
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 indicate read-only and idempotent behavior. The description adds value by disclosing authentication ('Auth: Bearer <token>') and the logging skip behavior for private sessions, which goes 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 two sentences, front-loading the core purpose, then providing usage guidance and a parameter note. Every sentence earns its place with no redundancy or fluff.
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 (2 parameters, good annotations, output schema present), the description covers purpose, usage context, auth, and a key behavioral aspect. It is complete enough 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%, and the description adds limited extra meaning beyond stating the private_session effect. The schema already describes both parameters adequately, so the description does not significantly enhance understanding.
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 'summarises your tool usage patterns and value signals from log data,' providing a specific verb and resource. It distinguishes itself from siblings like 'assets.list' or 'clusters.list' by focusing on summarization rather than listing or retrieval.
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 offers explicit guidance: 'Offer when user asks how the Blueprint is helping or what to explore next; not proactively.' It also notes the private_session parameter's effect. However, it does not explicitly mention when not to use or name alternative tools.
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!