Provides read-only tools to search, retrieve metadata, export citations and BibTeX, list collections and tags, and access full text from a Zotero library via its local API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zotero-mcp find papers on reinforcement learning in my Zotero"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small, read-only MCP server that exposes your Zotero library to Claude (or any MCP client) through Zotero's built-in local HTTP API. No API keys, no cloud — it talks to the Zotero desktop app running on your machine.
All tools are read-only:
Tool | Purpose |
| Search the library (title/creator/year, or everything) |
| Full metadata for one item |
| Notes, attachments, and annotations of an item |
| Extracted full text of a PDF/attachment |
| Browse the collection tree |
| Items in a collection |
| List/filter tags |
| List saved searches |
| Export items as BibTeX |
| Formatted citation + bibliography in any CSL style |
| Check connectivity |
Related MCP server: zotero-mcp
Zotero 7 or newer, running.
Enable the local API: Zotero → Settings → Advanced → "Allow other applications on this computer to communicate with Zotero".
uv installed.
Verify the API is up:
curl 'http://localhost:23119/api/users/0/items?limit=1'cd ~/zotero-mcp
uv sync
uv run pytest # unit tests (no running Zotero needed)Smoke-test against your live library (Zotero must be open):
uv run python -c "from zotero_mcp.client import ZoteroLocalClient as C; import json; print(json.dumps(C().search_items(q='', limit=3), default=str)[:600])"Inspect the tools interactively:
uv run mcp dev src/zotero_mcp/server.pyclaude mcp add zotero -- uv --directory ~/zotero-mcp run zotero-mcpThen ask Claude things like "search my Zotero for papers on diffusion models" or "give me the BibTeX for item ABCD1234".
Environment variables (optional):
ZOTERO_BASE_URL — override the API base (default http://localhost:23119/api).
Useful from WSL where Zotero runs on the Windows host, e.g.
http://<windows-host-ip>:23119/api.
ZOTERO_USER_ID — override the local user id (default 0; almost always correct).
Read-only by design. Zotero's local API does not support writes; this server intentionally mirrors that. Citation/BibTeX formatting is delegated to Zotero itself.
If a tool returns {"error": "Could not reach the Zotero local API..."}, Zotero is
closed or the local-API setting is off.
List the top-level items in a collection.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| collection_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states 'List the top-level items in a collection' without mentioning pagination (despite a 'limit' parameter), ordering, error handling, or access requirements. This leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it could be structured more helpfully (e.g., including parameter context), but given its brevity, it remains efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, no annotations, and an output schema (not shown), the description should specify what 'top-level items' means (e.g., excluding items in subcollections), mention pagination behavior, and clarify the required 'collection_key'. It does not do enough to be complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either parameter ('collection_key' or 'limit'). The input schema provides titles but no descriptions, and the tool description adds no meaning beyond the schema, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the top-level items in a collection,' which clearly identifies the action (list) and resource (top-level items in a collection). It distinguishes from siblings like 'zotero_get_children' (which lists children of an item) and 'zotero_get_item' (single item retrieval), though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need the top-level items of a specific collection. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'zotero_search' or 'zotero_get_children'), nor does it state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export one or more items as BibTeX (rendered by Zotero).
| Name | Required | Description | Default |
|---|---|---|---|
| item_keys | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Does not disclose whether it is read-only, rate limits, authentication needs, or behavior on invalid item keys. Merely states export action without behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with primary verb and resource. However, it is under-specified and lacks structured details that would aid comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter and an output schema, the description fails to provide essential context like how to get item keys or what the output contains. Lacks completeness for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain what 'item_keys' are (presumably Zotero item keys) or how to obtain them. Adds no value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'export', the resource 'items', and the format 'BibTeX (rendered by Zotero)'. It distinguishes from sibling tools like zotero_export_citation which exports citations in other formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, when not to use, or any context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return formatted citation + bibliography HTML for items, in the given CSL style.
Args: item_keys: Items to format. style: A CSL style id, e.g. "apa", "chicago-note-bibliography", "ieee".
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | apa | |
| item_keys | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the output is HTML but does not disclose behavioral traits like read-only safety, side effects, or auth requirements. Minimal beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a clear Args list. It is front-loaded with purpose and concise. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not provided), description need not explain return format. Parameters are covered adequately. Lacks prerequisites or usage context, but sufficient for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains both parameters: item_keys (required) and style (optional with examples like 'apa', 'chicago-note-bibliography'). This adds meaningful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'formatted citation + bibliography HTML for items', and specifies the CSL style context. It distinguishes from siblings like zotero_export_bibtex which exports in a different format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for citation formatting but does not provide explicit when-to-use or when-not-to-use guidance. Alternatives are not mentioned, though sibling tools suggest differences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the notes, attachments, and annotations belonging to an item.
Useful to find the attachment key needed for zotero_get_item_fulltext, or to read a paper's notes.
| Name | Required | Description | Default |
|---|---|---|---|
| item_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does not disclose behavioral traits beyond the purpose (e.g., read-only, pagination). However, for a simple list operation, the description is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It mentions the types of children (notes, attachments, annotations), which is sufficient context. However, it could clarify the nature of 'item_key' to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'item_key' parameter beyond what is in the schema (title 'Item Key'). With 0% schema description coverage, the description should compensate but fails to add any meaning. The parameter's role is implied but not explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists notes, attachments, and annotations belonging to an item. The verb 'list' and the specific resources are explicit, and it distinguishes from siblings like zotero_get_item and zotero_get_item_fulltext.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: to find the attachment key needed for zotero_get_item_fulltext, or to read a paper's notes. This guides the agent on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full metadata for a single item by its key.
| Name | Required | Description | Default |
|---|---|---|---|
| item_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It accurately describes the tool as a read operation that returns full metadata. No side effects are mentioned, which is appropriate for a read tool. The description is clear and truthful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, has output schema), the description is adequate. It conveys the core functionality. However, it could mention that the item key is a Zotero-specific identifier, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning beyond the schema. The parameter 'item_key' is not explained (e.g., its format or where to obtain it). The description should compensate for low coverage but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'full metadata for a single item', and the method 'by its key'. It effectively distinguishes from sibling tools like zotero_collection_items (which lists items in a collection) and zotero_get_children (which gets children of an item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It implies use when you have an item key, but does not mention exclusions or alternative tools for other scenarios, leaving the agent without clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the extracted full text for an item.
Accepts either an attachment key directly, or a parent item key (in which case the first attachment with indexed text is used). Full text is only available when Zotero has indexed the attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| item_key | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that full text may not be available if not indexed, but does not specify behavior when no indexed text exists or error handling. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two well-structured sentences, front-loading the main purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and an output schema (not shown), the description sufficiently explains the input resolution logic and a prerequisite (indexing). It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter item_key has no description in the schema (0% coverage). The description adds meaning by explaining it can be either an attachment key or a parent item key, and how resolution works, which is valuable beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the extracted full text for an item, specifying it can accept either an attachment key or a parent item key. This distinguishes it from siblings like zotero_get_item (metadata) and zotero_get_children (attachments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use each key type and notes that full text is only available when Zotero has indexed the attachment. It does not explicitly state when not to use it, but the context is clear for a simple retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the Zotero local API is reachable. Use this to debug connectivity.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates a non-destructive read-only check, which is transparent enough for a health probe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy; every word serves a purpose. The description is minimal yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool is simple (no parameters), the description adequately covers the tool's purpose and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to add parameter semantics. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'check' and the resource 'Zotero local API', distinguishing it from sibling tools that handle items, collections, or exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Use this to debug connectivity', giving clear context for when to invoke the tool, though it does not state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List collections. Pass a collection key as parent to list its subcollections.
| Name | Required | Description | Default |
|---|---|---|---|
| parent | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'List collections' and parameter usage, without disclosing behavioral traits like authentication requirements, read-only nature, pagination, or rate limits. The description adds minimal behavioral context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose 'List collections,' followed by a concise parameter instruction. Every word earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, output schema present), the description is sufficiently complete. It covers the core function and parameter usage. The output schema handles return value documentation, so the description does not need to explain that. Some minor context like pagination could be added, but it is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (coverage 0%), but the description compensates well by explaining the meaning of the parent parameter: passing a collection key lists subcollections, and omitting it lists top-level collections. This adds clear semantics beyond the schema's type-only specification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists collections, with a specific verb and resource. It also explains the optional parent parameter to list subcollections, distinguishing it from sibling tools like zotero_collection_items which list items in a collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool over alternatives. While it explains how to use the parent parameter, it lacks explicit when-to-use or when-not-to-use context relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags in the library, optionally filtered by a substring query.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description lacks details on pagination, sorting, or whether it returns all tags when query is null. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single front-loaded sentence with no unnecessary words, efficiently conveys core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered; but missing explanation of limit behavior and filtering nuances for a 2-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds 'substring' clarification for query parameter beyond schema, but does not explain limit parameter. With 0% schema coverage, partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists tags in the library with optional substring filtering, distinct from sibling tools like zotero_list_collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when needing tags with optional filtering, but does not provide explicit when-to-use/alternatives vs siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the library's saved searches (name + key + conditions).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'List' clearly indicates a read-only operation. It adds the behavioral context that it returns names, keys, and conditions, which is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no wasted words. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0 parameters and an external output schema, the description fully explains the tool's purpose and output format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, so no parameter documentation is needed. The description adds no extra parameter info, but none is required. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists saved searches and specifies the returned fields (name, key, conditions). It distinguishes from siblings like zotero_search (which likely searches items) and zotero_list_collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a list of saved searches is needed, but does not explicitly state when to use this tool versus alternatives like zotero_search. However, the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Zotero library for top-level items.
Args: query: Free-text search. Matches title/creator/year by default. item_type: Restrict to a Zotero item type, e.g. "journalArticle", "book". tag: Restrict to items carrying this tag. limit: Maximum number of items to return. everything: If true, search all fields and full-text rather than just title/creator/year.
Returns a compact list of items, each with its key (use it with
zotero_get_item / zotero_get_children / zotero_get_item_fulltext).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | ||
| query | No | ||
| item_type | No | ||
| everything | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses search behavior: free-text matching on title/creator/year by default, optional expansion to all fields via 'everything' parameter. It states that results are a compact list with 'keys'. While some details are missing (e.g., pagination beyond limit, error handling), the core behavior is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Args' and 'Returns' sections, front-loading the main purpose. Each sentence adds useful information. Could be slightly more concise, but no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters (all optional) and existence of an output schema, the description adequately covers search mechanics and return value (compact list with key). It notes usage of the 'key' with sibling tools, providing context. Lacks comparison to siblings but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. Each parameter is explained: 'query' (free-text search), 'item_type' (restrict to type), 'tag' (restrict to tag), 'limit' (maximum items), 'everything' (search all fields). This adds substantial value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search the Zotero library for top-level items.' It uses a specific verb ('search') and resource ('Zotero library'), and specifies scope ('top-level items'). This distinguishes it from siblings like zotero_get_item (retrieve specific item) and zotero_list_collections (list collections).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description mentions that returned items have a 'key' for use with other tools, but does not provide context for when search is preferred over other Zotero tools. No exclusions or when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0zotero_collection_itemszotero_export_bibtexzotero_export_citationzotero_get_childrenzotero_get_itemzotero_get_item_fulltextzotero_healthzotero_list_collectionszotero_list_tagszotero_saved_searcheszotero_searchScored across 11 tools
Each tool has a clearly distinct purpose: listing, searching, getting metadata/children/fulltext, exporting in different formats, checking health, and listing collections/tags/saved searches. No overlapping functionality that would cause confusion.
All tools share the 'zotero_' prefix and mostly follow a verb_noun pattern (e.g., zotero_get_item, zotero_search, zotero_list_collections). Minor deviations: 'zotero_collection_items' and 'zotero_saved_searches' are noun phrases rather than explicit verbs, but still clear.
11 tools is well-scoped for a research reference management server. Each tool serves a necessary function without redundancy, covering search, retrieval, listing, export, and health checks.
The tool set provides thorough read capabilities: search, get items/fulltext/children, list collections/tags/saved searches, and export. It lacks create/update/delete operations, but the server appears designed for querying and exporting, so the surface is appropriate for that purpose.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
Read-only MCP server exposing a user ORANO library to their own AI agent.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only