Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_create_annotation

Create text highlights or area annotations on PDFs in your Zotero library. Specify a page and either exact text or a region box to annotate, with optional comments and tags.

Instructions

Create an annotation on a PDF attachment (EPUB: highlights only). Exactly one of two modes per call: text= HIGHLIGHTS selectable text; rect= draws an AREA box over a figure, table, or other non-text region (PDF only). Passing both or neither is an error. attachment_key: the PDF/EPUB attachment key, NOT the parent item key (zotero_get_item_children finds it). page: 1-indexed page (EPUB: 1-indexed chapter). text: exact text to highlight, matched against the text layer — scanned/image-only PDFs will not match. rect: [x, y, width, height] normalized to [0, 1], with (0, 0) at the page's top-left; width/height are page-relative and the box must fit the page. Call zotero_get_page_layout first and reuse a detected region's bbox instead of guessing coordinates. comment, color (hex, default '#ffd400'), tags: optional. Requires PyMuPDF (the [pdf] extra) and a writable library: local writes (Zotero 10+) or a web API key. Examples: (attachment_key='NHZFE5A7', page=4, text='working memory'); (attachment_key='NHZFE5A7', page=7, rect=[0.15, 0.22, 0.6, 0.35], comment='Figure 3').

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageYes
rectNo
tagsNo
textNo
colorNo#ffd400
commentNo
attachment_keyYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.11.0
    • changedInput schema / properties / rect / anyOf
      Previous value: -[
-  {
-    "items": {
-      "type": "number"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "type": "number"
+    },
+    "type": "array"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Changed10 schema fields changedv0.9.0
    • removedInput schema / properties / attachment_key / description
      Removed value: -"Attachment key (e.g., \"NHZFE5A7\")"
    • removedInput schema / properties / color / description
      Removed value: -"Highlight color in hex format (default: \"#ffd400\" yellow)"
    • removedInput schema / properties / comment / description
      Removed value: -"Optional comment on the annotation"
    • removedInput schema / properties / page / description
      Removed value: -"For PDF: 1-indexed page number. For EPUB: 1-indexed chapter number."
    • addedInput schema / properties / rect
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
    • addedInput schema / properties / text / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / text / default
      Added value: +null
    • removedInput schema / properties / text / description
      Removed value: -"Exact text to highlight (used to find coordinates/CFI)"
    • removedInput schema / properties / text / type
      Removed value: -"string"
    • changedInput schema / required
      Previous value: -[
-  "attachment_key",
-  "page",
-  "text"
-]New value: +[
+  "attachment_key",
+  "page"
+]
  3. Addedv0.4.1

TDQS

A5/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden and meets it: passing both or neither mode is an error, scanned PDFs fail to match, the box must fit the page, and PyMuPDF plus a writable library (local Zotero 10+ or web API key) are required. These are precisely the failure modes and prerequisites an agent needs before invoking.

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?

Front-loads purpose and the mode rule, then flows through parameter semantics, prerequisites, and two worked examples. Though long (~200 words), every sentence earns its place because the schema provides zero parameter descriptions.

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-value documentation is not the description's job; everything else for this complex two-mode tool is covered: error conditions, EPUB-versus-PDF differences, coordinate rules, dependencies, and examples. The only omission — naming zotero_update_annotation/zotero_delete_annotation as alternatives — is trivial given the sibling verbs.

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?

With 0% schema description coverage across 7 parameters, the description fully compensates: it explains attachment_key is NOT the parent item key, 1-indexed page versus EPUB chapter indexing, rect's normalized [0, 1] coordinates with top-left origin, and the color default. Every parameter gains meaning that the schema's bare types 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 and resource — 'Create an annotation on a PDF attachment' — and immediately disambiguates its two modes: 'text= HIGHLIGHTS selectable text; rect= draws an AREA box.' The EPUB-only-highlights constraint further separates it from the annotation update/delete/get siblings.

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?

Provides explicit when-to-use guidance for each mode and names prerequisite siblings: zotero_get_item_children to find the attachment key and zotero_get_page_layout before supplying rect coordinates. The when-not side is also explicit: EPUB supports highlights only, rect is PDF-only, and scanned/image-only PDFs will not match text.

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

Deploy Server

Other Tools