mcp-server-kicad

by ProductOfAmerica

Overview Schema Source Related Servers Discussions Admin

Python

Local

add_hierarchical_sheet

Add a hierarchical sheet to a parent schematic with matching labels in the child.

Instructions

Add a hierarchical sheet to a parent schematic with matching labels in the child.

Creates the sheet block in the parent, with its pins on the left edge, and the
corresponding hierarchical labels in the child schematic. The child schematic must
already exist (create it with create_schematic first).

Everything is checked before the first write, so a refusal changes neither file: a pin
direction that is not one of the five below, an empty pin name, a child that is no
schematic, and a child that is the parent or has the parent somewhere below it.

The sheet's page is the lowest number no sheet of the hierarchy uses. It is written at
the instance path of the parent (the sheet that holds the block), which is where KiCad
reads a sheet's page; give project_path when the parent is itself a sub-sheet, so that
path can be found. Symbols already in the child get an instance entry at the new
sheet's path.

Args:
    parent_schematic_path: Path to parent .kicad_sch
    sheet_name: Display name for the sheet
    sheet_file: Path to child .kicad_sch (must exist)
    pins: List of dicts with 'name' (str) and 'direction' (str) keys.
          Direction: input, output, bidirectional, tri_state, passive.
    x: X position of sheet block (default 25.4)
    y: Y position of sheet block (default 25.4)
    project_path: Path to .kicad_pro file (for sub-sheet instance tracking)

Input Schema

Name	Required	Description	Default
`x`	No
`y`	No
`pins`	Yes
`sheet_file`	Yes
`sheet_name`	Yes
`project_path`	No
`parent_schematic_path`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.11.0Aug 10, 2026

addedInput schema / $defs

Added value: +{
+  "SheetPinSpec": {
+    "description": "A hierarchical sheet pin and its direction.",
+    "properties": {
+      "direction": {
+        "title": "Direction",
+        "type": "string"
+      },
+      "name": {
+        "title": "Name",
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "direction"
+    ],
+    "title": "SheetPinSpec",
+    "type": "object"
+  }
+}

addedInput schema / properties / pins / items / $ref
```
Added value: +"#/$defs/SheetPinSpec"
```
removedInput schema / properties / pins / items / additionalProperties
```
Removed value: -true
```
removedInput schema / properties / pins / items / type
```
Removed value: -"object"
```

First observedv0.9.1Jun 10, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false); the description adds far more, notably atomic validation ('Everything is checked before the first write, so a refusal changes neither file') and the enumerated refusal conditions. It also discloses non-obvious side effects: page-number allocation, instance-path writing, and instance entries added to symbols already in the child.

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

Conciseness4/5

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

Front-loads the action in the first sentence and then layers prerequisites, validation, and mechanics. The page-number/instance-path paragraph is dense but earns its place for a hierarchy-editing tool; it could be trimmed slightly without loss.

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 non-idempotent hierarchy mutation with 7 parameters and no schema descriptions, the definition covers prerequisites, failure atomicity, refusal conditions, placement defaults, and instance-path behavior. An output schema exists, so return values need not be explained.

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?

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: it defines the pins list shape ('dicts with name and direction'), enumerates the five legal directions, documents defaults for x/y, and explains the project_path-for-sub-sheet case and that sheet_file must exist. This fully compensates for the untyped 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?

Opens with a specific verb and resource ('Add a hierarchical sheet to a parent schematic') and immediately names the dual effect: the sheet block in the parent plus matching hierarchical labels in the child. This distinguishes it clearly from siblings like add_sheet_pin, add_hierarchical_label, and modify_hierarchical_sheet.

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?

States an explicit prerequisite and the alternative that satisfies it ('The child schematic must already exist (create it with create_schematic first)'). Also conditions when to supply project_path ('when the parent is itself a sub-sheet'). What's missing is a negative case — when to use modify_hierarchical_sheet or duplicate_sheet instead.

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

Deploy Server