Skip to main content
Glama
ProductOfAmerica

mcp-server-kicad

by ProductOfAmerica
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

modify_hierarchical_sheet

Destructive

Modify properties of an existing hierarchical sheet block.

Instructions

Modify properties of an existing hierarchical sheet block.

A new width or height keeps each pin on its edge and moves it with the edge, places the
name and file fields of an autoplaced sheet again, and moves a wire, bus end or
no-connect that sat on a moved pin with it, so the sheet stays connected. A size smaller
than the sheet's pins need is refused, naming the minimum, and a size equal to the
current one changes nothing.

Args:
    sheet_uuid: UUID of the sheet to modify (from list_schematic_sheets)
    schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.
    sheet_name: New display name (empty = keep)
    file_name: New file path (empty = keep)
    width: New width in mm (None = keep)
    height: New height in mm (None = keep)

Input Schema

NameRequiredDescriptionDefault
widthNo
heightNo
file_nameNo
sheet_nameNo
sheet_uuidYes
schematic_pathNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.1

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing side effects: pins stay anchored to resized edges, autoplaced name/file fields are re-placed, and wires, buses and no-connects riding a moved pin are dragged along so connectivity survives. It also documents the failure mode (sizes below the pin minimum are refused, naming the minimum) and the no-op case where the new size equals the current one, all of which the annotations could not convey.

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-loaded with purpose, then behavior, then an Args block, which is the right order for a mutation tool. The behavioral paragraph is dense and slightly awkwardly phrased ('places the name and file fields of an autoplaced sheet again') but every sentence carries information.

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?

An output schema exists, so return values need no prose. With all six parameters explained, side effects enumerated, and the error condition stated, an agent has everything needed to call a destructive sheet mutation correctly.

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 carries the full burden, and it does: every one of the six parameters is explained along with its sentinel value (empty string = keep for sheet_name/file_name, None = keep for width/height), units in mm, and optionality of schematic_path.

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?

States a specific verb and resource: modify properties of an existing hierarchical sheet block. The verb distinguishes it from add/remove/move_hierarchical_sheet by naming the operation, though it never explicitly says it edits metadata (name, file, size) rather than position.

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?

Points at list_schematic_sheets as the source of sheet_uuid and explains that omitting schematic_path uses the configured default, which is useful routing context. However, it never addresses the closest alternative, move_hierarchical_sheet, so an agent may not know that repositioning a sheet is out of scope here, and no when-not-to-use guidance is given.

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