Skip to main content
Glama
oscardvs

Zoteus

by oscardvs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Incremental sync delta

zotero_sync
Read-only

Retrieve changes since a given library version—changed keys and deletions—so you can sync only updated items.

Instructions

Return what changed in a library since a given version, for efficient incremental sync. Provide since (a library version; 0 = everything). Returns, per object type (items/collections/searches/tags), the map of keys→version that changed after since, plus the deletion log (keys removed since since). This is the version-based delta the Zotero sync algorithm uses: fetch the changed keys, then pull only those with zotero_get_item/zotero_search_items. Follows the library route: a running Zotero desktop app serves the delta for any library it holds, with no cloud API key, and otherwise the cloud Web API does; backend says which one answered. The whole delta comes from that one API, because the two number library versions independently. The desktop app serves item and collection versions but no tag versions and no deletion log; those are reported in unavailable, naming what is missing and why, and never as an empty result.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sinceNoLibrary version to diff from (default 0).
typesNoWhich object types to check (default all).
library_idNoNumeric 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_typeNoWhich 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.
include_deletedNoInclude the deletion log (default true).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
sinceYesThe version this delta was taken from, echoed back.
backendYesWhich API answered: "local" (Zotero desktop app) or "cloud". The two number versions independently.
changedYesPer object type (items/collections/searches/tags), what changed after `since`.
deletedNoThe deletion log per object type; absent when include_deleted was false or the backend has none.
unavailableNoWhat was asked for and could not be answered, instead of an empty result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.21.0
    • addedInput schema / properties / library_id / exclusiveMinimum
      Added value: +0
  2. Changed2 schema fields changedv1.20.2
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedOutput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
  3. Changed3 schema fields changedv1.20.0
    • 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": {
+    "backend": {
+      "description": "Which API answered: \"local\" (Zotero desktop app) or \"cloud\". The two number versions independently.",
+      "type": "string"
+    },
+    "changed": {
+      "additionalProperties": {
+        "additionalProperties": true,
+        "properties": {
+          "count": {
+            "description": "How many objects of this type changed.",
+            "type": "number"
+          },
+          "keys": {
+            "description": "Their keys; fetch them with zotero_get_item or zotero_search_items.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "count",
+          "keys"
+        ],
+        "type": "object"
+      },
+      "description": "Per object type (items/collections/searches/tags), what changed after `since`.",
+      "type": "object"
+    },
+    "deleted": {
+      "additionalProperties": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "description": "The deletion log per object type; absent when include_deleted was false or the backend has none.",
+      "type": "object"
+    },
+    "since": {
+      "description": "The version this delta was taken from, echoed back.",
+      "type": "number"
+    },
+    "unavailable": {
+      "description": "What was asked for and could not be answered, instead of an empty result.",
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "reason": {
+            "description": "Why, and where the answer does live.",
+            "type": "string"
+          },
+          "what": {
+            "description": "The part of the delta this backend cannot serve.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "what",
+          "reason"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "since",
+    "backend",
+    "changed"
+  ],
+  "type": "object"
+}
  4. First observedv1.0.4

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond readOnlyHint/openWorldHint annotations by detailing behavioral specifics: returns per-type key→version maps, includes deletion log, reports backend in `backend`, and explicitly discloses limitations (desktop app lacks tag versions and deletion log, reported in `unavailable` and never as empty result). This is rich behavioral context that an agent needs to interpret the output correctly.

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 longer than average but every sentence adds distinct information (delta semantics, retrieval pattern, backend selection, limitations). It front-loads the core purpose and then details behavior. It is dense without fluff, but could be slightly tightened without losing value; a 4 reflects it's well-structured but not minimalist.

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 complex tool with 5 optional parameters and multiple backend scenarios, the description covers all essential aspects: what it returns, how to use it with sibling tools, backend behavior, and edge cases. The output schema presumably details the return shape, so no need to repeat that. It leaves nothing an agent would need to invoke it 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?

Adds significant meaning beyond the schema: `since` 0 = everything, `types` default all, `library_id`/`library_type` interplay (an id without type is treated as group), `include_deleted` default true. Even though schema coverage is 100%, the description enriches defaults and edge cases, so it fully compensates and extends the 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?

The description clearly states a specific action: 'Return what changed in a library since a given version, for efficient incremental sync.' It identifies the resource (library) and the delta concept, and explicitly differentiates from siblings like zotero_get_item/zotero_search_items by explaining it's the version-based delta, not item fetching. This distinguishes it unambiguously.

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?

Provides explicit usage context: for efficient incremental sync, and tells the agent to fetch changed keys then pull specific objects with zotero_get_item/zotero_search_items. It also explains the backend selection (desktop app vs cloud) and the condition (library route). This gives clear when-to-use guidance and routes to alternatives, with no ambiguity.

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

Deploy Server

Other Tools