Skip to main content
Glama

Zotero Search Items

zotero_search_items

Search Zotero library items by keyword across title, creators, year, tags, type, or collection; narrow queries by filters and optionally include abstracts.

Instructions

Keyword search of item metadata: substring match on title, creators and year (qmode='everything' adds abstracts). Keep queries short, like 'Brewer 2011' or a surname: every extra word narrows the match. For topics or concepts use zotero_semantic_search. If nothing matches it retries simpler queries, then semantic search, and says so. tag: conditions that are ANDed; within one, ' OR ' alternates and a leading '-' excludes, e.g. ['methods OR methodology', '-draft']. Omit query to list items by tag alone (zotero_get_tags lists the names). item_type: '-attachment' (default) excludes attachments, or e.g. 'journalArticle'. limit: default 10. collection_key: search one collection (no retries); include_subcollections adds its subcollections. search_all_libraries=True searches every library and labels each result; needs a query, not with collection_key.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "zotero_search_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNo
limitNo
qmodeNotitleCreatorYear
queryNo
item_typeNo-attachment
collection_keyNo
search_all_librariesNo
include_subcollectionsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

No annotations exist, so the description carries the full burden, and it discloses non-obvious behavior: automatic retry with simpler queries, escalation to semantic search with a notice, and the fact that collection_key disables retries. It also reveals defaults (limit 10, '-attachment' exclusion) and that search_all_libraries labels each result, which no structured field provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and query-shaping advice before the parameter notes, and every sentence carries information. It is dense and slightly run-on in the tag and library clauses, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, no annotations, and no output schema, the description covers selection, defaults, tag syntax, and fallback behavior thoroughly. The remaining gap is return shape — it mentions that results are labeled in multi-library mode but not what fields a result carries or whether paging exists.

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?

Schema description coverage is 0%, so compensation is required, and the description defines nearly every parameter's meaning: tag AND-ing plus ' OR ' alternation and leading '-' exclusion, qmode's effect on abstracts, item_type defaults, limit, collection_key scope, include_subcollections, and the query requirement for search_all_libraries. Minor gap: limit's upper bound and item_type's other accepted values are not spelled out.

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?

States a specific verb and resource (keyword search of item metadata) and immediately scopes it (substring match on title, creators, year). It explicitly routes topic/concept searches to zotero_semantic_search and tag-name lookups to zotero_get_tags, so an agent can distinguish it from siblings without opening a schema.

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?

Gives concrete when-to-use guidance ('Brewer 2011' or a surname, keep queries short) and an explicit when-not ('For topics or concepts use zotero_semantic_search'). It also names a second alternative for tag names and explains the omit-query case, which is exactly the routing an agent needs.

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