Skip to main content
Glama

project_update_part

Change a project part's MPN, base part, category, manufacturer, distributor, or pinned document in place, then write the confirmed change to the CAD BOM and check the project.

Instructions

Change a part of the user project in place: its MPN, base part, category, manufacturer, preferred distributor, or a pinned document. A new manufacturer must agree with the datasheet of the part (as project_add_part). A file of the folder with the content of a document is a copy of sync when it is in the subfolder of the layout of its part, else it is pinned: project_sync tells it for each new reference, and pin_document or unpin_document changes it. The part keeps its place in datasheet-lens.toml and its copies (project_remove_part and project_add_part would delete and copy them again). Then project_sync moves a copy when the layout gives it a different subfolder. The CAD BOM is the master: write the change that the user confirmed into the CAD project too (MPN, MPN_Confirmed, Value_Confirmed, LCSC, Manufacturer, Distributor; kicad-workbench: set_symbol_fields), then project_check. Gives each changed field with its old and new value, then the part and its documents.

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": {
      "mpn": "<mpn>"
    },
    "name": "project_update_part"
  }
}

Input Schema

NameRequiredDescriptionDefault
mpnYesThe MPN of the project part now.
baseNoThe base part of the datasheet, for example TMP112D. Empty: no change.
pathNoA folder of the user project (default: the working folder of the server). The project file datasheet-lens.toml is in it or in a parent folder.
new_mpnNoThe new MPN, for example the concrete orderable MPN TMP112D0IDPWR in place of TMP112D0. Empty: no change.
categoryNoThe function of the part. None: no change; an empty text removes it.
distributorNoThe preferred distributor of the part that the user selected or gave (DigiKey, Mouser, LCSC, an other name), or N/A for none. The field Distributor of the CAD project gets it. Empty: no change.
manufacturerNoThe manufacturer, any of its names (TI or Texas Instruments: the store knows the names of one manufacturer). Necessary only when two parts have the same MPN. With a datasheet, the tool reads the manufacturer from it: a given name must be a name of the same manufacturer.
pin_documentNoA document of the part (its reference, a SHA-256 prefix, its document ID or its file name) to pin: project_sync does not move its file, and project_remove_part keeps it. Empty: no change.
unpin_documentNoA document of the part to unpin: project_sync manages its file as a copy (it moves it to the subfolder of the layout, and a removal deletes it). Empty: no change.
new_manufacturerNoThe new manufacturer, any name of the manufacturer of the part in the store (TI or Texas Instruments). The project file and its layout use this name. Empty: no change.
manufacturer_confirmedNoTrue when the user read page 1 of the datasheet and confirms the given manufacturer, for example the maker of a module whose datasheet names the maker of its chip more often: the tool does not compare it with the text of the PDF. Give it only when the user confirms it.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.6.0
    • addedInput schema / properties / distributor
      Added value: +{
      +  "default": "",
      +  "description": "The preferred distributor of the part that the user selected or gave (DigiKey, Mouser, LCSC, an other name), or N/A for none. The field Distributor of the CAD project gets it. Empty: no change.",
      +  "title": "Distributor",
      +  "type": "string"
      +}
    • changedInput schema / properties / manufacturer / description
      Previous value: -"The manufacturer, any of its names (TI or Texas Instruments: the store knows the names of one manufacturer). Necessary only when two parts have the same MPN."New value: +"The manufacturer, any of its names (TI or Texas Instruments: the store knows the names of one manufacturer). Necessary only when two parts have the same MPN. With a datasheet, the tool reads the manufacturer from it: a given name must be a name of the same manufacturer."
    • addedInput schema / properties / manufacturer_confirmed
      Added value: +{
      +  "default": false,
      +  "description": "True when the user read page 1 of the datasheet and confirms the given manufacturer, for example the maker of a module whose datasheet names the maker of its chip more often: the tool does not compare it with the text of the PDF. Give it only when the user confirms it.",
      +  "title": "Manufacturer Confirmed",
      +  "type": "boolean"
      +}
  2. Changed2 schema fields changedv0.5.0
    • addedInput schema / properties / pin_document
      Added value: +{
      +  "default": "",
      +  "description": "A document of the part (its reference, a SHA-256 prefix, its document ID or its file name) to pin: project_sync does not move its file, and project_remove_part keeps it. Empty: no change.",
      +  "title": "Pin Document",
      +  "type": "string"
      +}
    • addedInput schema / properties / unpin_document
      Added value: +{
      +  "default": "",
      +  "description": "A document of the part to unpin: project_sync manages its file as a copy (it moves it to the subfolder of the layout, and a removal deletes it). Empty: no change.",
      +  "title": "Unpin Document",
      +  "type": "string"
      +}
  3. Changed2 schema fields changedv0.2.0
    • changedInput schema / properties / manufacturer / description
      Previous value: -"The manufacturer, for example TI. Necessary only when two parts have the same MPN."New value: +"The manufacturer, any of its names (TI or Texas Instruments: the store knows the names of one manufacturer). Necessary only when two parts have the same MPN."
    • changedInput schema / properties / new_manufacturer / description
      Previous value: -"The manufacturer, with the spelling of list_parts. Empty: no change."New value: +"The new manufacturer, any name of the manufacturer of the part in the store (TI or Texas Instruments). The project file and its layout use this name. Empty: no change."
  4. First observedv0.1.0

TDQS

A3.6/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses validation behavior (a new manufacturer must agree with the datasheet), the copy-vs-pinned document distinction and how project_sync moves or preserves files, the CAD BOM being master, and the requirement to mirror the change into the CAD project. It does not cover atomicity, failure modes, or permission requirements, so it falls short of complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is relevant but the prose is heavily run-on, with tangled constructions such as 'A file of the folder with the content of a document is a copy of sync when it is in the subfolder of the layout of its part, else it is pinned.' The core purpose is front-loaded, but sentences are hard to parse and several clauses could be compressed or cut.

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 an 11-parameter mutation tool with no annotations, the description covers the workflow context an agent needs: validation constraint on manufacturer, document pinning semantics, side effects on sibling tools, and the mandatory CAD-project update plus project_check. Since an output schema exists, the return-value mention is redundant rather than a gap; the remaining omission is error/idempotency behavior.

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 description coverage is 100%, so the schema already documents all 11 parameters in detail. The description adds only cross-parameter meaning (the manufacturer name must match the datasheet-derived manufacturer, and new_manufacturer propagates to both the project file and layout). That is useful but modest beyond what the schema supplies, so the baseline of 3 applies.

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 opening sentence states a specific verb and resource ('Change a part of the user project in place') and enumerates the mutable fields (MPN, base part, category, manufacturer, distributor, pinned document). It also distinguishes itself from the delete-and-recreate path ('project_remove_part and project_add_part would delete and copy them again'). The differentiation is real but buried mid-paragraph rather than front-loaded.

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 concrete usage context: use this to change a part while keeping its place in datasheet-lens.toml, and it names the alternative tools that change pin state (pin_document/unpin_document) and the delete/copy pair to avoid. It also prescribes the follow-up workflow (write the confirmed change into the CAD project via kicad-workbench: set_symbol_fields, then project_check). No explicit 'do not use when' exclusions are stated.

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