Zotero MCP

Zotero Add Item

zotero_add_item

Add research sources to Zotero from DOI, URL, ISBN, BibTeX, CSL JSON, or files, with collection placement and duplicate handling.

Instructions

Add item(s) to Zotero from any source: DOI, URL, ISBN, BibTeX, CSL JSON, or a local file. Use for every 'add this to Zotero' request. source: the identifier, URL, citation text, or ABSOLUTE file path. DOI/URL/ISBN/PMID also take many at once (list or comma/newline-separated). BibTeX/CSL JSON may be inline (many entries per call) or a path to .bib/.bibtex/.json/.csljson; documents are .pdf, .epub, .docx and similar. source_type: 'auto' (default) detects it, incl. comma/newline DOI lists; override for URL/ISBN batches. Routing: doi → CrossRef (best metadata — prefer a DOI when you have one); url → doi.org/arxiv.org get full metadata, anything else becomes a bare 'webpage' item that is often not citable, so resolve to a DOI first; isbn → Open Library then Google Books (noisy — verify after); bibtex/csl_json → one item per entry, citation key kept in Extra; file → extracts the PDF's DOI and enriches via CrossRef, else guesses from filename/text, then attaches the file. collections: keys, names, or '/'-paths ('_project/topic'), validated before anything is created — an unknown or ambiguous spec fails the call rather than leaving an unfiled item; create_missing_collections=True creates them instead. if_exists: 'duplicate' (default) always creates; 'file' is idempotent — reuses the item matching the DOI/ISBN/URL, adding missing collections/tags, never removing; 'skip' leaves a match untouched. attach_mode: 'auto' (default) attaches an OA PDF, 'linked_url' bookmarks it, 'none' skips, 'required' fails without one. title: file sources only, when extraction misses. Requires a writable library (fails in local-only mode). Run zotero_update_search_database afterwards for semantic search. Example: zotero_add_item(source='10.1145/3708319', collections=['9SU943GB'], if_exists='file').

Input Schema

Name	Required	Default
`tags`	No
`title`	No
`source`	Yes
`if_exists`	No	duplicate
`attach_mode`	No	auto
`collections`	No
`source_type`	No	auto
`create_missing_collections`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 28, 2026

TDQS

A5/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 delivers: collections specs are validated before creation and fail the call on ambiguity, if_exists semantics are spelled out per mode, attach_mode enumerates behavior including failure on 'required', and it notes a writable library is required (fails in local-only mode). This is unusually complete behavioral disclosure.

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

Conciseness5/5

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

Long but densely packed and front-loaded: purpose and source formats first, then per-source routing, then parameter behavior, then a concrete example. No filler sentences; each clause adds actionable detail.

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 an 8-parameter mutation tool with an output schema (so return values needn't be described), the description covers prerequisites, source handling, collection validation, and duplicate/attachment behavior. Nothing an agent needs to invoke it correctly is missing.

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 0%, so the description must compensate, and it does for essentially every parameter: source formats and batch syntax, source_type auto-detection and overrides, collections key/name/path forms with validation, create_missing_collections, if_exists mode semantics, attach_mode options, and title's file-only limitation. Only 'tags' is left implicit, which is a minor gap.

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 (add) and resource (Zotero item) with the full scope of accepted sources: DOI, URL, ISBN, BibTeX, CSL JSON, and local files. An agent can distinguish this from update_item or attach_file without opening any 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?

Explicitly says 'use for every add this to Zotero request' and provides routing logic for each source type, including the caveat that a bare URL becomes a non-citable webpage and should be resolved to a DOI first. Also points to the follow-up sibling zotero_update_search_database.

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

Deploy Server