Skip to main content
Glama

search_distributors

Search enabled distributors and JLCPCB for orderable MPNs, returning stock, lifecycle, price, and datasheet links so you can select and verify BOM parts.

Instructions

The orderable parts at the enabled distributors, from their official APIs, and in the JLCPCB parts library when it is on the machine (with the C number and the library class): the part number of the source (adopt_part takes it), lifecycle state, stock, prices and datasheet URL (Mouser gives no package: read it in the datasheet). An MPN of more manufacturers gives one line for each manufacturer. A part that is obsolete or discontinued is marked NOT ORDERABLE. Use it to select the concrete MPN of the BOM, and to check that it can be ordered. Each result names its source (the terms of the distributors ask for it). The enabled distributors come from the project file or the global configuration (distributor_status). Each needs a personal API key: for a distributor with no key, the result has a note with the steps for the user. Give the note to the user. With no key at all, the result gives the search links of part_links.

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": "search_distributors"
  }
}

Input Schema

NameRequiredDescriptionDefault
mpnYesThe MPN: a concrete orderable MPN, or the start of the MPNs (a base part, for example MCP1827S).
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.
exactNoTrue: only this MPN. False: each MPN that starts with it (the concrete MPNs of a base part, up to 50).

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/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: it discloses the per-distributor personal API key requirement, the degraded result when a key is missing (a note with steps the user must be given), the total-failure path (search links from part_links), the NOT ORDERABLE marking for obsolete/discontinued parts, the mandatory source attribution, and a data-quality caveat (Mouser omits package).

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

Conciseness3/5

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

The front-loaded core (what is returned) is good, but the body sprawls across run-on sentences with erratic line breaks and parenthetical asides, mixing result fields, auth mechanics, and fallbacks without structural grouping. Dense content largely earns its place, but the packaging makes it harder to scan than it should be.

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 multi-source search tool with three simple params and an output schema, the description covers result fields, failure/degradation modes, and marking rules. Remaining gaps—pagination/limits beyond the exact expansion and error behavior for a partially enabled distributor set—are minor.

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 coverage is 100%, so the schema already documents mpn, path, and exact, including the 50-item prefix-expansion behavior. The description adds only that the returned part number is what adopt_part accepts, which is useful linkage but not parameter semantics per se.

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 and resource—searching enabled distributors' official APIs plus the JLCPCB library—and enumerates exactly what each result contains (source part number, lifecycle, stock, prices, datasheet URL, library class). It is clearly distinguished from siblings like adopt_part (which consumes the returned part number) and part_links (the no-key fallback).

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?

Explicitly says to use it to select the concrete MPN of the BOM and to verify orderability, and it routes the agent to a specific alternative (part_links) when no distributor key exists. It stops short of stating when not to use it, e.g. relative to find_parts or jlcpcb_library, which are never named.

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