Click on "Deploy 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., "@Vivado Agent MCP Check if the current project is ready for bitstream generation."
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.
一个面向 AI Agent 的 Vivado 自动化 MCP Server。它不追求把所有 Vivado Tcl 命令逐个包装成工具，而是提供少量、状态明确、可恢复的能力，让 Agent 完成“观察 → 决策 → 执行 → 验证”的闭环。
普通脚本只会按固定顺序执行；直接把任意 Tcl 暴露给大模型又缺少边界。本项目在两者之间增加一层 Agent 运行时：
AI Agent
│ MCP: Tools / Resources / Prompts
▼
Vivado Agent Service
│ 状态检查、前置条件、job id、统一结果
▼
单个 Vivado Tcl Session
│ 唯一请求标记、串行执行、超时隔离
▼
Vivado Project / Runs / Logs核心目标：
让 Agent 在行动前先读取工程状态，而不是猜测；
综合、实现和 bitstream 都异步启动，并返回可查询的 job id；
每个 Tool 返回同一种 JSON 结构；
在综合未完成、时序失败或日志存在阻断问题时拒绝危险的下一步；
保留 run_tcl 作为逃生舱，但优先使用有语义的专用 Tool。
Related MCP server: fpga-mcp
Tool | 用途 |
| 启动唯一的无头 Tcl 会话，可选打开 |
| 关闭本 Server 拥有的 Vivado 进程 |
| 执行无法由专用 Tool 表达的 Tcl |
| 读取器件、顶层、文件数和 run 状态 |
| 用 job id 或 Vivado run 名查询进度 |
| 幂等启动综合并返回 job id |
| 检查综合前置条件后启动实现 |
| 通过 readiness gate 后启动 bitstream |
| 从 |
| 检查 routed 状态、setup/hold slack 和阻断日志 |
vivado://project/current：当前工程快照；
vivado://jobs/{job_id}：某个异步任务的最近状态。
vivado_build_workflow：完整构建工作流；
vivado_debug_workflow：失败诊断与最小修复工作流。
每个 Tool 都返回：
{
"ok": true,
"state_changed": false,
"summary": "Project demo is open.",
"evidence": {"project": {}},
"recommended_actions": [
{
"tool": "run_synthesis",
"reason": "Synthesis has not completed.",
"arguments": {}
}
],
"error_code": null
}ok 表示 Tool 自身是否成功执行；业务结论放在 evidence 中。例如 readiness 检查成功，但 evidence.verdict 仍可能是 BLOCKED。
要求：Python 3.10+、支持 Tcl 模式的 Vivado。项目测试不要求安装 Vivado。
cd C:\path\to\vivado-agent-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"指定 Vivado 可执行文件：
$env:VIVADO_PATH = "C:\Xilinx\Vivado\2024.2\bin\vivado.bat"如果没有指定，程序依次检查参数、VIVADO_PATH、系统 PATH 和常见 Xilinx 安装目录。
本地启动 stdio MCP Server：
python -m vivado_agent_mcpCodex/兼容客户端的配置思路见 examples/codex-config.toml。把路径改成自己的绝对路径：
[mcp_servers.vivado_agent]
command = "C:\\path\\to\\vivado-agent-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "vivado_agent_mcp"]
env = { VIVADO_PATH = "C:\\Xilinx\\Vivado\\2024.2\\bin\\vivado.bat" }连接后可对 Agent 说：
使用 vivado_build_workflow 构建 D:\fpga\demo\demo.xpr。每个阶段都展示 evidence；遇到失败先诊断，不要绕过 readiness gate。
python -m pytest -q
python -m ruff check .默认测试使用假 Vivado 会话，覆盖协议封装、状态解析、job 幂等性、工作流前置条件和 bitstream 安全门。当前测试结果为 18/18 passed。
项目已在 Vivado 2018.3 和 Artix-7 xc7a35tcpg236-1 上完成真实端到端验证：
MCP discovery：10 Tools、2 Resources、2 Prompts；
connectivity：start_vivado → inspect_project → run_tcl → stop_vivado；
完整构建：synthesis、implementation、readiness gate、bitstream 全部完成；
timing：setup slack 7.201 ns，hold slack 0.324 ns；
bitstream：真实文件大小 2,192,119 bytes；
debug recovery：根据 [Synth 8-2715] 证据补回一个分号，错误数从 2 降为 0；
safety gate：缺少 create_clock 时 readiness 为 UNKNOWN，bitstream 被 BUILD_NOT_READY 阻止。
完整过程、job id、异常保护、两个真实 bug 修复和 Demo 脚本见 VIVADO_MCP_EXPERIMENT_REPORT.md。
experiments/projects/ 中只应提交可复现输入：RTL、XDC 和 create_project.tcl。Vivado 生成的 .xpr、.runs、缓存、报告、DCP 和 bitstream 由 .gitignore 排除，避免把机器相关文件和大体积构建产物提交到 GitHub。
需要复现实验工程时，在安装了 Vivado 的 Windows 环境中执行对应的 create_project.tcl，再通过 MCP 工作流启动构建。默认测试不会启动 Vivado。
第一版刻意不做 GUI 自动化、波形查看、IP Catalog、设备下载、远程 attach、自动安装和几十个同质化 Tcl wrapper。这些功能会放大代码量，却削弱“Agent 如何通过 MCP 可靠控制有状态工具”这一主线。
与参考项目相比，本项目的主要差异不是少几个 Tool，而是重新定义了抽象层：
从“Vivado 命令集合”改为“Agent 决策接口”；
从同步长调用改为 job id + 轮询；
从自由调用改为前置条件与 readiness gate；
从自然语言输出改为稳定的结构化证据和下一步建议；
核心逻辑可在无 Vivado 环境中测试。
src/vivado_agent_mcp/
├── server.py # MCP Tools / Resources / Prompts
├── service.py # Agent 工作流、前置条件和错误恢复
├── models.py # 统一 JSON 返回契约
├── tcl_commands.py # 有标签、可解析的 Tcl 查询
├── config.py # Vivado 路径发现
├── agent_context/
│ ├── state.py # 工程状态解析与下一步推荐
│ └── jobs.py # 异步 job id 注册表
└── vivado/
├── protocol.py # 请求编码、唯一标记和响应解析
└── session.py # 单 Vivado 进程与串行命令通道想真正掌握项目，请继续阅读 docs/FROM_ZERO.md。
Gate bitstream generation on routed state, timing slack, and blocking diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It does not say whether the tool is read-only, whether it can block/fail, whether it runs diagnostics itself, or what side effects it may have. 'Blocking diagnostics' is mentioned but not clarified, leaving important behavioral traits undisclosed.
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 concise sentence that front-loads the core purpose and key criteria. Every phrase (routed state, timing slack, blocking diagnostics) adds meaning without padding.
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 gives the essential gating purpose and conditions, and an output schema exists to document return values. However, with no annotations and no explicit prerequisite or usage timing, the agent must infer when exactly to invoke it and what happens when checks fail. Adequate but with clear 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 tool has zero parameters and schema coverage is 100%, so there is nothing for the description to explain. The baseline for no parameters is 4, and the description appropriately ignores 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 uses a specific gating concept ('Gate bitstream generation') and names three concrete criteria: routed state, timing slack, and blocking diagnostics. This distinguishes it broadly from generate_bitstream and diagnose_run, though the exact action ('check' vs 'enforce') is slightly implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Gate bitstream generation' clearly implies the tool should be used before generate_bitstream, but there is no explicit instruction on when to call it, what prerequisites exist (e.g., after run_implementation), or how it differs from diagnose_run and inspect_run. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract bounded errors and critical warnings from a Vivado run log.
| Name | Required | Description | Default |
|---|---|---|---|
| run_name | Yes | ||
| max_issues | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It implies a read-only extraction of errors and warnings, but does not state whether the operation is side-effect free, whether it requires a specific run state (e.g., a completed run), or what happens if the log is missing. It also does not describe the output format, despite an output schema existing. The description is too minimal to convey behavioral expectations.
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, focused sentence with no redundant wording. It is appropriately sized for a tool with two simple parameters, and the core action is front-loaded. However, it is so brief that it under-specifies content, which slightly reduces the score from a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and incomplete parameter documentation, the description is insufficient. It does not explain what 'bounded errors' means, how max_issues affects behavior, or what the output schema contains. An agent would struggle to know exactly what to expect or how to handle edge cases. The presence of an output schema does not compensate because its content is not described.
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 0%, so the description must compensate by explaining parameters. It fails to do so: 'run_name' is not described (likely the name of the run to diagnose), and 'max_issues' is not described either, though 'bounded' hints at a limit. The description provides no explicit meaning for either parameter, leaving an agent to guess their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Extract') and a specific resource ('bounded errors and critical warnings from a Vivado run log'). It distinguishes this tool from siblings like inspect_run by focusing on error extraction rather than general inspection. However, it does not explicitly name an alternative or contrast with a sibling, so it falls slightly short of a 5.
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. It does not mention that this is for diagnosing a run after synthesis/implementation, nor does it suggest that inspect_run or check_build_readiness might be more appropriate for other scenarios. An agent must infer usage context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch bitstream generation only when timing and diagnostic gates pass.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full disclosure burden. It reveals one meaningful behavioral trait—that the tool is gated by timing and diagnostic results and should not be launched before they pass—but stays silent on duration, blocking behavior, failure modes, and side effects of a generation run.
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 12-word sentence that front-loads the action ('Launch bitstream generation') and folds the precondition into a dependent clause. No filler, no repetition, 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?
For a one-parameter tool with an output schema, the description covers the central precondition, but it never connects the gates to the sibling workflow (check_build_readiness / diagnose_run) or explains what a launch entails (e.g., long-running FPGA build). An agent can attempt the call, but must infer the surrounding flow.
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 0%, so the description was expected to compensate for the single 'jobs' parameter, and it never mentions it. The schema's title 'Jobs' and default of 4 provide minimal meaning, but the description adds nothing beyond what the structured schema already exposes.
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 pairs a specific verb ('Launch') with a specific resource ('bitstream generation'), and the gating phrase positions it as the terminal build step. This distinguishes it cleanly from the earlier run_synthesis / run_implementation stages and from the diagnostic inspect/diagnose siblings, so an agent can tell this is the final generate step in the flow.
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?
'Only when timing and diagnostic gates pass' gives an explicit precondition for when to call the tool and implicitly forbids calling it before the gates pass. However, it never names the alternatives the agent should consult first (check_build_readiness, diagnose_run, inspect_run), so the routing guidance is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read current project, sources, part, top module, and build-run states.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Read' clearly signals a non-mutating operation, and the listed items outline what is inspected. It doesn't disclose potential side effects (though none are likely) or performance characteristics, but it adequately communicates the read-only nature.
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 with the key action 'Read' front-loaded. Every word adds value, and it avoids unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no parameters and an output schema, the description adequately covers the scope and purpose. It doesn't mention prerequisites (e.g., a project must be open), but such details are likely implicit in the tool's operation and not critical for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is vacuously 100%. The baseline for a no-parameter tool is 4, and the description doesn't need to add parameter semantics since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a read operation on the project state, listing the specific items (project, sources, part, top module, build-run states). It distinguishes from inspect_run by focusing on project-level state rather than a specific run, though it doesn't name the sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need to inspect overall project state) but doesn't explicitly contrast with siblings like inspect_run or diagnose_run. No exclusions or alternative recommendations are given, but the scope is clear enough for an agent to infer the intended use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect an asynchronous job by MCP job ID or a native Vivado run name.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| run_name | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden. The verb 'Inspect' implies a read-only operation and the dual lookup key is disclosed, but the description says nothing about what happens when both job_id and run_name are supplied, whether both may be empty (both have '' defaults), or whether the job must be in a particular state to be inspective.
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 13-word sentence with the verb, resource, and both lookup keys front-loaded. There is zero filler and every word contributes meaning; this is appropriately minimal for the tool's small parameter surface.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, an output schema exists to document return values, and the core mechanic is fully described. However, with no annotations and a potentially confusable sibling (diagnose_run), the description should have addressed selection criteria and dual-parameter behavior. It is adequate for a basic call but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does map job_id to 'MCP job ID' and run_name to 'native Vivado run name', and the word 'or' conveys that they are alternative selectors, which is real value beyond the bare schema. It stops short of clarifying precedence if both are provided or the meaning of the empty-string defaults, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Inspect') and resource ('an asynchronous job'), and specifies two lookup modalities (by MCP job ID or native Vivado run name), which clearly distinguishes it from inspect_project (project vs run/job). However, it does not differentiate itself from the sibling diagnose_run, which could plausibly serve a similar 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?
No when-to-use or when-not-to-use guidance is provided. It never says when to choose this tool over inspect_project or diagnose_run, nor does it contextualize usage within the async job lifecycle (e.g., 'after starting a job, use this to check its status'). The word 'asynchronous' implies a use case, but the description leaves the selection logic entirely to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch implementation only after project and synthesis prerequisites pass.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden of behavioral disclosure. It only says 'launch', implying a process start, but does not describe side effects, blocking behavior, output format, or whether it modifies state. The precondition hint is helpful but insufficient for an agent to understand what happens when the tool runs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the verb and the critical precondition. It is appropriately short, though it sacrifices detail for brevity.
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 role in a pipeline and the existence of siblings like check_build_readiness and run_synthesis, the description does not provide enough context. It does not explain how to verify the prerequisites, what the implementation stage entails, or how it relates to neighboring tools. The output schema exists, so return format is covered, but the operational context 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?
The single parameter 'jobs' has schema coverage of 0% and the description does not mention it at all. The agent is left to infer that it controls parallelism based only on the default value of 4. The description fails to explain the parameter's purpose or valid values.
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 'launch' and resource 'implementation', and includes a precondition. It is distinguishable from siblings like run_synthesis and generate_bitstream because it targets the implementation stage. However, it does not explicitly define what 'implementation' produces, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear precondition: 'only after project and synthesis prerequisites pass'. This implies usage timing but does not explicitly name alternatives or state when not to use the tool. It could be improved by referencing sibling tools like run_synthesis or check_build_readiness, but the prerequisite guidance is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch synthesis idempotently and return a job ID instead of blocking.
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, the description discloses key behaviors: it is idempotent (safe to call repeatedly) and non-blocking (returns a job ID rather than waiting). This goes beyond the tool name, but it does not cover what happens on repeated calls, whether a new job is created, or how the job is monitored.
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 filler; the main purpose and key behavior are front-loaded ('Launch synthesis...'). It packs useful modifiers without extra 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?
The tool is a launch operation with an output schema, so return values are covered elsewhere. However, the description omits any mention of the 'jobs' parameter and gives no indication of how to monitor the created job, despite siblings like inspect_run existing; the description is adequate for a default call but incomplete for customization.
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 single parameter 'jobs' is completely undocumented in the schema and the description never mentions it (schema coverage 0%). With no parameter semantics provided, an agent cannot tell whether 'jobs' means parallel count, retry count, or something else; this is a significant 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?
The description uses a specific verb ('Launch'), names the resource ('synthesis'), and adds two behavioral qualifiers ('idempotently', 'return a job ID instead of blocking') that distinguish it from sibling tools like run_implementation and generate_bitstream. An agent can tell exactly what this tool does and roughly how it behaves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over siblings. It does not mention prerequisites, context, or alternative tools for blocking runs; the 'instead of blocking' hint is behavioral, not usage guidance. An agent must infer when synthesis is the right step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use raw Tcl as an escape hatch, then refresh project context before further actions.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not warn that raw Tcl commands can modify project state, consume arbitrary time, or have side effects beyond what other tools handle. The only behavioral hint is the need to refresh project context, which suggests state may be stale but lacks detail on safety or reversibility.
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 with no filler or redundant phrasing. It front-loads the main action and adds a practical instruction for the next step. It is concise, though the density of meaning is low due to its brevity.
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 this is a raw command execution tool with no annotations and undocumented parameters, the description is insufficient. It does not explain how the command integrates with the Vivado environment, what the output schema represents, or any safety considerations. The presence of an output schema is noted, but the description still leaves critical calling details unspecified.
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 0%, so the description must compensate by explaining the parameters. It fails to describe the 'command' parameter format (e.g., that it contains Tcl syntax) or the 'timeout_seconds' parameter and its default behavior. The only clue is 'raw Tcl', which does not document either parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool runs raw Tcl, which is a specific action on a clear resource (Tcl commands in the context of the Vivado project). It is distinct from the sibling tools that operate on higher-level workflows like synthesis or bitstream generation. However, it uses the metaphorical phrase 'escape hatch' rather than an explicit verb like 'execute', which slightly weakens clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'escape hatch' implies use when other tooling is insufficient, and the instruction to 'refresh project context before further actions' provides a concrete post-condition. However, it does not explicitly name alternatives or state when not to use this tool, leaving the usage boundary implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start one headless Vivado Tcl session and optionally open an existing .xpr project.
| Name | Required | Description | Default |
|---|---|---|---|
| vivado_path | No | ||
| project_path | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It usefully reveals that the session is headless and that opening a project is optional, but it omits lifecycle details such as whether the session persists until stop_vivado, whether startup blocks, or what happens if the project path is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It communicates the operation, the headless mode, the Tcl session nature, and the optional project behavior 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?
The definition is adequate for a simple two-parameter tool, and the output schema covers return values. However, with no annotations, it leaves lifecycle context thin: an agent must infer from sibling names that the session should later be stopped and that run_tcl operates within it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must supply parameter meaning. It directly defines project_path as an existing .xpr project and strongly implies vivado_path is the Vivado executable path; the word 'optionally' also clarifies that both parameters are not required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Start'), the resource ('one headless Vivado Tcl session'), and the optional project file ('an existing .xpr project'). This clearly distinguishes start_vivado from siblings like run_tcl, stop_vivado, and inspect_project.
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 that starting a session is a prerequisite for later Tcl commands, but it does not explicitly say when to use this tool versus stop_vivado, run_tcl, or check_build_readiness. No alternative tools or exclusion conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the Vivado process owned by this MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| summary | Yes | |
| evidence | Yes | |
| error_code | Yes | |
| state_changed | Yes | |
| recommended_actions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action 'Stop' but does not disclose whether termination is graceful or forceful, whether it blocks until exit, what happens to active runs, or whether the operation is idempotent. This is a meaningful gap for a process-stopping mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action and scope with no filler. 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?
For a zero-parameter tool with an output schema, the description is mostly sufficient: it names the target process and ownership boundary. It could be improved by clarifying side effects or exit behavior, but given the low complexity, it is reasonably 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?
The tool has zero parameters and the schema is empty, so there is no parameter meaning for the description to add. The baseline of 4 applies because no parameter documentation is needed.
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 ('Stop') and a specific resource ('the Vivado process owned by this MCP server'). This clearly distinguishes it from siblings like start_vivado and run_tcl, and no schema inspection is needed to understand what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need to stop the MCP server's own Vivado process. However, it does not explicitly mention alternatives or provide any when-not-to-use guidance, leaving the usage context largely implicit.
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.
v0.1.0check_build_readinessdiagnose_rungenerate_bitstreaminspect_projectinspect_runrun_implementationrun_synthesisrun_tclstart_vivadostop_vivadoScored across 10 tools
Each tool targets a distinct stage or concern: session lifecycle, raw Tcl escape hatch, project/run inspection, build steps, log diagnostics, and readiness gating. No two tools have overlapping purposes, and run_tcl is clearly an escape hatch rather than a duplicate.
All tool names follow a consistent verb_noun pattern in snake_case (start_vivado, inspect_project, run_synthesis, generate_bitstream, check_build_readiness). The naming convention is uniform and predictable, making tool selection straightforward.
With 10 tools, the server is well-scoped for a Vivado build automation agent, covering lifecycle, inspection, build steps, diagnostics, and gating without redundancy. Each tool has a clear responsibility and earns its place.
The tool surface covers the full FPGA build flow: session management, project/run inspection, synthesis, implementation, bitstream generation, and diagnostics/gating. The raw Tcl escape hatch also covers edge cases, so there are no obvious dead ends for the stated purpose.
Flash and run real firmware on physical embedded dev boards from an AI agent, over MCP.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
One MCP tool for verified AI-agent outcomes with success-only charging.
