Skip to main content
Glama

Update a component in place

update_component
Destructive

Replace an existing component in an Altium .PcbLib or .SchLib file while keeping its library position. Provide a footprint or symbol; a differing name renames it, and dry_run previews changes safely.

Instructions

Replace one existing component of an Altium library (.PcbLib or .SchLib) with the object given, keeping its position in the library. component_name must name a component the library holds, in any case; a name it does not hold is an error listing the available ones. Provide footprint for a .PcbLib or symbol for a .SchLib, in the shape write_pcblib or write_schlib takes: the object replaces the stored component wholesale, so a primitive left out is removed — start from get_component's output when editing. A name in the object that differs from component_name renames the component as well; a name another component already holds is refused, and an object without a name keeps the stored one. dry_run true changes nothing and reports would_rename and a changes list (description, primitive counts per kind); a real run backs the file up, saves, and returns renamed, old_description, component_count and a post-write validation. Alternatives: write_pcblib or write_schlib to rewrite a whole library, batch_update for one change across every component (track widths, a layer, a parameter), update_pad or update_primitive to change one primitive in place, rename_component for a rename alone.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolNoFor SchLib: the symbol to store, in the shape write_schlib takes per symbols entry
dry_runNoIf true, show what would be updated without actually modifying the file
filepathYesPath to the .PcbLib or .SchLib file
footprintNoFor PcbLib: the footprint to store, in the shape write_pcblib takes per footprints entry
component_nameYesName of the component to update (must exist in library)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.2.0
    • addedInput schema / properties / symbol / properties / images / items / properties / image_compressed
      Added value: +{
      +  "description": "Set by read_schlib only for an image whose compressed /Storage entry this server would not reproduce (another writer's zlib): the entry exactly as read, reused while it still holds image_data. Pass back unchanged; omit when authoring or replacing an image.",
      +  "type": "string"
      +}
    • addedInput schema / properties / symbol / properties / pins / items / properties / name_code_page
      Added value: +{
      +  "description": "Set by read_schlib on a pin a script authored: the ANSI code page its name was widened through, so a rewrite stores the name as Altium did. Pass back unchanged; omit when authoring.",
      +  "enum": [
      +    874,
      +    1250,
      +    1251,
      +    1252,
      +    1253,
      +    1254,
      +    1255,
      +    1256,
      +    1257,
      +    1258
      +  ],
      +  "maximum": 1258,
      +  "minimum": 874,
      +  "type": "integer"
      +}
  2. Changed4 schema fields changedv1.1.0
    • changedInput schema / properties / footprint / properties / component_bodies / items / properties / identifier / description
      Previous value: -"The body's IDENTIFIER, a user-visible name (any Unicode; stored as code points on disk). Default: empty"New value: +"The body's IDENTIFIER, a user-visible name (any Unicode; stored as UTF-16 code units on disk). Default: empty"
    • addedInput schema / properties / footprint / properties / pads / items / properties / polygon_connect
      Added value: +{
      +  "description": "The pad's own polygon-connect style (Altium: Pad Stack > Thermal Relief), overriding the design rules for how a polygon pour joins the pad. Omit to follow the rules (the default); a key left out takes Altium's default.",
      +  "properties": {
      +    "air_gap": {
      +      "description": "Gap between the pad and the pour in mm. Default: 0.254 (10 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "auto_conductors": {
      +      "description": "Let Altium choose the conductor count. Default: false",
      +      "type": "boolean"
      +    },
      +    "conductor_width": {
      +      "description": "Width of each relief conductor in mm. Default: 0.254 (10 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "conductors": {
      +      "description": "Number of relief conductors. Default: 4",
      +      "enum": [
      +        2,
      +        4
      +      ],
      +      "maximum": 4,
      +      "minimum": 2,
      +      "type": "integer"
      +    },
      +    "min_distance": {
      +      "description": "Minimum distance used with auto_conductors when min_distance_enabled is set, in mm. Default: 0.381 (15 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "min_distance_enabled": {
      +      "description": "Apply min_distance (Altium's Min Distance checkbox). Default: false",
      +      "type": "boolean"
      +    },
      +    "rotation": {
      +      "description": "Conductor angle in degrees. Default: 90",
      +      "enum": [
      +        45,
      +        90
      +      ],
      +      "maximum": 90,
      +      "minimum": 45,
      +      "type": "integer"
      +    },
      +    "style": {
      +      "description": "How the pour joins the pad. Default: relief",
      +      "enum": [
      +        "relief",
      +        "direct",
      +        "no_connect"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / footprint / properties / regions / items / properties / raw_contours
      Added value: +{
      +  "description": "Base64 of the region's contour bytes exactly as read_pcblib emitted them (outline and hole vertices). Altium stores a vertex as a double in internal units and a poured polygon's copper sits on fractional ones, so the bytes are replayed while they still describe the vertices above; an edited outline drops them. Pass back unchanged; omit when authoring.",
      +  "type": "string"
      +}
    • addedInput schema / properties / footprint / properties / vias / items / properties / polygon_connect
      Added value: +{
      +  "description": "The via's own polygon-connect style (Altium: Pad Stack > Thermal Relief), overriding the design rules for how a polygon pour joins the via. Omit to follow the rules (the default); a key left out takes Altium's default.",
      +  "properties": {
      +    "air_gap": {
      +      "description": "Gap between the via and the pour in mm. Default: 0.254 (10 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "auto_conductors": {
      +      "description": "Let Altium choose the conductor count. Default: false",
      +      "type": "boolean"
      +    },
      +    "conductor_width": {
      +      "description": "Width of each relief conductor in mm. Default: 0.254 (10 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "conductors": {
      +      "description": "Number of relief conductors. Default: 4",
      +      "enum": [
      +        2,
      +        4
      +      ],
      +      "maximum": 4,
      +      "minimum": 2,
      +      "type": "integer"
      +    },
      +    "min_distance": {
      +      "description": "Minimum distance used with auto_conductors when min_distance_enabled is set, in mm. Default: 0.381 (15 mil)",
      +      "minimum": 0,
      +      "type": "number"
      +    },
      +    "min_distance_enabled": {
      +      "description": "Apply min_distance (Altium's Min Distance checkbox). Default: false",
      +      "type": "boolean"
      +    },
      +    "rotation": {
      +      "description": "Conductor angle in degrees. Default: 90",
      +      "enum": [
      +        45,
      +        90
      +      ],
      +      "maximum": 90,
      +      "minimum": 45,
      +      "type": "integer"
      +    },
      +    "style": {
      +      "description": "How the pour joins the via. Default: relief",
      +      "enum": [
      +        "relief",
      +        "direct",
      +        "no_connect"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  3. Changed3 schema fields changedv1.0.5
    • addedInput schema / properties / footprint / properties / additional_parameters
      Added value: +{
      +  "description": "The footprint's Parameters keys other than HEIGHT, captured verbatim on read whenever the block is not the plain five-key block this tool writes from scratch: the PATTERN and DESCRIPTION bytes, the UNICODE twins that carry a name or description outside ASCII, the item and revision GUIDs of a managed footprint, a UI-authored AREA, and any key a newer Altium version writes. Each entry is a [key, value] string pair. Pass back unchanged on a read-modify-write so nothing is dropped (a PATTERN, DESCRIPTION or twin that no longer matches the name or description is rebuilt from it); omit when authoring, or to have the block rebuilt in Altium's current shape.",
      +  "items": {
      +    "items": {
      +      "type": "string"
      +    },
      +    "maxItems": 2,
      +    "minItems": 2,
      +    "type": "array"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / footprint / properties / height
      Added value: +{
      +  "description": "Overall component height in mm — Altium's HEIGHT parameter, written as its mil string. Default: 0",
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / footprint / properties / param_key_order
      Added value: +{
      +  "description": "The footprint's Parameters keys in stored order, as read_pcblib emitted them; the writer replays this order so the block stays byte-faithful. Pass back unchanged; omit when authoring (canonical order).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  4. Changed2 schema fields changed
    • addedInput schema / properties / footprint / properties / storage_name
      Added value: +{
      +  "description": "The CFB storage the component was read from, as read_pcblib/read_schlib emit it. Pass it back unchanged on a read-modify-write so the component stays where Altium looks for it (Altium re-derives a short name's storage and maps a long one through SectionKeys, so a moved storage is a component it cannot load); omit when authoring or renaming, and the storage name is derived as Altium would: / \\ : ! * become _, then a cut at 31 characters.",
      +  "type": "string"
      +}
    • addedInput schema / properties / symbol / properties / storage_name
      Added value: +{
      +  "description": "The CFB storage the component was read from, as read_pcblib/read_schlib emit it. Pass it back unchanged on a read-modify-write so the component stays where Altium looks for it (Altium re-derives a short name's storage and maps a long one through SectionKeys, so a moved storage is a component it cannot load); omit when authoring or renaming, and the storage name is derived as Altium would: / \\ : ! * become _, then a cut at 31 characters.",
      +  "type": "string"
      +}
  5. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=false) set the safety frame, but the description adds substantial context beyond them: the replacement is wholesale so a primitive left out is removed, a non-existent component_name is an error listing available names, a name already held is refused, dry_run changes nothing and reports would_rename plus a changes list, and a real run backs up the file before saving and returns a post-write validation.

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?

Front-loads the core purpose, then error semantics, dry_run behavior, and alternatives in a logical order. It is dense and delivered as one long block, but nearly every clause carries unique operational information for a tool with two large polymorphic payloads.

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 destructive mutation tool with no output schema, the description covers the necessary ground: what is destroyed (unmentioned primitives), naming/rename rules, error conditions, dry_run vs real run, and the return fields (renamed, old_description, component_count, validation). Nothing essential for correct invocation is missing.

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?

Schema coverage is 100% (baseline 3), but the description adds real semantics the schema cannot: component_name must name a component the library holds in any case, footprint is for .PcbLib and symbol for .SchLib, a name in the object differing from component_name triggers a rename while an object without a name keeps the stored one, and dry_run's reporting behavior.

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+scope: 'Replace one existing component of an Altium library (.PcbLib or .SchLib) with the object given, keeping its position in the library.' It immediately distinguishes itself from the whole-library writers (write_pcblib/write_schlib) and from single-primitive tools (update_pad, update_primitive).

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

Usage Guidelines5/5

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

Explicitly names alternatives and the conditions selecting them: write_pcblib/write_schlib to rewrite a whole library, batch_update for one change across every component, update_pad/update_primitive to change one primitive in place, rename_component for a rename alone. It also says to start from get_component's output when editing, giving a concrete workflow.

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