Skip to main content
Glama

add_component_from_library

Place a symbol from a KiCad library into a schematic, applying its fields, pins and flags. Use it to add parts from global or project library tables with grid-aligned connections.

Instructions

Add a symbol of a KiCad symbol library to the schematic.

The library comes from the library tables of the installed KiCad and of the project, as in the symbol chooser of KiCad: a library of the project table replaces a global library with the same name. A derived symbol gets the units, the pins and the drawings of its parents. When the schematic has the symbol in its lib_symbols section, the tool uses that definition. The tool gets the version of the installed KiCad from kicad-cli, to find the global library table.

The placed symbol gets the fields of the library symbol (Datasheet, Description, user fields) at their library positions, the flags exclude_from_sim, in_bom, on_board and in_pos_files of the library symbol, and the reference of its sheet path, as KiCad places a symbol. The tool does not move the fields (KiCad: autoplace).

The connection grid is schematic.connection_grid_size of the project file (default 1.27 mm). ERC finds a pin off this grid (endpoint_off_grid).

As the schematic editor of KiCad, the tool removes the part of a wire between two pins of the new symbol, and adds a junction where a pin is in the middle of a wire. The output tells each junction and each changed wire.

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": {
      "file_path": "<file_path>",
      "library_name": "<library_name>",
      "symbol_name": "<symbol_name>",
      "reference": "<reference>",
      "value": "<value>"
    },
    "name": "add_component_from_library"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNo
yNo
unitNoThe unit, from 1 to the number of units of the symbol.
valueYesThe text of the Value field.
file_pathYesThe .kicad_sch file.
footprintNoThe footprint. Empty: the footprint of the library symbol.
referenceYesThe reference, for example "R1".
sheet_pathNoOnly for a sheet file that the hierarchy uses more than one time: the sheet that gets the reference, as the sheet names ("/Power/") or the UUID path. The error lists the sheet paths.
symbol_nameYesThe symbol name in the library.
library_nameYesThe library name of the library tables.
snap_to_gridNoTrue: move the symbol to the nearest position that puts its pins on the connection grid. When the move takes a pin away from a connection point of the sheet (a pin, a wire, a label), the symbol stays at x, y. False: use x, y as they are. The output tells the pins off the grid.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that kicad-cli is consulted for the KiCad version, that lib_symbols definitions take precedence, that fields/flags/reference are copied, that fields are not autoplaced, and that wires are split and junctions inserted as a side effect. The output's reporting of junctions and changed wires makes the mutation consequences explicit.

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 core action is front-loaded in one line, then behavior is layered in short paragraphs. A few sentences are wordier than needed (e.g., the kicad-cli version sentence, the symbol-chooser analogy), but no paragraph is filler.

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 11-parameter mutation tool with side effects, the description covers library resolution, field/flag copying, grid and snapping behavior, reference assignment, and wire/junction modification. An output schema exists, so the brief mention of output content is a bonus rather than a gap.

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 82%, so the schema already documents most parameters, and the description largely restates rather than extends them. It does add context around the connection grid (schematic.connection_grid_size, default 1.27 mm) and ERC's endpoint_off_grid, but per-parameter guidance for reference, value, footprint, or unit is left to 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 first sentence gives a specific verb and resource: 'Add a symbol of a KiCad symbol library to the schematic.' This is unmistakably distinct from the sibling tools that create wires, labels, or query libraries, and the rest of the description keeps the scope on placement into the schematic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than declared: the agent learns the tool places a symbol and how the library is resolved, but nothing says when to prefer it over search_library_symbols/get_library_symbol first, nor any when-not conditions. The sheet_path caveat ('only for a sheet file that the hierarchy uses more than one time') is the one explicit conditional.

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