Skip to main content
Glama
oscardvs

Zoteus

by oscardvs
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Hybrid

Semantic / hybrid library search

zotero_semantic_search
Read-only

Search your Zotero library by meaning instead of exact keywords. Combines keyword and vector matching across metadata, fulltext, notes, and annotations, returning snippet-scored results.

Instructions

Search the library by meaning, not just keywords. Combines BM25 keyword scoring with vector similarity (when an embedding provider is configured) via reciprocal-rank fusion, and returns the best-matching items with a snippet and score. By default it searches item metadata and abstracts; if the index was built with fulltext on (zotero_index fulltext:true, or ZOTEUS_INDEX_FULLTEXT=true) it also searches the body text of attachments, and a hit whose snippet came from a PDF body is marked source:"fulltext". It ALSO searches the words the reader wrote — child notes and PDF annotations (highlight text and comments) — unless that was turned off (ZOTEUS_INDEX_OWN_WORDS=false); a hit from one is marked source:"note" or source:"annotation" and is attributed to the item it hangs off, so an item with forty annotations is one result rather than forty. mode: "auto" (hybrid, default), "keyword" (BM25 only), or "semantic" (vector only). "semantic" needs vectors in the index: when the configured embedder is not running (e.g. the on-device model runtime is not installed) it returns an error naming the cause instead of an empty result set, and "auto" keeps working as keyword search while saying so. The index must be built once before first use: when it is empty this tool starts a background build automatically (auto_build, on by default) and tells you to poll zotero_index action:"status" and retry — pass auto_build:false to opt out. For exact field/tag/itemType filtering use zotero_search_items instead; use this for conceptual/"papers about X" queries. To read the actual passages of a found item (with page locators) use zotero_get_fulltext.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qYesNatural-language query.
modeNo
limitNoMax results (default 10).
auto_buildNoStart building the index automatically in the background when it is empty (default true).

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changedv1.3.1
    • addedInput schema / properties / auto_build
      Added value: +{
+  "description": "Start building the index automatically in the background when it is empty (default true).",
+  "type": "boolean"
+}
  2. First observedv1.0.4

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint:true and openWorldHint:true; the description carries the real behavioral burden and does so richly: config-dependent search scope (metadata/abstracts vs fulltext vs notes/annotations), source markers ("fulltext", "note", "annotation"), result aggregation (forty annotations collapse to one item), mode-specific failure behavior (semantic errors naming the cause, auto silently degrading to keyword while saying so), and the transparent disclosure of the background auto-build side effect during a read-only search. No contradiction with annotations.

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 (~8 dense sentences) but front-loaded with the core purpose and every clause carries distinct behavioral information — search scope, source markers, mode semantics, index prerequisites, sibling routing. A few parentheticals (e.g., 'e.g. the on-device model runtime is not installed') are slightly expandable, keeping it a notch below perfect conciseness.

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?

With no output schema, the description carries the return-value burden and covers it: best-matching items with snippet and score, plus source markers and one-result-per-item aggregation. It also covers prerequisites (index must be built), config-dependence (fulltext/own-words flags), and failure modes. For a read-only search tool of this complexity, nothing an agent needs to invoke it correctly or interpret results is missing.

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 coverage is 75% (mode lacks a description), so the description must compensate for the enum parameter — and it does, explaining each mode value and its failure/fallback behavior. It also enriches auto_build by explaining the consequence (background build triggers, poll and retry) beyond the schema's one-liner. The q parameter gains context ('papers about X' conceptual queries). Genuine added value beyond the structured schema.

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?

Opens with a specific verb+resource+approach ('Search the library by meaning, not just keywords') and details the mechanism (BM25 + vector similarity via reciprocal-rank fusion). It explicitly differentiates from siblings: 'For exact field/tag/itemType filtering use zotero_search_items instead; use this for conceptual/""papers about X" queries.' An agent can distinguish this from every sibling 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?

Names alternatives and the conditions that select them: zotero_search_items for exact field/tag/itemType filtering, zotero_get_fulltext for reading actual passages with page locators. It also gives the operational workflow for the empty-index case (poll zotero_index action:"status" and retry, or pass auto_build:false to opt out). Nothing is left to inference.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/oscardvs/zoteus'

If you have feedback or need assistance with the MCP directory API, please join our Discord server