Zotero MCP

Zotero Batch Update

zotero_batch_update

Batch-edit Zotero item metadata in one call: add or remove tags and upsert or remove Key: value Extra lines, selected by item keys, search query, or tag.

Instructions

Edit metadata across many items in one call: add/remove tags and upsert/remove Key: value lines in Extra (Better BibTeX keys, tex.* fields). Select items by item_keys, and/or a free-text query, and/or an existing tag (query and tag are ANDed; tag may be a list to OR); item_keys wins. At least one selector AND one action are required. add_tags/remove_tags keep the item's other tags — not a replace-all. set_keys upserts Extra lines, matching a line case-insensitively by its key: prefix and replacing it in place, else appending; remove_keys deletes those lines; lines without a colon are preserved. limit: max items for query/tag selection (default 50, at most 1000); the report says when more matched. A query-only selection leaves attachments out; Extra edits skip attachments, notes and annotations. Items needing no change are skipped and counted. Requires a writable library. Example: zotero_batch_update(tag='to-read', add_tags=['reviewed'], remove_tags=['to-read']).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "zotero_batch_update"
  }
}

Input Schema

Name	Required	Description	Default
`tag`	No
`limit`	No
`query`	No
`add_tags`	No
`set_keys`	No
`item_keys`	No
`remove_keys`	No
`remove_tags`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.7/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 well: it states add_tags/remove_tags are not replace-all, set_keys upserts by case-insensitive `key:` prefix (replace in place, else append), lines without a colon are preserved, Extra edits skip attachments/notes/annotations, no-op items are skipped and counted, and a writable library is required.

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?

Front-loaded with purpose and actions, then selectors, then per-action semantics, then limit and edge cases, ending with an example. It is dense single-paragraph prose with many clauses, but nearly every clause carries operational information.

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?

An output schema exists, so return-shape explanation is unnecessary; the mutation caveats, selector precedence, truncation reporting, and skipped-item counting fill the gaps an agent would otherwise have to guess at. Complete for an eight-parameter batch mutation tool with no annotations.

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 covers every parameter: tag (string or ORed list), limit (default 50, cap 1000, with truncation reported), query, item_keys precedence, and the set/remove semantics for tags and keys. This adds meaning the raw schema cannot convey.

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?

Opens with a specific verb+resource+scope: 'Edit metadata across many items in one call', then enumerates the two action families (tags, Extra lines). The 'batch' framing plus explicit mention of tags/Extra distinguishes it from the single-item zotero_update_item sibling.

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?

Strong operational guidance: at least one selector AND one action required, item_keys takes precedence, query and tag are ANDed while a tag list is ORed, and a concrete example is given. It does not explicitly say when to prefer zotero_update_item or zotero_search_by_tag instead, so the sibling routing is implied rather than stated.

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

Deploy Server