What can you do with this server?

This server exposes a local MCP interface to inspect and control a running KiCad PCB editor, with a set of read, edit, and fabrication tools. * Inspect the PCB: Check connection (kicad_status), read board info (get_board_info), board layers (get_board_layers), stackup (get_board_stackup), and current selection (get_selection). * Query components and nets: List footprints (list_footprints), nets (list_nets), pads, vias, zones, and detailed items by UUID (get_item_details). * Generate bills of materials: Read or export a grouped/ungrouped BOM with custom fields, DNP/excluded filtering, and CSV output (get_bom, export_bom). * Edit the board: Add text (add_text), create/delete vias, adjust layers, delete items, and trigger asynchronous zone refills. * Run design rule checks and fabrication exports: Use kicad-cli to run DRC and export Gerbers, drill files, component positions, and SVG from a copied board snapshot. * Control server mode: Launch over HTTP or stdio, with optional read-only mode exposing only the 15 inspection/BOM tools, and manage lifecycle via KiCad plugin actions or CLI commands.

Which integrations are available for this server?

Allows MCP clients to interact with an open KiCad PCB editor, providing tools for reading board information, footprints, nets, tracks, selections, and BOM data, as well as editing operations such as moving footprints, adding tracks/text, updating BOM fields, and saving the board.

How do I use kicad-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kicad-mcp List the footprints on the current board" 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.

kicad-mcp

by HackInvent

Overview Schema Source Related Servers Discussions Admin

Python

Local

KiCad MCP — HackInvent

Release Status: alpha KiCad 10+ Python 3.10+ License: MIT Downloads

A KiCad 10+ plugin that starts a Model Context Protocol server, letting MCP-compatible assistants work with the open PCB.

The plugin uses KiCad’s official IPC API and the kicad-python library, without pcbnew/SWIG bindings. It provides two actions: Start MCP server and Stop MCP server. A stdio mode also lets an MCP client launch the server directly.

Version 0.3.1, alpha. The MCP protocol, server lifecycle and operations are covered by automated tests. The KiCad tests use real kicad-python objects with a simulated editor; validation in a real KiCad interface is still pending. This project targets the PCB editor and requires a running GUI instance.

Available tools

MCP tool	Function
`kicad_status`	Check the connection and KiCad version
`get_board_info`	Read the board name, layers and item counts
`list_footprints`	Read references, values, positions, rotations and lock status; optional exact reference filter
`list_nets`	List electrical nets
`list_tracks`	Read straight and curved tracks, their dimensions and nets
`get_selection`	Read the items selected in the editor
`list_pads`	Inspect pad numbers, parent references, positions, nets and geometry; filter by reference or net
`list_vias`	Inspect via dimensions, layer spans and nets
`list_zones`	Inspect zone names, nets, layers, priorities and fill state
`get_item_details`	Retrieve type-specific details for exact item UUIDs
`get_board_layers`	Inspect enabled layers, display names, visibility and the active layer
`get_board_stackup`	Read ordered copper/dielectric layers, thicknesses, materials and finish settings
`get_net_connections`	List the pads, tracks and vias assigned to one net
`get_bom`	Read a grouped or individual-component BOM from the open PCB
`export_bom`	Return the PCB BOM as CSV text to the MCP client
`move_footprint`	Move a component by its reference and optionally rotate it
`add_track`	Add a straight track on an enabled copper layer
`add_text`	Add text to the board
`update_bom_fields`	Update component values, custom BOM fields and assembly flags
`set_selection`	Replace, add to or remove from the editor selection using item UUIDs
`set_active_layer`	Activate an enabled layer by its canonical name
`set_visible_layers`	Set which enabled layers are visible
`add_via`	Add a through-hole via spanning F.Cu to B.Cu
`delete_items`	Delete supported, unlocked top-level items by UUID in one undo step
`refill_zones`	Request an asynchronous zone refill in the editor
`run_drc`	Check the last saved PCB with kicad-cli and create a local JSON report
`export_fabrication`	Export Gerbers, drill files, component positions or SVG from the last saved PCB
`save_board`	Explicitly save the PCB to its current file

There are 28 tools: 15 read tools and 13 tools that change the editor, save the PCB or create artifacts. BOM export reads the PCB and returns text; it does not write a file.

Distances are in millimetres, positions are absolute and angles are in degrees. MCP numeric arguments must be JSON numbers and flags must be JSON booleans; implicit conversion between these types is rejected. Object creation, movement, deletion and BOM updates create an undo step in KiCad. Selection and layer visibility change the editor view. Zone refill is a separate asynchronous KiCad action. These operations never trigger an automatic save. save_board also saves any other unsaved changes currently in the editor.

add_track creates a segment and add_via creates a through-hole via; neither performs autorouting or design-rule checks. Locked components and ambiguous references are rejected. Footprints containing items that kicad-python cannot safely transform are also rejected; pads, standard geometry and 3D models are supported.

Related MCP server: KiCad MCP Server

Inspect and edit a PCB

Use get_board_layers to discover canonical layer names such as F.Cu, B.Cu and Edge.Cuts. get_board_stackup reports board thickness and material information from Board Setup.

Call list_pads with {"reference": "U1"} to inspect a component, or get_net_connections with {"net_name": "GND"} to inspect all pads, tracks and vias assigned to a net. These lists describe net membership. They do not prove that the copper is physically connected or that the design passes DRC; the net response explicitly reports connectivity_verified: false.

Use UUIDs returned by inspection tools to request get_item_details or control selection. Item requests accept up to 500 unique UUIDs at a time:

{
  "item_ids": ["REPLACE_WITH_AN_ITEM_UUID"],
  "mode": "replace"
}

set_selection also accepts "add" and "remove"; {"item_ids": [], "mode": "replace"} clears the selection. Layer tools accept canonical names: for example, call set_visible_layers with {"layers": ["F.Cu", "Edge.Cuts"]}.

To create a through-hole via assigned to an existing net, call add_via:

{
  "x_mm": 25.0,
  "y_mm": 30.0,
  "diameter_mm": 0.6,
  "drill_mm": 0.3,
  "net_name": "GND"
}

The drill must be smaller than the copper diameter. This tool supports through-hole vias only. Inspect the result and run DRC before using the board for manufacturing.

delete_items validates every requested UUID before deleting anything. It refuses locked items, footprint children such as pads and fields, and grouped items whose effective lock cannot be established through the API. Delete the parent footprint when appropriate, or ungroup items in KiCad first. A failed edit rolls back its transaction; an unconfirmed rollback is reported explicitly.

refill_zones schedules KiCad’s refill action and returns completed: false. Wait for the editor to finish before dependent edits or saving. The MCP response confirms that the action was requested, not that the fill finished.

Check DRC and export manufacturing files

These tools require kicad-cli from the same major KiCad version as the running editor. Put it on PATH or set KICAD_MCP_CLI to the executable’s full path before starting the server. They create local files and are unavailable in read-only mode.

Both tools use a private copy of the last saved PCB, along with saved project settings and custom design rules when available. Their responses identify this as snapshot: "last_saved_board" and includes_unsaved_changes: false. They never implicitly save the open PCB or project. Call save_board first to include pending PCB edits, and save changed project settings in KiCad before checking them. A never-saved PCB must first be saved in KiCad.

This choice avoids an effect of KiCad 10’s IPC Save Copy command, which can persist settings in the original project even when creating a copy.

Call run_drc with {"severity": "all"}. You can filter to "error" or "warning". A saved .kicad_pro is required so the check uses the project’s saved rules. The response includes a summary, up to 1,000 findings and the path to the complete JSON report; violations are returned as findings rather than a server failure. The check does not compare the PCB with its schematic. Filtered or excluded findings must not be interpreted as a complete clean-design result.

Call export_fabrication with these arguments for common manufacturing outputs:

{
  "formats": ["gerbers", "drill", "positions"]
}

These are also the defaults when formats is omitted. Gerbers, drill and position files share KiCad’s drill/place origin. Drill and position coordinates use millimetres; position export includes both sides and excludes DNP components. Gerber and SVG exports check zone fills and refill the private copy when necessary. "svg" exports a board drawing containing F.Cu, F.SilkS and Edge.Cuts. STEP export is not provided because a copied project can change how project-relative 3D model paths resolve. Export does not constitute a passing DRC check or manufacturing approval.

Results list generated files with paths and sizes on the machine running the MCP server. Outputs go into unique job directories under artifacts in the server’s state directory, or under KICAD_MCP_ARTIFACT_DIR when configured. Existing jobs are not overwritten. Temporary source copies are removed; successful reports and exports remain until you delete them. A remote MCP client may need a separate way to retrieve these local files.

Work with a bill of materials

The BOM is derived from the open PCB, including its current unsaved changes. It uses footprint values, library identifiers, custom fields and assembly flags available through KiCad’s PCB API. It does not read the schematic or resolve assembly variants.

get_bom and export_bom share these options:

Argument	Default	Behavior
`grouped`	`true`	Combine matching components into rows with references and a quantity per board; use `false` for one component per row
`include_dnp`	`false`	Include components marked “Do not populate” when enabled
`include_excluded`	`false`	Include components marked “Exclude from BOM” when enabled
`fields`	`null`	Include all custom fields; provide a list to select particular custom fields

Grouping compares values, complete library footprint identifiers and custom metadata, including manufacturer part numbers. Selecting fewer output fields does not merge components with different MPNs or other hidden metadata. References use natural ordering, such as R2 before R10. Quantities describe one copy of the board. Included components must have unique, annotated references; ambiguous or unannotated references produce an actionable error. Requested custom fields that are absent from a component are returned as empty strings.

A typical workflow is to inspect the BOM, update selected components, export it, and explicitly save the board if you want to keep the edits.

Call get_bom with these MCP arguments to inspect purchasing fields:

{
  "grouped": true,
  "include_dnp": false,
  "include_excluded": false,
  "fields": ["Manufacturer", "MPN"]
}

Call update_bom_fields to set the value, custom fields and assembly flags for selected references:

{
  "references": ["R1", "R2"],
  "value": "10k",
  "fields": {
    "Manufacturer": "Example Components",
    "MPN": "EXAMPLE-10K-0603"
  },
  "dnp": false,
  "exclude_from_bom": false
}

Provide references and at least one change; omit options you do not want to change. Use value for the built-in component value and fields to add or edit custom metadata such as Manufacturer or MPN. The update uses a single undoable transaction and does not save the board. It is unavailable in read-only mode. Use an empty string to clear a custom field’s value. Reapplying identical values makes no changes and returns updated_count: 0.

Call export_bom with these arguments to retrieve CSV text:

{
  "grouped": true,
  "fields": ["Manufacturer", "MPN"],
  "delimiter": ","
}

The MCP response contains csv, a suggested filename, mime_type, row_count and component_count for your client to display or save. Choose comma (","), semicolon (";") or tab ("\t") as the delimiter. The server does not create a CSV file on disk. CSV quoting handles commas, newlines and Unicode; spreadsheet formula prefixes are escaped to prevent them from being evaluated as formulas. Custom column names that would collide with another CSV header are prefixed with Field:; the original names remain unchanged in get_bom.

Inspect the board and call save_board with {} only when you want to save the result. This also saves any other pending PCB changes. You can undo the metadata update in KiCad before saving.

BOM updates modify PCB footprint data only. They do not edit or back-annotate the schematic. A later Update PCB from Schematic may overwrite these fields, so maintain the corresponding schematic metadata separately when it is the source of truth.

Install in KiCad

Requirements: KiCad 10.0 or later, Python 3.10+ with venv/pip support, and network access when dependencies are first installed. On Debian/Ubuntu, you may need the python3-venv package.

Using the Plugin and Content Manager

Download hackinvent-kicad-mcp-0.3.1.zip from the releases page.
In the KiCad project manager, open Plugin and Content Manager, choose Install from File and select the ZIP.
Enable the KiCad API in the plugin preferences, then open a PCB and reload the plugins or restart the editor.
Wait for the plugin’s Python environment to be created, then run Start MCP server.

The package is not yet listed in KiCad’s official plugin catalogue. Install it from the ZIP file.

From the repository

git clone https://github.com/HackInvent/kicad-mcp.git
cd kicad-mcp
python3 scripts/install_plugin.py --version 10.0

The installer copies the plugin into KiCad’s user directory. It does not modify KiCad’s program files. Typical paths are:

Linux: ~/.local/share/KiCad/10.0/plugins/org.hackinvent.kicad-mcp
macOS: ~/Documents/KiCad/10.0/plugins/org.hackinvent.kicad-mcp
Windows: %USERPROFILE%\Documents\KiCad\10.0\plugins\org.hackinvent.kicad-mcp

Use --destination /exact/path/to/plugin to choose another location, for example when your Documents folder is redirected. To update this installation, add --overwrite; the installer first checks the existing plugin’s identifier. Avoid installing both the ZIP and a manual copy of the same plugin.

On Windows, use py or python instead of python3, depending on your installation.

Connect an MCP client over HTTP

After running Start MCP server, the server listens at this address by default:

http://127.0.0.1:8765/mcp

A server-specific token protects every route. From the repository, retrieve the connection settings for running servers:

python3 scripts/connection_info.py

This command uses only the Python standard library. It displays the url and token fields to provide to your client:

Transport : Streamable HTTP
URL       : http://127.0.0.1:8765/mcp
Header    : Authorization: Bearer <value of the token field>

The configuration format depends on your client. It must support setting this HTTP header. Authentication uses a shared local token, without an OAuth server; clients that require OAuth cannot use this mode directly. Browser clients that send an Origin header are rejected; use a native MCP client or stdio mode.

The token changes on each startup unless KICAD_MCP_TOKEN is set. A fixed token must contain visible ASCII characters without whitespace; invalid values are rejected before the server starts. It is separate from KiCad’s internal IPC token. Do not include either token in issues or commits.

Without a copy of the repository, you can also find the connection settings in a session JSON file:

System	Session directory
Linux	`$XDG_STATE_HOME/kicad-mcp`, or `~/.local/state/kicad-mcp` if unset
macOS	`~/Library/Application Support/kicad-mcp`
Windows	`%LOCALAPPDATA%\kicad-mcp`

These files contain a secret; POSIX permissions restrict access to their owner. Stop MCP server stops the server associated with the KiCad instance that launches the action. Session locks prevent concurrent startups for the same instance.

Stdio mode and development

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/kicad-mcp serve --transport stdio

On Windows, the environment’s executables are in .venv\Scripts\.

For a client that accepts the mcpServers format, adapt the paths in this example:

{
  "mcpServers": {
    "kicad": {
      "command": "/ABSOLUTE/PATH/kicad-mcp/.venv/bin/python",
      "args": ["-m", "kicad_mcp", "serve", "--transport", "stdio"]
    }
  }
}

In this mode, the MCP client manages the server’s lifecycle; you do not need to click Start MCP server. The KiCad editor must remain open with its API enabled. With a single instance, kicad-python looks for the default KiCad socket. Use --socket or KICAD_API_SOCKET to target another instance. After restarting KiCad, restart the server to connect to the correct session.

Additional commands after installing the Python package:

kicad-mcp serve --transport streamable-http --port 8765
kicad-mcp serve --transport stdio --read-only
kicad-mcp status
kicad-mcp status --show-token
kicad-mcp stop

--read-only exposes only the 15 inspection/BOM read tools and also blocks the other operations in the KiCad adapter. Selection, layer changes, DRC reports and fabrication exports are disabled because they change editor state or create files. export_bom remains available because it returns CSV text without creating a file. An already running server cannot change its read-only setting through a second start command: stop it first, then restart with the intended setting. status hides the token by default. When multiple servers are running, use stop --socket /path/to/socket to select the instance to stop.

Configure startup from KiCad

Set these variables before starting KiCad:

Variable	Effect
`KICAD_MCP_PORT`	HTTP port, `8765` by default; `0` selects an available port
`KICAD_MCP_TOKEN`	Optional fixed HTTP token to keep the client configuration unchanged
`KICAD_MCP_READ_ONLY=1`	Enable read-only mode
`KICAD_MCP_STATE_DIR`	Override the session directory
`KICAD_MCP_CLI`	Full path to kicad-cli for DRC and fabrication tools; otherwise search PATH
`KICAD_MCP_ARTIFACT_DIR`	Override the directory that stores DRC reports and manufacturing exports

KiCad automatically passes KICAD_API_SOCKET and KICAD_API_TOKEN to plugin actions. For multiple simultaneous instances, use different ports or KICAD_MCP_PORT=0, then retrieve their URLs with connection_info.py.

Verification

.venv/bin/ruff check .
.venv/bin/python -m pytest -q
.venv/bin/python -m build
python3 scripts/build_plugin.py

CI runs these checks on Python 3.10, 3.12 and 3.13. Tests cover real HTTP/stdio MCP clients, errors, access restrictions, repeated startups, shutdown, KiCad units, transaction rollback, BOM grouping and CSV export, metadata updates, pad/via/zone inspection, stackup, selection and deletion, DRC/export command handling, artifact cleanup, and PCM archives. The tests use simulated editor and CLI boundaries; they do not require a KiCad GUI or kicad-cli.

For a manual check on a copy of a test PCB:

Install the plugin and start the server from KiCad.
Connect a client and call kicad_status, get_board_info and list_footprints.
Move an unlocked component and check its coordinates, then undo the change in KiCad.
Add text and a track on enabled layers; inspect the result and run DRC in the editor.
Read a BOM, update Manufacturer/MPN on test components, export the CSV and verify grouping, quantities and DNP filtering. Undo the metadata update in KiCad.
Inspect pads, zones, stackup and a net; select an item by UUID and check layer visibility.
Create and delete a test via, verify undo behavior, then request zone refill and wait for KiCad to finish.
Call save_board only if the result is as expected. Run run_drc, compare the report with the editor’s DRC, and check Gerbers, drill files and positions in appropriate viewers before manufacturing.
Stop the server using the KiCad action and confirm that the client disconnects.

If the plugin does not appear, check the Python environment and KiCad’s messages. If the server cannot connect, check that the API is enabled, a PCB is open and the correct socket is selected. If the port is occupied, choose another KICAD_MCP_PORT.

Architecture and references

flowchart LR
    A[MCP client] -->|Local Streamable HTTP or stdio| B[Python MCP server]
    B --> C[KiCad adapter with serialized access]
    C -->|IPC Protobuf / NNG| D[KiCad PCB editor]
    P[KiCad plugin action] -->|Start / stop| B
    C -->|Copy saved PCB and project context| S[Private job directory]
    S --> K[kicad-cli DRC and exports]
    K --> F[Local reports and manufacturing files]

src/kicad_mcp/server.py: MCP tools and HTTP authentication.
src/kicad_mcp/bridge.py: IPC access, conversions and edit transactions.
src/kicad_mcp/inspection.py: pads, vias, zones, item details, nets and stackup.
src/kicad_mcp/editing.py: selection, layer controls, vias, deletion and zone refill.
src/kicad_mcp/fabrication.py: saved-board snapshots, kicad-cli and artifact management.
src/kicad_mcp/bom.py: BOM grouping, CSV generation and metadata validation.
src/kicad_mcp/__main__.py: transports, sessions and control commands.
plugin/: IPC manifest, dependencies and KiCad actions.
scripts/: local installation, connection settings and PCM packaging.

Official references: KiCad IPC API, kicad-python library, KiCad 10 CLI, KiCad package format, MCP Python SDK, 1.x branch.

See CHANGELOG.md for release history.

MIT license.

Available Tools

13 tools

add_textA

Destructive

Add PCB text at absolute mm coordinates on the specified layer; do not save.

ParametersJSON Schema

Name	Required	Default
`text`	Yes
`x_mm`	Yes
`y_mm`	Yes
`layer`	No	F.SilkS
`height_mm`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds the important nuance that the operation does not save, which clarifies persistence behavior. However, it does not disclose other behavioral traits such as what happens on invalid input, coordinate system assumptions beyond 'absolute mm', or whether the change is reversible. It adds some value beyond annotations but is not rich.

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 description is a single sentence with no redundant words. The core action is front-loaded, and the critical 'do not save' caveat is placed at the end. Every word contributes to clarity. This is an excellent example of concise, well-structured documentation.

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 simple add-text operation with an output schema already defined, the description covers the essential behavioral and coordinate aspects. It omits details like default layer values or height units, but these are partially discoverable from the schema. The 'do not save' note is important and present. Overall, the description is nearly complete for an agent to safely invoke the tool, though a bit more context on coordinate origin or units would make it fully self-sufficient.

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

Parameters2/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 compensate. It mentions 'absolute mm coordinates' (covering x_mm and y_mm) and 'specified layer' (covering layer), but does not explain the text content or the height_mm parameter, nor the defaults for layer and height. The description adds minimal meaning beyond the schema and leaves several 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?

The description clearly states the action (Add), the resource (PCB text), and the key specifics (absolute mm coordinates, specified layer). It also adds a critical note about not saving, which distinguishes it from board-save operations and makes the tool's scope unambiguous. The purpose is fully transparent and easily distinguishable from siblings like add_track or move_footprint.

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

Usage Guidelines2/5

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

No guidance is given on when to use this tool versus alternatives such as add_track or move_footprint. The 'do not save' note is a behavioral caveat, not a usage guideline. There is no mention of prerequisites, typical scenarios, or when a different tool would be more appropriate, so an agent has 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.

add_trackA

Destructive

Add one straight copper track, optionally assigned to an existing net; no autorouting or DRC.

ParametersJSON Schema

Name	Required	Default
`layer`	No	F.Cu
`end_x_mm`	Yes
`end_y_mm`	Yes
`net_name`	No
`width_mm`	No
`start_x_mm`	Yes
`start_y_mm`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already indicate readOnlyHint=false and destructiveHint=true, so the description correctly reflects a mutation. It adds the 'no autorouting or DRC' caveat and the optional net assignment, but does not disclose potential failure conditions (e.g., invalid net name, coordinate ranges) or side effects. This is adequate but not rich; no contradiction with annotations.

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?

A single sentence that front-loads the primary action and includes the key caveat. Every word earns its place, and it is appropriately concise for a simple tool.

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

Completeness2/5

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

With 7 parameters, 4 required, and zero schema descriptions, the tool definition is incomplete. The description fails to explain the meaning of the coordinate parameters, the width default, the layer semantics, or the net_name behavior. An agent would need to guess or rely on external knowledge to call this correctly, despite the output schema existing.

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

Parameters2/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 compensate by explaining parameters. It only mentions net assignment (net_name) and implies endpoints via 'straight track', but does not clarify start/end coordinates, width, layer, or their units. The parameter names are somewhat self-explanatory, but the description adds minimal value beyond the schema.

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?

The description clearly states the action ('Add one straight copper track') and the resource, and adds a distinguishing constraint ('no autorouting or DRC') that separates it from hypothetical routing tools. It is specific and unambiguous, even without naming a sibling.

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

Usage Guidelines3/5

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

The description implies when to use the tool (manual track placement) via 'no autorouting or DRC', but it does not explicitly mention alternatives or conditions for not using it. There are no similar add tools among siblings, so the lack of explicit routing is acceptable, but no clear when/not-when guidance is given.

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

export_bomB

Read-onlyIdempotent

Return a spreadsheet-safe CSV BOM as text, without writing a file; delimiter may be comma, semicolon or tab.

ParametersJSON Schema

Name	Required	Default
`fields`	No
`grouped`	No
`delimiter`	No	,
`include_dnp`	No
`include_excluded`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the output is text and does not write a file, which is consistent with annotations and adds a minor behavioral detail. It does not contradict annotations, but it doesn't disclose other behaviors like output size or dependency on current board state.

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 description is a single, front-loaded sentence that states the core purpose and key differentiator (no file write, text output, delimiter options) without any fluff. Every word earns its place, making it exceptionally concise and well-structured.

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

Completeness2/5

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

Although an output schema exists (covering the return format), the description omits meaning for four of five parameters and provides no guidance on when to use this tool over the sibling get_bom. Given the tool's moderate complexity and the presence of siblings, the description is incomplete for an agent to call it correctly without external knowledge.

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

Parameters1/5

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

With 0% schema description coverage, the description must explain the five parameters (fields, grouped, delimiter, include_dnp, include_excluded). It only mentions delimiter, leaving the other four completely unexplained. The description fails to compensate for the lack of schema documentation, providing almost no semantic value for parameters.

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?

The description states a specific action ('Return') and resource ('CSV BOM as text') while explicitly noting it does not write a file. This distinguishes it from sibling get_bom by format (CSV) and delivery (text), making the tool's purpose clear and unambiguous.

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

Usage Guidelines3/5

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

The description implies usage when a CSV text output without file creation is desired, and the 'without writing a file' hint differentiates from get_bom. However, it does not explicitly state when to use this tool vs. alternatives or any exclusions, leaving the selection decision partially to inference.

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

get_board_infoA

Read-onlyIdempotent

Read the active PCB's name, layers and item counts.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the specific data read (name, layers, item counts) but no further behavioral context such as performance or response format. It does not contradict annotations.

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 description is a single concise sentence that is front-loaded with the action and resource. Every word adds value with no redundancy or filler.

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?

Given the tool has an output schema and no parameters, the description fully covers what an agent needs to know to invoke it correctly. It specifies the resource (active PCB) and the data returned, and the annotations handle safety. Nothing essential 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?

There are zero parameters, so the schema fully covers any parameter semantics (there are none). The description does not need to explain parameters. Baseline for 0 params is 4.

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?

The description uses a specific verb 'Read' and specifies the resource 'active PCB' and the exact data returned (name, layers, item counts). This clearly distinguishes it from sibling tools like list_nets or list_tracks, which focus on specific elements rather than board-level summary.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or when to prefer sibling tools. Given the many siblings, explicit routing would help, but it is absent.

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

get_bomA

Read-onlyIdempotent

Read the PCB bill of materials with quantities and custom fields; omit DNP/excluded parts by default.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	No
`grouped`	No
`include_dnp`	No
`include_excluded`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing safety context. The description adds the behavioral detail about omitting DNP/excluded parts by default, which is not in the annotations, offering useful additional context.

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 description is concise, consisting of two sentences with no redundant information. It front-loads the main verb and resource, and all content is relevant to the tool's functionality.

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?

The output schema is present, so the description does not need to detail return values. It mentions that the BOM includes quantities and custom fields, giving a sense of the output. However, it does not mention potential edge cases like empty BOMs or error conditions, but that is acceptable given the output schema provides structure.

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

Parameters2/5

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

The schema has 0% description coverage for all four parameters. The description only hints at include_dnp and include_excluded through 'omit DNP/excluded parts by default', but does not explain the 'fields' or 'grouped' parameters. This is insufficient compensation for the lack of parameter descriptions.

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?

The description clearly states the tool reads the PCB bill of materials and specifies it includes quantities and custom fields, and omits DNP/excluded parts by default. The verb 'Read' and resource 'PCB bill of materials' are specific, and it is distinguishable from sibling tools like export_bom and update_bom_fields.

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 implies usage for read-only BOM retrieval by using 'Read' and mentioning the default omission of DNP/excluded parts, which suggests when to use it for viewing. However, it does not explicitly contrast with alternative tools like export_bom, so it lacks explicit strategic guidance.

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

get_selectionA

Read-onlyIdempotent

Read the items currently selected in the PCB editor.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the context that this reads the 'currently selected' items, but does not disclose any additional behavioral traits such as behavior with an empty selection or whether it returns references versus values. With annotations carrying the safety burden, this is adequate but not rich.

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 description is a single, focused sentence with no wasted words. It front-loads the action ('Read') and immediately states the object ('items currently selected in the PCB editor'), making it highly scannable.

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 zero-parameter, read-only tool with an output schema, the description provides sufficient context for correct invocation. The only minor gap is that 'items' is generic and does not enumerate what types of entities may be selected (footprints, tracks, text, etc.), but the output schema likely covers return values.

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?

The input schema has zero parameters, so there is nothing for the description to explain. The baseline of 4 applies since parameter semantics are vacuously satisfied and no compensation is needed.

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?

The description uses a specific verb ('Read') and a clear resource ('items currently selected in the PCB editor'), making the tool's function immediately understandable. It also distinguishes itself from sibling tools like list_nets, list_tracks, and get_board_info by focusing specifically on the current selection state.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states what the tool does, leaving the agent to infer that it is appropriate whenever the current selection is needed.

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

kicad_statusA

Read-onlyIdempotent

Check the connection to KiCad and report the editor version.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

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

The description mentions the action of checking and reporting, which is consistent with the annotations (read-only, idempotent, non-destructive). However, it does not go beyond the annotations to disclose additional behavioral details like error handling or return format specifics, though the output schema likely covers that.

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 description is extremely concise and front-loaded, stating the purpose in a single sentence without any unnecessary details. It efficiently conveys the tool's function.

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?

Given the simplicity of the tool (no parameters, simple output), the description is complete. The output schema exists to define return details, so the description does not need to explain more. It fully covers the tool's purpose in context.

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

Parameters3/5

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

There are no parameters, and the schema coverage is 100% (empty). The baseline score of 3 applies because there is no parameter information to add; the description does not need to elaborate on nonexistent arguments.

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?

The description clearly states the action ('Check the connection') and the specific resource ('KiCad') along with the expected result ('report the editor version'). It is distinct from sibling tools like list_nets or get_board_info, which focus on board data rather than connectivity and version.

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

Usage Guidelines2/5

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

No explicit guidance is given on when to use this tool versus alternatives, such as using it as a preliminary health check before other operations. The description only states what it does without indicating typical usage context or conditions.

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

list_footprintsA

Read-onlyIdempotent

List components, references, values and placement in mm; optionally filter by reference.

ParametersJSON Schema

Name	Required	Description	Default
`reference`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns placement in mm and supports filtering, providing useful context without contradicting annotations.

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?

One concise sentence that packs all essential information without redundancy.

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?

For a simple read-only list operation, the description fully covers what the tool returns and the available filter. No missing details.

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

Parameters5/5

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

The only parameter 'reference' is explained by the phrase 'optionally filter by reference', which fully covers its meaning despite the schema lacking a description.

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?

Clearly states it lists components, references, values, and placement in mm, with an optional filter. Distinct from siblings like list_nets and list_tracks by specifying 'footprints'.

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?

Implies usage for listing footprints and mentions the optional filter, but does not explicitly contrast with alternatives. Still, the purpose is clear enough for an agent to select it.

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

list_netsA

Read-onlyIdempotent

List the electrical nets of the active PCB.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context beyond stating it lists nets, which is consistent with the annotations.

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 description is a single, concise sentence with no filler. It front-loads the action and resource, making it immediately clear and efficient.

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 no-parameter list tool, the description is adequate. It specifies the scope ('active PCB') and the resource. The output schema is present, so return format is covered. It could potentially mention ordering or filtering, but that is not necessary for a simple list operation.

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?

There are zero parameters, so the schema trivially covers 100% of them. Per the rubric, zero parameters yields a baseline score of 4. The description adds no parameter information, but none is needed.

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?

The description clearly states the verb 'List' and the resource 'electrical nets of the active PCB', which distinguishes it from sibling tools like list_tracks (tracks) and get_bom (BOM). It is specific and not a tautology.

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

Usage Guidelines3/5

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

The description implies the tool is for listing nets but provides no explicit guidance on when to use it versus alternatives. It does not mention when not to use it or name specific sibling tools for different tasks.

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

list_tracksA

Read-onlyIdempotent

Read PCB tracks, widths, positions, copper layers and nets.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds specificity about what data is read (widths, positions, copper layers, nets), which goes beyond the annotations.

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 description is a single, concise sentence with no filler. It front-loads the action and clearly states the resource and attributes.

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?

Given zero parameters, an output schema, and annotations covering safety, the description fully covers what the tool does. Nothing an agent needs to invoke it correctly is missing.

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

Parameters3/5

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

The input schema has zero parameters, so schema coverage is 100%. The description does not need to elaborate on parameters, but it also adds no extra information about them. Baseline of 3 is appropriate.

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?

The description clearly states a specific action ('Read') and the resource ('PCB tracks') along with the attributes returned (widths, positions, copper layers, nets). This distinguishes it from siblings like list_nets and list_footprints.

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

Usage Guidelines3/5

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

The description implies when to use it (to read track information) but does not explicitly mention alternatives or when not to use it. Sibling tools exist, but no explicit guidance is given.

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

move_footprintA

Destructive

Move one unlocked component to absolute mm coordinates, with optional rotation; do not save.

ParametersJSON Schema

Name	Required	Description	Default
`x_mm`	Yes
`y_mm`	Yes
`reference`	Yes
`rotation_degrees`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, indicating a write operation. The description adds two useful behavioral details: it only works on 'unlocked' components and it does not save the board, which is critical for the agent to know the persistence behavior. No contradiction with annotations.

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?

A single, tightly packed sentence with no wasted words. The core action is front-loaded, and the 'do not save' note is placed at the end as a critical behavioral flag.

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?

Covers the essential facts: what is moved, to what coordinates, optional rotation, and the no-save behavior. Given the tool's simplicity and the presence of an output schema, the description is adequate. Missing details like error handling for locked components are minor given the constraints already mentioned.

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

Parameters3/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 compensate. It clarifies that coordinates are absolute mm (matching x_mm/y_mm) and that rotation is optional (matching rotation_degrees with null default). It implies 'reference' refers to a component but does not explicitly describe it. Provides some value beyond the parameter names.

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 action ('Move') on a resource ('unlocked component') with clear details: absolute mm coordinates, optional rotation, and a 'do not save' modifier. This distinguishes it from sibling list/edit tools and leaves no ambiguity about what the tool does.

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

Usage Guidelines3/5

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

The description implies usage (move a component) but does not explicitly contrast with alternatives or state when to use it vs. other tools. It does mention the 'unlocked' constraint, which hints at when it might not be applicable, but lacks explicit guidance on alternatives or prerequisites.

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

save_boardA

DestructiveIdempotent

Explicitly save the active PCB, including unsaved changes made in the editor, to its current file.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value by clarifying that it saves unsaved changes and writes to the current file, which goes beyond a generic 'save' and helps the agent understand the exact persistence behavior without contradicting any annotation.

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 description is a single, well-structured sentence that immediately conveys the action and its scope. It is front-loaded with the core purpose and includes the key nuance of unsaved changes, with no wasted words.

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?

For a zero-parameter, simple save operation with an output schema present, the description fully covers what the tool does. It specifies the target (active PCB), the inclusion of unsaved changes, and the destination (current file). No additional behavioral or error information is necessary given the simplicity and existing structured metadata.

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?

There are no parameters, and the schema coverage is trivially 100%. With zero parameters, the baseline is 4, and the description correctly omits any parameter details since none exist. No further semantic enrichment is needed.

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?

The description clearly states the verb 'save' and the resource 'active PCB', and specifies that it includes unsaved changes and writes to the current file. This is a distinct operation from all sibling tools, which are read/list/export/update/move/add operations, so there is no ambiguity.

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 implies this tool is used when the agent needs to persist the current editor state, including unsaved changes. It does not explicitly mention when not to use it or name alternatives, but no sibling tool performs saving, so the context is clear enough. It lacks an explicit exclusion but provides sufficient usage context.

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

update_bom_fieldsA

Destructive

Update custom BOM fields, value or assembly flags on exact PCB references in one undo step; do not save or change the schematic.

ParametersJSON Schema

Name	Required	Description	Default
`dnp`	No
`value`	No
`fields`	No
`references`	Yes
`exclude_from_bom`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

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

The description adds behavioral context beyond the annotations: it notes the operation is atomic ('in one undo step') and explicitly states it does not save or change the schematic. This complements the destructiveHint=true annotation and gives the agent a clearer picture of 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.

Conciseness5/5

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

The description is a single, front-loaded sentence with no filler. It states the action first, then the atomicity and scope restrictions, making every word earn its place.

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

Completeness2/5

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

Given 5 parameters and zero schema descriptions, the description is insufficient. It does not explain the format of the 'fields' parameter, does not enumerate which parameters correspond to assembly flags (dnp vs exclude_from_bom), and omits how references should be formatted. The output schema exists, but that does not compensate for missing parameter semantics. An agent would likely need to infer or experiment to use it correctly.

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

Parameters3/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 compensate. It gives a high-level mapping of parameters: 'custom BOM fields' to fields, 'value' to value, and 'assembly flags' to dnp and exclude_from_bom. However, it does not explain the structure of the fields object (string-to-string map) or enumerate which flags are included, leaving some ambiguity.

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?

The description clearly states the tool updates BOM fields, value, and assembly flags on exact PCB references, which is a specific verb+resource. It distinguishes itself from read-only siblings like get_bom and export_bom, and the scope 'exact PCB references' adds precision.

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

Usage Guidelines3/5

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

It provides context by stating it does not save or change the schematic, which helps scope usage, but it does not explicitly name alternatives or conditions for when to use this tool over others. The sibling list offers no direct alternative for updating BOM data, so guidance is implied rather than explicit.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

13 tool updatesv0.2.0Sep 8, 2026
- First observedadd_text
- First observedadd_track
- First observedexport_bom
- First observedget_board_info
- First observedget_bom
- First observedget_selection
- First observedkicad_status
- First observedlist_footprints
- First observedlist_nets
- First observedlist_tracks
- First observedmove_footprint
- First observedsave_board
- First observedupdate_bom_fields

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored 2026-09-08 03:40 across 13 tools

Disambiguation5/5

Each tool has a distinct purpose: listing nets vs. tracks vs. footprints, reading vs. writing board info, and save/status are clearly separated. No overlapping or ambiguous tool boundaries.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (list_*, get_*, update_*, add_*, save_*, export_*), with a few exceptions like 'kicad_status' and 'get_board_info' breaking the strict verb-first pattern. Overall naming is predictable and readable.

Tool Count5/5

13 tools is a reasonable, focused set for a KiCad PCB MCP server. Each tool covers a necessary operation without redundancy, and the count is within the ideal 3-15 range.

Completeness4/5

The set covers core PCB inspection, modification, and board management operations. Minor gaps exist such as no explicit tool for deleting objects or modifying tracks/footprints, but the surface is largely complete for typical read/modify workflows.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

KodyOAuth
io.github.kentcdodds
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Developer Tools Code Execution Command Line
2617
Agentic Mermaid A
io.github.adewale
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Data Visualization Software Architecture
9210
slimaOAuth
io.github.slima-ai
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Developer Tools
21
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1

Related MCP Servers

mcp-kicad
Design Tools Embedded system
daedalus
A
license
B
quality
C
maintenance
MCP server exposing KiCad PCB Editor functionality via IPC API.
Updated 5 months ago (2026-04-21 19:26 UTC)
41
MIT
KiCad MCP Server
Embedded system Developer Tools
aswego123
F
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that exposes KiCad PCB design automation tools to AI assistants and other MCP clients.
Updated a year ago (2025-10-07 10:58 UTC)
-
mcp-kicad-cli
Developer Tools Command Line
SpectraSynq
A
license
B
quality
C
maintenance
Enables KiCad CLI automation via MCP, providing tools for ERC, DRC, BOM export, netlist export, Gerbers, drill files, STEP, IPC-2581, and GLB output.
Updated 2 months ago (2026-07-13 03:39 UTC)
10
Apache 2.0
pcb-mcp
Design Tools Developer Tools
Amagtoto
A
license
A
quality
B
maintenance
Enables AI assistants to read and modify KiCAD PCB designs through the KiCAD IPC API, providing tools for board queries, footprint placement, track creation, DRC, and export.
Updated a month ago (2026-07-31 17:30 UTC)
44
14
MIT