Zotero MCP

by 54yyyu

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Zotero Update Item

zotero_update_item

Update an existing Zotero item's metadata using its key; only passed fields, tags, collections, or creators change.

Instructions

Update metadata on an existing Zotero item by key. Only what you pass is changed. fields: {name: value} of metadata to set (a JSON object string is accepted). Names may be snake_case (title, date, doi, url, abstract, publication_title, access_date, short_title, book_title, citation_key, item_type, place, extra, volume, issue, pages, publisher, issn, isbn, edition, language) or any raw Zotero API field name. An unknown name fails the call and lists the valid ones; a name that is not valid for this item's type is reported as skipped. item_type migrates the item (overlapping fields kept, type-specific ones dropped). TAG SEMANTICS (easy to get wrong): tags REPLACES the whole tag list; add_tags/remove_tags are incremental and preferred. They are mutually exclusive with tags. collections (keys) and collection_names likewise REPLACE membership — pass collections=[] to clear it; for incremental moves use zotero_set_item_collections. creators: full replacement list of {creatorType, firstName, lastName} objects. Requires a writable library (fails in local-only mode). To edit notes use zotero_manage_note. Example: zotero_update_item(item_key='RTKZQI8E', fields={'doi': '10.1145/3708319'}, add_tags=['reviewed']).

Input Schema

TableJSON Schema

Name	Required	Description
`tags`	No
`fields`	No	mapping (or JSON object string) of field name -> value. Names may be snake_case aliases (``publication_title``, ``short_title``, ``citation_key``) or raw Zotero API keys (``publicationTitle``). ``place`` is the publication city (e.g. ``"New York"``) and is valid on book, bookSection, thesis, manuscript, report and conferencePaper. ``citation_key`` writes Zotero's native ``data.citationKey`` (the BetterBibTeX citation key); BBT auto-pins from metadata on creation and provides no programmatic refresh path in 9.x, so a direct write here is the only programmatic remediation for malformed pinned keys. ``item_type`` migrates the item across types: overlapping fields are preserved and type-specific fields that do not map are dropped.
`add_tags`	No
`creators`	No	full replacement creators list (also accepted as ``fields['creators']``).
`item_key`	Yes	8-character Zotero item key of the item to update.
`collections`	No
`remove_tags`	No
`collection_names`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed23 schema fields changedv0.9.0Aug 3, 2026

removedInput schema / properties / abstract

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / access_date

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / book_title

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / citation_key

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "BetterBibTeX / Zotero native citation key. Writes to data.citationKey. Useful when BBT auto-pinned the key from incomplete metadata and the programmatic refresh path is blocked (see https://github.com/retorquere/zotero-better-bibtex/issues/3522)."
-}

addedInput schema / properties / creators / description

Added value: +"full replacement creators list (also accepted as\n``fields['creators']``)."

removedInput schema / properties / date

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / doi

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / edition

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / extra

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

addedInput schema / properties / fields

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "mapping (or JSON object string) of field name -> value.\nNames may be snake_case aliases (``publication_title``,\n``short_title``, ``citation_key``) or raw Zotero API keys\n(``publicationTitle``). ``place`` is the publication city\n(e.g. ``\"New York\"``) and is valid on book, bookSection,\nthesis, manuscript, report and conferencePaper.\n``citation_key`` writes Zotero's native ``data.citationKey``\n(the BetterBibTeX citation key); BBT auto-pins from metadata\non creation and provides no programmatic refresh path in 9.x,\nso a direct write here is the only programmatic remediation\nfor malformed pinned keys. ``item_type`` migrates the item\nacross types: overlapping fields are preserved and\ntype-specific fields that do not map are dropped."
+}

removedInput schema / properties / isbn

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / issn

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / issue

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / item_type

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / language

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / pages

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / place

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Publication place (city), e.g., 'New York' or 'Cambridge, MA'."
-}

removedInput schema / properties / publication_title

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / publisher

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / short_title

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / title

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / url

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

removedInput schema / properties / volume

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null
-}

Changed1 schema field changedv0.6.0Jun 22, 2026

addedInput schema / properties / citation_key

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "BetterBibTeX / Zotero native citation key. Writes to data.citationKey. Useful when BBT auto-pinned the key from incomplete metadata and the programmatic refresh path is blocked (see https://github.com/retorquere/zotero-better-bibtex/issues/3522)."
+}

Addedv0.4.1May 24, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it delivers: it discloses failure modes (unknown names fail and list valid ones, invalid-for-type names are skipped), item_type migration semantics, tag replacement vs incremental behavior, collection replacement semantics, full-replacement creator semantics, and the local-only write failure. This goes well beyond a generic 'update item' statement.

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?

The description is long, but it is dense, front-loaded, and internally structured with explicit warning sections like 'TAG SEMANTICS (easy to get wrong)'. Every sentence adds operational value, including the example call at the end. The length is justified by the tool's complexity and the absent annotations.

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?

Given 8 parameters, no annotations, and a complex mutation tool, this description is complete: it covers update semantics, parameter edge cases, validation behavior, access requirements, and routing to alternatives. The presence of an output schema means return-value documentation is not required from the description.

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 only 38%, so the description must compensate. It does so thoroughly: it enumerates accepted field names, explains tag/collection replacement vs incremental modes, clarifies collections=[] clears membership, defines creators as a full replacement list with object shape, and notes the JSON-string-accepted form for fields. This adds substantial meaning beyond the bare schema.

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 description states an explicit verb and resource: 'Update metadata on an existing Zotero item by key.' It also clarifies the partial-update behavior ('Only what you pass is changed') and distinguishes the tool from related siblings like zotero_manage_note and zotero_set_item_collections.

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?

The description gives concrete when-to-use and when-not-to-use guidance: it warns that tags replaces the whole list and that add_tags/remove_tags are 'preferred,' routes incremental collection moves to zotero_set_item_collections, and directs note editing to zotero_manage_note. It also states the writable-library requirement.

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

Deploy Server