Skip to main content
Glama

add_document

Add a PDF datasheet to the store when list_documents cannot find it: copy or download the file, build its index and element map, and link it to the matching part.

Instructions

Add a PDF document to the store: copy or download it, build its index and its element map, and link it to its part. Use it when list_documents does not find the datasheet; the URL can come from a distributor tool or from the Datasheet field of a CAD symbol. The element map of a large document can take minutes: a background thread builds it, and the index and the page images are available at once. Gives the document reference, the pages, the size of the index and the state of the element map. Without part, it also gives a rough proposal of the MPN from the text of the PDF; it can be wrong. Read the MPN on page 1 of the original, then call add_document again with part. No tool removes a link of a document to a part in the store: give part only when the MPN is sure. The result gives the title of the document: the title of the PDF metadata can be wrong (a file name, a different document). No tool changes a title later: give title when you know it. The manufacturer of a datasheet comes from the datasheet: when the tool cannot read it, or the given name differs, the result asks (ASK THE USER) and links no part. To put the part into the user project: project_add_part.

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": {
      "path": "<path>"
    },
    "name": "add_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
partNoThe MPN that the datasheet describes: the base part, for example TLV755P (or one variant of a family). Empty: the result proposes an MPN from the PDF.
pathYesA local PDF file, or an http or https URL of a PDF.
roleNoThe role of the document: datasheet, manual, errata, appnote, package (a package drawing in its own document) or other.datasheet
titleNoThe title of the document, for example "TLV755P 500-mA Low-Dropout Regulator". Empty: the title of the PDF metadata. A document that the store has already keeps its title; a document of the store with no title gets this title.
variantsNoThe other parts that the same datasheet covers, for example ["ADC34J22", "ADC34J23"] for ADC34J24. Only with part.
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.
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. Changed2 schema fields changedv0.6.0
    • 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
    • changedInput schema / properties / role / description
      Previous value: -"The role of the document: datasheet, manual, errata, appnote or other."New value: +"The role of the document: datasheet, manual, errata, appnote, package (a package drawing in its own document) or other."
    • addedInput schema / properties / title
      Added value: +{
      +  "default": "",
      +  "description": "The title of the document, for example \"TLV755P 500-mA Low-Dropout Regulator\". Empty: the title of the PDF metadata. A document that the store has already keeps its title; a document of the store with no title gets this title.",
      +  "title": "Title",
      +  "type": "string"
      +}
  3. Changed1 schema field 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."
  4. First observedv0.1.0

TDQS

A4.8/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 that the element map is built by a background thread and can take minutes while index and page images are immediately available, that the proposed MPN and the PDF metadata title can both be wrong, and that manufacturer mismatch triggers an ASK THE USER path with no part linked. It also flags irreversibility — no tool removes a link or changes a title later.

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 purpose and alternative in the first two sentences, and nearly every sentence adds an operational fact. It is still a dense block of run-on sentences with a slightly repetitive 'No tool removes… / No tool changes…' cadence, which costs some scannability.

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 seven-parameter, side-effecting ingest tool with an output schema, this covers the full lifecycle: acquisition, indexing latency, the returned reference/pages/index size/element-map state, the MPN and title fallback hazards, the manufacturer confirmation exception, and the handoff to project_add_part. Nothing an agent needs in order to call it safely 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 100%, so the baseline is 3, but the description adds decision-level meaning beyond the schema: part is a commitment with no undo, so the workflow is 'read the MPN on page 1 of the original, then call add_document again with part', and variants only apply with part. These constraints shape how the parameters are sequenced and withheld, not just what they contain.

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 opening sentence names a specific verb and resource plus the concrete sub-steps it performs: 'Add a PDF document to the store: copy or download it, build its index and its element map, and link it to its part.' That is enough for an agent to distinguish it from list_documents and project_add_part without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger ('Use it when list_documents does not find the datasheet') with two named sources of the URL, and it names the downstream alternative 'project_add_part'. It also states exclusions: give part only when the MPN is sure, give title only when known, and give manufacturer_confirmed only when the user confirms it.

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