Skip to main content
Glama

set_symbol_fields

Writes confirmed symbol fields such as Value, MPN, and confirmation flags into KiCad schematic references, validating all changes and files before saving all or nothing.

Instructions

Write the fields of placed symbols, as KiCad writes them.

The tool writes each field into each unit of the reference (one package has one Value and one MPN). A field that the symbol does not have becomes a new field, hidden as KiCad 9 and 10 make it (a file of KiCad 8: visible; Value_Confirmed and MPN_Confirmed: always hidden). With a variant (KiCad 10), the tool writes the fields of that variant into each unit: a value equal to the field of the symbol removes the field from the variant. The tool checks all changes and all files first, and writes no file when a check fails. It writes all files or no file: an error of the disk also changes no file. KiCad must not have the files open. A schematic file of the project with an older version than the installed KiCad writes is an error: the user converts it in KiCad first (the output gives the step).

A symbol in a sheet that the hierarchy uses more than one time has one set of fields for all its references (U201 and U301): give the same fields for each of these references, or write different fields through a variant.

Use it for the fields that project_check of datasheet-lens or check_symbol_fields gives (MPN_Confirmed and Value_Confirmed for a confirmation; Value, MPN, MPN_Confirmed and Value_Confirmed for the move of the old convention), after the user confirmed them.

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": {
      "schematic_path": "<schematic_path>",
      "changes": "<changes>"
    },
    "name": "set_symbol_fields"
  }
}

Input Schema

NameRequiredDescriptionDefault
changesYesOne item for each reference (and variant): the reference, the fields by name, and the variant name (empty: the symbol).
schematic_pathYesA .kicad_sch file of the project. The tool finds the references in the full project.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/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 thoroughly: it discloses transactional semantics (all files or no file, disk errors change nothing), a validation-then-write sequence, the requirement that the files be closed in KiCad, and the error case for schematics older than the installed KiCad along with the remedy. It also explains hidden-field creation rules per KiCad version and variant-level removal when a value equals the symbol's field.

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 core action is front-loaded and the follow-on paragraphs are organized by concern (field creation, variants, atomicity, file state, hierarchy, invocation context). It is dense and somewhat long for a two-parameter tool, and the hidden-field rule overlaps with schema text, but no sentence is filler.

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 mutation tool with no annotations, the description covers everything an agent needs before calling: atomicity, prechecks, external process interference, version-mismatch errors, hierarchy edge cases, and variant semantics. Return values are covered by the output schema, so nothing critical is left implicit.

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%, so the baseline is 3, but the description adds meaning the schema does not: the multi-instance hierarchy constraint that a reused sheet symbol shares one field set across references such as U201 and U301, so the caller must supply identical fields for each reference or diverge via a variant. That is a real usage constraint on the 'changes' array beyond the per-field documentation.

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 first sentence states a specific verb and resource ('Write the fields of placed symbols'), and the closing paragraph routes the agent away from the read-side siblings by naming check_symbol_fields and project_check as the producers of the data this tool consumes. An agent can tell this is the write counterpart to the check tools without opening the schema.

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 when-to-use rule: apply it to the fields reported by project_check or check_symbol_fields (MPN_Confirmed/Value_Confirmed for confirmations, Value/MPN/MPN_Confirmed/Value_Confirmed for the old-convention move) and only 'after the user confirmed them'. Preconditions are spelled out (KiCad must not have the files open; older-version schematics must be converted first), though there is no explicit statement of what the tool should not be used for.

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