@xevos117/mcp-zotero 2.0.2 → 2.0.3

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 } 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,7 +19,8 @@ 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"],
@@ -34,6 +36,7 @@ export async function handleDeleteCollection(zoteroApi, userId, args, unsafeOps
         if (version === null) {
             return formatErrorResponse("Could not determine collection version", {
                 collection_key,
+                hint: "Nothing was deleted. Retry the same call once.",
             });
         }
         await zoteroApi
@@ -53,10 +56,11 @@ 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.", {
+                return formatErrorResponse("Collection was modified by another client, so it was not deleted. Retry the same call.", {
                     collection_key,
                     status: "version_conflict",
                 });

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 } 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,10 +23,11 @@ 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 {
@@ -36,6 +38,7 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
             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),
@@ -43,6 +46,7 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
         if (libraryVersion === null) {
             return formatErrorResponse("Could not determine library version", {
                 item_keys,
+                hint: "Nothing was deleted. Retry the same call once.",
             });
         }
         // only keys the caller asked for, whatever the API returned
@@ -64,7 +68,7 @@ export async function handleDeleteItems(zoteroApi, userId, args, unsafeOps = "no
     catch (err) {
         if (isZoteroApiError(err)) {
             if (err.response.status === 412) {
-                return formatErrorResponse("Items were modified by another client. Retry the operation.", {
+                return formatErrorResponse("Items were modified by another client, so nothing was deleted. Retry the same call.", {
                     item_keys,
                     status: "version_conflict",
                 });

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) {

package/build/tools/import-pdf-to-zotero.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse, errorMessage, logToolError } from "../utils/error-formatter.js";
 import { downloadAndUploadPdf } from "../utils/pdf-uploader.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT, ITEM_KEY_HINT, MISSING_API_KEY, MISSING_API_KEY_HINT, describeAnyError, zoteroStatusHint } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "import_pdf_to_zotero",
-    description: "Download a PDF from a URL and upload it to Zotero storage as an imported_url attachment. Unlike linked URL attachments, imported files are stored in Zotero's storage and become fulltext-indexed (searchable via get_item_fulltext). Use this when you need the PDF content to be indexed by Zotero.",
+    description: "Download a PDF from a URL and upload it to Zotero storage as an imported_url attachment. Unlike linked URL attachments, imported files are stored in Zotero's storage and become fulltext-indexed (searchable via get_item_fulltext). Use this when you need the PDF content to be indexed by Zotero. The URL must lead straight to the PDF file (no login, paywall or HTML landing page); files up to 100 MB, counted against the user's Zotero file storage. For items with a DOI, find_and_attach_pdfs finds open-access PDFs by itself.",
     inputSchema: {
         url: z.string().url().describe("URL of the PDF to download and import"),
         filename: z
@@ -36,12 +37,33 @@ export const toolConfig = {
     },
 };
 const ImportPdfSchema = z.object(toolConfig.inputSchema);
+/** Next step for an HTTP error from the site serving the PDF. */
+function downloadFailureHint(status) {
+    if (status === 401 || status === 402 || status === 403) {
+        return "The site refuses the download (login, paywall or bot protection): try an open-access copy (find_and_attach_pdfs for an item with a DOI, or a repository link), or the user downloads it in a browser and adds it in Zotero desktop.";
+    }
+    if (status === 404 || status === 410)
+        return "The URL does not exist: check it for typos or find the current PDF link.";
+    if (status === 429 || (status !== undefined && status >= 500))
+        return "The site is busy or failing: wait a minute and retry once.";
+    return "Check that the URL leads straight to the PDF file and retry.";
+}
+/** Zotero storage step failed after the attachment record was created: say so, and what to do next. */
+function uploadFailureHint(status, itemKey) {
+    const next = status === 401 || status === 403
+        ? zoteroStatusHint(status).hint
+        : "Retry once after a short wait (timeouts and 5xx errors are usually temporary).";
+    return {
+        ...(itemKey ? { item_key: itemKey } : {}),
+        hint: `${itemKey ? "An attachment record (item_key) was created without the file; a retry creates a new one, so mention it to the user (they can delete it in Zotero). " : ""}${next}`,
+    };
+}
 export async function handleImportPdfToZotero(zoteroApi, userId, args) {
     const { url, filename, title, content_type, parent_item, collections, tags, library_type, library_id } = ImportPdfSchema.parse(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 {
         const result = await downloadAndUploadPdf(zoteroApi, libraryType, libraryId, apiKey, {
@@ -59,48 +81,59 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
                     return formatErrorResponse("Network error downloading file", {
                         url,
                         details: result.error.networkDetail,
-                        suggestion: "The server may be blocking automated requests, the URL may redirect to an HTML page, or it may require authentication. Try a direct PDF link from another source (e.g. PubMed Central, Sci-Hub, or the publisher's direct PDF endpoint).",
+                        suggestion: "The site may be unreachable, block automated downloads or require a login. Retry once if it looks temporary (timeout, connection reset); otherwise try a direct PDF link from an open source (PubMed Central, arXiv, an institutional repository, the publisher's PDF link) or, for an item with a DOI, find_and_attach_pdfs. If the user has the PDF, they can add it in Zotero desktop.",
                     });
                 case "download_failed":
-                    return formatErrorResponse("Failed to download file from URL", {
+                    return formatErrorResponse(`Failed to download file from URL (HTTP ${result.error.status})`, {
                         url,
                         status: result.error.status,
+                        suggestion: downloadFailureHint(result.error.status),
                     });
                 case "file_too_large":
                     return formatErrorResponse("File exceeds 100 MB limit", {
                         size_bytes: result.error.sizeBytes,
+                        suggestion: "This tool imports files up to 100 MB; nothing was created. The user can add larger files in Zotero desktop.",
                     });
                 case "storage_quota_exceeded":
                     return formatErrorResponse("Zotero storage quota exceeded", {
                         status: result.error.status,
                         suggestion: "Your Zotero cloud storage is full. Free up space by deleting stored files in your Zotero library, or upgrade your storage plan at https://www.zotero.org/settings/storage. Note: item metadata and linked URL attachments do not consume storage — only imported file attachments do.",
                         item_key: result.itemKey,
-                        note: "An attachment metadata record was created but the file could not be uploaded. You may want to delete it with delete_items or retry after freeing storage.",
+                        note: "An attachment record (item_key) was created without the file. Tell the user: they can delete it in Zotero (or with delete_items, if deletion is enabled) and retry after freeing storage.",
                     });
                 case "auth_failed":
                     return formatErrorResponse("Upload authorization failed", {
                         status: result.error.status,
                         details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "upload_failed":
                     return formatErrorResponse("File upload failed", {
                         status: result.error.status,
                         details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "not_pdf":
                     return formatErrorResponse("Downloaded file is not a valid PDF", {
                         url,
                         details: result.error.message,
-                        suggestion: "The URL may redirect to an HTML page or require browser access. Try a direct PDF link.",
+                        suggestion: "Nothing was created. The URL may redirect to an HTML page or require browser access: use the direct PDF link (on arXiv /pdf/ instead of /abs/), or for an item with a DOI try find_and_attach_pdfs.",
                     });
                 case "registration_failed":
                     return formatErrorResponse("Upload registration failed", {
                         status: result.error.status,
                         details: result.error.networkDetail, // e.g. the timeout or connection error
+                        ...uploadFailureHint(result.error.status, result.itemKey),
                     });
                 case "item_creation_failed":
                     return formatErrorResponse("import_pdf_to_zotero failed", {
                         details: result.error.message,
+                        ...(result.error.status !== undefined ? { status: result.error.status } : {}),
+                        hint: result.error.status !== undefined && result.error.status !== 400
+                            ? `Nothing was created. ${zoteroStatusHint(result.error.status).hint}`
+                            : parent_item
+                                ? `Zotero refused to create the attachment (details). parent_item must be an existing regular item, not an attachment or note: ${ITEM_KEY_HINT}`
+                                : `Zotero refused to create the attachment (details). Check the collections keys: ${COLLECTION_KEY_HINT}`,
                     });
             }
         }
@@ -118,6 +151,7 @@ export async function handleImportPdfToZotero(zoteroApi, userId, args) {
     }
     catch (err) {
         logToolError("import_pdf_to_zotero", err);
-        return formatErrorResponse("import_pdf_to_zotero failed", { details: errorMessage(err) });
+        const { error, ...described } = describeAnyError(err);
+        return formatErrorResponse(`import_pdf_to_zotero failed: ${error}`, { ...described, details: errorMessage(err) });
     }
 }

package/build/tools/index.js

@@ -13,7 +13,8 @@ import { handleImportPdfToZotero, toolConfig as importPdfToZoteroConfig } from "
 import { handleFindAndAttachPdfs, toolConfig as findAndAttachPdfsConfig } from "./find-and-attach-pdfs.js";
 import { handleDeleteCollection, toolConfig as deleteCollectionConfig } from "./delete-collection.js";
 import { handleDeleteItems, toolConfig as deleteItemsConfig } from "./delete-items.js";
-import { logToolError } from "../utils/error-formatter.js";
+import { formatErrorResponse, logToolError } from "../utils/error-formatter.js";
+import { describeError } from "../utils/error-hints.js";
 const tools = [
     { config: collectionsConfig, handler: handleGetCollections },
     { config: collectionItemsConfig, handler: handleGetCollectionItems },
@@ -32,14 +33,21 @@ const tools = [
     { config: deleteItemsConfig, handler: handleDeleteItems },
 ];
 const handlers = new Map(tools.map(({ config, handler }) => [config.name, handler]));
-/** Run a tool handler; Zotero API errors it throws are logged here once for every tool. */
+/**
+ * Run a tool handler; Zotero API errors it throws are logged here once for every tool. API, timeout and
+ * network errors become a structured error with a hint on what to do next; anything else (a bug) is rethrown.
+ */
 async function runTool(name, handler, zoteroApi, userId, args, unsafeOps) {
     try {
         return await handler(zoteroApi, userId, args, unsafeOps);
     }
     catch (err) {
         logToolError(name, err);
-        throw err;
+        const described = describeError(err);
+        if (!described)
+            throw err;
+        const { error, ...details } = described;
+        return formatErrorResponse(error, details);
     }
 }
 export async function handleToolCall(name, args, zoteroApi, userId, unsafeOps = "none") {