一个开源的 Model Context Protocol 服务器，为 AI 助手提供完整的 FPGA 工具链——lint、仿真、综合、布局布线、烧录比特流，以及一个由 GitHub 驱动的实时 IP 核注册表。
你可以让 AI 搜索 IP 核、拉取它们、lint HDL、综合磁盘上的多文件 VHDL 或 Verilog 工程、运行仿真，然后把比特流烧录到你的开发板上——全程无需离开聊天窗口。
多语言支持：Verilog、SystemVerilog 和 VHDL（通过 ghdl-yosys-plugin）
三种输入模式：内联 code 字符串、多文件 files 字典，或磁盘上的 project_dir 路径
文件列表支持：files.f/sources.f，支持 +incdir+、+define+ 和嵌套的 -f 指令
开发板预设：11 块内置开发板（iCEBreaker、ULX3S、TinyFPGA BX、Tang Nano 等）——自动设置 target/device/package/clock
约束自动检测：在工程目录中自动查找 .pcf/.lpf/.pdc/.cst
比特流烧录：通过 iceprog（iCE40）或 openFPGALoader（ECP5/Gowin/Nexus/Xilinx）烧录
Vivado：通过 start_build 批量运行，Xilinx 构建通过 LiteX，build_status 中结构化解析 Vivado 日志
仿真结果判定：PASS/FAIL/UVM 模式检测，附带 VCD 信号摘要
后台构建：长时间运行的综合/布局布线，支持状态轮询和严格的仅 EDA 命令白名单
并发请求：在慢速工具调用仍在运行时响应 ping、构建状态和取消请求；notifications/cancelled 可中止正在进行的调用
机器可读结果：工具结果上的 structuredContent（MCP 2025-06-18），以及用于重试/回退决策的统一 error_code 分类
进度通知：当客户端发送 progressToken 时，在综合、布局布线和 LiteX 运行的阶段边界发送 notifications/progress
IP 核注册表：从 GitHub 实时搜索和导入，支持 FuseSoC CAPI2 元数据
健康检查：发现 OSS CAD Suite 中已安装且可访问的工具
Related MCP server: vivado-mcp-agent
MCP 服务器作为本地子进程运行。你的 AI 通过 JSON-RPC（stdio）调用其上的工具。服务器会调用 OSS CAD Suite 中的 Yosys、nextpnr、iverilog、Verilator 等工具——并且可以直接从 GitHub 拉取开源 FPGA IP 核。
Your AI assistant <--> fpgaZeroMCP (stdio MCP server) <--> OSS tools
|
cores/ registry on GitHub
(uart_tx, fifo + any imported)要求 | 说明 |
Python 3.11+ | |
一次性打包下载 iverilog、Yosys、nextpnr、Verilator、Verible、GHDL | |
可选——仅在使用 LiteX 工具时需要 |
安装后，将 OSS CAD Suite 添加到你的 PATH。如果某个工具缺失，所有工具包装器都会优雅降级。
默认情况下，GitHub API 请求未经过身份验证，并受速率限制。设置个人访问令牌可提高限额：
# Linux/macOS
export GITHUB_TOKEN=ghp_...# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_..."git clone https://github.com/lcapossio/fpgaZeroMCP
cd fpgaZeroMCP
pip install -e .添加到 claude_desktop_config.json：
{
"mcpServers": {
"fpgaZeroMCP": {
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}
}添加到工作区中的 .vscode/mcp.json：
{
"servers": {
"fpgaZeroMCP": {
"type": "stdio",
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}
}添加到你的 MCP 设置（Settings → MCP Servers）：
{
"fpgaZeroMCP": {
"command": "python",
"args": ["/path/to/fpgaZeroMCP/server.py"],
"env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
}
}"帮我找一个 I2C 主机 IP 核并导入。"
"综合 ~/projects/my_fpga 中的 VHDL 文件，并告诉我 LUT 数量。"
"对我的工程执行面向 iCEBreaker 开发板的布局布线，然后烧录。"
"使用 seed 42 运行布局布线，尝试获得更好的时序。"
"对这个 Verilog 执行 lint 并修复所有错误。"
"仿真这个 FIFO，并告诉我测试平台是否通过。"
"格式化这个 SystemVerilog 文件。"
"我安装了哪些 OSS CAD Suite 工具？"
工具 | 说明 |
| 通过 iverilog（V/SV）或 GHDL（VHDL）进行语法/错误检查——单文件 |
| 同时 lint 多个文件，使跨模块引用能够解析 |
| 结构化的逐行诊断——Verilator → verible 回退（V/SV），GHDL（VHDL） |
| 通过 verible-verilog-format（V/SV）或 vsg（VHDL）自动格式化 |
工具 | 说明 |
| 编译并运行测试平台——iverilog（V/SV）或 GHDL（VHDL）。接受 |
| 使用 Yosys 综合并给出资源统计。接受 |
| 一步完成 Yosys + nextpnr。开发板预设、约束自动检测，比特流写入磁盘（ |
| 通过 |
| 枚举内置开发板预设（target/device/package/clock） |
工具 | 说明 |
| 浏览本地注册表，按类别筛选 |
| 获取某个 IP 核的清单和 HDL 源码 |
| 获取参数化实例化片段 + 源文件 |
| 在 GitHub 上搜索 MIT 许可的 FPGA IP 仓库 |
| 将 GitHub 仓库下载到本地注册表 |
| 导入本地 FuseSoC CAPI2 |
工具 | 说明 |
| 使用 |
| 生成 LiteX SoC，不构建 gateware |
| 使用完全自定义的参数运行 LiteX 开发板目标 |
工具 | 说明 |
| 在后台启动长时间运行的命令（仅限白名单中的 EDA 工具） |
| 检查进度——状态、已用时间、解析出的阶段/资源利用率/时序 |
| 列出所有被跟踪的构建（运行中和已完成） |
| 终止正在运行的后台构建 |
| 按年龄和总大小删除旧的构建日志 |
工具 | 说明 |
| 报告哪些 OSS CAD Suite 工具已安装，含路径和版本 |
| 无需重启服务器即可重新扫描 IP 核目录 |
IP 核存放在 cores/<name>/ 中——包含一个 core.json 清单和一个或多个 HDL 文件。服务器在启动时自动发现它们，并在任何导入后重新加载。
内置两个参考 IP 核（uart_tx、fifo）以演示该格式。注册表并非要在这里增长——它由 GitHub 驱动。
# Find a RISC-V softcore
search_github_cores("riscv softcore", language="verilog")
# Pull it in
import_github_core("YosysHQ/picorv32")
# It is now in the local registry
get_ip_core("picorv32")
generate_ip("picorv32", {"COMPRESSED_ISA": 1})当仓库中存在 FuseSoC CAPI2 元数据（.core 文件）时，服务器会自动使用它，从而获得更丰富的参数和端口信息。只有具有允许的许可证的仓库才会被接受。
请不要为此仓库提交添加 IP 核的 PR。 而是：
在 GitHub 上发布你的 HDL 仓库，带上 fpga 主题和 MIT 许可证
可选：添加 FuseSoC CAPI2 .core 文件以获得更丰富的元数据
然后任何人都可以直接 import_github_core("you/your-core")
这样可以让服务器保持精简，并让社区在 GitHub 上有机地成长。
目标 | 供应商 / 系列 | 完整的开源 P&R |
| Lattice iCE40 | 是——nextpnr-ice40 |
| Lattice ECP5 | 是——nextpnr-ecp5 |
| Lattice Nexus (CrossLink-NX, CertusPro-NX) | 是——nextpnr-nexus |
| Gowin | 是——nextpnr-gowin |
| Xilinx / AMD | 仅综合 |
| Intel / Altera | 仅综合 |
| 与技术无关 | 仅网表 |
用于 place_and_route 的常用 device/package 值：
目标 | device | package |
ice40 |
|
|
ecp5 |
|
|
nexus |
| (内嵌在设备字符串中) |
gowin |
| (内嵌在设备字符串中) |
LiteX 是一个基于 Python 的 SoC 框架，可以面向许多 FPGA 开发板。fpgaZeroMCP 提供了三个专用的 LiteX 工具，并且在 synthesize 和 place_and_route 中也接受 backend="litex"。
# Dedicated tools
litex_build(board="arty", args=["--build"])
litex_soc(board="arty", args=["--no-compile"])
litex_flow(board="arty", args=["--build", "--output-dir", "build_arty"])
# As a backend in existing flow tools
synthesize(code="...", top_module="top", backend="litex", litex_board="arty")
place_and_route(code="...", top_module="top", target="ice40", device="hx1k",
backend="litex", litex_board="arty", litex_args=["--build"])你可以通过两种方式将注册表指向你自己的本地 HDL 目录：
环境变量：
Linux/macOS（冒号分隔）：
export USERCORES_PATH=/home/you/my-cores:/home/you/work-coresWindows（分号分隔，PowerShell）：
$env:USERCORES_PATH = "C:\Users\you\my-cores;C:\Users\you\work-cores"配置文件（~/.fpgazero_mcp/config.json）：
{
"core_paths": [
"/home/you/my-cores",
"/home/you/work-cores"
]
}默认情况下，import_github_core 接受以下任一 SPDX 许可证的仓库：
MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0通过 FPGA_ZERO_ALLOWED_LICENSES 环境变量覆盖（逗号分隔的 SPDX ID）：
# Linux/macOS
export FPGAZERO_ALLOWED_LICENSES=MIT
export FPGAZERO_ALLOWED_LICENSES=MIT,Apache-2.0# Windows (PowerShell)
$env:FPGAZERO_ALLOWED_LICENSES = "MIT"
$env:FPGAZERO_ALLOWED_LICENSES = "MIT,Apache-2.0"许可证 ID 遵循 SPDX 表示法。检查是在导入时进行的；search_github_core 返回结果时不受许可证影响，因此你可以在导入前进行审查。
pip install -e ".[dev]"
python -m pytest tests/ -v某些测试需要 PATH 中包含 OSS CAD 工具。缺少所需工具的测试会自动跳过。
服务器通过 stdio 传输以 1 进程/会话 的子进程运行（这就是 MCP 客户端如 Claude Desktop 启动它的方式）。每个会话在 Linux 上闲置时占用约 60-90 MB RSS，主要来自 Python 解释器及依赖库。
如果你运行许多并发 MCP 会话，请在启动 MCP 客户端之前设置以下环境变量：
# Linux — reduces glibc malloc arena fragmentation (can save 10-20 MB per session)
export MALLOC_ARENA_MAX=2
# Strip bytecode position annotations from tracebacks (saves a few MB)
export PYTHONNODEBUGRANGES=1
# Skip .pyc cache files (no memory impact, avoids disk writes)
export PYTHONDONTWRITEBYTECODE=1这些是零代码更改，并且完全透明。
变量 | 描述 |
| GitHub 个人访问令牌 — 提高 API 速率限制 |
| 额外的内核搜索目录（操作系统路径分隔符分隔） |
| 用于 |
| 覆盖临时工作区根目录 |
| 持久服务器工件（构建日志、XYZ 输出、临时工作区）的根目录（默认： |
| OS pathsep 分隔的额外目录列表， |
Python API 可以直接使用，无需 MCP 客户端：
from registry.resolver import CoreRegistry
from tools.lint import lint_hdl
reg = CoreRegistry()
# Import a core from GitHub
reg.import_github_core("ben-marshall/uart")
# Generate a parameterized instantiation
result = reg.generate_ip("uart", {"CLKS_PER_BIT": 868})
print(result["instantiation"])
# Lint some HDL
lint_hdl(open("my_design.v").read())python example.py # runs the built-in demo{
"name": "my_core",
"version": "1.0.0",
"description": "...",
"author": "you",
"license": "MIT",
"language": "verilog",
"category": "communication",
"tags": ["spi", "serial"],
"parameters": {
"DATA_WIDTH": { "type": "integer", "default": 8, "description": "..." }
},
"ports": {
"clk": { "direction": "input", "width": 1, "description": "System clock" }
},
"files": ["my_core.v"]
}Leonardo Capo (bard0) — hello@bard0.com
MIT — 参见 LICENSE。
Check the progress of a background build. Returns status (running/success/failed), elapsed time, and recent log output.
| Name | Required | Description | Default |
|---|---|---|---|
| build_id | Yes | Build ID returned by start_build | |
| tail_lines | No | Number of log lines to return from the end | |
| parse | No | Parse log for build phase/utilization/timing (set false for fast polling) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses return values (status, time, logs) but does not mention idempotency, side effects, or safety. Adequate for a read operation but lacks depth.
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, well-structured sentence that front-loads the key action and result. 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?
Without output schema, description partially covers return values. Missing details on error responses or pagination. Adequate for a simple status check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds no additional information about parameters beyond the schema. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Check the progress' and resource 'background build', with specific return fields. Distinguishes from siblings like start_build and cancel_build.
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?
Implied usage after start_build, but no explicit when-to-use or comparison with alternatives like list_builds. Missing guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a running background build.
| Name | Required | Description | Default |
|---|---|---|---|
| build_id | Yes | Build ID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the cancellation is immediate, what happens to partial outputs, or authorization needs. The word 'cancel' implies destructiveness but lacks 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?
One sentence with no filler, but could be improved by front-loading key context like prerequisites or side effects while staying 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?
For a simple cancellation tool with no output schema, the description omits return values, error conditions, and any confirmation behavior, leaving the agent underinformed.
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 has 100% coverage for the single parameter, so the description adds no extra meaning beyond the schema's 'Build ID to cancel'. 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 clearly states the action ('Cancel') and the resource ('a running background build'), distinguishing it from siblings like start_build or build_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?
No guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., build must be running) or scenarios to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check which EDA tools are installed and reachable. Returns tool name, path, and version for each detected binary.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries burden. It states tools are 'installed and reachable' and returns details, but does not disclose potential side effects or failure modes. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded, with no extraneous information. Efficient 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 no parameters, no output schema, and low complexity, the description covers what the tool does and what it returns. Could add error handling details but sufficient for understanding.
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?
Tool has zero parameters with 100% schema description coverage. No parameter info in description is acceptable; baseline 4 for no parameters.
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 checks installed EDA tools, with a specific verb 'check' and resource 'EDA tools'. It distinguishes from sibling tools that perform actions like building or linting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives. The purpose is implied but lacks exclusions or context for when this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete old build logs to reclaim disk space. Removes logs older than max_age_days, then trims oldest until under max_total_mb.
| Name | Required | Description | Default |
|---|---|---|---|
| max_age_days | No | Delete logs older than this many days | |
| max_total_mb | No | Target max total log size in MB |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes the tool's behavior: it performs two actions—deleting logs older than max_age_days and trimming the oldest until under max_total_mb. This is transparent about the destructive nature and the algorithm, though it does not mention permissions or side effects.
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 totaling 18 words, with the primary action stated first. Every word is necessary and no redundancy. The structure is 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 (no output schema, 2 parameters with full schema coverage), the description covers the main behavior adequately. It does not explain return values, but for a cleanup operation this is acceptable. The sibling tools list confirms it's distinct.
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 covers both parameters with descriptions, but the description adds value by explaining the sequence of actions (age-based then size-based) and that trimming targets the oldest logs. This provides context beyond what the schema individual descriptions convey.
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: 'Delete old build logs to reclaim disk space.' It specifies the exact operations (removing logs by age and trimming by size) and the resource (build logs). This distinguishes it from siblings like build_status or start_build, which have different functions.
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 disk space reclamation but does not explicitly state when to use this tool versus alternatives (e.g., manual deletion or other cleanup tools). No guidance on prerequisites or when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Format HDL source code and return the result. Verilog/SystemVerilog: uses verible-verilog-format. VHDL: uses vsg (pip install vsg). Returns the formatted code and whether it changed.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | HDL source code to format | |
| language | No | HDL language variant | verilog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns formatted code and a change indicator, and names the underlying formatters. However, since no annotations are provided, the description bears full burden; it does not explicitly state whether the tool modifies files or is read-only, nor does it cover potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences front-load the main action and provide key details without redundancy. 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?
With only two parameters having full schema coverage and no output schema, the description explains the return value and underlying tools. It could mention installation requirements or side effects but is sufficiently complete for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions (100% coverage). The description adds context about the formatters used per language but does not provide additional semantic details beyond the schema, warranting a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: formatting HDL source code and returning the result. It specifies the tools used for Verilog/SystemVerilog and VHDL, distinguishing it from sibling tools like lint_hdl and synthesize.
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 the tool should be used to format HDL code but provides no explicit guidance on when to use it versus alternatives like lint_hdl for linting. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a parameterized instance of an IP core. Returns the HDL source files and a ready-to-paste Verilog instantiation snippet with the requested parameter values applied.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Core name, e.g. 'uart_tx' or 'fifo' | |
| parameters | No | Parameter overrides, e.g. {"CLKS_PER_BIT": 434} | |
| instance_name | No | Verilog instance name (default: <core_name>_inst) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions the return type (HDL files and snippet) but omits side effects, permission requirements, error handling, or whether the tool consumes external resources. Without annotations, this lack of safety and behavioral detail is a significant gap.
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 fluff, front-loaded with action and output. Every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity (3 params, one nested object), the description covers the basic purpose and return type but lacks details on expected structure of HDL files, error conditions, and dependencies. It is adequate but leaves gaps that could mislead an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value ('with the requested parameter values applied') and does not elaborate on the 'parameters' object structure or validation rules beyond the schema. No additional semantic guidance is provided.
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 ('Generate') and resource ('parameterized instance of an IP core'), clearly stating the output: 'HDL source files and a ready-to-paste Verilog instantiation snippet'. This distinguishes it from sibling tools like get_ip_core (which likely retrieves without generating) and list_ip_cores (which lists cores).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With many sibling tools (e.g., get_ip_core, list_ip_cores, import_*), the description fails to mention scenarios where other tools would be more appropriate, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return structured lint diagnostics (line, column, severity, message) for HDL source. Verilog/SystemVerilog: uses Verilator (primary) with verible-verilog-lint as fallback. VHDL: uses GHDL. All tools are part of OSS CAD Suite.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | HDL source code | |
| language | No | HDL language variant | verilog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the toolchain (Verilator with fallback, GHDL) and mentions OSS CAD Suite, which is helpful. However, it lacks information on side effects, error behavior, required permissions, or performance implications. The read-only nature is implied but not stated.
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 with two sentences, no redundant information. The first sentence defines purpose and output structure, the second provides toolchain details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description compensates by listing the output fields (line, column, severity, message). It also explains language-tool mapping. However, it does not address error cases or tool availability, but overall it is fairly complete for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters. The description adds no additional parameter-level meaning beyond what the schema already conveys. Baseline score of 3 is appropriate as the description does not enhance parameter 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 returns structured lint diagnostics with specific fields (line, column, severity, message). It identifies the resource as 'HDL source' and distinguishes by specifying the toolchain per language. However, it does not explicitly differentiate from sibling tools like 'lint_hdl' or 'lint_project', leaving room for ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or context. The sibling list includes similar tools like 'lint_hdl', but the description offers no basis for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full manifest and HDL source files for a named IP core.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Core name, e.g. 'uart_tx' or 'fifo' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states the action but does not disclose whether the tool is read-only, any required permissions, side effects, or output format. This is insufficient for a fetch operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. No extraneous words, every part 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?
With no output schema or annotations, the description is somewhat limited. It explains what the tool does but does not specify what is returned (e.g., raw files, metadata). For a simple fetch, it is minimally adequate but could provide more context about expected output.
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 provides a complete description for the only parameter 'name' (e.g., core name with examples). The description adds no additional meaning beyond the schema, so baseline score 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 uses a specific verb ('Fetch') and identifies the resource ('full manifest and HDL source files') and the input ('named IP core'). It clearly distinguishes from siblings like 'list_ip_cores' and 'generate_ip'.
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?
There is no guidance on when to use this tool vs alternatives such as 'search_github_cores' or 'import_fusesoc_core'. The description does not mention prerequisites or when it is appropriate to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a local FuseSoC CAPI2 .core file into the registry. HDL files referenced in the .core file must exist in the same directory. Useful when you already have FuseSoC cores checked out locally.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or relative path to the .core file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description provides one behavioral constraint: HDL files must exist in same directory. However, it does not disclose side effects, idempotency, or what 'registry' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences directly stating purpose, requirement, and use case. 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 simple tool with one parameter and no output schema, the description provides sufficient context: purpose, prerequisite (HDL files in same dir), and use case. Minor gap: no explanation of registry impact.
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 description is not required to add much. It merely restates the parameter's purpose without further detail, maintaining baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports a local FuseSoC CAPI2 .core file into the registry, specifying the file format and local nature, distinguishing it from sibling like import_github_core.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Useful when you already have FuseSoC cores checked out locally,' implying when to use and distinguishing from remote imports, though it doesn't explicitly list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download an open-source GitHub repository and add it to the local IP core registry. Automatically uses FuseSoC CAPI2 metadata (.core file) if one exists in the repo. After import, the core is immediately available via get_ip_core and generate_ip.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | GitHub repo in 'owner/repo' format, e.g. 'ultraembedded/core_uart' | |
| subdir | No | Subdirectory within the repo to scope HDL search (for monorepos) | |
| ref | No | Branch, tag, or commit SHA (default: repo's default branch) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it downloads and adds to registry, and uses FuseSoC metadata automatically. It does not disclose whether existing cores are overwritten, authentication requirements, or error behavior on missing metadata.
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 with zero wasted words. First sentence states the main action, second adds important post-import availability information. Highly concise 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?
The description is brief and covers core functionality but lacks details on error handling, behavior when no .core file exists, or cleanup on failure. Given the tool's complexity (remote download, metadata parsing), more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by clarifying the repo format (owner/repo), subdir for monorepos, and ref for branch/tag/commit. Examples like 'ultraembedded/core_uart' are helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool downloads a GitHub repo and adds it to the local IP core registry, with automatic use of FuseSoC metadata. This distinguishes it from siblings like search_github_cores (search only) and import_fusesoc_core (likely different import source).
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 notes that after import, the core is available via get_ip_core and generate_ip, guiding subsequent usage. However, it does not explicitly mention when not to use this tool or compare with the sibling import_fusesoc_core.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lint HDL source code using iverilog/verilator (Verilog/SystemVerilog) or ghdl (VHDL). Use linter='verilator' to enable -Wall checks including multidriven net detection.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | HDL source code to lint | |
| language | No | HDL language variant | verilog |
| top_module | No | Top-level module name (optional) | |
| linter | No | Linter backend for Verilog/SV. 'verilator' enables -Wall (multidriven nets, etc.) | iverilog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description adds some behavioral context (linter options, verilator -Wall), but doesn't disclose output format or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with primary action, second sentence provides a useful tip. No 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?
Tool is simple; description covers main action and key parameter nuance. Absence of output schema is acceptable for a lint tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds marginal value by noting verilator's -Wall checks beyond the schema's enumeration.
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 it lints HDL source code using specific tools. Distinguishes from lint_project by implying it's for single code snippets, but not explicit.
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 context for when to use (linting HDL code) and a tip for using verilator for extended checks. Does not explicitly exclude other scenarios like project linting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lint multiple HDL files together so cross-module references resolve. Pass a dict of filename-to-source pairs. All files are compiled in one invocation of iverilog/verilator (Verilog/SystemVerilog) or ghdl (VHDL). Use linter='verilator' to enable -Wall checks including multidriven net detection.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Mapping of filename to source code, e.g. {"uart_tx.v": "module uart_tx...", "top.v": "module top..."} | |
| language | No | HDL language variant | verilog |
| top_module | No | Top-level module name (optional) | |
| timeout | No | Timeout in seconds | |
| linter | No | Linter backend for Verilog/SV. 'verilator' enables -Wall (multidriven nets, etc.) | iverilog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that all files are compiled in one invocation and mentions backend tools, but does not describe the output format (e.g., errors/warnings) or error handling. With no annotations, the description partially meets transparency 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?
Two concise sentences, front-loaded with the core purpose, followed by specific technical detail. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers multi-file and linter details, but lacks explanation of return values or behavior on lint errors. Given no output schema, the description should ideally mention what the agent can expect as output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the description adds extra value: explains the 'files' dictionary parameter with an example, elaborates on the 'linter' parameter (verilator -Wall), and implicitly ties 'language' to backend (ghdl for VHDL).
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 lints multiple HDL files together with cross-module resolution, specifying the verb 'Lint' and the resource 'multiple HDL files'. It distinguishes from sibling 'lint_hdl' by focusing on multi-file compilation.
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 context for when to use (multi-file linting with cross-module resolution) and a specific recommendation for using 'verilator' to enable -Wall checks. However, it does not explicitly state when not to use or compare with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all known FPGA board presets with target, device, package, and clock frequency.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states that it lists presets. It does not disclose any behavioral traits such as whether it is read-only, requires authentication, or has side effects. As a result, the description does not add sufficient context beyond the obvious.
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 extraneous information, front-loading the key verb and resource. Every word adds value, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description provides the essential aspects: what is listed and the fields included. It is complete enough for the tool's simplicity, though it could mention if the list is comprehensive or cached.
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 no parameters, so the baseline is 4. The description adds value by listing the fields included in the output (target, device, package, clock frequency), which aids understanding without needing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all known FPGA board presets', and specifies the output includes target, device, package, and clock frequency. This clearly distinguishes it from sibling tools like list_builds or list_ip_cores.
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 need a list of board presets with specific fields. However, it does not explicitly state when not to use it or mention alternative tools. For a tool with no parameters, this is largely clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tracked builds (running and finished) with status summary.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description merely states the action without disclosing behavioral traits like pagination, ordering, or data freshness.
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 with 12 words, front-loaded with action verb, no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no params and no output schema; description is adequate for a list operation but could mention return format.
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, so schema coverage is 100%. Description adds no parameter info, which is acceptable; baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'List all tracked builds (running and finished) with status summary.' Distinguishes from sibling 'build_status' which likely shows status of a single build.
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?
Implied usage for getting an overview of all builds, but no explicit when-to-use or alternatives provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available IP cores in the registry. Optionally filter by category.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter by category, e.g. 'communication' or 'memory' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries burden—but only states listing operation. Does not disclose return format, pagination, rate limits, or side effects. Adequate for a simple query, but could add context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Essential information is front-loaded. 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?
Adequate for a simple list tool with no output schema and no annotations. Missing details like return format or empty-state behavior, but contextually complete enough given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with schema describing 'category' as filter. Description merely restates filtering without added detail. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (list), resource (IP cores in registry), and optional filtering by category. Distinct from siblings like get_ip_core or search_github_cores due to registry scope.
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 usage for listing all cores or filtered by category, but provides no explicit guidance on when to use this vs. alternatives like get_ip_core or search_github_cores. No exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run LiteX board target with --build. Returns logs and output directory.
| Name | Required | Description | Default |
|---|---|---|---|
| board | Yes | LiteX board target | |
| args | No | Extra LiteX CLI args | |
| output_dir | No | Optional output directory | |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states it runs a build and returns logs and an output directory, but does not reveal side effects (e.g., file creation, duration), required permissions, or error handling. This is insufficient for a build 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?
The description is a single concise sentence, front-loading the core action. However, it may be overly minimal; slightly more detail could enhance clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations), the description lacks completeness. It does not explain return format, timeout behavior, or effect of optional args. The tool's behavior is only partially 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?
All 4 parameters are described in the input schema (100% coverage). The tool description adds no further semantics beyond what the schema provides, so a baseline score 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 clearly states the action (Run) and resource (LiteX board target) with the specific flag --build. It also mentions outputs (logs and output directory). While it doesn't explicitly distinguish from siblings like litex_flow or start_build, the purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like litex_flow or start_build. There is no mention of prerequisites, context, or exclusions, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a generic LiteX board target with caller-provided args.
| Name | Required | Description | Default |
|---|---|---|---|
| board | Yes | LiteX board target | |
| args | No | Extra LiteX CLI args | |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It does not mention if the tool is blocking, what side effects occur (e.g., writing to disk), permission requirements, or how output is handled. Minimal transparency beyond purpose.
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, no redundancy. Every word adds meaning. Efficient for a generic tool.
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 24 siblings and no output schema, the description is adequate for a simple runner but could mention typical use case (e.g., for prototyping or custom builds). Nearly 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 100%, so baseline is 3. The description adds 'caller-provided args' but does not explain how args interact with board target or provide examples. No extra semantic value 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 clearly states it runs a generic LiteX board target with caller-provided args. The verb 'Run' and resource 'LiteX board target' are specific, and it distinguishes from siblings like litex_build and litex_soc by being generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for running arbitrary board targets with extra args, but does not specify when to use this tool over siblings like litex_build or simulate. No explicit alternative or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate LiteX SoC without building gateware. Returns logs and output directory.
| Name | Required | Description | Default |
|---|---|---|---|
| board | Yes | LiteX board target | |
| args | No | Extra LiteX CLI args | |
| output_dir | No | Optional output directory | |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that gateware is not built and that logs and output directory are returned, but lacks details on side effects, permissions, or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single, front-loaded sentence that efficiently conveys the core action and return values. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description provides basic purpose and return type. However, it lacks context on prerequisites, file system effects, or error conditions, which would be helpful for 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 coverage is 100%, so parameters are already documented. The description adds no additional meaning beyond the schema; it does not explain how parameters like 'board' or 'args' affect generation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool generates a LiteX SoC without building gateware, distinguishing it from sibling tools like litex_build which actually builds gateware. The verb 'generate' and resource 'LiteX SoC' are 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?
Description implies usage when you want to generate a SoC without building gateware, but does not explicitly state when to use or when not to use. No alternatives are mentioned, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synthesize HDL with Yosys then place-and-route with nextpnr in one step. Provide source as: code (single string), files (dict of filename→source), or project_dir (path to HDL files on disk). If backend=litex, runs LiteX build and ignores HDL inputs. Returns max frequency, critical path, resource utilization, bitstream, and full logs. Supported targets: ice40, ecp5, nexus, gowin. Common device/package values: ice40: device=hx1k|hx8k|up5k|lp1k package=tq144|qn84|sg48|cm81 ecp5: device=25k|45k|85k package=CABGA256|CABGA381 nexus: device=LIFCL-40-9BG400C (package embedded in device string) gowin: device=GW1N-UV4LQ144C6/I5 (package embedded in device string)
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | HDL source code (single-file mode) | |
| files | No | Multi-file mode: mapping of filename to source code | |
| project_dir | No | Disk mode: path to directory containing HDL source files | |
| top_module | Yes | Top-level module name | |
| language | No | HDL language variant | verilog |
| target | No | FPGA family | |
| device | No | Device variant, e.g. 'hx1k', '25k', 'LIFCL-40-9BG400C' | |
| package | No | Package, e.g. 'tq144', 'CABGA256' (not needed for nexus/gowin) | |
| constraints | No | Optional pin constraints (PCF/LPF/PDC/CST text) | |
| timeout | No | PnR timeout in seconds | |
| backend | No | PnR backend | yosys |
| litex_board | No | LiteX board target (required if backend=litex) | |
| litex_args | No | Extra LiteX CLI args (backend=litex) | |
| board | No | Board preset (e.g. 'icebreaker', 'ulx3s_85f'). Sets target/device/package/clock automatically. | |
| nextpnr_args | No | Extra nextpnr arguments (e.g. ['--seed', '42', '--placer', 'heap']) | |
| work_dir | No | Persistent working directory for incremental runs. Returned in response for reuse. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description discloses return values (max frequency, critical path, etc.), supported targets, and the behavior difference for litex backend. It lacks explicit statements on authorization or rate limits, but overall is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then details mode specifics and device values. It is slightly lengthy but well-structured and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, multiple modes, nested objects, no output schema), the description covers all essential aspects: source modes, target families, return values, and special backend behavior.
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 valuable extra meaning, such as explaining the three source input modes and providing common device/package values, which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs synthesis and place-and-route in one step, specifies multiple source input modes, and distinguishes from siblings like 'synthesize' and 'litex_build'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use this combined step, including the special case for 'backend=litex'. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flash a bitstream to an FPGA board using iceprog (ice40) or openFPGALoader (ecp5/gowin/nexus). Provide bitstream as base64 (from place_and_route output) or a file path on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | FPGA family (used to select default programmer) | |
| bitstream_b64 | No | Base64-encoded bitstream (from place_and_route bitstream_b64 field) | |
| bitstream_path | No | Path to bitstream file on disk | |
| programmer | No | Programmer tool (auto-detected from target if omitted) | |
| board | No | openFPGALoader --board flag (e.g. 'ulx3s', 'tangnano9k') | |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It describes the programming process and options, but lacks details on hardware prerequisites, potential destructive nature (e.g., overwriting existing config), or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey essential information. No superfluous content; every part 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?
Covers input format and tool selection. No output schema, so return values need not be explained. Missing context about hardware connection requirements or success/failure handling, but still 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?
Schema description coverage is 100%, so baseline is 3. The description adds context by explaining bitstream sources and auto-detection of programmer, going 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?
Description clearly states the action ('Flash a bitstream to an FPGA board') and specifies the tools (iceprog, openFPGALoader) and FPGA families. It is distinct from sibling tools like place_and_route, which generates the bitstream.
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 guidance on when to use (after place_and_route) and how to provide input (base64 or file path). Mentions auto-detection of programmer but does not explicitly state when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-scan all core directories and rebuild the IP core cache. Call after adding cores to disk or editing config.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must fully disclose behavior. It states the action (re-scan, rebuild) but does not clarify side effects (e.g., whether the cache is overwritten, if the operation is safe, or if it has any performance impact). It is minimally transparent.
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, each essential. The first states the action and resource, the second provides the trigger condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers the purpose and usage context well. However, it omits any indication of the return value or error handling, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% trivially. The description adds no parameter info, which is acceptable since there are none. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Re-scan' and clearly identifies the resource 'core directories' and the effect 'rebuild the IP core cache', effectively distinguishing it from sibling tools like build or lint operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Call after adding cores to disk or editing config.json.' This clearly indicates when to invoke the tool, though it does not specify when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search GitHub for open-source FPGA IP cores (MIT, BSD, Apache, GPL, etc). Returns repo names, star counts, descriptions and topics. Use import_github_core to download a result into the local registry.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search terms, e.g. 'uart verilog' or 'riscv softcore' | |
| language | No | Filter by HDL language (optional) | |
| max_results | No | Maximum number of results to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it is a read-only search that returns repo details. It does not mention rate limits or authentication, but for a search tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first explains purpose and output, second directs to sibling. Front-loaded and no 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?
For a search tool with 3 parameters and no output schema, the description is complete: it explains the search scope, returned data, and a follow-up action. 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 100% description coverage, so the baseline is 3. The description adds no extra parameter details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for FPGA IP cores on GitHub, specifies license types, and lists returned fields. It distinguishes from import_github_core by describing the next step.
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 is clear: search for cores. It mentions import_github_core as the alternative for downloading. However, it does not explicitly state when not to use this tool or other alternatives among many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compile and simulate HDL using Icarus Verilog (iverilog + vvp) or GHDL (VHDL). Provide the design source and a separate testbench. Returns all $display/$monitor output (Verilog) or report output (VHDL) and any runtime errors.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | HDL design source | |
| testbench | Yes | HDL testbench source | |
| language | No | HDL language variant | verilog |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that outputs include $display/$monitor output or report output and runtime errors, but does not mention side effects, statefulness, permissions, or error handling beyond runtime errors. Adequate but not comprehensive.
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 at two sentences, front-loaded with the main action. Every sentence provides essential information without 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?
The description covers the core functionality and output type, compensating for the missing output schema. However, it lacks details about simulation behavior under errors, simulator versions, or requirements for the testbench (e.g., must include main module). Mostly 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 100% with descriptions for each parameter. The tool description adds minimal value by reiterating that the design and testbench are separate, which is already clear from the schema. No additional format, constraints, or usage tips are provided.
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: compile and simulate HDL using specific simulators (Icarus Verilog, GHDL). It distinguishes from sibling tools like lint_hdl, synthesize, etc., which have different objectives. The verb 'simulate' and resource 'HDL' are 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?
The description implies usage for running simulations but does not explicitly state when to use it versus alternatives (e.g., lint_hdl, synthesize). No exclusions or prerequisites are mentioned, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a long-running build command in the background. Returns a build_id to check progress with build_status. Use for synthesis, place-and-route, LiteX builds, or any command that takes minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| cmd | Yes | Command and arguments, e.g. ['yosys', '-s', 'synth.ys'] | |
| label | No | Human-readable label for this build (optional) | |
| work_dir | No | Working directory for the build (optional, defaults to project root) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description discloses that the command runs in background and returns an ID for status checking. Lacks details on resource consumption, error handling, or non-blocking nature, but core behavior is conveyed.
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 sentences: action, return value, usage suggestions. No fluff, well 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?
Covers purpose, return, and usage contexts. Lacks mention of async/background nature explicitly, but overall adequate. No output schema so return type is 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 coverage is 100% with descriptions for all parameters. Description adds no additional meaning beyond what the schema already provides. Baseline score 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?
Clearly states it starts a long-running build command in the background and returns a build_id for progress tracking. Distinct from siblings like build_status (check) and cancel_build (cancel).
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 recommends use for synthesis, place-and-route, LiteX builds, or any long-running command. Does not explicitly list when not to use, but gives clear positive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synthesize HDL (Verilog, SystemVerilog, or VHDL) using Yosys or run LiteX backend. Provide source as: code (single string), files (dict of filename→source), or project_dir (path to HDL files on disk). Returns resource statistics and the list of inferred modules. Supported targets: generic, ice40, ecp5, gowin, xilinx, intel.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | HDL source code (single-file mode) | |
| files | No | Multi-file mode: mapping of filename to source code | |
| project_dir | No | Disk mode: path to directory containing HDL source files | |
| top_module | Yes | Name of the top-level module | |
| language | No | HDL language variant | verilog |
| target | No | FPGA family / synthesis target | generic |
| backend | No | Synthesis backend | yosys |
| litex_board | No | LiteX board target (required if backend=litex) | |
| litex_args | No | Extra LiteX CLI args (backend=litex) | |
| timeout | No | Timeout in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the synthesis process using Yosys/LiteX, output details, and source handling. No contradictions with annotations (none present).
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 sentences front-load the main action, then explain source options, output, and targets. No redundant information; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description covers core functionality, input modes, supported targets, and return information. It is complete enough for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by summarizing the three source modes and output returns, providing a high-level understanding beyond individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool synthesizes HDL using Yosys or LiteX backend, specifies source modes (code, files, project_dir), and mentions return type (resource statistics and module list). This distinguishes it from siblings like lint_hdl or simulate.
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 explains three source input modes and lists supported targets/backends, providing clear context for when to use this tool. It does not explicitly exclude alternatives or provide when-not-to-use, but the clarity of purpose suffices.
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.3.0build_statuscancel_buildcheck_toolscleanup_build_logsformat_hdlgenerate_ipget_diagnosticsget_ip_coreimport_fusesoc_coreimport_github_corelint_hdllint_projectlist_boardslist_buildslist_ip_coreslitex_buildlitex_flowlitex_socplace_and_routeprogram_fpgareload_registrysearch_github_coressimulatestart_buildsynthesizeScored across 25 tools
Each tool targets a distinct operation: build management, IP core management, HDL linting/simulation, synthesis/P&R, and LiteX flows. Overlaps like lint_hdl vs lint_project are clearly differentiated by single vs multi-file scope, so agents can reliably select the correct tool.
All tool names follow consistent snake_case with a verb_noun pattern (e.g., list_boards, generate_ip, cancel_build). No camelCase or mixed styles, making naming predictable and easy to remember.
25 tools cover a broad FPGA development workflow without being excessive. Each sub-domain (builds, IP cores, linting, synthesis, LiteX) is adequately represented, though the count is at the upper end of typical scopes.
The tool set covers the main FPGA flow: HDL linting, simulation, synthesis, place-and-route, and programming, plus build management and IP core discovery/import. Minor omissions like constraint file generation or waveform viewing exist, but core operations are well-supported.
A MCP server built for developers enabling Git based project management with project and personal…
Create, deploy, and operate MCP servers directly from your GitHub repositories.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP Server for JFrog, providing tools for development and artifact management.