eda-agent

Overview Schema Source Related Servers Discussions Admin

lib_link_3d_model

Link a 3D STEP model to a named PcbLib footprint in the active library, loading it as a component body that drives 3D view and height/placement DRC.

Instructions

Link a 3D STEP model to a PcbLib footprint.

Loads the STEP geometry into the footprint as an IPCB_ComponentBody (the real 3D body that drives the 3D view and the height/placement DRC), so the active document must be the .PcbLib that contains the footprint. component_name selects the footprint by name (empty uses the library's current footprint).

Args: component_name: Name of the footprint in the active PcbLib model_path: Path to the 3D model file (.step, .stp); must exist offset_x: X offset in mils from the FOOTPRINT's origin. The body is always moved onto that origin first: it arrives at the board origin, and a footprint open in the editor sits at Altium's library origin, about 50000,50000 mil, so an offset of 50000 used to be needed to bring it back. Do not add that any more. offset_y: Y offset in mils, applied with offset_x offset_z: Z offset in mils, sets the body's StandoffHeight. This is the common adjustment: lifting a connector body off the board so it sits on its pads rather than through them. rotation_x: NOT APPLIED, accepted for signature stability. Set it in the library editor after linking. rotation_y: NOT APPLIED, same reason as rotation_x. rotation_z: NOT APPLIED. This one used to assign Body.Rotation, and IPCB_ComponentBody has no such property on AD26 26.9.1.9. MEASURED: it raised "Undeclared identifier: Rotation", which DelphiScript cannot catch, so the Try around it never fired and the resulting modal took the whole polling loop down with it. Passing a rotation used to cost you the bridge. The rotation lives on the MODEL, not the body, and has to be set before the model is attached (Model.SetState in AutoSTEPplacer.pas). Its four arguments are undocumented, so they are not guessed at here. Rotate in the library editor for now.

Returns: Dict with success, footprint, model, footprint_origin_mils and moved_to_footprint_origin (false means the body may sit at the board origin, away from the footprint), and applied -- which adjustments were actually written to the body (standoff_height, rotation_z, offset_xy). Check it rather than assuming: each assignment is individually guarded, so one failing does not fail the call. rotation_z is now ALWAYS false, see above. standoff_height is confirmed live; offset_xy is not yet.

A ``false`` means the adjustment did not happen, which
covers both a rejected assignment and an argument left at
its default of 0: the handler skips a zero rather than
writing it. ``offset_xy`` covers ``offset_x`` and
``offset_y`` together and is true if either is non-zero.

Input Schema

Name	Required	Description	Default
`offset_x`	No
`offset_y`	No
`offset_z`	No
`model_path`	Yes
`rotation_x`	No
`rotation_y`	No
`rotation_z`	No
`component_name`	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.5/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 behavioral burden and does so unusually well: it explains that the STEP geometry becomes an IPCB_ComponentBody, that the body is moved to the footprint origin first, and that offset_z controls StandoffHeight. It explicitly warns that rotation_x, rotation_y, and rotation_z are NOT APPLIED, explains the prior rotation_z failure mode, and documents the 'applied' return dict so callers know which adjustments actually happened.

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 and the Args/Returns structure makes the long description navigable. However, it includes historical detail such as the former 50000 mil offset and the modal failure that 'took the whole polling loop down,' which is useful but more verbose than strictly necessary.

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 8-parameter mutation-style library tool with no annotations, the description is complete: it covers preconditions, every parameter, the return dict, and the 'applied' semantics. Although an output schema exists, the extra return-value explanation is valuable because it clarifies which adjustments may silently fail.

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%, so the description must compensate for all 8 parameters, and it does. It documents units and meaning for offset_x, offset_y, and offset_z, explains component_name and model_path, and clearly marks rotation_x, rotation_y, and rotation_z as accepted but not applied. It also notes that offset_x and offset_y together drive the offset_xy applied flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/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: 'Link a 3D STEP model to a PcbLib footprint.' It also states the active document must be the .PcbLib containing the footprint and that component_name selects the footprint. It does not explicitly distinguish itself from sibling tools such as lib_auto_link_3d_models or pcb_place_3d_body, so it stops short of a 5.

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?

The description gives clear preconditions: the active document must be the .PcbLib, component_name selects the footprint, an empty name uses the current footprint, and model_path must exist. It does not name alternatives or say when to use lib_auto_link_3d_models instead, so the routing guidance is not fully explicit.

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

Deploy Server