zotero-library-mcp

Create Annotation

create_annotation

Highlight quoted text in a Zotero PDF by searching for the passage, then create a visible annotation with optional comment, color, and overlap handling.

Instructions

Highlight a text passage in a PDF attached to a Zotero item.

Searches the PDF for the quoted text and creates a visible highlight annotation in Zotero's PDF reader. Tries a normalized word match first, then fuzzy matching (for OCR errors, hyphenation differences, or minor transcription mismatches).

Smart overlap handling:

If the same text is already highlighted, appends the new comment to the existing annotation instead of creating a duplicate.
If the new text is a sub-passage of an existing highlight (or vice versa), the new highlight is created in a contrasting color so both are visually distinct.

Args: item_key: The Zotero item key (the parent item, not the attachment) quoted_text: The text passage to highlight in the PDF (fuzzy matching handles minor differences from the actual PDF text) comment: Optional comment to attach to the highlight color: Highlight color as hex (default "#ffd400" yellow) max_l_dist: Maximum Levenshtein distance for fuzzy matching. Default is ~20% of the search text length. Increase if the PDF has many OCR errors; decrease for stricter matching. attachment_key: Optional PDF attachment key when the item has multiple PDFs page_number: Optional one-based page number to search occurrence: One-based occurrence to highlight when text repeats

Input Schema

TableJSON Schema

Name	Required	Default
`color`	No	#ffd400
`comment`	No
`item_key`	Yes
`library_id`	No
`max_l_dist`	No
`occurrence`	No
`page_number`	No
`quoted_text`	Yes
`library_type`	No
`attachment_key`	No

Output Schema

TableJSON 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

A4.5/5.0

Behavior5/5

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

Annotations only give the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), while the description adds rich behavior: normalized-then-fuzzy matching, the Levenshtein fallback for OCR/hyphenation issues, appending comments to existing overlapping annotations instead of duplicating, and contrasting colors for sub-passages. This is substantial disclosure beyond what structured fields provide, and it is consistent with destructiveHint=false since operations are additive.

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?

Purpose is front-loaded and the behavior/matching details are organized under clear headings, with an Args block that adds meaning rather than restating schema titles. The Args list is somewhat long, but given 0% schema coverage each entry earns its place; only the two undocumented library parameters are omissions rather than bloat.

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?

With an output schema present, return values need no explanation, and the description covers the tricky parts of this operation (fuzzy matching, overlap/duplicate behavior). It is incomplete on failure modes (what happens when no match is found) and on library scoping via the undocumented library_id/library_type params.

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

Parameters4/5

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

Schema description coverage is 0%, so the description carries the full burden, and it mostly delivers: it clarifies that item_key is the parent item rather than the attachment, gives the color default, and explains max_l_dist tuning tradeoffs (increase for OCR errors, decrease for strictness) plus one-based semantics for page_number and occurrence. It leaves library_id and library_type entirely undocumented, so it does not fully compensate for the 10-parameter surface.

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 opening sentence gives a specific verb, resource, and scope ('highlight a text passage in a PDF attached to a Zotero item'), which cleanly separates it from siblings like update_annotation, delete_annotation, and get_annotations. An agent can identify the operation without opening the schema.

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?

Usage context is clear: it's for creating visible PDF highlights with support for fuzzy text matching, and the 'Smart overlap handling' section explains what happens when text is already highlighted or is a sub-passage. However, it never explicitly names alternatives (e.g., update_annotation for modifying an existing highlight, or get_annotations to check first) or states when not to use it, so it stops short of a 5.

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