markdown string with 1-line summary followed by bullets details.
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., "@cg-agent-kit compile and check this C⏚ design for errors"
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.
An MCP server that hands the C⏚ FPGA toolchain to an AI agent. The model writes hardware; the server compiles, simulates and synthesis-checks it against the real compiler, and hands back structured diagnostics the model can act on.
That is the difference worth caring about. An LLM asked for Verilog will confidently emit something that does not build, does not synthesize, or silently folds away to nothing. Here every step is judged by the same compiler a human uses.
Two parts work together:
cg_context.md — a knowledge pack. Load it as the system prompt and the
model can write plausible C⏚: the mental model, types, ports,
structs/enums/generics, the standard library, and the gotchas that sink first
drafts.
the MCP server — the compiler as tools, so the model verifies its own output instead of recalling it.
Knowledge gives a good first draft; the compiler in the loop makes it right. Both are model-agnostic — any stdio-MCP host (Claude Desktop, Claude Code, Cursor, Cline) works, and the context pack works with any LLM at all.
Why not fine-tune? C⏚ is a niche language with little public code, and it gains features every release. A fine-tuned model is expensive and goes stale. In-context knowledge plus a verification loop costs nothing to retrain, tracks the language as the compiler evolves, and converges by running code rather than recalling it.
pip install neosyn-fpga-mcpThen point it at a C⏚ compiler jar:
export CG_JAR=/path/to/cg-language-server.jarTwo ways to get that jar:
Open source — a prebuilt jar from cg-compiler releases, or build it from source.
Commercial — the jar inside an installed
Neosyn C⏚ extension, which adds the fast
bytecode simulator and VHDL output.
It needs your licence file: set NEOSYN_CG_LICENSE to it, or keep it at the
default path the extension uses. Without one, every tool reports the licence
problem instead of running.
cg_capabilities reports which one you have and what it can do, probed rather
than assumed.
Related MCP server: EDA Tools MCP Server
Python 3.10+
Java 17 or newer on PATH — the jar's bytecode targets 17.
Optional: yosys on PATH for cg_synth (override with $YOSYS);
iverilog for cg_simulate(simulator='iverilog'). Neither is needed for
cg_check, cg_generate_verilog, or the bytecode simulator.
Smoke-test the verification core without an MCP client:
python3 - <<'EOF'
from neosyn_fpga_mcp import cg_mcp_server as cg
print(cg.simulate("package d;\ntask T { properties { test: { v:[1,2,3] } }\n"
" out push u8 v; u8 c; void setup(){c=0;}\n"
" void loop(){c=c+1; v.write(c);} }"))
EOFAdd a server entry. Use absolute paths.
{
"mcpServers": {
"cg": {
"command": "neosyn-fpga-mcp",
"args": [],
"env": {
"CG_JAR": "/abs/path/to/cg-language-server.jar"
}
}
}
}The same command/args/env shape works for Claude Desktop, Claude Code,
Cursor, Cline and other stdio-MCP hosts.
Then load cg_context.md as the system prompt (or paste it at the top of
the conversation). The model now knows the language and can verify it.
13 tools. Every tool that takes source accepts source (a C⏚ string) and an
optional extra_files map ({"Defs.cg": "..."}) for imported bundles/tasks.
These are the only names that exist, and the server says so rather than hoping
you read this table: a call to a tool that does not exist comes back with the
whole list and the closest real name (cg_compile → "did you mean cg_check?"),
cg_capabilities carries the list, and the first call of a session carries it
once. The list is generated from the tool
registry, so it cannot drift out of step with the table below.
Tool | Params (besides | Returns | When to use it |
| — |
| After |
|
|
| The ground-truth correctness check. |
|
|
| After simulate passes, to hand off RTL. |
|
|
| The strongest correctness signal — yosys-synthesizes the Verilog. |
| — |
| What this host can actually do, probed rather than assumed. The fast bytecode simulator ships with the commercial distribution and is absent from the open-source compiler, so any flat claim about it is wrong in one of the two environments — call this before deciding how to verify. |
|
|
| Start here when writing new C⏚ from a blank file. Returns a complete, COMPILING, self-checking skeleton with the datapath left as |
|
| no pattern → | Scored lazy lookup into the validated-code dictionary (NOT search). Specificity-weighted, so |
| — |
| Static checks for code the compiler accepts and is still wrong. Chiefly a |
|
|
| Map a compiler rejection to the recipe with the fix pattern (div/shift-by-variable → Recip; data-dependent loop bound → SeqDiv). |
|
|
| Finalize the FPGA report: renders |
|
|
| Confirm a task's compiled state machine has the intended states/transitions. |
|
|
| Confirm a network's compiled wiring (instances, ports with widths/interfaces, connections). |
|
| no topic → | Fetch a markdown knowledge doc on demand. |
Two tools take a backend selector:
cg_simulate(source, simulator=…) — which simulator runs the design:
'bytecode' (default) — the compiler's fast bytecode simulator. No HDL
toolchain needed; a properties { test: {...} } block self-checks.
cg_simulate(src) or cg_simulate(src, simulator="bytecode").
'iverilog' — generate Verilog + a testbench and run Icarus Verilog
(vvp), a Verilog-level cross-check. A testbench is emitted only for a
network whose name contains Test with a capital T (e.g.
network TestFoo); a lowercase _test network drives the bytecode sim's
test property only, not iverilog. Needs iverilog on PATH.
cg_simulate(src, simulator="iverilog").
'verilator' — accepted for forward-compat but reported unavailable unless
the verilator binary is installed. cg_simulate(src, simulator="verilator").
cg_synth(source, flow=…) — which yosys synthesis flow runs:
'generic' (default) — portable synthesizability check (synth).
cg_synth(src) or cg_synth(src, flow="generic").
a vendor FPGA family — 'ice40', 'ecp5', 'xilinx', 'gowin',
'intel' — maps to that part's primitives (LUTs/BRAM/DSP).
cg_synth(src, flow="ice40").
top defaults to the first non-testbench task/network (the synthesizable
DUT); pass it when a file holds several designs. Override the yosys binary
with $YOSYS.
Draft C⏚ (always starting with package).
cg_lint → free and instant; catches the mistakes the compiler will happily
accept, above all a test: block that checks nothing.
cg_check → fix every diagnostic, and read warnings: those are the
compiler's own objections to code it will nonetheless accept.
cg_simulate → confirm ok: true and that the output matches intent.
cg_generate_verilog once it simulates, to hand off RTL.
cg_synth (optional) → confirm the Verilog maps to real hardware
(ok: true, a sensible cells count, no problems).
Step 2 exists because steps 3–4 can BOTH pass on a design that does nothing: a
fixture with no output vector is green against a dead DUT. cg_lint is the only
step that catches that, and it costs nothing to run.
The loop in steps 2–3 is the point: the model writes, the compiler judges, the
model fixes. cg_context.md ends with the same protocol so the model follows
it even without separate instruction.
from neosyn_fpga_mcp import cg_mcp_server as cg
src = '''package com.example.demo;
task Counter {
properties { test: { value: [1, 2, 3] } }
out push u8 value;
u8 count;
void setup() { count = 0; }
void loop() { count = count + 1; value.write(count); }
}'''
cg.check(src) # {'ok': True, 'diagnostics': [], ...}
cg.simulate(src) # {'ok': True, 'simulator': 'bytecode', ...}
cg.generate(src, output_dir="build/v") # {'ok': True, 'file_count': N, 'written': [...]}
cg.synth(src, flow="ice40") # {'ok': True, 'top': 'Counter', 'cells': ..., 'problems': []}Through the MCP tools the same calls are cg_check → cg_simulate →
cg_generate_verilog → cg_synth. Draft, then walk down the list, fixing
diagnostics at each gate; cg_synth is the final hardware gate.
Knowledge + verification gets a model surprisingly far, but there's a ceiling:
for a genuinely hard fixed-point datapath (e.g. an n-body force kernel with a
1/r²·√r² term), a model asked to write it from scratch flails — in C⏚ and
in Verilog. The reliable pattern is seed-and-adapt: hand the model a small,
verified base and have it change only the dataflow, keeping the parts it
can't invent (the Q16.16 multiply-accumulate, the task/network/monitor shape).
Call cg_example(pattern) to fetch one. This is a curated dictionary of
validated code with scored lazy access (not free-form search): no pattern
returns the index; a name or intent ("1/sqrt", "distance", "divide a by b",
…) returns the single best-matching source plus 1-2 runners-up so the model can
self-correct. Matching is specificity-weighted, so "1/sqrt"→RSqrt while a bare
"sqrt"→FixedSqrt. When the compiler rejects something,
cg_suggest_for_error(msg) points at the recipe with the synthesizable pattern.
examples/ holds the verified entries — every one simulates, generates Verilog,
and passes yosys synth. kind splits the reusable primitives (Recip, Divide,
SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct, Fir, Integ, Distance, Counter)
from application examples (Force, GalaxyForce — n-body composition). Full
table with use_when/tags/cell counts in examples/RECIPES.md. A primitive
whose demo drives constant inputs (DotProduct, FixedSqrt, Distance) reports
cg_synth verdict: FOLDED — drive it with in push ports (as SqrDist does) so
the datapath survives.
See cg_adapt_demo.py in the
repository to watch the
seed-and-adapt loop run end to end, and EVAL.md for how C⏚ and Verilog write
rates were measured on small tasks — including what that measurement does not
show.
Installing C⏚ — the extension and the CLI
This project was published as cg-agent-kit up to 1.0.0; "cg" is our shorthand
for C⏚ and meant nothing to anyone searching for an FPGA tool. On PyPI that name
is now a shim that installs this package, and inside the package
python -m cg_agent_kit.cg_mcp_server and the cg-mcp-server command both
still resolve — so existing instructions and host configs keep working. New
installs should use neosyn-fpga-mcp.
MIT. Copyright (c) 2026 Neosyn.
The software is provided "as is", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability, fitness
for a particular purpose and noninfringement. In no event shall the authors or
copyright holders be liable for any claim, damages or other liability, whether
in an action of contract, tort or otherwise, arising from, out of or in
connection with the software or the use or other dealings in the software. The
full text ships with the package as LICENSE.
C⏚, Cg and Neosyn are marks of Neosyn. The C⏚ compiler is a separate work under its own licence — see neosyn.io/open.
Parse, scope, and type-check C⏚ source without running it. Returns
{ok, diagnostics:[{file,line,message}], summary}. Call this first on
any draft; fix every diagnostic before simulating. extra_files maps
filename → content for imported bundles/tasks (e.g. {"Defs.cg": "..."}).
For a MULTI-FILE project, pass package_dir (the folder holding your
.cg files, e.g. "fpga/src/main/cg", relative to the project root): the
tool then reads every sibling .cg there, so tasks defined in other files
of the same package resolve — just like the IDE. A task you only got from
cg_example is text; it must be saved to a file in that dir to resolve.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| extra_files | No | ||
| package_dir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only behavior, return format (ok, diagnostics, summary), and parameter effects. No annotations exist, so description bears full burden. Does not mention performance or rate limits, but sufficient for static analysis 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?
Single paragraph packs essential information. Front-loads purpose. Slightly dense but no wasted words. Could benefit from structured formatting for readability, but overall 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?
Handles both simple and multi-file usage, explains return format, and warns about tasks from cg_example needing file storage. No output schema exists, but description covers everything needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description compensates fully: explains source is required, extra_files maps filename to content for imports, and package_dir is relative project folder for multi-file projects. Adds crucial context 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?
Clearly states the tool parses, scopes, and type-checks source without running it, distinguishing it from siblings like cg_simulate (execution) and cg_suggest_for_error (error-specific). Includes return format and usage context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling this first on any draft and fixing diagnostics before simulating. Explains when to use extra_files and package_dir. Lacks explicit exclusions but context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a markdown knowledge doc. No topic → an index of available topics with descriptions; a topic → its full content. Topics: 'context' (the core C⏚ language pack — load before writing any Cg) and 'riscv' (the worked RV32I CPU reference: the loadable single-cycle core and the reusable patterns for CPU-shaped hardware in Cg — barrel shifter, signed/unsigned widening, sub-word load/store, count-prefixed boot-stream program loading, and the lossless-capture / address-filtered testbench patterns). Read 'riscv' when building or extending a processor, instruction decoder, datapath, or stack machine.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Clearly states the read-only behavior: fetches docs, returns index or full content depending on topic. Does not mention error cases or response format, but for a doc-fetching tool this is acceptable.
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?
Front-loaded with the core action. Every sentence adds value, but the bullet-style topic list could be slightly more concise. Still well-organized 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 simple parameter set (one optional string, no enums, no output schema), the description covers all necessary context: behavior, parameter semantics, and topic choices. No missing information for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage and one parameter 'topic'. The description exhaustively explains its meaning, including the effect of omitting it (index) vs. providing a topic (full content), and enumerates the valid topic values with detailed content summaries.
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?
Describes a specific verb 'Fetch' and resource 'markdown knowledge doc'. Clearly distinguishes behavior for no topic vs. a topic. Sibling tools are all other operations (check, generate, simulate), so this tool's role as a documentation retriever is 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?
Provides explicit context for when to use the 'riscv' topic ('when building or extending a processor...'). Implies usage for 'context' as core language pack. Does not explicitly state when not to use or suggest alternatives, but given the tool's unique role, this is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a VERIFIED C⏚ base to seed-and-adapt from (don't synthesize hard
kernels from scratch — adapt a known-good one). This is a curated
dictionary of validated code with scored lazy lookup, NOT free-form
search. No pattern → a compact index (name + kind + use_when + tags). A
pattern → the single best-matching source plus its metadata and 1-2
runners_up so you can self-correct on an ambiguous query. k>1 also
returns the next sources when the task implies composition.
Matching is specificity-weighted (exact name ≫ name word ≫ full tag
phrase ≫ partial overlap), so e.g. "1/sqrt" → RSqrt while a bare "sqrt"
→ FixedSqrt. kind distinguishes general PRIMITIVES (the reusable
library: Recip, Divide, SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct,
Fir, Integ, Distance, Counter) from application EXAMPLES (Force,
GalaxyForce). Every entry passes simulate + generate + iverilog + yosys.
Workflow: cg_example → edit only the dataflow → cg_check → cg_simulate →
cg_generate_verilog → cg_synth.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses that the tool is a curated dictionary, not free-form search; describes return formats for no pattern and with pattern; explains matching specificity-weighted logic; distinguishes entry kinds; and states verification status. It does not cover auth, rate limits, or error behavior, but is comprehensive for a read-only lookup 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 somewhat long but every sentence adds value. It is front-loaded with purpose and then details behavior. Some redundancy could be trimmed, but overall well-structured for the complexity of the 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 the absence of output schema and only two parameters, the description is thorough: it explains input behavior (no pattern vs pattern), output format (compact index or best match plus runners-up), matching algorithm, entry types, verification status, and a workflow. No significant gaps remain.
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 fully explain parameters. It does: 'pattern' is described in detail with matching behavior and examples (e.g., '1/sqrt' vs 'sqrt'); 'k' is explained as controlling the number of returned sources, with k>1 for composition. This adds rich meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a verified C⏚ base for seeding and adaptation, contrasting with synthesizing from scratch. It explains it's a curated dictionary with scored lazy lookup, not free-form search. This verb+resource combination is specific and distinguishes it from sibling tools like cg_check, cg_simulate, etc.
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 a workflow (cg_example → edit → cg_check → cg_simulate → cg_generate_verilog → cg_synth) and advises against synthesizing hard kernels from scratch. It implies when to use this tool (to get a verified base) and when not to (when free-form search is needed), but does not explicitly name alternatives for specific tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a task's compiled state machine (states + transitions). Useful to confirm an FSM has the intended number of states.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | ||
| source | Yes | ||
| extra_files | No |
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 'shows' information but does not disclose whether it is read-only, if it requires compilation, or error conditions. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no fluff. First sentence states the primary action, second provides a use case. Efficiently structured.
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 3 parameters and no output schema, the description should explain parameters and prerequisites. It lacks this information, making it incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 3 parameters with 0% description coverage. The description adds no meaning about 'source', 'task', or 'extra_files', leaving the agent to infer from parameter names only.
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 shows a task's compiled state machine (states+transitions), distinguishing it from siblings like cg_graph or cg_report. However, it could be more explicit about the context (e.g., hardware tasks).
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 a specific use case: 'confirm an FSM has the intended number of states'. No mention of when to avoid using it or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate synthesizable HDL from C⏚. target is 'verilog' (default) or 'vhdl'. Returns {ok, file_count, files:{path:content}}. Use after cg_simulate passes, to hand off RTL.
Pass output_dir (e.g. "fpga/build/verilog", relative to the project
root) to WRITE the files to disk and KEEP them — the result then also
carries {output_dir, written:[paths]}. Without it the files are only
returned inline and the temp dir is cleaned. Prefer output_dir when
the host needs the .v on disk (to inspect or run yosys).
For a MULTI-FILE project, pass package_dir (the folder with your .cg
files) so sibling tasks in the same package resolve during generation.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| target | No | verilog | |
| output_dir | No | ||
| extra_files | No | ||
| package_dir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return format, file writing vs inline behavior, and temp directory cleanup. Lacks info on overwrite behavior or permissions, but covers main behavioral traits well.
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 well-focused paragraphs. Front-loaded with purpose, then parameter details. No redundant sentences. Efficient and readable.
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 main functionality, return values, key parameters, and usage context. Lacks details on source format or error handling, but sufficient 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?
With 0% schema coverage, description explains target, output_dir, and package_dir clearly. Source is implied but not explicitly described. extra_files not mentioned. Good but not complete.
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 'Generate synthesizable HDL from C⏚' and specifies target languages. It distinguishes from siblings by positioning as the step after cg_simulate passes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use after cg_simulate passes, to hand off RTL.' Provides when to use output_dir vs not, and package_dir for multi-file projects. Clear context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a network's compiled graph (instances, ports with widths and interfaces, connections). Useful to confirm wiring.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| network | No | ||
| extra_files | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no information about side effects, permissions, or whether the operation is read-only. The tool appears to be a read operation, but this is not explicitly 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 concise, consisting of two short sentences that front-load the main purpose. However, it sacrifices necessary parameter details for brevity, earning a slightly lower score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters with no descriptions in the schema, no output schema, and no annotations, the description is inadequate. It lacks details on parameter usage, return values, and ties to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain what parameters like 'source', 'network', and 'extra_files' mean in the context of the tool. It does not, leaving the agent to guess their purpose.
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 shows a network's compiled graph, listing specific elements like instances, ports, widths, interfaces, and connections. This distinguishes it from sibling tools like cg_synth or cg_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 notes it is 'useful to confirm wiring', providing a clear use case. However, it does not mention when not to use it or suggest alternative tools for other tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize the FPGA report: (re)render /report.html — a self-contained HTML with the synthesis table (REAL/FOLDED/SUSPECT verdict
cell/arith/latch counts), the simulation PASS/FAIL + output, the generated-Verilog file list, and (best-effort) datapath schematic SVGs.
This does NO synthesis — the rows are built incrementally by passing the
SAME report_dir to cg_synth (per kernel) and cg_simulate as you run
them; cg_report just aggregates those fragments + the Verilog under
/verilog and renders. Workflow:
cg_generate_verilog(output_dir="/verilog", package_dir=...)
cg_simulate(..., report_dir="")
cg_synth(..., report_dir="") # once per kernel
cg_report(report_dir="") # finalize + schematics
Returns {ok, report (the .html path), kernels, sim_ok, message}. Set
schematics=False to skip the SVGs (faster).
| Name | Required | Description | Default |
|---|---|---|---|
| report_dir | No | fpga/build | |
| schematics | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It transparently states that cg_report does NO synthesis, only aggregates existing fragments. It discloses the return object with fields like ok, report, kernels, sim_ok, message, and notes that schematics are 'best-effort'. This exceeds what's required.
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 provides a workflow and return value summary. It is slightly lengthy due to the workflow explanation, but every sentence adds value and the structure is logical.
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 only 2 parameters, no output schema, and a clear set of sibling tools, the description is fully adequate. It explains the tool's role, dependencies, parameter effects, and output, leaving no obvious gaps for an agent to misinterpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides essential parameter semantics: report_dir defaults to 'fpga/build', schematics defaults to true and setting it to false skips SVG generation. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that cg_report finalizes an FPGA report by rendering a self-contained HTML with synthesis table, simulation results, Verilog file list, and datapath SVGs. It distinguishes itself from siblings by noting it aggregates fragments from cg_synth and cg_simulate, not performing synthesis itself.
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 a clear workflow showing the correct order: cg_generate_verilog, cg_simulate, cg_synth, then cg_report. It also notes that setting schematics=False skips SVGs for faster execution. However, it doesn't explicitly state when not to use it or compare to other sibling tools beyond the implied workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate C⏚ source. Returns {ok, simulator, timed_out, diagnostics,
output}. output holds port values and print() lines; a
properties { test: {...} } block self-checks and fails the run on
mismatch. This is the ground-truth correctness check — iterate until
ok is true.
simulator picks the backend: 'bytecode' (default — the compiler's
fast simulator, no HDL toolchain) or 'iverilog' (generate Verilog +
testbench and run Icarus Verilog, a Verilog-level cross-check; needs a
network <Name>_test). 'verilator' is accepted but reported
unavailable unless installed.
For a MULTI-FILE project, pass package_dir (the folder with your .cg
files, e.g. "fpga/src/main/cg") so every sibling task in the same package
resolves — a cg_example you pulled must be saved to a file in that dir,
not just referenced.
report_dir DEFAULTS to "fpga/build" — this run's PASS/FAIL + output is
recorded into that dir's accumulating report.html (see cg_report). Pass
report_dir="" to disable.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| timeout | No | ||
| simulator | No | bytecode | |
| report_dir | No | fpga/build | |
| extra_files | No | ||
| package_dir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: return values (ok, simulator, timed_out, diagnostics, output), self-check blocks that fail on mismatch, and simulator availability conditions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded return structure and separate sections for simulator options and multi-file projects. It is informative without being overly verbose, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, no output schema, no annotations), the description covers main use cases, return values, and configuration. Missing details on 'extra_files' and exact format of 'source', but overall provides sufficient context 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?
Schema coverage is 0%, so the description carries the burden. It explains source (implied), simulator (choices and requirements), report_dir (default and disable), and package_dir (multi-file usage). Timeout and extra_files are less explained, but key parameters are well covered.
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 simulates a C⏚ source and details the return structure. It distinguishes itself from siblings like cg_generate_verilog or cg_synth by focusing on simulation and correctness checking.
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 guidelines on when to use built-in bytecode or Verilog simulators, notes dependencies for iverilog and verilator, and explains multi-file projects. It does not explicitly contrast with all siblings but gives clear context for iterative testing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map a compiler error/diagnostic to the recipe that demonstrates the
synthesizable pattern for what was rejected. Returns {ok, recipe, hint,
source}. div/shift-by-a-variable → Recip (bit-serial long division);
a data-dependent/runtime loop bound → SeqDiv (sequential FSM divider).
cg_check/cg_simulate/cg_generate_verilog already auto-attach this as a
suggestion when a diagnostic matches; call this directly to look one up.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the return format ({ok, recipe, hint, source}) and provides examples of mappings, giving insight into behavior. It could mention what happens if no match is found, but the examples are helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with the main purpose, followed by examples and usage context. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers purpose, usage, return format, and examples. It is mostly complete, though it could explicitly state behavior for unmatched inputs.
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 required parameter 'message' is described as a compiler error/diagnostic, with examples of specific error patterns. Since the schema has 0% description coverage, the description compensates by adding meaning beyond the type definition.
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: mapping a compiler error/diagnostic to a recipe demonstrating a synthesizable pattern. It uses specific verbs and examples (e.g., 'div/shift-by-a-variable → Recip') to illustrate the mapping, and distinguishes from sibling tools by noting that some auto-attach suggestions.
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 that other tools (cg_check, etc.) already auto-attach suggestions, so this tool is for direct lookup when needed. This provides clear context for when to use it, though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synthesize the generated Verilog with yosys — the strongest signal
that a design maps to real hardware (catches non-synthesizable
constructs that simulate/iverilog accept). Returns {ok, verdict, top,
flow, cells, arith_ops, latches, warnings, stat, problems, output}.
verdict is the one-word classification so you can't confabulate
success: REAL (a genuine datapath), FOLDED (0 datapath cells — inputs
weren't on ports, dead hardware), SUSPECT (latches inferred — a
data-dependent loop / missing reset), or ERROR (yosys failed). cells
is the gate count; problems lists any ERROR/Warning lines.
warnings flags the two silent failure modes: a DEGENERATE datapath
(arith_ops == 0 → the design constant-folded; drive it with input
ports) and inferred LATCHES (latches > 0 → a data-dependent loop bound
or incomplete assignment; expected a clocked FSM). A clean synth has
ok: true, a sensible cells, arith_ops > 0, and empty warnings.
NOT a correctness oracle: a REAL verdict means real (synthesizable)
hardware, NOT correct hardware — it can't tell a good sequential FSM
from a buggy one. cg_simulate (the asserting test network) is the
correctness check; run it FIRST, then cg_synth to confirm the hardware
is real, not folded or latched.
top defaults to the first non-testbench task/network (the DUT); pass
it when a file holds several designs. flow selects the synthesis
flow: 'generic' (default, portable check) or a vendor FPGA family —
'ice40', 'ecp5', 'xilinx', 'gowin', 'intel' — to map to that part's
primitives. Override the yosys binary with the $YOSYS env var. Run
after cg_simulate passes. A constant-bound for synthesizes (it's
unrolled); a data-dependent loop becomes an FSM (also fine).
report_dir DEFAULTS to "fpga/build", so each synth automatically records
THIS kernel's verdict + cell counts as a row in /report.html —
synthesizing the kernels builds the whole report as a byproduct, no
separate step (see cg_report). Pass report_dir="" to disable.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| flow | No | generic | |
| source | Yes | ||
| timeout | No | ||
| report_dir | No | fpga/build | |
| extra_files | No | ||
| package_dir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully shoulders the burden. It details the return value structure (ok, verdict, top, flow, cells, etc.), explains failure modes (FOLDED, SUSPECT, ERROR), and warns about silent failures (warnings for degenerate datapath and latches). It also notes the default report_dir behavior and how to disable it, offering comprehensive behavioral insight.
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 long but well-structured, starting with purpose, then return value, usage warnings, parameter details, and defaults. Every sentence provides useful information. While it could be slightly more concise, the detail is justified given the tool's complexity.
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 (synthesis, 7 parameters, rich output) and lack of output schema and annotations, the description is quite complete. It thoroughly explains return values, failure modes, usage order relative to siblings, and key parameters. It misses explanations for a few parameters (timeout, extra_files, package_dir), but overall provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains key parameters: top (defaults to first non-testbench task), flow (lists options like generic, ice40, etc.), and report_dir (defaults to 'fpga/build', can disable with ''). However, it does not cover all 7 parameters; missing explanations for source, timeout, extra_files, and package_dir. Still, it adds significant context beyond the schema for the most critical 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's purpose: 'Synthesize the generated Verilog with yosys — the strongest signal that a design maps to real hardware.' It explicitly distinguishes from cg_simulate, which checks correctness, and explains what each verdict means, making the purpose 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?
The description provides explicit usage guidance: 'Run after cg_simulate passes.' It clarifies that the tool is not a correctness oracle and directs to cg_simulate for that. It also gives advice on when to adjust parameters like top and flow, and how to interpret results to know if the tool was used correctly.
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.1cg_checkcg_docscg_examplecg_fsmcg_generate_verilogcg_graphcg_reportcg_simulatecg_suggest_for_errorcg_synthScored across 10 tools
Each tool targets a distinct stage in the C⏚ hardware design workflow: type-checking, documentation, example retrieval, FSM analysis, HDL generation, graph visualization, reporting, simulation, error-to-recipe mapping, and synthesis. No overlaps are apparent.
All tools share the 'cg_' prefix. Most follow a verb_noun pattern (e.g., cg_check, cg_generate_verilog, cg_simulate), but a few use nouns alone (cg_docs, cg_example, cg_fsm, cg_graph). This minor inconsistency slightly reduces clarity but remains acceptable.
With exactly 10 tools, the set is well-scoped for a hardware design assistant. It covers the full front-to-back workflow without being overwhelming or too sparse.
The tool surface provides complete lifecycle coverage: code checking, example retrieval, simulation, synthesis, Verilog generation, report finalization, plus supplementary tools for debugging (FSM, graph) and error guidance. No obvious gaps for the stated purpose.
A public board where AI agents design pieces of an open AI inference accelerator on sky130. Submit Verilog and it is linted, synthesised, simulated against hidden vectors, mapped to real standard cells for area, timed for critical path and power, and proven equivalent to a reference. No key, no account, one call. The best verified design gets fabricated.
Run, build, and validate firmware on virtual hardware from your AI agent. Hardware knowledge corpus.
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
