Copper

Overview Schema Source Related Servers Discussions Admin

Schematic: tidy layout

sch_tidy

Destructive

Redraws a KiCad schematic sheet into titled functional blocks with signal-flow layout, canonical idiom drawings and design notes, while verifying the netlist is unchanged and ERC stays clean.

Instructions

Re-draw a schematic sheet so it reads like a hand-drawn professional sheet WITHOUT changing the circuit: titled functional blocks in signal-flow columns, canonical drawings per idiom (LDO, op-amp loop, crystal, LED chain), support parts wired at the pin they serve, supplies up and grounds down, design notes, smallest paper that fits. Nothing is written unless KiCad's netlist of the WHOLE project is identical before and after and ERC reports nothing new. A sheet wired by hand is left alone (style_used: 'kept') unless force=true; sheets with sheet symbols, buses or several instances are refused. style 'pro2' (default); when the checks refuse it a simpler style is drawn: style_used says which, fallback says why. Example: sch_tidy() · sch_tidy(sheet='power.kicad_sch', dry_run=true) · sch_tidy(blocks=[{"id":"U2","title":"MCU"}])

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": "sch_tidy"
  }
}

Input Schema

Name	Required	Description
`force`	No	Also re-lay a hand-wired sheet.
`paper`	No	A4, A3 ... (default: smallest that fits).
`route`	No	off: no routed wires inside blocks.
`sheet`	No	Sub-sheet file or sheet name (default: root sheet).
`style`	No	pro2 (default): idiom templates, flow columns, notes; pro: blocks + wires; labels: every connection a pin label.
`blocks`	No	Block hints: {id: anchor ref, title?, note?, members? [refs]}.
`frames`	No	Block frames + titles (default true).
`symfix`	No	pro2: overprinting pin texts. hint (default) reports them; auto redraws the sheet's copy of Copper-imported symbols only (never KiCad stock); off: silent.
`dry_run`	No
`preview`	No	attach a PNG (default false)
`project`	No	project path (default: active)
`while_open`	No	refuse (default) \| revert
`title_block`	No	title, date, rev, company, comment1..9 (title/date auto-filled when empty).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Nov 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations declare destructiveHint=true; the description earns that by explaining exactly what is rewritten (the whole sheet) and the safety gate (netlist of the whole project must be identical, ERC must report nothing new). It also discloses refusal conditions, the fallback style with 'fallback' rationale, and the 'kept' outcome for hand-wired sheets — behavior well 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.

Conciseness4/5

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

Front-loaded with the guarantee of circuit-invariance and the layout result, then constraints, then examples. Dense but each clause carries information; the mid-sentence parentheticals are heavy but not filler.

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 13-parameter, nested-object tool with no output schema, it covers the critical unknowns: mutation scope, safety checks, refusal cases, fallback behavior, and the 'style_used'/'fallback' return fields. Remaining gaps (preview PNG details, while_open semantics) are adequately covered by the 92% schema coverage.

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 coverage is 92%, so the schema already carries most parameter meaning; the description adds value by explaining the default style 'pro2', that force re-lays hand-wired sheets, and by giving concrete call examples including dry_run and blocks hints. It stops short of explaining route, frames, or symfix beyond what the schema says.

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 ('Re-draw a schematic sheet') plus the invariant constraint ('WITHOUT changing the circuit'), and enumerates the layout characteristics it produces (functional blocks, signal-flow columns, idiom templates, supplies up/grounds down). This clearly separates it from siblings like sch_apply or sch_read, which are about applying/reading rather than re-laying out.

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?

Strong when/when-not guidance: hand-wired sheets are left alone unless force=true, and sheets with sheet symbols, buses or multiple instances are refused. The default style and its fallback path are also explained. It does not name alternative tools (e.g. sch_apply) for cases where tidying is refused, which keeps it short of a 5.

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