zotero-library-mcp

Add Item From Metadata

add_item_from_metadata

Add an item to your Zotero library from manual, CSL-like, or parsed metadata; the template enforces valid fields for the chosen item type.

Instructions

Add an item from manual, CSL-like, or previously parsed metadata.

The Zotero item template determines which fields are accepted for the requested item type, preventing invalid cross-type metadata.

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_type": "<item_type>",
      "title": "<title>"
    },
    "name": "add_item_from_metadata"
  }
}

Input Schema

Name	Required	Description	Default
`title`	Yes
`fields`	No
`creators`	No
`item_type`	Yes
`library_id`	No
`library_type`	No
`collection_id`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.10.0Sep 14, 2026

addedInput schema / properties / library_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Library Id"
+}

addedInput schema / properties / library_type

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "user",
+        "group"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Library Type"
+}

First observedv0.9.0Aug 12, 2026

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral detail beyond that: the Zotero item template gates which fields are accepted and blocks invalid cross-type metadata. However, it says nothing about where the item lands or permission requirements, so it adds only moderate value on top of the annotations.

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?

Two short sentences with the purpose front-loaded and no filler. The second sentence on template validation is the only part that could be tightened, but overall it is well-sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/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 values need not be described. But for a 7-parameter creation tool with 0% schema coverage, the description omits how items are targeted to a library or collection and gives no guidance on the creators/fields shapes, leaving real gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there are 7 parameters, so the description must carry the burden and largely does not. It loosely relates the item template to item_type and fields, but says nothing about creators, library_id, library_type, or collection_id, whose formats and roles are undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Add an item from ... metadata') and identifies the input sources (manual, CSL-like, or previously parsed metadata). This distinguishes it from identifier-based siblings such as add_paper_by_doi and add_book_by_isbn, though it never names them directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: describing the input as 'manual, CSL-like, or previously parsed metadata' hints at when to prefer this over the DOI/ISBN/arXiv siblings, but there is no explicit when-to-use or when-not statement, and no routing to alternatives.

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