Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_get_item_fulltext

Retrieve the full extracted text of a Zotero item's PDF or EPUB attachment to read the entire paper. Use only when you need to read the content, not for searching or metadata queries.

Instructions

Return the extracted text of a Zotero item's primary attachment (PDF or EPUB). WARNING: returns most or all of the paper (often 10K+ tokens). Use ONLY when the user explicitly wants to READ the paper — not for searching or browsing. For topic search use zotero_semantic_search; for metadata only use zotero_get_item_metadata. PDFs are read up to fulltext_display_max_pages (10 by default); when that cuts a document short the heading names the page range and TRUNCATED — read on with zotero_read_pdf_pages. Avoid calling this on multiple papers in one conversation unless the user specifically asked to read several. item_key: 8-character Zotero item key. Normally the parent item — the tool locates the attached PDF/EPUB itself, preferring PDF unless attachment_priority says otherwise. Passing an attachment's own key instead reads exactly that file and skips the priority order, which is how you read one specific attachment of an item that has several (find keys via zotero_get_item_children). Scope: active library only. Extraction path (in order): local Zotero storage via SQLite when running in local mode (fastest, respects pdf_max_pages config); Zotero's server-side fulltext index; direct download and parsing as a last resort. Image-only scanned PDFs without OCR may return little or no text. Example: zotero_get_item_fulltext(item_key='RTKZQI8E').

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
item_keyYesZotero item key/ID. Normally the parent item, whose best attachment is chosen by ``attachment_priority``. Passing an *attachment's* own key is also supported and reads exactly that file, bypassing the priority order — pair it with ``zotero_get_item_children`` to read one specific attachment of an item that has several (#378).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • changedInput schema / properties / item_key / description
      Previous value: -"Zotero item key/ID"New value: +"Zotero item key/ID. Normally the parent item, whose best\nattachment is chosen by ``attachment_priority``. Passing an\n*attachment's* own key is also supported and reads exactly that\nfile, bypassing the priority order — pair it with\n``zotero_get_item_children`` to read one specific attachment of\nan item that has several (#378)."
  2. Addedv0.4.1
  3. Removedv0.1.6
  4. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden, and it delivers: it warns about large outputs, explains page-limit truncation and TRUNCATED headings, specifies parent-item vs. attachment-key behavior, lists the extraction path, and notes that scanned PDFs without OCR may return little text. This far exceeds the minimum required transparency.

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?

The description is long but every sentence earns its place: warning first, then usage exclusions, alternatives, truncation behavior, parameter semantics, extraction order, caveats, and a concrete example. It is front-loaded with the most decision-relevant 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?

Given the tool's complexity and the absence of annotations, the description is remarkably complete. It covers what the tool returns, when to use it, how the item_key selects the attachment, what happens with page limits, extraction fallbacks, limitations, and an example call. Nothing needed to invoke it correctly is missing.

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?

The input schema already documents item_key well (100% coverage), but the description adds further meaning: 8-character key format, the parent-item convention, attachment_priority behavior, and reading a specific attachment via its own key. This goes beyond the schema, though some detail overlaps with the schema's own description.

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 specific verb and resource: 'Return the extracted text of a Zotero item's primary attachment (PDF or EPUB).' It immediately distinguishes the tool from semantic search and metadata retrieval by naming those siblings explicitly, so an agent can select this tool correctly without ambiguity.

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?

Usage rules are explicit: 'Use ONLY when the user explicitly wants to READ the paper — not for searching or browsing.' It names alternatives for those cases (zotero_semantic_search, zotero_get_item_metadata) and even advises against calling it on multiple papers unless specifically requested.

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