Skip to main content
Glama

Zotero Update Item

zotero_update_item

Update a Zotero item's metadata, creators, tags, or collections while changing only the values you provide.

Instructions

Change metadata on one item; only what you pass changes. fields: {name: value} with snake_case names (title, date, doi, url, abstract, publication_title, short_title, book_title, citation_key, item_type, place, extra, volume, issue, pages, publisher, issn, isbn, edition, language, access_date) or raw Zotero field names. Unknown names fail and list the valid ones; names the item's type lacks are skipped and reported. citation_key sets the BetterBibTeX key; item_type converts the item, dropping fields the new type lacks. creators: a full replacement list of {creatorType, firstName, lastName}. tags REPLACES all tags; add_tags/remove_tags edit incrementally (preferred; not with tags). collections (keys) or collection_names REPLACE membership (collections=[] clears it); for incremental moves use zotero_set_item_collections. For notes use zotero_manage_note.

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": {
      "item_key": "<item_key>"
    },
    "name": "zotero_update_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNo
fieldsNo
add_tagsNo
creatorsNo
item_keyYes
collectionsNo
remove_tagsNo
collection_namesNo

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 so well: it discloses partial-update semantics, that unknown field names fail and enumerate valid ones, that type-incompatible names are skipped and reported, that tags REPLACES all tags, that collections=[] clears membership, that creators is a full replacement, and that item_type conversion drops fields. The one notable omission is any mention of write authorization or read-only-library failures, which the sibling zotero_authorize_local_writes implies may be a real precondition.

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 the core rule and organized by parameter group (fields, creators, tags, collections, out-of-scope), with no filler sentences. It is a single dense paragraph, though, and the long field-name list makes it harder to scan than a bulleted layout would; a semicolon-joined run-on in the middle reduces readability slightly.

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 mutation tool with no annotations and no output schema, the description covers nearly everything an agent needs, including error behavior and destructive-replacement warnings. Missing pieces are the authorization prerequisite for writes and whether the updated item is returned; the latter is partly excused by the absence of an output schema, but the auth gap is real for a write tool.

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 enumerates accepted snake_case field names plus the raw-Zotero-name fallback, spells out the creators object shape ({creatorType, firstName, lastName}), and defines the mutually exclusive tags/add_tags/remove_tags and collections/collection_names semantics. This adds substantially more meaning than the bare array/object properties in the 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?

Opens with a specific verb and resource ("Change metadata on one item") and immediately scopes it with the partial-update rule ("only what you pass changes"), which separates it from an add/delete tool and hints at the one-item scope vs. a batch sibling.

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 routes the agent: use add_tags/remove_tags over tags ("preferred; not with tags"), use zotero_set_item_collections for incremental collection moves rather than collections/collection_names, and use zotero_manage_note for notes. That is when-to-use, when-not-to-use, and named alternatives in one compact block.

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