Skip to main content
Glama
Copper

Copper

Search parts

parts_search
Read-onlyIdempotent

Search electronic parts by value spec, MPN, or category across configured providers. Returns ranked results with package, stock, price, and match quality for schematic import.

Instructions

Find parts. The project's parts providers are asked in order and the first with results answers (provider in the result says which; 'local' = the user's own catalogue file, 'kicad' = generic library parts). Results are ranked by spec match, then by the provider's part class (parts without a setup fee first), stock and price. query: a value spec ('10k 0603', '100nF 16V 0402 X7R', 'LED red 0603', '12MHz crystal', 'LDO 3.3V SOT-223'), an MPN ('AMS1117-3.3') or a category phrase ('USB-C 16P', 'Header 1x4 2.54mm'). Each result: provider, id (the provider's part number), mpn, package, stock, price, match ('partial' = not every term confirmed) and next = the exact sch_apply op. Passives by spec and known part numbers need no search: sch_apply place resolves and imports them itself. Example: parts_search(query='USB-C 16P', limit=5)

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": {
      "query": "<query>"
    },
    "name": "parts_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
liveNoquery live supplier data (default true); false = offline data only
limitNomax results (default 8)
queryYesvalue spec, MPN, or a description of the part
packageNooptional package filter, e.g. '0603', 'SOT-23', 'SOIC-8'
categoryNooptional kind/category filter: resistor, capacitor, led, diode, mosfet, ldo, crystal, usb_connector, header, mcu, module, … or catalogue wording ('sensor', 'gas sensors', 'wifi module')
in_stockNoonly parts in stock (default: the config policy, true)
providerNoparts provider to ask (default: the project's parts.providers, in order): lcsc | local | kicad | a third-party name
min_stockNo
basic_onlyNoonly the provider's cheapest assembly class (JLC Basic)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, open-world, so the description's job is added behavior and it delivers: the ordered provider fallback, the ranking rule (spec match, then part class so fee-free parts come first, then stock and price), and the meaning of match='partial'. This is exactly the non-obvious behavior an agent cannot get from the annotations.

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?

It is front-loaded with the resolution model, then the query semantics, then the result shape, then the exclusion — a sensible order with no filler. It is on the long side and the example line could arguably be trimmed, but every block carries information an agent uses.

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?

With nine parameters and no output schema, the description compensates by enumerating every returned field (provider, id, mpn, package, stock, price, match, next) and explaining the 'next' hook into sch_apply. Nothing an agent needs in order to call this correctly or interpret the response 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 89%, so the baseline is 3; the description earns above that by explaining `query` with concrete value-spec, MPN and category-phrase examples, and by glossing `provider` values ('local' = user's own catalogue file, 'kicad' = generic library). It adds nothing for limit, package, min_stock or basic_only, keeping it at 4 rather than 5.

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 description opens with a specific verb+resource ('Find parts') and immediately explains the resolution strategy (providers asked in order, first with results answers) and which provider values mean what. An agent knows exactly what this tool returns and how it differs from a catalogue lookup, and the closing note distinguishes it from sch_apply's implicit resolution.

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 an explicit exclusion — 'Passives by spec and known part numbers need no search: sch_apply place resolves and imports them itself' — which is exactly the when-not-to-use guidance an agent needs. It also explains the default provider ordering. It stops short of explaining when to prefer explicit provider/package/category filters over the defaults, so a 4 rather than 5.

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