zotero-local-mcp

Overview Schema Source Related Servers Score Discussions Admin

zotero_semantic_search

Find papers semantically similar to a natural-language query using AI embeddings. Supports metadata filters and searching across all indexed libraries.

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 metadata filters as a dict (e.g. {'itemType': 'journalArticle', 'year': '2023'}); also accepts a JSON 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 ZOTERO_SEARCH_BACKEND=sqlite, 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

Name	Required	Description
`limit`	No	Maximum number of results to return (default: 10)
`query`	Yes	Search query text - can be concepts, topics, or natural language descriptions
`filters`	No	Optional metadata filters as dict or JSON string. Example: {"item_type": "note"}
`library_id`	No	Optional library scope — 0/"user" for the personal library or a groupID for a group library. Defaults to the active library.
`search_all_libraries`	No	Search 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

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 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 full responsibility. It discloses the requirement for a populated search database, availability only with the optional semantic dependency, default library scope behavior, and the labeling of results when searching all libraries. It also notes the mutual exclusivity of library_id and search_all_libraries. This is thorough and transparent.

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?

Despite being longer than average, every sentence serves a purpose. The description front-loads the core purpose and usage guidance, then systematically covers parameters, prerequisites, and an example. It is well-organized and avoids redundancy, earning 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 a tool with 5 parameters and an output schema, the description covers all necessary aspects: when to use, how to use each parameter, prerequisites, availability constraints, and a clear example. It also cross-references the status-check sibling, making it complete for an agent to call 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?

Schema coverage is 100%, but the description adds substantial value beyond the schema. It explains query semantics (natural-language phrases work well), filter format examples, library_id interpretation (0/'user' vs groupID), and the exact conditions and implications of search_all_libraries. It also clarifies the relationship between parameters.

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 explicitly states the tool performs semantic similarity search on papers using AI embeddings, and positions it as the best tool for topic-based discovery. It distinguishes itself from siblings like zotero_search_items by emphasizing topic focus and efficiency over scanning collections or reading abstracts.

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?

It clearly states when to use this tool (for topic search) and implies when not to (when scanning collections is more appropriate). It also provides explicit conditions for search_all_libraries, prerequisites (populated database, semantic dependency), and gives a concrete example. It even references a sibling tool for checking database status.

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

Install Server