Zoteus

Permanently delete Zotero items

zotero_delete_items

Destructive

PERMANENTLY and IRREVERSIBLY delete items by key (this purges them; it is NOT the trash). Prefer zotero_trash_items, which is reversible.

Instructions

PERMANENTLY and IRREVERSIBLY delete items by key (this purges them; it is NOT the trash). Prefer zotero_trash_items, which is reversible. This tool is disabled unless the server is started with ZOTEUS_ALLOW_DELETE=true, and additionally requires confirm: true on every call. For the personal library, and for a group library the running Zotero desktop app holds, it goes through that app when it supports local-API writes (Zotero 10+), otherwise the cloud Web API. The current library version is used as a precondition; the operation auto-chunks to 50 keys per request.

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": {
      "item_keys": "<item_keys>"
    },
    "name": "zotero_delete_items"
  }
}

Input Schema

Name	Required	Description
`confirm`	No	Must be true to proceed with permanent deletion.
`item_keys`	Yes	Item keys to permanently delete.
`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.
`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
`count`	Yes	How many were purged.
`target`	No	Where the write went: "local" (Zotero desktop local API), "desktop" (connector protocol) or "cloud" (Zotero Web API).
`deleted`	Yes	Keys purged from the library; this is not the trash and cannot be undone.

Schema Changelog

Changes observed during successful MCP inspections.

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#"

Changed3 schema fields changedv1.20.0Sep 13, 2026

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": {
+    "count": {
+      "description": "How many were purged.",
+      "type": "number"
+    },
+    "deleted": {
+      "description": "Keys purged from the library; this is not the trash and cannot be undone.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "target": {
+      "description": "Where the write went: \"local\" (Zotero desktop local API), \"desktop\" (connector protocol) or \"cloud\" (Zotero Web API).",
+      "type": "string"
+    }
+  },
+  "required": [
+    "deleted",
+    "count"
+  ],
+  "type": "object"
+}

First observedv1.0.4Jul 30, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare destructiveHint=true; the description adds far more: that deletion purges rather than trashes, the required server env flag, the per-call confirm requirement, the routing logic between the desktop local API and cloud Web API, a version precondition, and 50-key auto-chunking. This is exactly the extra behavioral context annotations cannot carry.

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-loaded with the most consequential fact (irreversible purge), then the safer alternative, then the gating requirements. Slightly dense with routing detail, but no sentence is filler.

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?

Covers prerequisites, gating, routing, and batching for a destructive multi-param tool, and an output schema exists so return values need no explanation. An agent has everything required to call it correctly or avoid it.

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 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining the confirm gate and that item_keys are batched at 50 per request. It does not elaborate on library_id/library_type semantics, which the schema already documents well.

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 a specific verb+resource with scope: 'PERMANENTLY and IRREVERSIBLY delete items by key'. It immediately distinguishes itself from the trash operation, which is the main sibling confusion risk.

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?

Explicitly routes the agent to the reversible alternative ('Prefer zotero_trash_items, which is reversible') and states the hard gating conditions (server flag plus confirm:true on every call), so an agent knows when this tool is callable at all.

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

Deploy Server