kicad

Overview Schema Source Related Servers Discussions Admin

add_component

Add a component to a KiCad schematic by specifying its library ID and value. Auto-generates reference designators and positions if not provided.

Instructions

Add a component to the current schematic.

Creates a new component with the specified library ID, value, and optional parameters. If no reference is provided, one will be auto-generated based on the component type (e.g., R1, C1, U1). If no position is provided, the component will be auto-placed.

Args: lib_id: Library identifier (e.g., "Device:R", "Amplifier_Operational:TL072") value: Component value or part description (e.g., "10k", "100nF", "TL072") reference: Component reference designator (e.g., "R1", "U2") - auto-generated if None position: Component position as (x, y) tuple in mm - auto-placed if None rotation: Component rotation in degrees (0, 90, 180, or 270), defaults to 0 footprint: PCB footprint identifier (e.g., "Resistor_SMD:R_0603_1608Metric") ctx: MCP context for progress reporting (optional)

Returns: ComponentInfoOutput with component information, or ErrorOutput on failure

Examples: >>> # Add a resistor with auto-generated reference >>> result = await add_component( ... lib_id="Device:R", ... value="10k", ... position=(100.0, 100.0) ... ) >>> print(f"Added {result.reference}")

>>> # Add a capacitor with specific reference and footprint
>>> result = await add_component(
...     lib_id="Device:C",
...     value="100nF",
...     reference="C1",
...     position=(120.0, 100.0),
...     footprint="Capacitor_SMD:C_0603_1608Metric"
... )

Input Schema

TableJSON Schema

Name	Required	Description	Default
`value`	Yes
`lib_id`	Yes
`position`	No
`rotation`	No
`footprint`	No
`reference`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.0Oct 6, 2026

TDQS

A4.2/5.0

Behavior4/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 well: it discloses that a missing reference is auto-generated (R1, C1, U1), that a missing position triggers auto-placement, that rotation defaults to 0, and that failures return ErrorOutput. It stops short of covering permissions, whether an open schematic is required, or side effects on existing design data.

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 opening sentence is front-loaded and the Args/Returns/Examples structure is scannable. The two worked examples are useful for a call-shape-sensitive tool, though the Returns line partially duplicates the existing output schema and could be trimmed.

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?

For a six-parameter mutation tool with an output schema available, the description covers intent, every parameter, defaults, auto-behavior, and failure mode, so an agent can call it correctly. The main remaining gap is environmental preconditions (schematic must be open) and any permission requirements, which are absent with no annotations to fall back on.

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?

Schema coverage is 0%, so the description must compensate and it does: each parameter gets a plain-language meaning plus concrete format examples (lib_id 'Device:R', value '10k'/'100nF', position as (x, y) in mm, rotation limited to 0/90/180/270, footprint 'Resistor_SMD:R_0603_1608Metric'). This adds real meaning the schema alone does not convey.

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?

States a specific verb+resource ('Add a component to the current schematic') and immediately clarifies that it creates a new component. This distinguishes it from siblings such as update_component, remove_component, and list_components without the agent needing to open any schema.

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 by 'Add a component to the current schematic,' and the argument docs make the intended call shape obvious, but there is no explicit when-to-use guidance, no prerequisites (e.g., a schematic must be loaded first), and no routing to alternatives like update_component for existing parts. A reasonable agent can infer the case, but the description does not spell it out.

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