mcp-server-kicad

Overview Schema Source Related Servers Discussions Admin

reorder_sheet_pages

Destructive

Put hierarchical sheets in the page order given: sheets listed come first, in that order, then the others in the order they have now.

Instructions

Put hierarchical sheets in the page order given: sheets listed come first, in that order, then the others in the order they have now.

KiCad orders sheets by their page numbers, not by where their blocks sit in the file, so
this rewrites the page numbers and leaves the blocks where they are. Call it on the root
schematic: a sheet's page is stored at its parent's path, and a sub-sheet's blocks are
refused. The numbers already in use are given back in the new order, so custom labels
such as "Intro" stay; when they repeat, or a deeper sheet uses one, the sheets are numbered
from the lowest positive whole number no other sheet holds. A sheet whose instance entry
was written at its own path, as earlier versions of the tools did, has it moved to the path
KiCad reads. A root older than format 20221110, which keeps every page in its own
sheet_instances table, is refused.

Args:
    page_order: List of sheet UUIDs in desired order
    schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.

Input Schema

Name	Required	Description	Default
`page_order`	Yes
`schematic_path`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.9.1Jun 10, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description earns real credit beyond them: it explains that page numbers are rewritten while blocks stay put, that existing custom labels like 'Intro' are preserved, and that conflicting/duplicate labels trigger renumbering from the lowest unused positive integer. It also discloses a silent migration of mis-pathed instance entries, which is exactly the kind of side effect an agent needs warned about before a destructive call.

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 the primary action and ordering rule, then progressively narrower caveats. The third sentence is dense and slightly run-on, packing label preservation, renumbering fallback, and instance-path migration together, but every sentence still carries operational content.

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 destructive, non-idempotent mutation with an output schema, the description covers preconditions, side effects, refusal cases, and ordering semantics; the returned numbers need not be described since the output schema exists. An agent has enough to decide and call correctly.

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 Args block carries the burden — it identifies page_order as sheet UUIDs in desired order and schematic_path as the root .kicad_sch with an optional default. The body additionally explains partial-list behavior (unlisted sheets keep current order), which the schema cannot convey. Minor gap: no guidance on invalid or duplicate UUIDs, which matters given destructiveHint=true.

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 verb and resource — 'Put hierarchical sheets in the page order given' — and immediately defines the resulting ordering semantics (listed sheets first, then the rest unchanged). This is clearly distinct from siblings like move_hierarchical_sheet or modify_hierarchical_sheet, which an agent could otherwise confuse it with.

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 calling context: 'Call it on the root schematic', notes that sub-sheet blocks are refused, and lists two refusal conditions (own-path instance entries handled via migration, root older than format 20221110 refused). It stops short of naming a sibling alternative for reordering within a non-root sheet, so it is strong but not fully routing.

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

Deploy Server