eda-agent

Overview Schema Source Related Servers Discussions Admin

design_add_circuit_block

Adds a canonical circuit block to a DesignPlan with automatic refdes allocation and net wiring, replacing manual pin-by-pin boilerplate.

Instructions

Fold a canonical circuit block into a DesignPlan in one call.

Authoring boilerplate sub-circuits pin-by-pin in plan JSON is slow and error-prone (a decoupling network is N caps, 2N pins, and two net merges that must line up). This emits the canonical topology of a common block and wires it into plan_json -- allocating unique refdes, tying every pin to the right net, and tagging power/ground and roles -- then returns the augmented plan plus an inline re-validation so the next authoring step starts from a known state.

It is naming-agnostic: it owns the wiring pattern, never the part choice. YOU supply every part identity in params (lib_ref/value/footprint/mpn/datasheet_url), picked semantically from the live inventory snapshot. Pass computed values from design_compute_component_value where relevant.

Blocks and their required params (all also accept pins to override default pin names, refdes_prefix, sheet):

decoupling power_net, ground_net, lib_ref [, count, value, footprint] -- N bypass caps.
pullup signal_net, rail_net, lib_ref [, value].
pulldown signal_net, ground_net, lib_ref [, value].
series_resistor net_a, net_b, lib_ref [, value].
voltage_divider rail_net, ground_net, lib_ref_top, lib_ref_bottom [, value_top, value_bottom, output_net] -- fresh midpoint net.
rc_lowpass input_net, ground_net, lib_ref_r, lib_ref_c [, value_r, value_c, output_net].
rc_highpass input_net, ground_net, lib_ref_r, lib_ref_c [, value_r, value_c, output_net] -- series C + shunt R (AC coupling).
led_indicator anode_net, cathode_net, lib_ref_r, lib_ref_led [, value_r, mid_net].
crystal xin_net, xout_net, ground_net, lib_ref, cap_lib_ref [, value, cap_value] -- crystal + a matched pair of load caps (one shared cap_value keeps the legs equal).
pi_filter input_net, ground_net, lib_ref_l, lib_ref_c [, value_l, value_c, output_net] -- shunt C, series L/ferrite, shunt C.
mosfet_low_side control_net, load_net, ground_net, lib_ref_r, lib_ref_fet [, value_r_gate, value_r_pulldown, pulldown, fet_pins] -- gate series R + gate pull-down + FET switching a load low-side.
mosfet_high_side control_net, load_net, rail_net, lib_ref_r, lib_ref_fet [, value_r_gate, value_r_pullup, pullup, fet_pins] -- gate series R + gate pull-up + PMOS switching a load high-side (source at the rail).

Call design_list_circuit_blocks for the full per-block parameter contract.

Net endpoints the block does NOT own (a pullup's signal, an RC input, a divider rail) should already exist in the plan; the block only creates the nets it fully populates. If you point a block at a net that ends up with a single pin, the inline ERC reports it as a floating net for you to complete.

Args: plan_json: the DesignPlan as a JSON string or dict. block: block name (see the list above). params: block parameters (see per-block requirements above).

Returns: {ok, plan, added: {refdes, nets, extended_nets}, notes, validation} where plan is the augmented DesignPlan dict ready for the next design_add_circuit_block or design_execute_plan, and validation is the same payload design_validate_plan returns. ok is False on a bad block name / missing param / schema error, with errors.

Input Schema

Name	Required	Description	Default
`block`	Yes
`params`	Yes
`plan_json`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.6.1Oct 29, 2026

TDQS

A4.7/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: it discloses what is created and mutated (unique refdes, pins tied to nets, power/ground and role tagging), what the block will not do (it only creates nets it fully populates), and the failure mode (ok=False with errors on bad block name, missing param, or schema error). It also warns that single-pin nets surface as floating-net ERC findings.

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?

It is front-loaded with a one-sentence summary, then rationale, then the block contract table, then notes, then Args/Returns — a sensible ordering. The per-block required-parameter list is long and partially duplicates the design_list_circuit_blocks contract it tells you to call, so the length is justified but not optimal.

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 a tool with three nested/complex parameters, an output schema, and no annotations, everything an agent needs to invoke it correctly is present: valid block names, per-block parameter requirements, preconditions about pre-existing nets, error semantics, and a pointer to the follow-up tools. Return-value explanation is a bonus on top of the existing output schema.

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 description coverage is 0%, but the description compensates fully: plan_json is defined as a DesignPlan in JSON-string or dict form, block is enumerated against the complete list of 12 valid block names, and params is spelled out per block with required fields separated from optional ones in brackets, plus shared overrides (pins, refdes_prefix, sheet). That is more than the schema could ever 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?

The opening sentence states a specific verb and resource — fold a canonical circuit block into a DesignPlan — and the following paragraphs explain exactly what it emits (topology, refdes allocation, pin-to-net wiring, role/power tagging). It is clearly distinguished from siblings like design_add_part and design_list_circuit_blocks, so an agent can tell which one to open.

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?

It gives a concrete use case (replacing error-prone pin-by-pin boilerplate such as a decoupling network), routes to design_list_circuit_blocks for the full contract and design_compute_component_value for values, and states a prerequisite that endpoints the block does not own must already exist. There is no explicit statement of when NOT to use it (e.g., a single one-off part, which belongs to design_add_part), so it falls just short of a 5.

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

Deploy Server