io.github.54yyyu/zotero-mcp

zotero_synthesize_collection

Aggregate all papers in a Zotero collection into one structured digest with metadata, abstracts, and optional full text, enabling a literature-review comparison table without per-item calls.

Instructions

Gather every paper in a collection — metadata, abstract, and (optionally) extracted full text — into ONE structured digest so YOU (the agent) can build a literature-review comparison table (method, sample, findings, relevance to the user's question) without calling a per-item tool once per paper. This tool does NOT call an LLM itself; like zotero_synthesize_annotations, it only collects and formats — the synthesis step is yours. collection_key: the 8-character collection key (see zotero_search_collections). include_fulltext=False (default) includes title/authors/date/abstract only — fast, good for a first-pass comparison table. Set True to also extract each paper's full text via the same path as zotero_get_item_fulltext (local storage / server index / download+convert), which is far slower and produces a much larger response; each paper's extracted text is capped at fulltext_max_chars to keep the combined digest usable — read one paper in full with zotero_get_item_fulltext if you need more. fulltext_max_chars: per-paper cap on extracted full-text length when include_fulltext=True (default 3000, max 20000). limit: maximum number of papers to include (default 20, capped at 50) — scope to a smaller collection or raise cautiously, since include_fulltext=True on many papers is slow. A paper whose text or metadata can't be read is skipped with an inline note rather than failing the whole call. Example: zotero_synthesize_collection(collection_key='MT53KB66', include_fulltext=True, limit=15).

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum number of papers to include.
`collection_key`	Yes	Collection to digest.
`include_fulltext`	No	Also extract each paper's full text (slow).
`fulltext_max_chars`	No	Per-paper cap on extracted text length.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A5/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 of behavioral disclosureais it does extensively. It states the tool does NOT call an LLM, explains that extracting full text is slower and produces larger responses, discloses per-paper caps, and notes that unreadable papers are skipped inline rather than failing the call.

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 adds genuine value, and the most important information (purpose, alternatives, key parameter behavior) is front-loaded. The parameter guidance, error-handling note, and worked example are all relevant and non-redundant.

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?

For a complex tool with no annotations but with an output schema, the description covers purpose, usage alternatives, performance characteristics, error handling, parameter semantics, and a concrete example. Nothing important is missing for an agent to invoke it correctly.

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?

Although schema coverage is 100%, the description significantly enriches each parameter: collection_key format and lookup reference, include_fulltext tradeoffs, fulltext_max_chars defaults and max not in schema, and limit's cap and performance implications. This goes well beyond the schema descriptions.

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 names a specific verb and resource: gathering every paper in a collection (metadata, abstract, optional full text) into one structured digest for building literature-review comparison tables. It also explicitly differentiates from the per-item tools and sibling zotero_synthesize_annotations by stating it only collects and formats, leaving synthesis to the agent.

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?

The description gives explicit when-to-use and when-not-to-use guidance: use it instead of calling per-item tools once per paper, use zotero_get_item_fulltext for reading a single paper in full, and choose include_fulltext=False for a fast first pass. It also advises scoping collections or raising limit cautiously when full text is enabled.

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

Deploy Server