siliconsmith-mcp

Overview Schema Source Related Servers Discussions Admin

write_spec

Destructive

Validate and save a complete spec.yaml so chip requirements, clock, pins, and tile assumptions stay authoritative; invalid specs are rejected without being saved.

Instructions

Check and save spec.yaml, the short spec of the chip. It is the only source of the clock, the pin meanings and the requirements, and the owner reads it to judge what you plan to build. Send the full file as YAML text in content; it is saved exactly as you wrote it (comments are kept) only if it is valid, and an invalid file is not saved.

Format (version 1; unknown keys are rejected): version: 1 # optional, must be 1 title: "One line name" summary: "What the chip does and why, in plain English." clock_hz: 10000000 # required, integer > 0 (Tiny Tapeout pins manage up to ~66 MHz) tiles: "1x1" # optional, default "1x1"; allowed: 1x1, 1x2, 2x2, 3x2, 3x4, 4x2, 4x4, 5x4, 6x2, 6x4, 8x2, 8x4 reset: "rst_n, active-low, synchronous" # plain English; write 'none' if there is no reset pins: # optional; bit numbers 0-7 as integer keys ui: {0: "enable", 1: "mode"} # inputs ui_in[bit] uo: {0: "count bit 0"} # outputs uo_out[bit] uio: {} # bidirectional uio[bit] requirements: # at least one - id: R1 # R followed by a number, unique: R1, R2, R10 text: "The counter adds 1 each clock while enable is high." limit: {min: 0, typ: 1, max: 2, unit: "V"} # optional; at least one of min/typ/max open_questions: # optional; write your assumptions here - "Assumed 10 MHz; please confirm."

Tiles are the chip area rented on Tiny Tapeout, and bigger tiles cost the owner money: keep "1x1" unless the design cannot fit. Never change tiles yourself: ask the owner, or in a headless run with nobody to ask, keep the current tile and write the assumption to open_questions. A bad tiles value lists the allowed ones.

After a valid save the tool copies the clock and tiles into src/config.json and info.yaml for you (you cannot edit those files); a clock above 66 MHz is saved with a warning.

On errors ok is false and details.errors lists {path, message} (for example pins.ui.8 or requirements[1].id). Fix them and call again. Then write tests whose docstrings say 'Covers: R1' for the requirement ids.

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>",
      "content": "<content>"
    },
    "name": "write_spec"
  }
}

Input Schema

Name	Required	Description	Default
`content`	Yes
`project`	Yes

Output Schema

Name	Required	Description	Default
`ok`	Yes
`details`	No
`summary`	Yes
`artifacts`	No
`next_hints`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 14, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the destructiveHint=true annotation: it states the file is saved verbatim (comments kept) only if valid, that invalid files are discarded, that clock and tiles are copied into src/config.json and info.yaml which the agent cannot edit, and that clocks above 66 MHz save with a warning. Error semantics (ok=false, details.errors with {path, message}) are also disclosed.

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?

Front-loaded: purpose, then input contract, then format reference, then side effects and errors. The format block is long but every line encodes a validation rule an agent must satisfy to avoid a rejected save; the closing tests hint is the only mild scope drift and is short enough to earn its place.

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

Completeness5/5

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

Despite high complexity and 0% schema coverage, an agent has everything needed: required keys, allowed tile values, requirement id format, error shape, side-effect list, and the tiles-cost-money escalation rule. An output schema exists, and the description appropriately does not re-explain success payloads beyond noting the warning case.

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 the load; it does so exhaustively for `content` by spelling out the entire YAML contract, key-by-key, including optionality and validation rules. The `project` parameter is never mentioned, leaving one of two parameters undocumented.

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?

Opens with a specific verb+resource pair: 'Check and save spec.yaml, the short spec of the chip.' It then states what the artifact contains (clock, pin meanings, requirements) and who consumes it (the owner), which clearly separates it from write_rtl/write_test/write_spec-adjacent siblings.

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

Usage Guidelines4/5

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

Gives explicit when-to-use context (the spec is the source of truth the owner reads), a when-not constraint ('Never change tiles yourself: ask the owner'), and a fallback behavior for headless runs. It also routes the follow-up work ('Then write tests whose docstrings say Covers: R1'), though it never names a sibling tool explicitly.

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

Deploy Server