Skip to main content
Glama
Sign In
Copper

Copper

by claynicholson
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Schematic: apply ops

sch_apply
Destructive

Apply a single atomic batch of schematic edits—place parts, connect pins by net name, and validate with ERC/netlist—so either all changes succeed or nothing is written.

Instructions

Edit the schematic with ONE atomic batch of ops (all succeed or nothing is written). Put a whole sub-circuit, or the whole design, in a single call. Creates the .kicad_sch if missing. One call edits one sheet. Pins are 'REF.PIN', PIN = number or name ('U1.PA9', 'J1.VBUS', 'R1.2'); a name on several pins connects them all. Never compute coordinates: connect by NET NAME and Copper anchors the label or power symbol on the pin. New parts take a temporary 'id' (one word) used in pins ('led.A'); the result's refs maps id to reference. Parts without 'at' are laid out automatically, and a sheet only Copper has arranged is re-drawn as titled functional blocks (layout='keep' never does that; nothing is redrawn unless the netlist is proven identical). ops (objects with "op"):

  • place: lib_id | lcsc "C25804" | part (+provider) | spec "10k 0402" (resolved by the parts providers); id, ref, value, footprint, fields {LCSC:..}, near (ref/id), group mcu|power|connector|passive, at [x,y], rot, mirror, unit, dnp

  • connect: pin | pins [..], net (power names like GND, +3V3, VBUS become power symbols; kind:'global' between sheets)

  • power: pin(s), net · no_connect: pin | pins · pwr_flag: net · wire: from, to | points · label: net + pin | at

  • set_field: ref, field, value | fields · move: ref, at | by, rot, mirror · swap: ref + lib_id | lcsc | part | footprint

  • delete: ref | label | wire_at [x,y] | dangling:true · disconnect: pin(s) · rename_net: from, to · text: text, at The result has what changed, the netlist check of every requested connection and KiCad's ERC with a ready fix per issue, so a separate verify call is not needed. Example: ops=[{"op":"place","lib_id":"Regulator_Linear:AMS1117-3.3","id":"ldo"},{"op":"place","spec":"10uF 0805","id":"cin"}, {"op":"connect","pins":["ldo.VI","cin.1"],"net":"VBUS"},{"op":"connect","pins":["ldo.GND","cin.2"],"net":"GND"}]

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ops": "<ops>"
    },
    "name": "sch_apply"
  }
}

Input Schema

NameRequiredDescriptionDefault
opsYesOrdered list of op objects (see description).
sheetNoSub-sheet file or sheet name (default: root sheet).
layoutNoauto (default): a sheet only Copper arranged is re-drawn as functional blocks after a batch without at/rot (netlist proven identical); keep: never; pro: always try.
verifyNoRun ERC + netlist connectivity check after writing. Default true.
dry_runNoValidate and report what would change without writing.
previewNoattach a PNG (default false)
projectNoproject path (default: active)
while_openNorefuse (default) | revert

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true and openWorldHint=false; the description adds much more: atomicity, auto-creating the .kicad_sch when missing, layout='keep' never redrawing, and redraw only when the netlist is proven identical. It also discloses what the result contains (refs map, netlist check, ERC with a ready fix), which is critical for a destructive batch tool.

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 atomic-batch constraint and safety rules before the op catalog, and nearly every sentence carries information. It is dense and the bullet list of ops is a wall of text, but for a 14-op batch tool the length is justified rather than padded.

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 an 8-parameter destructive tool with no output schema, the description covers atomicity, file creation, layout behavior, pin/net conventions, id-to-ref mapping, and result contents including ERC fixes. Nothing an agent needs to invoke it correctly appears missing.

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?

Although schema coverage is 100%, the schema types `ops` only as a generic array of objects; the description supplies the entire op vocabulary (place, connect, power, no_connect, pwr_flag, wire, label, set_field, move, swap, delete, disconnect, rename_net, text) with field-level meaning. It also clarifies pin syntax ('REF.PIN', name-or-number), temporary ids, and net-name-to-power-symbol behavior, adding real meaning 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 opening sentence states a specific verb and resource ('Edit the schematic with ONE atomic batch of ops') plus the all-or-nothing semantics. It distinguishes itself from the verify sibling by noting 'a separate verify call is not needed', so an agent can route without opening schemas.

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 clear usage context: batch a whole sub-circuit or the whole design into one call, one call edits one sheet, and never compute coordinates. It also routes away from a separate verify call. It does not explicitly say when to prefer sch_read or sch_tidy over this tool, so not quite a 5.

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