Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_search_items

Search your Zotero library by author, title, or year to retrieve item metadata and abstracts. Use short, simple substring queries for best results.

Instructions

Search Zotero items by substring match against metadata (title, creators, year, and — in 'everything' mode — abstract). Returns metadata + abstracts as markdown. IMPORTANT: keep queries SHORT and SIMPLE — 'Author Year' (e.g. 'Brewer 2011') or just an author name ('Cladder-Micus'). This is substring matching, not web search: each extra word NARROWS the match, so adding topic words usually returns fewer results, not more. For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag. If a query finds nothing, this tool automatically falls back to simplified queries and then semantic search. query: required substring. qmode: 'titleCreatorYear' (default) matches only title/authors/year; 'everything' also searches abstract. item_type: '-attachment' (default) excludes attachments; pass 'journalArticle', 'book', etc. to filter. tag: optional list of tag conditions (ANDed). limit: max results (default 10). collection_key: 8-char key to restrict to a collection (bypasses the fallback cascade). include_subcollections: also search collections nested beneath it (default False). search_all_libraries: search personal + all group libraries at once, labelling each result with its library — use it when you don't know which library holds the item. Needs the SQLite backend (the default in local mode); excludes collection_key. Example: zotero_search_items(query='Cladder-Micus') or zotero_search_items(query='Brewer 2011', search_all_libraries=True).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tagNoTag filter. Accepts ["tagA", "tagB"] (preferred), a bare string "tagA", a JSON-string list '["tagA", "tagB"]', or the dict-shape [{"tag": "tagA"}] sometimes emitted by clients that confuse the filter form with Zotero's stored-tag form. All are normalized internally to the list[str] form pyzotero expects.
limitNoMaximum number of results to return
qmodeNoQuery mode (titleCreatorYear or everything)titleCreatorYear
queryYesSearch query string
item_typeNoType of items to search for. Use "-attachment" to exclude attachments.-attachment
collection_keyNoOptional collection key to scope the search to a specific collection. When provided, bypasses the fallback cascade and searches the collection directly.
search_all_librariesNoSearch every accessible library at once instead of the active one (#163). Requires the SQLite backend; each result is labelled with the library it came from. Cannot be combined with collection_key, which names a collection inside one library.
include_subcollectionsNoAlso search collections nested beneath collection_key. Ignored when collection_key is not given. Defaults to False, matching Zotero's own "Search subcollections" checkbox.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.11.0
    • addedInput schema / properties / include_subcollections
      Added value: +{
+  "default": false,
+  "description": "Also search collections nested beneath\ncollection_key. Ignored when collection_key is not given. Defaults\nto False, matching Zotero's own \"Search subcollections\" checkbox.",
+  "type": "boolean"
+}
    • addedInput schema / properties / search_all_libraries
      Added value: +{
+  "default": false,
+  "description": "Search every accessible library at once instead\nof the active one (#163). Requires the SQLite backend; each result\nis labelled with the library it came from. Cannot be combined with\ncollection_key, which names a collection inside one library.",
+  "type": "boolean"
+}
  2. Addedv0.4.1
  3. Removedv0.1.6
  4. First observedv1.0.0

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, and it delivers: it discloses the automatic fallback cascade ('falls back to simplified queries and then semantic search'), the condition that bypasses it (collection_key), backend requirements (SQLite), and behavioral caveats such as search_all_libraries labelling results. This is substantive behavioral context beyond a mere 'searches items' statement.

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: the critical usage warning is front-loaded, each parameter gets a compact clause, alternatives and exclusions are stated, and concrete examples close it out. The structured one-sentence-per-parameter format makes it easy to scan despite its length.

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 an 8-parameter search tool with an output schema and zero annotations, the description covers invocation strategy, fallback behavior, parameter interactions, and library-selection guidance. There is no obvious missing piece an agent would need to call this tool 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 adds meaningful usage nuance beyond each schema field: keep queries short, query modes expand what is searched, item_type defaults to excluding attachments, collection_key bypasses the fallback cascade, and search_all_libraries is for when the library is unknown. The description teaches correct invocation rather than just restating parameter names.

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 states a specific verb and resource ('Search Zotero items') plus the exact mechanism ('substring match against metadata... in 'everything' mode — abstract'), and notes the return format ('metadata + abstracts as markdown'). It also distinguishes itself from siblings by naming two alternatives, so an agent can tell it apart without opening schemas.

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 guidance: keep queries SHORT and SIMPLE, explains why substring matching behaves differently from web search, and names alternatives for distinct needs ('For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag'). It also gives concrete examples such as 'Brewer 2011' and 'Cladder-Micus', leaving little to inference.

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