Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_read_pdf_pages

Read specific pages from a Zotero PDF attachment as Markdown text or PNG images, with optional region cropping, to extract exact content for analysis or citation.

Instructions

Read specific page range(s) from a PDF attachment of a Zotero item. Use this when you know which pages to read — for example after getting the PDF outline via zotero_get_pdf_outline. Pages are 1-indexed. format='text' (default) returns Markdown with the heading structure preserved and flags pages whose equations, figures or tables the text garbles. format='image' returns the pages as PNG images (up to 10) so those can be read exactly; rect=[x, y, width, height] (normalized 0-1, e.g. from zotero_get_page_layout) returns just that region of start_page, zoomed in.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
rectNoWith format="image", crop start_page to [x, y, width, height].
formatNo"text" for Markdown, "image" for PNG page images.text
end_pageNoLast page to read (1-indexed). If omitted, reads only start_page.
item_keyYesZotero item key/ID of the paper or its PDF attachment.
start_pageYesFirst page to read (1-indexed).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.12.4
    • addedInput schema / properties / format
      Added value: +{
+  "default": "text",
+  "description": "\"text\" for Markdown, \"image\" for PNG page images.",
+  "enum": [
+    "text",
+    "image"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / rect
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With format=\"image\", crop start_page to [x, y, width, height]."
+}
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "type": "object",
-  "x-fastmcp-wrap-result": true
-}New value: +null
  2. Addedv0.4.1

TDQS

A4.8/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 burden. It richly discloses behavior: pages are 1-indexed, text format returns Markdown with heading preservation and flags garbled content, image format returns PNGs with a 10-page cap, and rect crops exactly the specified region with normalized coordinates. This goes far beyond a simple mutation/read label and gives the agent realistic expectations of output and quirks.

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?

Every sentence in this description carries useful information. It is organized logically: purpose, usage context, format options, and rect parameter details. It is not overly long for the amount of behavioral nuance it communicates, and it avoids repeating schema descriptions. The structure is easy to parse and front-loads the most important information.

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?

The description covers the main behavioral aspects, parameter semantics, and concrete usage guidance. Given that the input schema fully documents all parameters and there is no output schema, the description sufficiently explains both input semantics and expected outputs. It also ties into related tools (zotero_get_pdf_outline, zotero_get_page_layout) to place itself within the larger workflow, making it complete for an agent.

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 coverage is already 100%, but the description adds substantial value beyond the schema. It explains that pages are 1-indexed, clarifies that 'end_page' defaults to reading only 'start_page', and gives crucial context for 'rect' by defining normalized 0-1 coordinates and referencing zotero_get_page_layout. This makes parameter usage concrete and reduces the chance of misuse.

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 opens with a clear verb and object: 'Read specific page range(s) from a PDF attachment of a Zotero item.' It distinguishes itself by specifying that it is for when the agent already knows which pages to read, and references related tools like zotero_get_pdf_outline. This makes the tool's function unambiguous and easy to differentiate from siblings.

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?

The description explicitly states when to use it: 'Use this when you know which pages to read.' It also gives a concrete example ('for example after getting the PDF outline via zotero_get_pdf_outline') and differentiates format='text' vs format='image' with clear use cases. Missing are explicit instructions on when not to use it or when to prefer alternatives like full-text retrieval, but the provided context is still strong.

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