Skip to main content
Glama

project_check

Compare a CAD project's symbols or BOM against its project file to flag missing datasheets, unconfirmed MPNs, conflicts, and folder mismatches before sync and availability checks.

Instructions

Compare the project file with the parts of the CAD project, so that the two hold the same parts. Each part with an MPN needs its datasheet, also an alternative in MPN. The convention: Value holds the general value ("2N7002", "100nF 10V"), the field MPN the MPNs ("2N7002LT1G, BSS138LT1G"), and the hidden fields Value_Confirmed and MPN_Confirmed the copies of the last confirmation. The confirmation of the user is the truth: until it, the confirmed MPNs are the parts. With bom, one line for each BOM file gives the columns that the tool read. Then the result gives these lines:

  • conflict: the fields or the columns of one symbol do not agree.

  • change in the CAD project: MPN is not MPN_Confirmed, or Value is not Value_Confirmed. Add the datasheet of a new MPN at once; tell the user; write the given fields only when the user confirms it.

  • not confirmed: the fields are not confirmed yet.

  • the old convention: the MPNs are in the parentheses of Value (or only of Value_Confirmed). Write the given fields (the move); the confirmed state and the parts do not change.

  • no field Value_Confirmed or MPN_Confirmed, no part selected (a general value and no MPN).

  • CAD lines with a part, the symbols that are not fitted (DNP: their parts stay parts of the project), the number of the same parts, and one line for each part that is different (one part with two MPNs), missing (with the documents of the store or the Datasheet field, and the next call) or extra.

  • project folder: the folder does not agree with the project file and the store (new references, missing copies, copies to move, files of the inbox to take): run project_sync; project_status gives the files.

  • project folder (a second line): the files that need a step of the user, because project_sync cannot do it (files of the folder or of the inbox with no part, changed copies, documents that the store does not have): tell the user.

  • next steps: when the two hold the same parts and no symbol needs a step of the user: project_sync (when the folder needs it), then project_availability. A JLCPCB (LCSC) finding of a symbol that is not fitted (DNP) is information for the user, not a step. A message of an other variant names it. A message names the fields to write by the columns of the BOM (the BOM must name its columns as the fields of the symbols: export_bom of kicad-workbench does), or by mpn_fields of the parts; when the field is not known, it names the choices and tells you to ask the user. In KiCad, write the fields with set_symbol_fields of the MCP server kicad-workbench. When the store is connected to a team server, it gets the rows of the server first: a datasheet that a different person added is not missing. In a project that uses JLCPCB (a JLCPCB purchase source, or an LCSC field), the lines "LCSC:" compare the JLCPCB number of each symbol (the LCSC column of the BOM, or lcsc of the parts) with the purchase source and with the JLCPCB parts library. The lines "Manufacturer:" and "Distributor:" compare the fields Manufacturer (the manufacturers of the MPNs of the field MPN, in their order) and Distributor (the preferred distributor of the fitted part) with the project: write the given fields, and ask the user where a line tells it. It changes nothing in the project.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "project_check"
  }
}

Input Schema

NameRequiredDescriptionDefault
bomNoThe path of a BOM file (CSV) of the full CAD project, or a list of paths: one BOM file for each variant of the product, the default variant first (the tool takes the parts of all files, and checks the confirmed fields in each file; a message of an other variant names its file). One line for each symbol: for example the CSV file of 'kicad-cli sch export bom' (the MCP server kicad-workbench writes it with export_bom and output_path). A .csv, .tsv or .txt file: an absolute path, or a path relative to the project folder (the folder of datasheet-lens.toml). The tool finds the columns by their names (MPN, Value, Reference, Datasheet, DNP); a line with DNP is not fitted, and its parts stay parts of the project. Give parts or bom, not the two.
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.
partsNoThe parts of the CAD project, from the CAD tool (for example its MCP server). One item for each symbol or BOM line, with its MPN and Value fields as they are; give each part, not only the new ones. A general value with no MPN has no selected part. Give parts or bom, not the two.
bom_quoteNoThe quote character of the BOM file: '"' (CSV, Excel, kicad-cli and export_bom), "'" (the Semicolons preset of KiCad) or 'none' (the TSV preset of KiCad). Empty: '"'.
bom_columnNoThe column of the MPN in the BOM file. Empty: each column with a usual MPN name (MPN, Manufacturer Part Number, MP ...). The tool always reads the Value column too.
bom_delimiterNoThe delimiter of the BOM file: a text or 'tab'. Empty: the one of , ; tab | that splits the header line. Give it when the tool asks for it.
bom_confirmed_columnNoThe column of the field Value_Confirmed in the BOM file, for example an unused custom column of the BOM of an other CAD tool. Empty: Value_Confirmed.
bom_mpn_confirmed_columnNoThe column of the field MPN_Confirmed in the BOM file, for example an unused custom column of the BOM of an other CAD tool. Empty: MPN_Confirmed.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.6.0
    • addedInput schema / $defs / CadPart / properties / distributor
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The field Distributor of the symbol, as it is: the preferred distributor of the fitted part, or N/A. Null when the symbol has no such field.",
      +  "title": "Distributor"
      +}
    • addedInput schema / $defs / CadPart / properties / distributor_field
      Added value: +{
      +  "default": "",
      +  "description": "The name of the field Distributor in the CAD tool, when it has an other name (Supplier). Empty: Distributor.",
      +  "title": "Distributor Field",
      +  "type": "string"
      +}
    • addedInput schema / $defs / CadPart / properties / manufacturer
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The field Manufacturer of the symbol, as it is: the manufacturers of the MPNs of the field MPN, in their order. Null when the symbol has no such field.",
      +  "title": "Manufacturer"
      +}
    • addedInput schema / $defs / CadPart / properties / manufacturer_field
      Added value: +{
      +  "default": "",
      +  "description": "The name of the field Manufacturer in the CAD tool, when it has an other name (MFR). Empty: Manufacturer.",
      +  "title": "Manufacturer Field",
      +  "type": "string"
      +}
    • changedInput schema / $defs / CadPart / properties / mpn / description
      Previous value: -"The field MPN of the symbol, as it is: the confirmed copy of the MPNs in the parentheses of Value (\"2N7002LT1G, BSS138LT1G\"). Empty if there is none; '-' or N/A when the symbol needs no part (a test point)."New value: +"The field MPN of the symbol, as it is: the MPNs of the part, the fitted part first and then the alternatives (\"2N7002LT1G, BSS138LT1G\"; separators , and ;; an MPN with , or ; is in quotes, as in CSV: '\"BC847B,215\", BSS138LT1G'). Empty if there is none; '-' or N/A when the symbol needs no part (a test point)."
    • addedInput schema / $defs / CadPart / properties / mpn_confirmed
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The hidden field MPN_Confirmed of the symbol, as it is: a copy of the field MPN of the last confirmation. Null when the symbol has no such field.",
      +  "title": "Mpn Confirmed"
      +}
    • addedInput schema / $defs / CadPart / properties / mpn_confirmed_field
      Added value: +{
      +  "default": "",
      +  "description": "The name of the field MPN_Confirmed in the CAD tool, when it has an other name. Empty: MPN_Confirmed.",
      +  "title": "Mpn Confirmed Field",
      +  "type": "string"
      +}
    • changedInput schema / $defs / CadPart / properties / value / description
      Previous value: -"The Value field of the symbol, as it is: a general value, and the MPNs in parentheses, the fitted part first and then the alternatives (\"2N7002 (2N7002LT1G, BSS138LT1G)\", \"100nF 10V (GRM155R71A104KA01D)\"; separators , and ;). Only the text in parentheses gives MPNs. An MPN with , ; or a parenthesis is in quotes, as in CSV: '2N7002 (\"BC847B,215\", BSS138LT1G)'."New value: +"The Value field of the symbol, as it is: the general value (\"2N7002\", \"100nF 10V\"). Old projects have the MPNs in parentheses in Value: the tool proposes to move them into MPN."
    • addedInput schema / properties / bom_mpn_confirmed_column
      Added value: +{
      +  "default": "",
      +  "description": "The column of the field MPN_Confirmed in the BOM file, for example an unused custom column of the BOM of an other CAD tool. Empty: MPN_Confirmed.",
      +  "title": "Bom Mpn Confirmed Column",
      +  "type": "string"
      +}
  2. Changed4 schema fields changedv0.5.0
    • addedInput schema / $defs / CadPart / properties / dnp
      Added value: +{
      +  "default": false,
      +  "description": "True when the symbol is not fitted (DNP). Its parts stay parts of the CAD project, with their datasheets.",
      +  "title": "Dnp",
      +  "type": "boolean"
      +}
    • addedInput schema / $defs / CadPart / properties / lcsc
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The JLCPCB (LCSC) part number field of the symbol (C47616), as it is. Null when the symbol has no such field. Give it for the JLCPCB assembly.",
      +  "title": "Lcsc"
      +}
    • addedInput schema / $defs / CadPart / properties / lcsc_field
      Added value: +{
      +  "default": "",
      +  "description": "The name of the field of the JLCPCB (LCSC) number in the CAD tool, for example 'LCSC Part #'. Empty: LCSC.",
      +  "title": "Lcsc Field",
      +  "type": "string"
      +}
    • changedInput schema / properties / bom / description
      Previous value: -"The path of a BOM file (CSV) of the full CAD project, or a list of paths: one BOM file for each variant of the product, the default variant first (the tool takes the parts of all files, and checks the confirmed fields in each file; a message of an other variant names its file). One line for each symbol: for example the CSV file of 'kicad-cli sch export bom' (the MCP server kicad-workbench writes it with export_bom and output_path). A .csv, .tsv or .txt file: an absolute path, or a path relative to the project folder (the folder of datasheet-lens.toml). The tool finds the columns by their names (MPN, Value, Reference, Datasheet, DNP); a line with DNP is not fitted. Give parts or bom, not the two."New value: +"The path of a BOM file (CSV) of the full CAD project, or a list of paths: one BOM file for each variant of the product, the default variant first (the tool takes the parts of all files, and checks the confirmed fields in each file; a message of an other variant names its file). One line for each symbol: for example the CSV file of 'kicad-cli sch export bom' (the MCP server kicad-workbench writes it with export_bom and output_path). A .csv, .tsv or .txt file: an absolute path, or a path relative to the project folder (the folder of datasheet-lens.toml). The tool finds the columns by their names (MPN, Value, Reference, Datasheet, DNP); a line with DNP is not fitted, and its parts stay parts of the project. Give parts or bom, not the two."
  3. Changed17 schema fields changedv0.3.0
    • addedInput schema / $defs / CadPart / properties / confirmed_field
      Added value: +{
      +  "default": "",
      +  "description": "The name of the field Value_Confirmed in the CAD tool, when it has an other name. Empty: Value_Confirmed.",
      +  "title": "Confirmed Field",
      +  "type": "string"
      +}
    • changedInput schema / $defs / CadPart / properties / mpn / description
      Previous value: -"The MPN field of the symbol, as it is (empty if there is none)."New value: +"The field MPN of the symbol, as it is: the confirmed copy of the MPNs in the parentheses of Value (\"2N7002LT1G, BSS138LT1G\"). Empty if there is none; '-' or N/A when the symbol needs no part (a test point)."
    • addedInput schema / $defs / CadPart / properties / mpn_fields
      Added value: +{
      +  "description": "The names of the fields of the symbol that hold its MPN in the CAD tool, for example ['Manufacturer Part Number']. The messages name them as the fields to write. Empty: MPN.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "title": "Mpn Fields",
      +  "type": "array"
      +}
    • changedInput schema / $defs / CadPart / properties / value / description
      Previous value: -"The Value field of the symbol, as it is: it can hold a value (100nF), an MPN, a value and an MPN (\"390uF (EEU-FS1H391L)\") or alternatives (\"AP2205-33YR-13 / AP7370-33Y-13\"). The tool finds the MPNs in it."New value: +"The Value field of the symbol, as it is: a general value, and the MPNs in parentheses, the fitted part first and then the alternatives (\"2N7002 (2N7002LT1G, BSS138LT1G)\", \"100nF 10V (GRM155R71A104KA01D)\"; separators , and ;). Only the text in parentheses gives MPNs. An MPN with , ; or a parenthesis is in quotes, as in CSV: '2N7002 (\"BC847B,215\", BSS138LT1G)'."
    • addedInput schema / $defs / CadPart / properties / value_confirmed
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The hidden field Value_Confirmed of the symbol, as it is: a copy of the Value of the last confirmation. Null when the symbol has no such field.",
      +  "title": "Value Confirmed"
      +}
    • addedInput schema / $defs / CadPart / properties / variant
      Added value: +{
      +  "default": "",
      +  "description": "The name of an other variant of the product (KiCad 10) when the fields are the fields of this variant. Empty for the default variant: give it first.",
      +  "title": "Variant",
      +  "type": "string"
      +}
    • addedInput schema / properties / bom
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    }
      +  ],
      +  "default": "",
      +  "description": "The path of a BOM file (CSV) of the full CAD project, or a list of paths: one BOM file for each variant of the product, the default variant first (the tool takes the parts of all files, and checks the confirmed fields in each file; a message of an other variant names its file). One line for each symbol: for example the CSV file of 'kicad-cli sch export bom' (the MCP server kicad-workbench writes it with export_bom and output_path). A .csv, .tsv or .txt file: an absolute path, or a path relative to the project folder (the folder of datasheet-lens.toml). The tool finds the columns by their names (MPN, Value, Reference, Datasheet, DNP); a line with DNP is not fitted. Give parts or bom, not the two.",
      +  "title": "Bom"
      +}
    • addedInput schema / properties / bom_column
      Added value: +{
      +  "default": "",
      +  "description": "The column of the MPN in the BOM file. Empty: each column with a usual MPN name (MPN, Manufacturer Part Number, MP ...). The tool always reads the Value column too.",
      +  "title": "Bom Column",
      +  "type": "string"
      +}
    • addedInput schema / properties / bom_confirmed_column
      Added value: +{
      +  "default": "",
      +  "description": "The column of the field Value_Confirmed in the BOM file, for example an unused custom column of the BOM of an other CAD tool. Empty: Value_Confirmed.",
      +  "title": "Bom Confirmed Column",
      +  "type": "string"
      +}
    • addedInput schema / properties / bom_delimiter
      Added value: +{
      +  "default": "",
      +  "description": "The delimiter of the BOM file: a text or 'tab'. Empty: the one of , ; tab | that splits the header line. Give it when the tool asks for it.",
      +  "title": "Bom Delimiter",
      +  "type": "string"
      +}
    • addedInput schema / properties / bom_quote
      Added value: +{
      +  "default": "",
      +  "description": "The quote character of the BOM file: '\"' (CSV, Excel, kicad-cli and export_bom), \"'\" (the Semicolons preset of KiCad) or 'none' (the TSV preset of KiCad). Empty: '\"'.",
      +  "title": "Bom Quote",
      +  "type": "string"
      +}
    • addedInput schema / properties / parts / anyOf
      Added value: +[
      +  {
      +    "items": {
      +      "$ref": "#/$defs/CadPart"
      +    },
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / parts / default
      Added value: +null
    • changedInput schema / properties / parts / description
      Previous value: -"The parts of the CAD project, from the CAD tool (for example its MCP server or its BOM export). One item for each symbol or BOM line, with its MPN and Value fields as they are; give each part, not only the new ones. A part with no MPN in the two fields needs no datasheet."New value: +"The parts of the CAD project, from the CAD tool (for example its MCP server). One item for each symbol or BOM line, with its MPN and Value fields as they are; give each part, not only the new ones. A general value with no MPN has no selected part. Give parts or bom, not the two."
    • removedInput schema / properties / parts / items
      Removed value: -{
      -  "$ref": "#/$defs/CadPart"
      -}
    • removedInput schema / properties / parts / type
      Removed value: -"array"
    • removedInput schema / required
      Removed value: -[
      -  "parts"
      -]
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and mostly meets it: it declares 'It changes nothing in the project', so the agent knows writes go through set_symbol_fields rather than this call. It also discloses that a team-server store fetches rows first (so a colleague's datasheet is not reported missing) and that messages may name fields via BOM columns or mpn_fields, prompting a user question when unknown. Prerequisites are only implicit (the project file 'is in it or in a parent folder' is stated in the schema, not the description).

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 text is a ~500-word run-on paragraph with heavy fragments and near-missing articles, so several result-line bullets ('- the old convention: ...', '- CAD lines with a part, ...') take real effort to parse. The critical constraints — read-only, parts/bom exclusivity, the sync-then-availability sequence — are scattered rather than front-loaded. Content mostly earns its place, but the packaging does not.

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 a complex multi-mode checker with 8 parameters, an output schema and a large part model, the description covers the hard cases: variants and their files, DNP handling, LCSC/Manufacturer/Distributor comparison lines, and what to do when the store lacks a document. Some residual ambiguity remains in the message taxonomy, but nothing essential for calling it correctly is absent.

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 coverage is 100%, so the baseline is 3, and the description goes further by explaining the field convention that the inputs encode: Value holds the general value, MPN holds fitted-plus-alternative MPNs, and Value_Confirmed/MPN_Confirmed are copies from the last confirmation, with the old-convention parenthetical MPNs called out. It also resolves the ambiguity between the two data sources: 'Give parts or bom, not the two.' This is meaning the schema alone does not convey.

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 gives a specific verb and resource: 'Compare the project file with the parts of the CAD project, so that the two hold the same parts.' The final sentence, 'It changes nothing in the project', pins it as a check rather than a mutation, and the text repeatedly routes to siblings (project_sync, project_status, project_availability, set_symbol_fields). What keeps it from a 5 is that the read-only nature — the single most distinguishing fact versus project_sync — is buried at the very end of a long paragraph.

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 definition supplies an explicit follow-on sequence: run project_sync when the folder disagrees, then project_availability once parts match and no user step remains, and it names project_status as the source of the file list. It also states the JLCPCB DNP finding is 'information for the user, not a step', which is a genuine exclusion rule. It lacks a crisp upfront 'use this before/after X' statement, so the routing must be reconstructed from the enumerated result lines.

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