Copper

Overview Schema Source Related Servers Discussions Admin

Focus (what the user points at)

focus

Idempotent

Captures the user's current click, box, or KiCad selection and resolves it to schematic or PCB references, pins, nets, and a cropped preview, so you can act on exactly what they mean.

Instructions

What the user is pointing at. Call it when they say "this part", "here", "that corner" instead of guessing. action: get (default; the latest click / box in the Copper Canvas or selection in KiCad's PCB editor; wait=N waits up to N s for their next one) | resolve (no human: what is inside box=[x0,y0,x1,y1] or nearest near=[x,y] mm on document='schematic' | 'pcb') | open (start the Copper Canvas viewer and return its URL) | clear. Returns focus {document, mode, box_mm | point_mm, refs, pins, nets, age_s}, items with value / footprint / position, and a cropped PNG with the focus outlined. Empty refs with a box or point means the user means that AREA. Use refs / pins in sch_apply, pcb_place, pcb_route; box_mm in render(crop=...). Examples: focus() · focus(wait=60) · focus(action='resolve', document='pcb', box=[100,100,120,115])

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

Input Schema

Name	Required	Description
`box`	No	resolve: [x0,y0,x1,y1] mm — everything inside or touching
`near`	No	resolve: [x,y] mm — nearest part and pin
`side`	No	resolve (pcb): only footprints on this side (default both; a pad under the point beats a bare courtyard)
`wait`	No	get: seconds to wait for the user's next click/box (0 = don't wait, max 300)
`sheet`	No	resolve (schematic): sheet path or name, e.g. '/' or '/amp/left' (default root)
`action`	No
`launch`	No	open: also open the user's browser (default true)
`radius`	No	resolve near: search radius mm (default 5.08 schematic, 3 pcb)
`render`	No	attach the cropped PNG of the focus (default true)
`source`	No	get: auto (default) = whichever the user touched last; kicad = the PCB editor selection (needs KiCad's IPC API; KiCad has none for schematics)
`project`	No	project path (default: active)
`document`	No	resolve: which document the mm coordinates are in

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Nov 13, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations cover safety (idempotent, non-destructive, closed-world), and the description adds real behavior beyond them: get blocks up to N seconds for the user's next click, open launches the Copper Canvas viewer and returns a URL, and resolve runs with no human in the loop. It also clarifies the semantic edge case that empty refs plus a box or point means the user intends that AREA. It does not cover failure modes (no user click within wait, no KiCad IPC API present) beyond the schema's parenthetical.

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?

The purpose is front-loaded in one sentence, followed by a compact pipe-delimited action map, a returns summary, and three concrete call examples — efficient for a 12-parameter, four-mode tool. The action line is dense and mildly run-on, but no sentence is 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?

With no output schema, the description carries the return contract itself and does so: focus object fields, resolved items with value/footprint/position, and the cropped PNG. Defaults for action, wait and render are stated. Minor gaps remain for `project` default resolution and what happens when a wait expires with no click, but the agent can call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 92%, so nearly all parameter meaning is already documented in structured data, establishing a baseline of 3. The description restates the action enum semantics and reinforces wait=N and box_mm usage, but adds little syntax or unit detail the schema does not already carry.

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 line names the resource in agent-relevant terms — resolving the user's deictic reference ('this part', 'here') — and the action list enumerates the four concrete operations (get/resolve/open/clear) with what each targets. Downstream routing to sch_apply, pcb_place, pcb_route and render makes the tool's role unambiguous against siblings like pcb_read or sch_read.

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?

Explicit invocation trigger is given ('call it when they say "this part", "here", "that corner" instead of guessing'), and each action mode carries its own condition (get = passive latest click, resolve = no human involved, open = start viewer). It lacks an explicit when-not-to-use statement or comparison to reading tools like pcb_read/sch_read, which keeps it below 5.

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