Skip to main content
Glama
mcp-server-kicad

mcp-server-kicad

run_erc

Idempotent

Run Electrical Rules Check (ERC) on a schematic.

Instructions

Run Electrical Rules Check (ERC) on a schematic.

A sub-sheet is checked from its project's root, so the hierarchy around it
counts, and only that sheet's own violations are returned, those of every
use of it under every top-level sheet the project lists. A sheet below a
top-level sheet other than the root is refused when that kicad-cli did not
check it from the root; run_erc on that top-level sheet checks it on its
own. A file that no sheet of its project uses is checked on its own. A run
that makes no report raises and leaves output_dir as it was.

Returns JSON report with violations. An item's position is in
millimetres (mm) in sheet coordinates, the numbers get_pin_positions prints.
The report file saved in output_dir is kicad-cli's own.

Args:
    schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.
    output_dir: Directory for report file (default: beside the file ERC runs on).
        Optional; omit to use the configured default.
    project_path: Path to .kicad_pro file; the project whose hierarchy to look in.
        Refused when no sheet of it uses the file.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "run_erc"
  }
}

Input Schema

NameRequiredDescriptionDefault
output_dirNo
project_pathNo
schematic_pathNo

Output Schema

NameRequiredDescriptionDefault
noteNo
sourceYes
violationsYes
kicad_versionYes
violation_countYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.17.1
    • addedOutput schema / description
      Added value: +"ERC report. ``note`` carries any remarks, space-joined.\n\nIt is deliberately not single-purpose: it began as \"ERC was redirected to\nthe root sheet\" and now also explains a missing sym-lib-table. Test for the\nremark you care about rather than for the field being empty."
  2. Addedv0.10.1

TDQS

A3.9/5.0
Behavior4/5

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

Beyond the annotations, the description discloses that a run with no report raises and leaves output_dir unchanged, that certain sheets are refused, and that the report file in output_dir is kicad-cli's own format. Those are non-obvious behaviors the annotations do not cover. Return-format detail is somewhat redundant with the output schema but not contradictory.

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

Conciseness3/5

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

Purpose and key constraints are front-loaded, but the hierarchy paragraph is dense and awkwardly worded ("those of every use of it under every top-level sheet the project lists"), forcing re-reading. The Args block duplicates some of the body's hierarchy content.

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 tool with an output schema, the description need not restate return values, and it still adds useful context (positions in mm matching get_pin_positions). The combination of annotations, output schema, and the hierarchy/refusal rules leaves little an agent needs that is missing.

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 description coverage is 0%, so the description must carry the burden, and it does: each of the three optional params is explained, including defaults ("omit to use the configured default", "beside the file ERC runs on") and the refusal condition for project_path. Format/syntax details for paths are implied rather than spelled out.

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

Purpose4/5

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

The opening line states a specific verb and resource ("Run Electrical Rules Check (ERC) on a schematic"), which is distinguishable from the PCB counterpart run_drc. It never explicitly names the alternative tools, but the verb+resource pairing is unambiguous.

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?

The description gives real operational guidance: sub-sheets are checked from the project root, a sheet below a non-root top-level sheet is refused, and the caller is told to instead run_erc on that top-level sheet. That is a concrete when-to-use/when-refused rule. It stops short of contrasting with validate_hierarchy or run_drc.

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

Deploy Server

Other Tools