Skip to main content
Glama
ProductOfAmerica

mcp-server-kicad

add_junctions

Add multiple junctions, as KiCad's junction tool places them. Each point dict has keys: x, y.

Instructions

Add multiple junctions, as KiCad's junction tool places them. Each point dict has keys: x, y.

A junction joins only where three or more wire directions, pins or sheet pins meet: a
crossing, a T, a wire end at a pin with another wire. Anywhere else (empty space, a
straight wire's interior, an L corner, a wire ending at a pin) KiCad's editor refuses it,
"Junction location contains no joinable wires and/or pins." (sch_drawing_tools.cpp:
1465-1497 at 9.0.8), and its cleanup deletes one placed there, so the whole call is
refused, naming each such point, and nothing is written. Every wire through a junction
is split there, which kicad-cli 9 needs to read the join; where a junction is already
exactly at a point no second one is added, but a wire still running through it is split.
A point where KiCad allows a junction, or where one already is, is taken even off the
page: it lies on wires or pins already drawn, which KiCad reads there as anywhere else.
Any other point off the page is refused as off the page. The result names each junction
written, each one already there and each split.

Args:
    points: List of junction positions [{x, y}, ...]
    schematic_path: Path to .kicad_sch file. Optional; omit to use the configured default.

Input Schema

NameRequiredDescriptionDefault
pointsYes
schematic_pathNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.11.0
    • addedInput schema / $defs
      Added value: +{
      +  "PointSpec": {
      +    "description": "A bare coordinate: junction positions and zone polygon corners.",
      +    "properties": {
      +      "x": {
      +        "title": "X",
      +        "type": "number"
      +      },
      +      "y": {
      +        "title": "Y",
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "x",
      +      "y"
      +    ],
      +    "title": "PointSpec",
      +    "type": "object"
      +  }
      +}
    • addedInput schema / properties / points / items / $ref
      Added value: +"#/$defs/PointSpec"
    • removedInput schema / properties / points / items / additionalProperties
      Removed value: -true
    • removedInput schema / properties / points / items / type
      Removed value: -"object"
  2. First observedv0.9.1

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: atomic refusal with nothing written, per-point error naming, wire-splitting side effects, no duplicate junction insertion, and the nuanced off-page rule. This is exactly the mutation behavior (partial idempotency on junctions, mutation of existing wires) an agent cannot infer from readOnlyHint=false / destructiveHint=false / idempotentHint=false.

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 first sentence is front-loaded and the critical refusal semantics come early. The source citation (sch_drawing_tools.cpp:1465-1497 at 9.0.8) and the convoluted off-page sentence ("...which KiCad reads there as anywhere else") cost some density, and the trailing Args block partly repeats the schema.

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?

An output schema exists, yet the description still summarizes what the result names (written, already present, split), which is helpful rather than redundant. For a mutation tool with two params and no annotation safety detail, every behavior an agent needs is present.

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?

With 0% schema description coverage, the description compensates well: it spells out the points list shape ({x, y} dicts) and clarifies that schematic_path is optional and falls back to the configured default. It doesn't give coordinate units or a concrete example payload, which keeps it from a 5.

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?

Opens with a specific verb and resource ("Add multiple junctions") plus the domain reference (KiCad's junction tool), which separates it cleanly from add_wires, remove_junction and list_schematic_junctions. The spatial rule that follows makes the resource even more concrete.

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-not guidance: it enumerates exactly the geometries where KiCad refuses a junction (empty space, wire interior, L corner, wire ending at a pin) and states the whole call fails if any point is invalid. It never names a sibling tool as an alternative (e.g. add_wires to create the wires first), so it stops short of full routing guidance.

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