@xevos117/mcp-zotero 2.0.2 → 2.0.4

package/build/tools/delete-collection.js

@@ -4,9 +4,10 @@ import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { canDeleteCollections } from "../utils/unsafe-operations.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT, unsafeOperationsHint, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "delete_collection",
-    description: "Delete a collection (folder) from your Zotero library. Items inside the collection are NOT deleted — they remain in your library. Requires UNSAFE_OPERATIONS environment variable set to 'all'.",
+    description: "Delete a collection (folder) from your Zotero library; confirm with the user first. Items inside the collection are NOT deleted — they remain in your library. Disabled unless the server setting UNSAFE_OPERATIONS is 'all'.",
     inputSchema: {
         collection_key: zoteroKey()
             .describe("Zotero collection key to delete. Get this from get_collections."),
@@ -18,34 +19,46 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
     const { collection_key, library_type, library_id } = DeleteCollectionSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (!canDeleteCollections(unsafeOps)) {
-        return formatErrorResponse("Deletion of collections is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'all' to enable this operation.", {
+        return formatErrorResponse(`Deletion of collections is not allowed: it needs UNSAFE_OPERATIONS 'all' in this server's configuration (it is '${unsafeOps}'). Nothing was deleted.`, {
+            hint: unsafeOperationsHint("collections"),
             env_var: "UNSAFE_OPERATIONS",
             current_value: unsafeOps,
             required_values: ["all"],
         });
     }
     try {
-        const response = await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .get();
-        const collection = response.getData();
-        const version = response.getVersion();
-        if (version === null) {
-            return formatErrorResponse("Could not determine collection version", {
+        for (let attempt = 1;; attempt++) {
+            const response = await zoteroApi
+                .library(libraryType, libraryId)
+                .collections(collection_key)
+                .get();
+            const collection = response.getData();
+            const version = response.getVersion();
+            if (version === null) {
+                return formatErrorResponse("Could not determine collection version", {
+                    collection_key,
+                    hint: "Nothing was deleted. Retry the same call once.",
+                });
+            }
+            try {
+                await zoteroApi
+                    .library(libraryType, libraryId)
+                    .collections(collection_key)
+                    .version(version)
+                    .delete();
+            }
+            catch (err) {
+                // 412: the collection changed between the GET and the DELETE; read it again and retry once
+                if (attempt === 1 && isZoteroApiError(err) && err.response.status === 412)
+                    continue;
+                throw err;
+            }
+            return formatJsonResult({
+                deleted: true,
                 collection_key,
+                name: collection.name || collection_key,
             });
         }
-        await zoteroApi
-            .library(libraryType, libraryId)
-            .collections(collection_key)
-            .version(version)
-            .delete();
-        return formatJsonResult({
-            deleted: true,
-            collection_key,
-            name: collection.name || collection_key,
-        });
     }
     catch (err) {
         if (isZoteroApiError(err)) {
@@ -53,12 +66,16 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
                 return formatErrorResponse("Collection not found", {
                     collection_key,
                     status: "not_found",
+                    hint: `Nothing was deleted. ${COLLECTION_KEY_HINT}`,
                 });
             }
             if (err.response.status === 412) {
-                return formatErrorResponse("Collection was modified by another client. Retry the operation.", {
+                const { hint } = zoteroStatusHint(412);
+                return formatErrorResponse("Collection was modified by another client (HTTP 412 Precondition Failed), also on a second try with its new version, so it was not deleted.", {
                     collection_key,
                     status: "version_conflict",
+                    http_status: 412,
+                    hint,
                 });
             }
         }

package/build/tools/delete-items.js

@@ -5,9 +5,10 @@ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.
 import { canDeleteItems } from "../utils/unsafe-operations.js";
 import { fetchItemsByKeys } from "../utils/pagination.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { ITEM_KEY_HINT, unsafeOperationsHint, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "delete_items",
-    description: "Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero trash). Accepts up to 50 item keys per call. Requires UNSAFE_OPERATIONS environment variable set to 'items' or 'all'.",
+    description: "Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero trash), so confirm with the user first. Accepts up to 50 item keys per call. Disabled unless the server setting UNSAFE_OPERATIONS is 'items' or 'all'.",
     inputSchema: {
         item_keys: z
             .array(zoteroKey())
@@ -22,53 +23,72 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
     const { item_keys, library_type, library_id } = DeleteItemsSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (!canDeleteItems(unsafeOps)) {
-        return formatErrorResponse("Deletion of items is not allowed. Set the UNSAFE_OPERATIONS environment variable to 'items' or 'all' to enable this operation.", {
+        return formatErrorResponse(`Deletion of items is not allowed: destructive operations are disabled in this server's configuration (UNSAFE_OPERATIONS is '${unsafeOps}'). Nothing was deleted.`, {
             env_var: "UNSAFE_OPERATIONS",
             current_value: unsafeOps,
             required_values: ["items", "all"],
+            hint: unsafeOperationsHint("items"),
         });
     }
     try {
-        const { items, version: libraryVersion } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), item_keys);
-        const foundKeys = new Set(items.map((item) => item.key).filter(Boolean));
-        const notFoundKeys = item_keys.filter((k) => !foundKeys.has(k));
-        if (foundKeys.size === 0) {
-            return formatErrorResponse("No items found for the given keys", {
-                item_keys,
-                status: "not_found",
-            });
-        }
-        // Use library version from response header (Last-Modified-Version),
-        // not individual item versions — required for multi-object DELETE
-        if (libraryVersion === null) {
-            return formatErrorResponse("Could not determine library version", {
-                item_keys,
-            });
-        }
-        // only keys the caller asked for, whatever the API returned
-        const keysToDelete = item_keys.filter((k) => foundKeys.has(k));
-        await zoteroApi
-            .library(libraryType, libraryId)
-            .items()
-            .version(libraryVersion)
-            .delete(keysToDelete);
-        const result = {
-            deleted_keys: keysToDelete,
-            deleted_count: keysToDelete.length,
-        };
-        if (notFoundKeys.length > 0) {
-            result.not_found = notFoundKeys;
-        }
-        return formatJsonResult(result);
-    }
-    catch (err) {
-        if (isZoteroApiError(err)) {
-            if (err.response.status === 412) {
-                return formatErrorResponse("Items were modified by another client. Retry the operation.", {
+        const notFoundKeys = [];
+        let pending = item_keys;
+        for (let attempt = 1;; attempt++) {
+            const { items, version: libraryVersion } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), pending);
+            const foundKeys = new Set(items.map((item) => item.key).filter(Boolean));
+            notFoundKeys.push(...pending.filter((k) => !foundKeys.has(k)));
+            if (foundKeys.size === 0) {
+                return formatErrorResponse("No items found for the given keys", {
+                    item_keys,
+                    status: "not_found",
+                    hint: `Nothing was deleted: none of these keys exists in this library (already deleted, or in another library). ${ITEM_KEY_HINT}`,
+                });
+            }
+            // Use library version from response header (Last-Modified-Version),
+            // not individual item versions — required for multi-object DELETE
+            if (libraryVersion === null) {
+                return formatErrorResponse("Could not determine library version", {
                     item_keys,
-                    status: "version_conflict",
+                    hint: "Nothing was deleted. Retry the same call once.",
                 });
             }
+            // only keys the caller asked for, whatever the API returned
+            const keysToDelete = pending.filter((k) => foundKeys.has(k));
+            try {
+                await zoteroApi
+                    .library(libraryType, libraryId)
+                    .items()
+                    .version(libraryVersion)
+                    .delete(keysToDelete);
+            }
+            catch (err) {
+                // 412: the library changed between the GET and the DELETE (another client, a sync). Read the new
+                // version and the keys that still exist, and retry once with those.
+                if (attempt === 1 && isZoteroApiError(err) && err.response.status === 412) {
+                    pending = keysToDelete;
+                    continue;
+                }
+                throw err;
+            }
+            const result = {
+                deleted_keys: keysToDelete,
+                deleted_count: keysToDelete.length,
+            };
+            if (notFoundKeys.length > 0) {
+                result.not_found = notFoundKeys;
+            }
+            return formatJsonResult(result);
+        }
+    }
+    catch (err) {
+        if (isZoteroApiError(err) && err.response.status === 412) {
+            const { hint } = zoteroStatusHint(412);
+            return formatErrorResponse("Items were modified by another client (HTTP 412 Precondition Failed), also on a second try with the new library version, so nothing was deleted.", {
+                item_keys,
+                status: "version_conflict",
+                http_status: 412,
+                hint,
+            });
         }
         throw err;
     }

package/build/tools/find-and-attach-pdfs.js

@@ -4,9 +4,11 @@ import { formatJsonResult, formatErrorResponse, formatEmptyResult, errorMessage,
 import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
 import { fetchAllPages, fetchItemsByKeys } from "../utils/pagination.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { describeAnyError, MISSING_API_KEY, MISSING_API_KEY_HINT } from "../utils/error-hints.js";
+import { UNPAYWALL_EMAIL_HINT, UNPAYWALL_EMAIL_MISSING } from "../utils/unpaywall.js";
 export const toolConfig = {
     name: "find_and_attach_pdfs",
-    description: "For each Zotero item, check Unpaywall for open access PDFs and attach them. Items must have a DOI. Uses the same source as Zotero Desktop's 'Find Available PDFs'.",
+    description: "For each Zotero item, check Unpaywall for open access PDFs and attach them. Items must have a DOI; needs UNPAYWALL_EMAIL in the server settings. Uploads use the user's Zotero file storage; dry_run only reports what is available. Uses the same source as Zotero Desktop's 'Find Available PDFs'.",
     inputSchema: {
         item_keys: z
             .array(zoteroKey())
@@ -32,14 +34,14 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     // Validate: exactly one of item_keys or collection_key
     if (item_keys && collection_key) {
-        return formatErrorResponse("Provide either item_keys or collection_key, not both");
+        return formatErrorResponse("Provide either item_keys or collection_key, not both: call once per selection.");
     }
     if (!item_keys && !collection_key) {
-        return formatErrorResponse("Provide either item_keys or collection_key");
+        return formatErrorResponse("Provide either item_keys or collection_key: item_keys for specific items (from search_library), collection_key for every item of a collection (from get_collections).");
     }
     const apiKey = process.env.ZOTERO_API_KEY;
     if (!apiKey) {
-        return formatErrorResponse("ZOTERO_API_KEY environment variable is not set");
+        return formatErrorResponse(MISSING_API_KEY, { hint: MISSING_API_KEY_HINT });
     }
     try {
         // 1. Resolve item keys
@@ -55,7 +57,11 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
             keys = item_keys;
         }
         if (keys.length === 0) {
-            return formatEmptyResult("No items to process");
+            return formatEmptyResult("No items to process", {
+                suggestion: collection_key
+                    ? "The collection is empty or holds only attachments and notes: check it with get_collection_items."
+                    : "item_keys is empty: pass at least one item key (from search_library or get_collection_items).",
+            });
         }
         // 2. Batch-fetch item metadata to get DOIs
         const { items: metaItems } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), keys);
@@ -71,9 +77,9 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
         for (const key of keys) {
             const item = itemMap.get(key);
             if (!item)
-                preResults.set(key, { item_key: key, doi: null, status: "error", reason: "Item not found" });
+                preResults.set(key, { item_key: key, doi: null, status: "error", reason: "Item not found in this library" });
             else if (!item.DOI)
-                preResults.set(key, { item_key: key, doi: null, status: "error", reason: "No DOI" });
+                preResults.set(key, { item_key: key, doi: null, status: "error", reason: "No DOI: Unpaywall needs one. Add the DOI to the item, or attach a PDF from a known URL with import_pdf_to_zotero" });
             else
                 targets.push({ itemKey: key, doi: item.DOI });
         }
@@ -118,14 +124,16 @@ export async function handleFindAndAttachPdfs(zoteroApi, userId, args) {
             dry_run,
             ...(quotaExceeded > 0
                 ? {
-                    storage_quota_warning: "Zotero storage quota is full. Remaining PDF uploads were skipped. Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+                    storage_quota_warning: "Zotero storage quota is full. Remaining PDF uploads were skipped. Tell the user they can free up space or upgrade at https://www.zotero.org/settings/storage, then run this tool again.",
                 }
                 : {}),
+            ...(results.some((r) => r.reason === UNPAYWALL_EMAIL_MISSING) ? { hint: UNPAYWALL_EMAIL_HINT } : {}),
             results,
         });
     }
     catch (err) {
         logToolError("find_and_attach_pdfs", err);
-        return formatErrorResponse("find_and_attach_pdfs failed", { details: errorMessage(err) });
+        const { error, ...described } = describeAnyError(err);
+        return formatErrorResponse(`find_and_attach_pdfs failed: ${error}`, { ...described, details: errorMessage(err) });
     }
 }

package/build/tools/get-collection-items.js

@@ -5,15 +5,16 @@ import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../uti
 import { formatCreators, formatTags } from "../utils/item-formatter.js";
 import { fetchAllPages } from "../utils/pagination.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "get_collection_items",
-    description: "Get all items in a specific Zotero collection. Returns item keys, titles, authors, and dates. Use the collectionKey from get_collections. Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.",
+    description: "Get all items in a specific Zotero collection (only items directly in it, not those in its subcollections). Returns item keys, titles, authors, and dates. Use the collectionKey from get_collections. Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.",
     inputSchema: {
-        collectionKey: zoteroKey().describe("The collection key/ID"),
+        collectionKey: zoteroKey().describe("Collection key from get_collections"),
         excludeAttachments: z
             .boolean()
             .default(true)
-            .describe("Exclude attachment and note items (default: true)"),
+            .describe("Exclude attachment and note items (default: true). Set false to list them too."),
         ...libraryArgsSchema,
     },
 };
@@ -26,7 +27,7 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
         if (!allItems || allItems.length === 0) {
             return formatEmptyResult("Collection is empty", {
                 collectionKey,
-                suggestion: "Add some items to this collection in Zotero",
+                suggestion: "No items directly in this collection. Items of its subcollections are not listed: find them with get_collections (parentCollection = this key). To add items, pass collection_key to add_items_by_doi or add_items.",
                 status: "empty",
             });
         }
@@ -50,7 +51,7 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
         if (formatted.length === 0) {
             return formatEmptyResult("No valid items found in collection", {
                 collectionKey,
-                suggestion: "Check that items in this collection have the expected metadata",
+                suggestion: "The collection contains only attachments or notes, which excludeAttachments=true (the default) hides: call again with excludeAttachments=false to list them.",
                 status: "invalid_items",
             });
         }
@@ -63,9 +64,9 @@ export async function handleGetCollectionItems(zoteroApi, userId, args) {
     catch (err) {
         if (isZoteroApiError(err)) {
             if (err.response?.status === 404) {
-                return formatErrorResponse("Collection is empty or not accessible", {
+                return formatErrorResponse("Collection not found: no collection with this key in this library, or the API key cannot access it.", {
                     collectionKey,
-                    suggestion: "Verify the collection exists and try adding some items to it",
+                    suggestion: COLLECTION_KEY_HINT,
                     status: "not_found",
                 });
             }

package/build/tools/get-collections.js

@@ -21,7 +21,7 @@ export async function handleGetCollections(zoteroApi, userId, args) {
     const { items: allCollections } = await fetchAllPages((params) => zoteroApi.library(libraryType, libraryId).collections().get(params));
     if (!Array.isArray(allCollections) || allCollections.length === 0) {
         return formatEmptyResult("No collections found", {
-            suggestion: "Create a collection in your Zotero library first",
+            suggestion: "This library has no collections. Items can still be found with search_library; to organize them, create one with create_collection.",
             helpUrl: "https://www.zotero.org/support/collections",
         });
     }
@@ -32,7 +32,7 @@ export async function handleGetCollections(zoteroApi, userId, args) {
         : allCollections.filter((c) => !c.deleted);
     if (collections.length === 0) {
         return formatEmptyResult("No collections found", {
-            suggestion: "All collections are in the trash. Use include_trashed=true to see them.",
+            suggestion: "All collections of this library are in the Zotero trash: call again with include_trashed=true to see them, or create a new one with create_collection.",
         });
     }
     return formatJsonResult(collections);

package/build/tools/get-item-fulltext.js

@@ -6,16 +6,19 @@ import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
 import { findPdfAttachments, isLinkedUrl, isPdfAttachment } from "../utils/attachments.js";
 import { fetchWithTimeout, isTimeoutAbort, timeoutError, TIMEOUTS } from "../utils/timeouts.js";
+import { ITEM_KEY_HINT, MISSING_API_KEY, MISSING_API_KEY_HINT, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "get_item_fulltext",
-    description: "Get the full text content of a Zotero item's PDF attachment via Zotero's fulltext index. Zotero desktop automatically indexes PDFs when synced. Use this to read the full content of papers instead of relying on abstracts.",
+    description: "Get the text of a Zotero item's stored PDF from Zotero's full-text index. Works for PDFs indexed by Zotero desktop and synced, or imported with import_pdf_to_zotero / find_and_attach_pdfs; not for linked URLs or web pages. Use this to read the full content of papers instead of relying on abstracts.",
     inputSchema: {
-        item_key: zoteroKey().describe("The Zotero item key (parent item or attachment key)"),
+        item_key: zoteroKey().describe("Item key (the parent item or its PDF attachment), from search_library or get_collection_items"),
         max_characters: z
             .number()
+            .int()
+            .min(0)
             .optional()
             .default(50000)
-            .describe("Maximum characters to return (default: 50000, 0 = no limit)"),
+            .describe("Maximum characters to return: a positive integer, or 0 for no limit (default: 50000); truncated: true in the result when cut"),
         ...libraryArgsSchema,
     },
 };
@@ -25,7 +28,7 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     const apiKey = process.env.ZOTERO_API_KEY;
     if (!apiKey) {
-        return formatErrorResponse("ZOTERO_API_KEY environment variable is not set");
+        return formatErrorResponse(MISSING_API_KEY, { hint: MISSING_API_KEY_HINT });
     }
     try {
         // Fetch parent item metadata for context
@@ -37,7 +40,7 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
         // If the item itself is a PDF attachment, use it directly (a web link has no stored file)
         if (isPdfAttachment(itemData)) {
             if (isLinkedUrl(itemData)) {
-                return formatErrorResponse("This attachment is a link to a PDF on the web (linked URL): Zotero stores no file or full text for it. Fetch the URL directly.", { item_key, url: itemData.url || undefined });
+                return formatErrorResponse("This attachment is a link to a PDF on the web (linked URL): Zotero stores no file or full text for it. Fetch the URL directly if you have a web tool, or store the PDF with import_pdf_to_zotero and call again.", { item_key, url: itemData.url || undefined });
             }
             return fetchFulltext(item_key, item_key, libraryType, libraryId, apiKey, max_characters);
         }
@@ -46,24 +49,25 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
         const pdfAttachment = pdfs.find((p) => !isLinkedUrl(p));
         const linkedPdf = pdfs.find(isLinkedUrl);
         if (!pdfAttachment?.key && linkedPdf) {
-            return formatErrorResponse("No stored PDF attachment found. This item only links to a PDF on the web (linked URL attachment), which Zotero does not index — fetch the linked URL directly.", { item_key, attachment_key: linkedPdf.key, url: linkedPdf.url || undefined });
+            return formatErrorResponse("No stored PDF attachment found. This item only links to a PDF on the web (linked URL attachment), which Zotero does not index — fetch the linked URL directly if you have a web tool, or store the PDF with import_pdf_to_zotero (parent_item = this item) and call again.", { item_key, attachment_key: linkedPdf.key, url: linkedPdf.url || undefined });
         }
         if (!pdfAttachment?.key) {
             // Provide context-aware error messages
             if (itemData.itemType === "webpage" || itemData.itemType === "blogPost") {
-                return formatErrorResponse("This is a web page item. Use the item's URL to fetch its content directly.", { item_key, url: itemData.url || undefined });
+                return formatErrorResponse("This is a web page item: Zotero has no PDF text for it. Fetch its URL directly if you have a web tool; otherwise tell the user.", { item_key, url: itemData.url || undefined });
             }
             if (itemData.url) {
-                return formatErrorResponse(`No PDF attachment found. This item has a URL — you can fetch its content directly from the web.`, { item_key, url: itemData.url });
+                return formatErrorResponse("No PDF attachment found. This item has a URL — you can fetch its content directly from the web, or attach the PDF " +
+                    "(find_and_attach_pdfs if the item has a DOI, import_pdf_to_zotero for a PDF URL) and call again.", { item_key, url: itemData.url });
             }
-            return formatErrorResponse("No PDF attachment found for this item.", { item_key });
+            return formatErrorResponse("No PDF attachment found for this item. Attach one with find_and_attach_pdfs (items with a DOI) or import_pdf_to_zotero (a PDF URL), then call again.", { item_key });
         }
         return fetchFulltext(item_key, pdfAttachment.key, libraryType, libraryId, apiKey, max_characters);
     }
     catch (err) {
         if (isZoteroApiError(err)) {
             if (err.response?.status === 404) {
-                return formatErrorResponse("Item not found", { item_key });
+                return formatErrorResponse("Item not found in this library", { item_key, hint: ITEM_KEY_HINT });
             }
         }
         throw err;
@@ -73,10 +77,20 @@ async function fetchFulltext(itemKey, attachmentKey, libraryType, userId, apiKey
     const url = `https://api.zotero.org/${libraryType}s/${userId}/items/${attachmentKey}/fulltext`;
     const response = await fetchWithTimeout(url, { headers: { "Zotero-API-Key": apiKey } }, TIMEOUTS.zoteroApiMs, "Zotero fulltext request");
     if (response.status === 404) {
-        return formatErrorResponse("Full text not indexed for this item. Open the PDF in Zotero desktop to trigger indexing, then sync.", { item_key: itemKey, attachment_key: attachmentKey });
+        return formatErrorResponse("Full text not indexed for this item: Zotero has no text for this PDF yet. Retrying now will not help.", {
+            item_key: itemKey,
+            attachment_key: attachmentKey,
+            hint: "Tell the user to open the PDF in Zotero desktop (or right-click it → Reindex Item) and let Zotero sync, then try again. " +
+                "A scanned PDF without a text layer cannot be indexed.",
+        });
     }
     if (!response.ok) {
-        return formatErrorResponse(`Zotero fulltext API returned status ${response.status}`, { item_key: itemKey, attachment_key: attachmentKey });
+        const { error, hint } = zoteroStatusHint(response.status);
+        return formatErrorResponse(`Zotero fulltext API returned status ${response.status}. ${error}`, {
+            item_key: itemKey,
+            attachment_key: attachmentKey,
+            hint,
+        });
     }
     let data;
     try {
@@ -91,6 +105,7 @@ async function fetchFulltext(itemKey, attachmentKey, libraryType, userId, apiKey
         return formatErrorResponse(timeoutError("Zotero fulltext request", url, TIMEOUTS.zoteroApiMs).message, {
             item_key: itemKey,
             attachment_key: attachmentKey,
+            hint: "Retry once; large PDFs can be slow. If it keeps timing out, tell the user to check the network connection of the machine running this server.",
         });
     }
     let text = data.content;

package/build/tools/get-items-details.js

@@ -4,9 +4,10 @@ import { formatJsonResult, formatErrorResponse, formatEmptyResult } from "../uti
 import { formatCreators } from "../utils/item-formatter.js";
 import { fetchItemsByKeys } from "../utils/pagination.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { ITEM_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "get_items_details",
-    description: "Get metadata for multiple Zotero items in a single call. Accepts an array of item keys and returns a map of key → metadata. Use this instead of one call per item. Returns all type-specific fields (e.g. bookTitle for bookSection, proceedingsTitle for conferencePaper, university for thesis). Set include_abstract to include abstracts (excluded by default to keep responses lightweight).",
+    description: "Get metadata for multiple Zotero items in a single call. Accepts an array of item keys and returns a map of key → metadata. Use this instead of one call per item. Returns all type-specific fields (e.g. bookTitle for bookSection, proceedingsTitle for conferencePaper, university for thesis). Set include_abstract to include abstracts (excluded by default to keep responses lightweight). Keys not found in the library are listed in not_found (present only when some are missing).",
     inputSchema: {
         item_keys: z
             .array(zoteroKey())
@@ -30,12 +31,13 @@ export async function handleGetItemsDetails(zoteroApi, userId, args) {
     const { item_keys, include_abstract, library_type, library_id } = GetItemsDetailsSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (item_keys.length === 0) {
-        return formatErrorResponse("At least one item key is required");
+        return formatErrorResponse("At least one item key is required: pass item_keys from search_library, get_collection_items or add_items_by_doi.");
     }
     const { items } = await fetchItemsByKeys((params) => zoteroApi.library(libraryType, libraryId).items().get(params), item_keys);
     if (items.length === 0) {
         return formatEmptyResult("No items found for the given keys", {
             item_keys,
+            suggestion: `None of these keys exists in this library (deleted, or from another library). ${ITEM_KEY_HINT}`,
         });
     }
     const result = {};
@@ -69,5 +71,7 @@ export async function handleGetItemsDetails(zoteroApi, userId, args) {
         }
         result[key] = entry;
     }
-    return formatJsonResult(result);
+    // Lowercase name: never collides with an item key (8 uppercase characters); the skill's inject.js skips it
+    const notFound = [...new Set(item_keys)].filter((k) => !(k in result));
+    return formatJsonResult(notFound.length > 0 ? { ...result, not_found: notFound } : result);
 }

package/build/tools/get-user-id.js

@@ -2,7 +2,7 @@ import { resolveLibrary } from "../utils/library-context.js";
 import { formatJsonResult } from "../utils/error-formatter.js";
 export const toolConfig = {
     name: "get_user_id",
-    description: "Returns the Zotero library configured in the server environment: user_id, library_type, library_id and library_path (\"users/<id>\" or \"groups/<id>\"). Pass library_path to the standalone inject-citations skill script (inject.js) to generate Zotero field code URIs. Not needed when using the inject_citations MCP tool, which reads the library internally.",
+    description: "Returns the Zotero library configured in the server environment: user_id, library_type, library_id and library_path (\"users/<id>\" or \"groups/<id>\"). Pass library_path to the zotero-mcp-integrations skill script (inject.js) to generate Zotero field code URIs. Not needed when using the inject_citations MCP tool, which reads the library internally.",
     inputSchema: {},
 };
 export async function handleGetUserId(_zoteroApi, userId, _args) {