Skip to main content
Glama
54yyyu

Zotero MCP

by 54yyyu
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

zotero_semantic_search

Find papers by topic using AI semantic similarity. Search your Zotero library with natural language queries to locate relevant research without scanning abstracts.

Instructions

Prioritized topic-search tool. Find papers by semantic similarity to a query using AI embeddings — the BEST tool for finding papers on a topic (e.g. 'papers about mindfulness-based therapy'), far more efficient than scanning collection items or reading abstracts. Searches the ACTIVE library by default; pass search_all_libraries=True to cover every indexed library. query: the topic or concept; natural-language phrases work well. limit: max results (default 10). filters: optional ChromaDB metadata filter, one key per dict (e.g. {'item_type': 'journalArticle'}); also accepts a JSON string. Keys: item_type, item_key, citation_key, doi, publication, tags, has_fulltext. Combine keys with {'$and': [{...}, {...}]}. There is no year filter: 'date' holds the raw Zotero date string. library_id: optional — scope to one library other than the active one: 0 or 'user' for personal, else a groupID (see zotero_list_libraries). search_all_libraries: search every indexed library at once, labelling each result with its library; needs the SQLite backend (the default in local mode), excludes library_id. Requires the semantic search database to be POPULATED — run zotero_update_search_database first if you just installed the server or added new items; check readiness with zotero_get_search_database_status. Available only when the [semantic] optional dependency is installed. Example: zotero_semantic_search(query='mindfulness-based cognitive therapy for depression', limit=5).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return (default: 10)
queryYesSearch query text - can be concepts, topics, or natural language descriptions
filtersNoOptional metadata filters as dict or JSON string. Example: {"item_type": "note"}
library_idNoOptional library scope — 0/"user" for the personal library or a groupID for a group library. Defaults to the active library.
search_all_librariesNoSearch every indexed library at once (#163). Requires the SQLite backend; results are labelled with their source library. Mutually exclusive with library_id.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.11.0
    • changedInput schema / properties / library_id / description
      Previous value: -"Optional library scope — 0/\"user\" for the personal library, a\ngroupID for a group library, or None (default) to search every\nindexed library."New value: +"Optional library scope — 0/\"user\" for the personal library\nor a groupID for a group library. Defaults to the active library."
    • addedInput schema / properties / search_all_libraries
      Added value: +{
+  "default": false,
+  "description": "Search every indexed library at once (#163).\nRequires the SQLite backend; results are labelled with their\nsource library. Mutually exclusive with library_id.",
+  "type": "boolean"
+}
  2. Changed1 schema field changedv0.6.4
    • addedInput schema / properties / library_id
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional library scope — 0/\"user\" for the personal library, a\ngroupID for a group library, or None (default) to search every\nindexed library."
+}
  3. Addedv0.4.1

TDQS

A4.7/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 disclosure and meets it: it reveals the active-library default, the search_all_libraries behavior (SQLite backend required, results labelled by library, mutually exclusive with library_id), the filter constraints (one key per dict, $and combos, no year filter), and the population/dependency prerequisites. An agent understands limitations, side effects, and preconditions before invoking.

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?

The description is long but effectively structured: purpose → default scope → parameter walk-through → prerequisites → dependency → example, and nearly every sentence adds information. The promotional phrasing ('BEST', 'far more efficient') is mildly surplus but serves a routing purpose, so only a small deduction applies.

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 moderately complex tool sitting among 40+ siblings, several of which are other search tools, the definition is complete: it differentiates the search method, covers all five parameters including filter syntax, sets preconditions via the database-status check, and names the required dependency. An output schema exists, so return-value documentation is not needed. The example anchors the most common call pattern.

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% (baseline 3), the description adds substantial meaning per parameter: the six valid filter keys, the $and combination syntax, the no-year-filter caveat ('date' holds the raw Zotero date string), the library_id convention (0/'user' vs groupID) with a cross-reference to zotero_list_libraries, and the backend requirement for search_all_libraries. Every parameter is enriched beyond its schema 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 leads with a specific verb+resource — 'Find papers by semantic similarity to a query using AI embeddings' — and positions the tool as 'the BEST tool for finding papers on a topic', which distinguishes it from sibling keyword-search tools. The concrete example query reinforces the intended use case. Nothing is tautological or ambiguous.

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 states exactly when to use it ('the BEST tool for finding papers on a topic') and contrasts it with scanning collection items or reading abstracts, which maps to sibling tools like zotero_search_items and zotero_get_item_fulltext — though those siblings are not named explicitly. It also gives exclusions (no year filter) and hard prerequisites (run zotero_update_search_database first, [semantic] dependency required). The when-not-to-use guidance for keyword-style searches is implied rather than explicit.

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