Agents & MCP New

MCP Tool Reference

14 min read Updated Markdown
On this page

When your agent connects to WireFrame, the bridge offers it 33 tools. This page describes each one as WireFrame 2.0.3 reports it. The descriptions are the ones wf-mcp-server --tools of 2.0.3 prints, edited lightly for this guide; the parameters and the read-only marks are the ones each tool declares to your agent when it connects. WireFrame 2.0.1 and 2.0.2 offer fourteen of them, call ask_penalty chat, and count every call.

wf-mcp-server --tools prints the list as JSON and needs no WireFrame running, so it is a quick way to see what your copy has (where the bridge is: Find the bridge). It prints all 33. A connected agent is offered them only while WireFrame is open and signed in to a plan that includes MCP — started without WireFrame, or with nobody signed in, the bridge offers none and says why.

None of them runs until you press Allow in WireFrame's AI panel — see Allow it in WireFrame. Only a call that changes the design, or puts Penalty, WireFrame's own agent, to work, counts as an MCP call; reading, checking and analysing are free. With ask_penalty, run_command and build_blocks, Penalty's job also spends AI credits, as it would if you had typed the request in the panel. See How calls are counted.

The design tools behind call_tool#

One of the 33, call_tool, reaches the design tools WireFrame's own Copilot works with. Which ones are offered follows what is open — the board tools need a board, the simulation tools a simulation — and on a real project with its schematic and board open there are 117. They are listed by task on Use WireFrame from your own agent. list_design_tools gives the list as it stands, and one tool's full description with name; the resource wireframe://tools gives every tool's parameters. Both are free.

A design tool that can run for minutes — propose_layout, optimize_layout, evaluate_layouts, propose_placement, propose_floorplans, close_open_connections, analyze_current, analyze_thermal, run_simulation, research_layout, repeat_channel — answers within wait_s seconds (20 unless your agent asks for up to 50) or carries on as a job, and job_status gives its answer when it is done.

What reads, and what may change the design#

Each tool carries MCP's hints — readOnlyHint, and for the tools that are not read-only, destructiveHint — so your agent's client can decide what to ask you before it calls one:

Marked Tools
Read-only read_design, read_guide, design_status, list_projects, list_commands, read_transcript, is_busy, list_design_tools, job_status
Not read-only, not destructive open_project, new_project, close_project, stop, attach, new_session
May change the design (destructive) submit_bom, bind_part, install_part, confirm_parts, submit_netlist, revise_design, submit_blocks, edit_schematic, resolve_erc, save_design, ask_penalty, run_command, confirm_all, update_schematic, build_blocks, place_schematic, update_pcb, call_tool

ask_penalty, run_command and call_tool are marked as changing the design because they can: what they do depends on what is asked. /bom, or call_tool with score_board, only reads; /layout apply, or call_tool with apply_layout, writes. What counts as a call follows what really happens, not the mark: call_tool with score_board is free.

While Penalty is working on a job, a call that would change the design is refused — and not counted — until the job ends; so is a write, or a second long design tool, while a long design tool runs as a job. Tools that only read still answer. See What changes the design, and what waits.

Start here#

Free, however often your agent calls them. An agent that reads read_guide before each stage and loops on design_status until it says done does better work for the same calls.

read_guide#

Read-only. Free.

How to design a board here: the way of working and what good looks like, by topic. Read start_here first and each stage's guide before that stage. With no topic it lists them.

Parameter Type Required Description
topic string no start_here, schematic, parts, board_and_floorplan, power_stage, decoupling, routing, signal_and_noise, thermal, manufacturing, review

design_status#

Read-only. Free.

Is this design done? ERC, board checks, open connections, signal integrity and manufacturability in one answer, with done and what remains. Loop until done is true, or until what remains is the person's to decide.

No parameters.

read_design#

Read-only. Free.

The plan as it stands: every part with its binding and what blocks it, every net, the checkers' findings, the blocks and sheets. pins adds the real pin tables: read them before writing a netlist, because pin numbers come from the symbols, never from memory. A list of designators gives those parts' tables whole; true gives a long BOM's in part.

Parameter Type Required Description
pins boolean or array no true, or a list of designators. Default none

list_design_tools#

Read-only. Free.

The design tools call_tool can run on this project, one line each. Pass name for one tool's full description and arguments.

Parameter Type Required Description
name string no A tool's name. Omit for the list

job_status#

Read-only. Free.

The answer of a long tool that outlasted its call (optimize_layout, propose_layout, close_open_connections...). Says if it is still running, else gives its result. Omit job for the latest. wait_s waits up to 50 s first.

Parameter Type Required Description
job string no The id the call gave, e.g. "j3"
wait_s integer no Seconds to wait first. Default 0

Choose the project#

Every other tool works on the active project. Listing, opening and closing projects are free; a new project is written to disk and counts as a call. close_project never discards anything: it refuses while any sheet or board of the project has unsaved changes, and names them.

list_projects#

Read-only. Free.

The projects open in WireFrame, the active one marked: every other tool works on that one. With folder, also the WireFrame projects (.prjxml) under it, three levels deep.

Parameter Type Required Description
folder string no An absolute folder to look in. Omit for the open projects only

open_project#

Changes which project is active, not a design. Free.

Open a WireFrame project and make it the active one, the project every other tool works on. path is its .prjxml, or a folder holding exactly one. A project already open only becomes active. Its sheets and board open with it.

Parameter Type Required Description
path string yes Absolute path to the .prjxml, or to its folder

new_project#

Writes a new, empty project to disk. Counts as a call.

Create an empty WireFrame project at <folder>/<name>/<name>.prjxml and make it the active one, ready for submit_bom. Refused when that folder already holds a project: open_project it instead. This writes to disk.

Parameter Type Required Description
folder string yes Absolute path of the folder the project's own folder goes in
name string yes The project's name: letters, digits, spaces, - and _

close_project#

Changes which project is active, not a design. Free; refused while the project has unsaved changes.

Close an open project, the active one unless path names another. Refused while any of its sheets or boards has unsaved changes: call save_design first, or leave it to the person. Nothing is ever discarded, and the plan stays with the project for when it is opened again.

Parameter Type Required Description
path string no The .prjxml of an open project. Omit for the active one

Write the design yourself#

Your agent's own work: the BOM, the bindings, the wiring, the blocks and sheets, and the push to the board. Each one counts as a call.

submit_bom#

Changes the design. Counts as a call.

Write the BOM yourself. Replaces the plan's parts and clears its wiring and blocks. Held to the same checks as any BOM, then every row is matched to the library; the answer says what bound and what blocks each row that did not. One physical part per row: a quantity above 1 is split. This writes to the design.

Parameter Type Required Description
components array yes The parts
requirement string no What the board must do, for the checks and later readers
summary string no One line on the design

bind_part#

Changes the design. Counts as a call.

Bind one BOM row to exactly the symbol and footprint you chose, overruling the matcher. symbol is a name in a loaded library, symbol_file an absolute path to a .kicad_sym to import. footprint is a footprint name, a standard land such as "0805 (SMD Passive)", or a wire pad in any size such as "SolderWirePad_1x01_SMD_3.5x4.5mm" ("SolderWirePad_1x01_THT_3.5x4.5mm_D1.7mm" with a plated hole for the wire); those two are made if they are not there yet. This writes to the design.

Parameter Type Required Description
footprint string no Library footprint name
id string yes The row's designator
symbol string no Library symbol name
symbol_file string no Absolute path to a .kicad_sym

install_part#

Changes the design. Counts as a call.

Get a part the library does not hold yet, into this project's library. With ids: the part number those BOM rows name, as sold, from WireFrame's published library and then LCSC, bound to those rows. With draft: the id of a part draft_part drafted; bind it afterwards with bind_part. Calls no model. This writes to the design and to disk.

Parameter Type Required Description
draft string no A draft's id from draft_part
ids array no BOM rows to install for; rows naming one part share it

confirm_parts#

Changes the design. Counts as a call.

Accept parts you have checked. Only a row that passes the checks can be confirmed. A confirmed row is protected from Penalty's work, and the record says you confirmed it, not a person. Rows sharing one symbol and footprint are confirmed together. This writes to the design.

Parameter Type Required Description
ids array yes Designators

submit_netlist#

Changes the design. Counts as a call.

Write the wiring yourself, against the parts now bound. A part you leave out of every net is left unwired rather than refused. The answer carries the checkers' findings. This writes to the design.

Parameter Type Required Description
netlist array yes The nets
summary string no One line on the design

revise_design#

Changes the design. Counts as a call.

Change only what you name; every other row keeps its binding and confirmation and only the blocks you touch are redrawn. Use it instead of resubmitting. set_components: rows by id with only the fields that change (name, type, role, value, package, rationale, pin_count, quantity, block); a new id adds a part. remove_components: ids. set_nets: nets by name with all their pins. remove_nets: names. A part that loses its binding is reported, not fetched for you. This writes to the design.

Parameter Type Required Description
remove_components array no Designators to remove
remove_nets array no Net names to remove
set_components array no Rows by id with only the fields that change: name, type, role, value, package, rationale, pin_count, quantity, block. A new id adds a part
set_nets array no Nets by name, each with all its pins
summary string no What this revision does

submit_blocks#

Changes the design. Counts as a call.

Split the parts into blocks and pages yourself, and draw the sheets. Every physical part in exactly one block, every block on exactly one page. Leave out sheets for one page per block. This writes to the design and to disk.

Parameter Type Required Description
blocks array yes The blocks; every physical part in exactly one
build boolean no Draw the sheets now. Default true
sheets array no The pages; every block on exactly one. Leave out for one page per block

edit_schematic#

Changes the design. Counts as a call.

Change the drawn schematic directly, as one undo step. edits are the ops call_tool preview_edit takes: add_component, remove_component, connect, disconnect, set_value. Checked here against the design: a change that introduces an error is refused. This writes to the design.

Parameter Type Required Description
edits array yes The changes — add_component, remove_component, connect, disconnect, set_value, the ops preview_edit takes
reason string yes One sentence, kept in the chat for the person
sheet string no Which sheet, by name. Default: the one that holds these parts

update_schematic#

Changes the design. Counts as a call.

Draw the planned design onto the schematic sheets, or update them after a revision. Reports the blocker instead when something is in the way. This writes to the design.

No parameters.

place_schematic#

Changes the design. Counts as a call — except with review_only, which changes nothing and is free.

Place the parts on the sheets, marking anything still unresolved on the canvas rather than refusing. With review_only it reports what can be drawn and what waits, and changes nothing.

Parameter Type Required Description
review_only boolean no Report without placing. Default false

resolve_erc#

Changes the design. Counts as a call.

Act on what call_tool run_erc found, by its #numbers. fix: WireFrame's own fixes (No-Connect on a pin meant to stay open, PWR_FLAG on a rail fed from a connector, a dangling wire). exclude: items the design means, kept with why. Answers the ERC totals after. This writes to the design.

Parameter Type Required Description
exclude array no ERC item numbers the design means, kept with why
fix array no ERC item numbers for WireFrame's own fixes
why string no Why these are right

update_pcb#

Changes the design. Counts as a call.

Push the schematic's netlist onto the PCB and save it — footprints and nets are overwritten. Run this before any /layout, and again after the schematic changes. This writes to the design and to disk.

No parameters.

save_design#

Changes the design. Counts as a call.

Write every open sheet and board to disk. An applied layout and an edited sheet stay in the window until this runs. This writes to disk.

No parameters.

Hand a job to Penalty#

Penalty is WireFrame's own agent. ask_penalty, run_command and build_blocks wait for the job to finish — up to half an hour — before they answer. A job still running after that answers that it is still running, and nothing is lost: poll is_busy, then read_transcript.

ask_penalty#

Changes the design. Counts as a call; the job also spends AI credits, as it would in the panel.

Give Penalty, WireFrame's built-in co-pilot, one bounded job. You decide the design; Penalty does what you hand it: find candidates for a part, draft a symbol from a datasheet, review what you wrote, answer something it asked. The answer ends with what WireFrame measured it changing. Its report is a claim: check it against that. Spends the account's AI credits. Blocks until the job is done.

Parameter Type Required Description
task string yes The job, in plain language, naming what it may touch

run_command#

Changes the design. Counts as a call; the job also spends AI credits, as it would in the panel.

Have Penalty run one of WireFrame's slash commands. The ones a design uses: /layout [place,route|fresh reseed|fix|apply|discard|check] lays the PCB out and nothing changes until apply; /board <describe it> sets the shape; /fix <REF> <what is wrong> repairs one part; /missing lists parts with no symbol; /bom, /nets, /findings, /review read the design; /topology weighs one board against a stack; /erc review sorts real faults from intended ones. Call list_commands for the rest. Blocks until the command is done.

Parameter Type Required Description
command string yes The whole command, e.g. "/layout fresh reseed"

list_commands#

Read-only. Free.

Every slash command Penalty offers right now, with what it does. Cheap, no model call — read it before guessing a command.

No parameters.

build_blocks#

Changes the design. Counts as a call; the job also spends AI credits, as it would in the panel.

Have Penalty group the design into blocks and build the sheets from them. Spends AI credits; to decide the grouping yourself use submit_blocks. stage is "group" (propose the grouping) or "build" (draw the sheets). This writes to the design.

Parameter Type Required Description
stage string yes "group" or "build"

confirm_all#

Changes the design. Counts as a call.

Accept everything Penalty is currently offering, unseen. Prefer confirm_parts, which names what you checked. This writes to the design — every change is one undo step, attributed to this client in the project's ledger.

No parameters.

Follow and steer a job#

None of these changes the design, and none counts.

read_transcript#

Read-only. Free.

The conversation so far, newest last. Use it after a job timed out, or to see what Penalty did and why.

Parameter Type Required Description
last integer no Only the last N messages. Omit for all

is_busy#

Read-only. Free.

Whether Penalty or the library match is still working. Poll this instead of guessing when a call reported that it was still running.

No parameters.

stop#

Changes nothing in the design. Free.

Cancel what Penalty is doing, or the long tool running as a job. A layout that has not been applied changes nothing on the board.

No parameters.

attach#

Changes nothing in the design. Free.

Put files in front of Penalty for the NEXT job — a datasheet PDF, a pinout image, a reference project. Paths on this machine.

Parameter Type Required Description
paths array yes Absolute paths

new_session#

Changes nothing in the design. Free.

Start a fresh conversation with Penalty, keeping the planned BOM. Use it when the chat has grown long and Penalty is repeating itself; the design is not lost.

No parameters.

Call a design tool#

call_tool#

Counts as a call only when the design tool it names changes the design; a design tool that reads, checks, analyses or proposes is free.

Call one of WireFrame's design tools by name, with JSON arguments: the board, library, datasheet, layout, simulation and power engines Penalty uses. You choose and sequence them. list_design_tools shows what this project offers. Writes under names like apply_, edit_ and set_ land on the design. Their descriptions were written for Penalty: where one says to ask the person first, the decision is yours.

Parameter Type Required Description
arguments object no Its arguments. Omit for none
name string yes The tool's name, e.g. "score_board"
wait_s integer no A long tool waits this long (up to 50 s, default 20), then continues as a job: see job_status

A design tool opens what it reads: if no sheet or no board of the project is open, call_tool opens them before it runs. It reaches only the tools list_design_tools lists for the open project; a name that is not one of them is refused, nothing runs, and the call is given back — the answer ends "No call was counted."

See also#