Zoteus

Manage Zotero saved searches

zotero_saved_searches

Destructive

Instructions

List, create, or delete saved-search DEFINITIONS. NOTE: the Zotero cloud Web API stores saved searches but does NOT execute them — to get the items a saved search matches, run an equivalent zotero_search_items query (or use the desktop local API when available). Set action to "list" (all saved searches with their conditions), "create" (needs name and conditions, each {condition, operator, value}), or "delete" (needs search_key). Writes to your personal library go to the running Zotero desktop app (Zotero 10+) and otherwise to the cloud Web API; group libraries always write to the cloud.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "zotero_saved_searches"
  }
}

Input Schema

Name	Required	Description
`name`	No	Saved-search name (create).
`action`	Yes	What to do. "list" returns every saved-search definition; "create" needs `name` + `conditions`; "delete" needs `search_key`.
`conditions`	No	Search conditions (create).
`library_id`	No	Numeric id of the library to address, e.g. 5234875 for a group (zotero_groups lists the ids you can reach). Omit to use the configured default library; an id given without library_type is read as a group id.
`search_key`	No	Saved-search key (delete).
`library_type`	No	Which library to address: "user" (a personal library) or "group" (a shared group library). Omit to use the library this server is configured for. "group" on its own is refused: pass library_id with it.

Output Schema

Name	Required	Description
`target`	No	Where the write went: "local" (Zotero desktop local API), "desktop" (connector protocol) or "cloud" (Zotero Web API).
`created`	No	Key of the saved search created.
`deleted`	No	Key of the saved search deleted.
`searches`	No	Saved-search definitions (action:"list"). The cloud API stores them but does not execute them.
`libraryVersion`	No	The library's Last-Modified-Version after this write.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.23.0Oct 23, 2026

addedOutput schema / properties / target

Added value: +{
+  "description": "Where the write went: \"local\" (Zotero desktop local API), \"desktop\" (connector protocol) or \"cloud\" (Zotero Web API).",
+  "type": "string"
+}

Changed1 schema field changedv1.21.0Sep 23, 2026
- addedInput schema / properties / library_id / exclusiveMinimum
```
Added value: +0
```

Changed2 schema fields changedv1.20.2Sep 16, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

Changed7 schema fields changedv1.20.0Sep 13, 2026

addedInput schema / properties / action / description

Added value: +"What to do. \"list\" returns every saved-search definition; \"create\" needs `name` + `conditions`; \"delete\" needs `search_key`."

addedInput schema / properties / conditions / items / properties / condition / description

Added value: +"Zotero search field, e.g. \"title\", \"tag\", \"itemType\", \"dateAdded\"."

addedInput schema / properties / conditions / items / properties / operator / description

Added value: +"Zotero operator for that field, e.g. \"is\", \"isNot\", \"contains\", \"doesNotContain\", \"isBefore\"."

addedInput schema / properties / conditions / items / properties / value / description

Added value: +"Value to compare against, as a string, e.g. \"kalman\" or \"journalArticle\"."

addedInput schema / properties / library_id / description

Added value: +"Numeric id of the library to address, e.g. 5234875 for a group (zotero_groups lists the ids you can reach). Omit to use the configured default library; an id given without library_type is read as a group id."

addedInput schema / properties / library_type / description

Added value: +"Which library to address: \"user\" (a personal library) or \"group\" (a shared group library). Omit to use the library this server is configured for. \"group\" on its own is refused: pass library_id with it."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "created": {
+      "description": "Key of the saved search created.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "deleted": {
+      "description": "Key of the saved search deleted.",
+      "type": "string"
+    },
+    "libraryVersion": {
+      "description": "The library's Last-Modified-Version after this write.",
+      "type": "number"
+    },
+    "searches": {
+      "description": "Saved-search definitions (action:\"list\"). The cloud API stores them but does not execute them.",
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "conditions": {
+            "description": "Its conditions, each { condition, operator, value } as Zotero stores them.",
+            "items": {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "key": {
+            "description": "8-character saved-search key.",
+            "type": "string"
+          },
+          "name": {
+            "description": "Saved-search name.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

First observedv1.0.4Jul 30, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds genuinely new behavior: writes route to the running Zotero desktop app (Zotero 10+) for personal libraries and always to the cloud for group libraries, and it warns that cloud searches aren't executed. It doesn't spell out delete irreversibility or failure modes, but its added context clearly exceeds the annotation baseline.

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 the key cloud-vs-desktop caveat, then enumerates the actions. Dense but each clause earns its place; the length is justified by the execution gap and write-routing behavior it must convey.

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 an output schema present, return values needn't be explained, and the description covers the non-obvious behavioral gotchas (searches stored but not executed, write routing). It is essentially complete for a 6-param, annotation-covered tool, with only minor gaps like delete consequences left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents name, action, conditions, search_key, library_id, and library_type. The description restates the action semantics and condition shape, adding marginal value beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 specific verbs (list/create/delete) on a specific resource (saved-search DEFINITIONS) and explicitly distinguishes itself from the sibling that would otherwise be confusable: it names zotero_search_items as the tool that executes a search. The 'DEFINITIONS' emphasis makes the scope unambiguous.

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 explicit when-to-use per action ('list'/'create'/'delete') with required arguments, and adds a critical when-not/what-to-use-instead: the cloud API stores but does not execute searches, so use zotero_search_items or the local API for matches. 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.

Deploy Server