Skip to main content
Glama

Zotero Add Item

zotero_add_item

Add a DOI, URL, ISBN, PMID, BibTeX, CSL JSON, or local file to Zotero, with collection, tag, duplicate-handling, and PDF attachment options.

Instructions

Add items from a DOI, URL, ISBN, PMID, BibTeX, CSL JSON or a local file; use it for every 'add this to Zotero' request. source: the identifier, URL, citation text or ABSOLUTE file path. DOI/URL/ISBN/PMID also take a comma- or newline-separated batch; BibTeX and CSL JSON may be inline (many entries) or a .bib/.json path. source_type: 'auto' (default) detects it. Prefer a DOI: a URL other than doi.org or arxiv.org becomes a bare webpage item, and ISBN metadata is noisy (verify it). For a file, its DOI is looked up, else metadata is guessed, then the file is attached; title overrides a missed title. collections: keys, names or 'Parent/Child' paths, checked before anything is created (create_missing_collections=True makes missing ones). if_exists: 'file' (default) reuses an item with the same DOI/arXiv ID/ISBN/URL, adding missing collections and tags; 'duplicate' always creates; 'skip' leaves a match alone. attach_mode: 'auto' (default) attaches an open-access PDF, 'linked_url' links it, 'none' skips, 'required' fails without one.

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": {
      "source": "<source>"
    },
    "name": "zotero_add_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNo
titleNo
sourceYes
if_existsNofile
attach_modeNoauto
collectionsNo
source_typeNoauto
create_missing_collectionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/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 load and does it well: it discloses the file-import pipeline (DOI lookup, then metadata guessing, then attachment), the ordering guarantee that collections are checked before anything is created, and the failure mode of attach_mode='required'. What it omits is equally behavioral: no mention of write authorization (a zotero_authorize_local_writes sibling exists), which library receives the item, or what is returned on success.

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?

Purpose is front-loaded and nearly every clause carries load-bearing information (batch syntax, DOI preference, title override). The weakness is presentation: a single dense block of semicolon-chained clauses makes it hard to scan, and the 'tags' parameter is only referenced obliquely inside the if_exists explanation rather than being defined.

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 an 8-parameter write tool with no annotations and no output schema, this is close to complete: it covers input formats, deduplication policy, collection creation, and attachment policy. The remaining gaps are environmental rather than mechanical — no statement of which library is targeted, whether authorization is required first, or what the call returns.

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 description coverage is 0%, so the description must compensate, and it does: it defines the accepted syntax of source (identifier, URL, citation text, ABSOLUTE path), explains that DOI/URL/ISBN/PMID accept comma- or newline-separated batches while BibTeX/CSL JSON may be inline or a .bib/.json path, and spells out the semantics of both enum parameters. Seven of eight parameters gain meaning that the bare schema does not provide.

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 ('Add items ... to Zotero') and enumerates every accepted input kind (DOI, URL, ISBN, PMID, BibTeX, CSL JSON, local file). It also scopes itself ('use it for every "add this to Zotero" request'), which separates it from siblings like zotero_attach_file or zotero_manage_collection without needing to open their schemas.

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?

Gives an explicit routing rule for the whole tool ('use it for every add request') plus preference guidance inside the call: 'Prefer a DOI', with reasons why a bare URL degrades to a webpage item and why ISBN metadata must be verified. It also states the decision rule for each enum parameter (if_exists 'file' vs 'duplicate' vs 'skip'), so the agent knows which option to pick rather than guessing.

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