Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vibe-blueprint Plan a simple expense tracking app with data and login."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
It plans the start. It does not build your app or watch your code. 它只规划怎么开工，不替你生成应用，也不会在后台盯着代码。
This project is not yet published to npm. Install it from the public source repository for now.
You can ask in ordinary language:
I want to build a small expense reimbursement app. I do not understand tech stacks. Give me a practical starting plan, explain the important choices, and tell me what remains uncertain.
Vibe Blueprint can return a plan shaped like this:
Part of the blueprint | Example answer |
App shape | Start with one web application instead of several services. |
Data + login | Keep receipts and accounts in managed server-side storage with managed login. |
Deployment | Use one managed deployment path for the first launch. |
Boundaries | Include employee submissions and approvals; exclude payroll and direct money movement; confirm whether offline work is required. |
Why | Fewer moving parts make the first version easier to build and maintain. |
Drawback | The managed platform creates a vendor dependency. |
Review trigger | Revisit the data approach if field staff must work through outages. |
This is an illustration of the deliverable, not a universal recommendation for every expense app.
Related MCP server: Intelligent Architecture Recommendation Engine
Describe what you want to build and the realities that matter. The configured model extracts facts and proposes complete foundation routes. Code-based gates then reject hard-constraint failures, merge look-alike choices, remove dominated routes, check required minimum safeguards, and either select a route, ask one material question, offer at most two genuinely different business routes, escalate, or abstain.
The result covers the application shape, data and login, deployment, included and excluded capabilities, important assumptions, tradeoffs, and conditions that should trigger another review.
After you approve a proposal, Vibe Blueprint saves versioned, Git-friendly project state. Later coding sessions can retrieve the accepted choices and their reasons instead of reconstructing them from chat history.
The machine-readable source of truth remains:
.project-foundation/foundation.jsonReadable and evidence-oriented artifacts include:
PROJECT-FOUNDATION.md
.project-foundation/session-brief.md
.project-foundation/evidence.json
.project-foundation/decisions.jsonlReview happens only when you or your coding agent requests it:
a new requirement can trigger focused reassessment of affected capabilities;
an on-demand Git scan can report combined payment, multi-organization, offline, and sensitive-data signals plus affected capabilities; and
a registered evidence check can be previewed or run through the command allowlist.
A Git signal does not silently rewrite the saved blueprint, identify every affected decision with semantic certainty, repair code, block a commit, or run continuously in the background.
Node.js 20 or newer
npm
Git for change scanning and commit-aware evidence
your own key for an OpenAI Responses-compatible endpoint
No API key is bundled, shared, or read from Codex authentication files.
git clone https://github.com/SinboBoop/vibe-blueprint.git
cd vibe-blueprint
npm ci
npm run build
npm linkThis exposes:
vibe-blueprint-mcp — the stdio MCP server; stdout is reserved for protocol messages.
vibe-blueprint — secure credential management and local diagnostics.
vibe-blueprint auth set
vibe-blueprint auth statusauth set accepts no key argument. It reads from an interactive terminal without echo and stores the credential in the platform user-config directory with restrictive permissions where supported. Never paste a key into chat or an MCP client configuration.
First resolve the executable's absolute path:
command -v vibe-blueprint-mcpFor Codex, replace the executable and project-root placeholders with absolute paths:
codex mcp add vibe_blueprint \
--env FOUNDATION_ALLOWED_ROOTS=/absolute/path/to/projects \
--env FOUNDATION_CODE_SHARING=none \
-- /absolute/path/to/vibe-blueprint-mcpLong model analyses may need the client timeout shown in the complete Codex, Claude Code, Cursor, and generic stdio configurations.
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "/absolute/path/to/vibe-blueprint/skill/vibe-blueprint" \
"${CODEX_HOME:-$HOME/.codex}/skills/vibe-blueprint"The Skill decides when to invoke Vibe Blueprint and presents the result in plain language. The decision logic stays in the MCP server.
vibe-blueprint doctor /absolute/path/to/project --check-modelThen start a new client session and ask:
I want to build a small SaaS where agencies manage separate client workspaces and pay monthly. Create a Vibe Blueprint before coding.
For an existing project:
Field staff must now keep editing during outages. Revisit the saved blueprint before implementation.
For a normal bug, styling change, or isolated feature that does not cross a project-foundation boundary, use the ordinary coding workflow instead.
Vibe Blueprint is not a prompt-only stack picker. Its configured model authors facts, candidate routes, scores, explanations, and safeguard declarations. Deterministic code validates that structured proposal against the documented Decision Integrity boundary: hard constraints, activity-risk rules, route equivalence and dominance, stable ordering, and minimum-invariant completeness.
Those checks reduce plausible-sounding choices that contradict the stated project realities. They do not prove a universally best stack, independently verify a vendor, inspect whether safeguards were implemented correctly, or certify production readiness.
An approved plan is written atomically as schema-versioned project state with readable summaries and an append-only decision record. Pending analysis_id values exist only in the running MCP process; restart the server before committing and the pending analysis is discarded, while committed project files remain durable.
Registered evidence commands run with separated arguments, shell: false, a controlled working directory, an allowlist, timeouts, output caps, redaction, and package-script hash binding. This is narrower than arbitrary command execution, but a passing check proves only what that registered check actually covers.
The repository includes automated tests, strict TypeScript checks, linting, protocol integration, installed-shape stdio checks, a checked-in known-regression inventory, and a repository secret scan. The inventory covers maintained failure families; it is not an expert-labelled representative benchmark, a general accuracy score, or evidence of superiority over another model.
Reproduce the checks locally:
npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run inventory:report
npm run test:protocol
npm run test:e2e
npm run scan:secrets
npm run check:skill
npm run check:brand
npm run check:packageProvider-backed verification is explicit, opt-in, and may consume quota:
npm run verify:liveIts sanitized record is scoped to that run; it is not an SLA or a production-readiness certificate.
The foundation_* names below are stable protocol identifiers retained for compatibility; they are not a second public brand.
Tool | Responsibility |
| Check configuration, credential presence, allowed roots, model connectivity, saved state, and protection coverage. |
| Ask the internal model for facts and candidate routes, then apply activity-risk, invariant, and route checks. |
| Apply the user's answer to the returned material-reality question and re-evaluate the recommendation. |
| Atomically write a user-confirmed proposal to project-foundation artifacts without modifying application source. |
| Read saved state as JSON, Markdown, or a compact Session Brief. |
| Compare a new requirement with committed state and reanalyse affected capabilities. |
| Inspect Git changes, dependencies, migrations, environment names, and structure for combined boundary signals. |
| Preview or run one explicitly registered, allowlisted evidence check without a shell. |
Your key stays outside the repository. vibe-blueprint auth set uses a user-level credential file; CLI key arguments are rejected.
No repository context by default. FOUNDATION_CODE_SHARING=none sends no caller-supplied summary, source, or Git diff.
Explicit context ceilings. summary accepts only bounded, redacted structural text; only diff permits bounded, redacted added lines.
Narrow filesystem access. Every project_root is canonicalized with realpath and checked against FOUNDATION_ALLOWED_ROOTS, including symbolic-link escapes.
Untrusted repository text stays data. Comments, documentation, summaries, and diffs are isolated from instructions before model analysis.
No arbitrary shell runner. Evidence commands use an allowlist, shell: false, timeouts, output caps, redaction, and package-script hash binding.
Protocol-safe logging. stdio stdout carries MCP only; diagnostics go to stderr and redact headers, bearer tokens, and key-shaped strings.
No silent model fallback. The configured model ID is preserved and reported when the provider rejects it.
No response-storage request. Responses requests send store: false; the endpoint operator's infrastructure remains outside this project's control.
Read the complete security model and security reporting policy before sharing repository diffs or sensitive requirements.
The FOUNDATION_* environment variables and .project-foundation/ state names remain stable protocol and persistence contracts.
Variable | Default | Purpose |
| none | Highest-priority credential; prefer |
|
| Responses-compatible base URL. |
| discovered | Explicit path override; otherwise |
|
| Exact model ID; never silently replaced. |
|
| Responses reasoning effort. |
| server working directory | Platform-delimited roots under which |
|
| Maximum repository context: |
Endpoint discovery caches only non-secret endpoint metadata in the user config directory. See .env.example for placeholders; never put a real credential in a tracked file.
Vibe Blueprint is scoped to early Web apps, SaaS products, internal tools, and AI Web projects across five reviewed architecture patterns.
It is not:
a complete application generator;
a background repository monitor, automatic plan updater, commit blocker, or deployment blocker;
a guarantee of the best technology stack;
a universal architecture, vendor, medical, financial, legal, privacy, security, or compliance advisor;
proof that declared safeguards exist in source code;
a technology evidence catalog or exact-version freshness service;
a production-readiness, security, or compliance certificate; or
an expert-labelled general-quality benchmark.
Change scanning reports conservative signals and affected capabilities, not whole-program semantic proof or a replacement blueprint. Only separately configured hooks, CI checks, and protected branches can turn selected findings into technical blockers.
See the Decision Integrity release notes for the exact compatibility contract.
Before the public rename, local checkouts used the pre-release executable aliases foundation-guard and foundation-guard-mcp and stored credentials under a foundation-guard user-config directory. This package temporarily keeps those executable aliases and safely reads that credential location when the new one is absent, so existing local users do not need to re-enter a key. New setup should use vibe-blueprint, vibe-blueprint-mcp, the vibe_blueprint client key, and the skill/vibe-blueprint path.
The eight foundation_* tools, FOUNDATION_* settings, .project-foundation/ directory, PROJECT-FOUNDATION.md, and schema version 1 intentionally remain stable.
Upgrade a source checkout with git pull --ff-only, npm ci, npm run build, npm test, and npm link. Review the release notes before upgrading a shared project because the Decision Integrity contract adds abstain as a fifth successful interaction mode.
Before uninstalling the executable, remove the user credential and MCP registration:
vibe-blueprint auth delete
codex mcp remove vibe_blueprint
npm unlink --global vibe-blueprint-mcpUninstalling does not delete .project-foundation/ or PROJECT-FOUNDATION.md from projects; those are project records and must be reviewed separately.
Issues and pull requests are welcome. Do not put keys, private source, raw diffs, exploit details, or unredacted logs in a public issue. Follow SECURITY.md to report vulnerabilities privately through GitHub.
Use the MCP's internal model plus deterministic activity-risk, minimum-invariant, and order-independent route checks to propose or deliberately abstain from a project Foundation. Additive traces explain activity evidence and route elimination. Does not write project state.
| Name | Required | Description | Default |
|---|---|---|---|
| requirement | Yes | ||
| project_diff | No | ||
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS | |
| project_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds context about additive traces, route elimination, and deliberate abstention. It also mentions the analysis is deterministic and uses specific checks, going beyond the annotation basics.
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 and each sentence carries meaningful information about purpose, traces, and side effects. It is appropriately front-loaded and avoids redundant statements, though the phrasing is dense with technical terms.
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 absence of an output schema and the complexity of four parameters, the description leaves gaps: no explanation of the return value (beyond proposal/abstention), no parameter details, and no explicit usage guidance. However, it covers the high-level behavior and safety profile reasonably.
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 only 25% (only project_root has a description). The description does not mention or explain any of the four parameters (requirement, project_diff, project_root, project_summary), leaving their semantics mostly undocumented. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool proposes or deliberately abstains from a project Foundation using specific checks. It distinguishes itself by noting it does not write project state, implying a read-only analysis. Sibling differentiation is implicit via the 'Does not write' contrast, but no explicit alternative names are given.
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 the tool is used for Foundation decision-making with the MCP's internal model, but it does not provide explicit when-to-use vs alternatives like foundation_commit or foundation_scan_changes. No exclusions are stated, so usage is implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply the user's answer to the one returned material-reality or financial-scope question, then re-run classification and the internal model recommendation.
| Name | Required | Description | Default |
|---|---|---|---|
| answer | Yes | ||
| analysis_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool re-runs classification and the internal model recommendation, which adds procedural context beyond the readOnlyHint/destructiveHint annotations. No contradiction is present, though it could be more explicit that no persistent changes are made.
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, direct, and front-loaded with the primary action. No filler or redundancy is present; every clause contributes meaningful 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 explains the workflow (apply answer, re-run classification/recommendation) but does not state what the tool returns, especially since there is no output schema. For an agent invoking the tool, the return value or result handling is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for missing parameter documentation. It implies the 'answer' parameter is the user's answer, but it does not clearly explain 'analysis_id', leaving the agent to infer that it identifies the returned question/analysis.
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 ('Apply') and identifies the resource ('the one returned material-reality or financial-scope question'), then states the follow-up actions. It is reasonably distinct from siblings like analyze_project or get, although it does not explicitly name alternatives or contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when a single material-reality or financial-scope question has been returned and the user has provided an answer. It provides clear context but does not include exclusions or explicit alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare a new requirement with committed Foundation state and reanalyze only affected capabilities. Does not commit changes.
| Name | Required | Description | Default |
|---|---|---|---|
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS | |
| new_requirement | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Does not commit changes' reiterates that. The description adds valuable behavior beyond annotations: 'reanalyze only affected capabilities', indicating a scoped analysis rather than a full reanalysis. However, it does not disclose return format, error conditions, or prerequisites like needing a committed state, so the additional context is moderate.
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-loaded with the core purpose. Every sentence earns its place: the first says what it does, the second clarifies a key non-behavior. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two parameters, no output schema, and read-only annotations, the description gives enough to invoke the tool: it knows what it does, what it affects, and that it doesn't commit. However, it lacks any mention of return values or next steps after the assessment, which an agent would need to interpret the result. A brief note on output would improve completeness.
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 50%: project_root has a description, but new_requirement does not. The description mentions 'new requirement' and 'committed Foundation state', which gives some meaning to new_requirement, but it does not clarify parameter syntax or format beyond what the schema already provides. Since coverage is below 80%, the description partially compensates but could be more explicit about the 'new_requirement' content and how it relates to project_root.
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 compares a new requirement with committed Foundation state and reanalyzes only affected capabilities. This specific verb+resource combination distinguishes it from siblings like foundation_commit (which commits) and foundation_analyze_project (which likely analyzes the whole project). The explicit note 'Does not commit changes' further disambiguates its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you have a new requirement and want to assess its impact without committing. It does not explicitly name alternatives or exclusions, but the 'Does not commit changes' caveat implicitly tells the agent not to use this for committing. A small gap is that it doesn't mention when to prefer this over foundation_scan_changes or foundation_analyze_project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically commit a validated, user-confirmed analysis proposal to Foundation artifacts. Never modifies application source.
| Name | Required | Description | Default |
|---|---|---|---|
| analysis_id | Yes | ||
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS | |
| evidence_checks | No | ||
| selected_route_id | No | ||
| protection_coverage | No | ||
| excluded_capabilities | No | ||
| included_capabilities | No | ||
| undecided_capabilities | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotation hints are provided, so the description carries the burden. It discloses atomicity and the boundary (never modifies application source), but doesn't explain what 'commit to Foundation artifacts' actually entails, side effects, or failure modes. Minimal but not misleading.
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 the core action, and no wasted words. The key constraint 'Never modifies application source' is prominent.
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 8 parameters, no output schema, and low schema coverage, the description is too thin. It doesn't mention required parameters, return values, or the meaning of the complex capability/evidence fields, leaving the agent under-informed for a multi-parameter 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 only 13%, and the description adds no parameter-level detail. It doesn't clarify what project_root, analysis_id, evidence_checks, or capability lists mean semantically, leaving the agent with sparse guidance.
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 ('commit') and resource ('Foundation artifacts') with a clear condition ('validated, user-confirmed analysis proposal'). It clearly distinguishes this commit tool from the analysis/scan/verify 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?
The description implies it should be used only after validation and user confirmation, and explicitly states it never modifies application source. It could name alternative tools more explicitly, but the contextual guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check non-secret model configuration, credential presence, allowed-root access, model connectivity, project Foundation state, and protection coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| check_model | No | ||
| project_root | No | Absolute project directory within FOUNDATION_ALLOWED_ROOTS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds valuable behavioral context by specifying it checks 'non-secret' configuration and 'credential presence' (not values), plus allowed-root access. This clarifies scope and avoids ambiguity, with 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 sentence that starts with the verb 'Check' and efficiently enumerates six specific areas without filler. While the sentence is long and could be split for readability, every term contributes to defining the tool's scope.
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 thoroughly lists what is checked, providing a solid overview. However, with no output schema, it doesn't mention the return format or how results are delivered, which is a gap for a diagnostic tool. Annotations cover safety, and the scope is clear, but the expected output remains unstated.
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 50%: project_root is described, but check_model is not. The tool description doesn't explain check_model's role or connection to the listed checks, so the agent must guess its meaning. The description fails to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'check' and lists six distinct resources or aspects being examined, making it clear this is a diagnostic tool. It distinguishes itself from sibling tools like 'commit' or 'scan_changes' by focusing on model configuration, credentials, connectivity, and protection status.
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 no explicit guidance on when to use this tool versus alternatives. It doesn't state conditions like 'when you suspect connectivity issues' or mention sibling tools as alternatives, leaving the usage context implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the authoritative Foundation JSON, readable Markdown, or compact Session Brief.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | json | |
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context: it explains the output can be 'readable Markdown' or 'compact Session Brief', and emphasizes the data is 'authoritative'. However, it does not disclose error behavior, permission requirements beyond schema hints, or how the output structure differs by format. This adds value but lacks deeper behavioral detail.
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, front-loaded with the action verb 'Read' and directly naming the resource and output variants. There is zero fluff; every phrase ('authoritative', 'readable', 'compact') earns its place by sharpening the tool's nature.
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 read-only tool with two parameters and no output schema, the description adequately conveys the core purpose and output formats. However, it omits practical notes such as the allowable roots restriction (mentioned in schema) and does not describe what happens when the project_root is invalid or not found. Given the simplicity, it is nearly complete but leaves minor edge-case questions.
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 50%: project_root has a clear description, but format is only an enum. The description's 'readable Markdown' and 'compact Session Brief' add mild semantic shades to the format values, but it does not explain the relationship between the format parameter and the output, nor any constraints beyond the schema. The enum itself already enumerates the choices, so the added value is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read the authoritative Foundation JSON, readable Markdown, or compact Session Brief.' It names a specific verb ('Read') and resource (Foundation), and enumerates the three output formats, effectively distinguishing it as the canonical read tool among the sibling analysis and mutation 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 no guidance on when to use this tool versus alternatives. There is no mention of preferred scenarios, exclusions, or explicit comparisons to sibling tools like foundation_analyze_project or foundation_scan_changes. The word 'authoritative' hints at being the primary read source, but no direct alternatives are cited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan Git changes, dependencies, migrations, environment names, and structure for combined Foundation boundary signals.
| Name | Required | Description | Default |
|---|---|---|---|
| base_ref | No | ||
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the scope of scanning multiple sources but provides no additional behavioral details such as output format, computation cost, or prerequisites beyond what annotations cover.
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, well-structured sentence that efficiently lists the scan targets and the overall goal. Every word contributes to the purpose, with no redundancy or filler.
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 scans multiple complex sources and produces 'combined boundary signals,' yet the description does not explain what the output looks like, how signals are defined, or when this should be used relative to sibling tools. The complexity demands more informational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: project_root is described, but base_ref has no description. The tool description does not mention either parameter or clarify how base_ref affects the scan, failing to compensate for the missing schema-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: scanning Git changes, dependencies, migrations, environment names, and structure. It states the goal of combining boundary signals, which distinguishes it from generic analysis tools, though 'boundary signals' could be more specific.
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 when-to-use guidance is provided. The description does not mention alternatives or contrast with sibling tools like foundation_analyze_project or foundation_doctor, so the agent has no context for selecting this tool over similar ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview or run one explicitly registered, allowlisted Foundation evidence check with no shell.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | preview | |
| check_id | Yes | ||
| project_root | Yes | Absolute project directory within FOUNDATION_ALLOWED_ROOTS |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (readOnlyHint: false, destructiveHint: false), and the description adds valuable safety context: 'with no shell' indicates command execution is disabled, and 'preview or run' clarifies available modes. This exceeds the annotation baseline without contradicting it.
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, immediately front-loaded with the core purpose, and contains no filler or redundant phrasing. Every word contributes to understanding.
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 has no output schema and the description does not mention return values, failure modes, or what 'preview' vs 'run' produces. For a simple tool this is adequate, but it leaves gaps about expected outcomes, making it minimally complete.
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 only 33%, with only project_root described. The description compensates by mapping 'preview or run' to the mode parameter and 'one explicitly registered' to check_id, providing meaning that the schema lacks. It partially compensates for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Preview or run') and the resource ('one explicitly registered, allowlisted Foundation evidence check'), with a scope constraint ('with no shell'). It distinguishes from siblings by focusing on a single check rather than broad analysis or scanning.
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 a single, pre-registered check, but does not explicitly name alternatives or state when to prefer this over sibling tools like foundation_analyze_project or foundation_scan_changes. This is clear context but lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0foundation_analyze_projectfoundation_answer_questionfoundation_assess_changefoundation_commitfoundation_doctorfoundation_getfoundation_scan_changesfoundation_verifyEach tool targets a distinct phase of the Foundation workflow: health check (doctor), proposal (analyze_project), user interaction (answer_question), reading (get), writing (commit), re-evaluation (assess_change), scanning (scan_changes), and verification (verify). There is no meaningful overlap between any two tools.
All tools share the fixed prefix 'foundation_' followed by a clear verb_noun pattern (e.g., analyze_project, answer_question, scan_changes). This provides a predictable and systematic naming scheme across the entire set.
With 8 tools, the set is well-scoped for the Foundation domain. Each tool serves a necessary function and none feel redundant or superfluous, fitting comfortably within the ideal 3-15 tool range.
The toolset covers the full lifecycle: analysis, user interaction, commit, change assessment, scanning, verification, and health checks. There are no obvious dead ends or missing core operations for the stated purpose of managing project Foundation state.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Turn your app idea into IA, wireframes, PRD, style guides, and dev specs for coding agents.
Generate MantleKit setup plans and launch-ready SaaS blueprints from a product idea.
Draw your app's architecture on a live canvas and flag the bottlenecks and security gaps.
Discover software problems, analyze evidence, and create implementation-ready Build plans.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/SinboBoop/vibe-blueprint'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
