Skip to main content
Glama
siliconsmith-mcp

siliconsmith-mcp

by RFingAdam

write_rtl

Destructive

Write or replace complete HDL source and documentation files using full UTF-8 content for Amaranth, MyHDL, Verilog, or docs; Python files receive a syntax check, and tests use write_test.

Instructions

Write a design source file or a doc, replacing the whole file. Always send the full new content: diffs and patches are not accepted. Allowed paths: hdl//*.py for Amaranth and MyHDL projects (the entry file is hdl/.py); src/.v for Verilog projects; docs//*.md (except the generated docs/verification.md). Tests go through write_test instead. Content must be UTF-8 text of at most 256 KiB. A .py file gets a syntax check (it is never run); the file is saved even when the check fails, and then ok is false with file:line:col and the message.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project": "<project>",
      "path": "<path>",
      "content": "<content>"
    },
    "name": "write_rtl"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYes
contentYes
projectYes

Output Schema

NameRequiredDescriptionDefault
okYes
detailsNo
summaryYes
artifactsNo
next_hintsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnly=false and destructive=true; the description goes well beyond by disclosing whole-file replacement semantics, the 256 KiB UTF-8 limit, and the crucial .py behavior: a syntax check runs, the file is still saved on failure, and ok is false with file:line:col plus the message. That is exactly the non-obvious consequence an agent needs before a destructive write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single most important constraint (whole-file replacement, full content required) is front-loaded, followed by path rules, size/encoding limits, and error semantics in a tight sequence. Every sentence carries a rule the agent would otherwise get wrong; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive three-parameter writer, the description covers mutation scope, path constraints, size limits, and failure behavior, and an output schema exists so return values need not be restated. The only meaningful hole is the unexplained `project` parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning, and it does for two of three: `path` gets an explicit allowlist of patterns per project type plus one excluded file, and `content` gets format and size constraints. The `project` parameter is never explained, leaving one required input undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Write a design source file or a doc, replacing the whole file") and immediately scopes it with an allowlist of path patterns per project type. It also names the sibling it is not ("Tests go through write_test instead"), so an agent can route between the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use rules (full content only, no diffs or patches), explicit exclusions (docs/verification.md, tests -> write_test), and concrete path requirements per project type. Nothing about selecting this tool is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.