@xevos117/mcp-zotero 2.0.1 → 2.0.3

package/build/tools/add-items-by-doi.js

@@ -6,12 +6,13 @@ import { cslToZoteroItem } from "../utils/csl-to-zotero.js";
 import { postInBatches } from "../utils/write-results.js";
 import { attachOpenAccessPdfs } from "../utils/oa-pdf.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { UNPAYWALL_EMAIL_HINT, UNPAYWALL_EMAIL_MISSING } from "../utils/unpaywall.js";
 export const toolConfig = {
     name: "add_items_by_doi",
     description: `Add items to your Zotero library by resolving DOIs. Works with ANY item type that has a DOI — journal articles, books, datasets, preprints, conference papers, reports, etc. For each DOI, resolves metadata via content negotiation and creates the item in Zotero with the correct type automatically. Returns a list of successfully added items (with item_key and title) and any failures.
 
 WHEN TO USE vs add_items:
-- Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches OA PDFs.
+- Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches open-access PDFs (when the server has UNPAYWALL_EMAIL set).
 - Use add_items when the item does NOT have a DOI, or when you need to override specific metadata fields (add_items_by_doi does not allow metadata overrides).
 - Mixed batch: if some items have DOIs and others don't, make two separate calls — add_items_by_doi for the DOIs and add_items for the rest.
 
@@ -20,8 +21,8 @@ WORKFLOW TIPS:
 - To create a cited Word document, use the returned item_keys as <zcite keys="ITEMKEY"/> placeholders in a .docx, then call inject_citations. See inject_citations description for the full workflow.`,
     inputSchema: {
         dois: z
-            .array(z.string())
-            .describe('Array of DOI strings (e.g. ["10.1038/s41586-023-06647-8"]). Each DOI will be resolved and added to Zotero.'),
+            .array(z.string().trim().min(1, "DOI must not be empty"))
+            .describe('Array of bare DOIs (e.g. ["10.1038/s41586-023-06647-8"], without "https://doi.org/"). Each DOI will be resolved and added to Zotero.'),
         collection_key: zoteroKey()
             .optional()
             .describe("Zotero collection key to add items to. Get this from create_collection or get_collections."),
@@ -32,7 +33,7 @@ WORKFLOW TIPS:
         auto_attach_pdf: z
             .boolean()
             .default(true)
-            .describe("Attach freely available OA PDFs via Unpaywall (default: true). This is lightweight and adds no cost — leave enabled. Only set to false if PDF attachment is causing errors."),
+            .describe("Attach open-access PDFs found via Unpaywall (default: true; needs UNPAYWALL_EMAIL in the server settings, uses the user's Zotero file storage). Leave enabled unless the user does not want PDFs or attachment is causing errors."),
         ...libraryArgsSchema,
     },
 };
@@ -41,12 +42,14 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
     const { dois, collection_key, tags, auto_attach_pdf, library_type, library_id } = AddItemsByDoiSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (dois.length === 0) {
-        return formatErrorResponse("At least one DOI is required");
+        return formatErrorResponse('At least one DOI is required: pass dois as an array, e.g. ["10.1038/s41586-023-06647-8"].');
     }
     const resolved = await resolveDois(dois);
     if (resolved.success.length === 0) {
         return formatErrorResponse("All DOI resolutions failed", {
             failed: resolved.failed,
+            hint: "Nothing was created; failed[].error gives the reason per DOI. Pass bare DOIs (10.xxxx/...) and check them for typos. " +
+                "For a DOI that does not resolve, add the item with add_items and its metadata instead. If every DOI failed with a timeout, network or 5xx error, retry later.",
         });
     }
     const zoteroItems = resolved.success.map((r) => cslToZoteroItem(r.data, {
@@ -61,7 +64,10 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
     ];
     if (write.created.length === 0) {
         const errorMessages = write.failed.map(({ index, error }) => `Item ${index}: ${error}`).join("; ");
-        return formatErrorResponse(`Zotero API write failed: ${errorMessages}`, { failed });
+        return formatErrorResponse(`Zotero API write failed: ${errorMessages}`, {
+            failed,
+            hint: "Nothing was created. Fix what failed[].error reports (an invalid collection_key: check it with get_collections) and retry; for a rate limit or server error, wait a minute and retry once.",
+        });
     }
     const success = write.created.map(({ index, entity }) => {
         const { doi, data } = resolved.success[index];
@@ -81,14 +87,16 @@ export async function handleAddItemsByDoi(zoteroApi, userId, args) {
             : { ...r, pdf_attached: false, error: r.reason });
     }
     const quotaHit = pdf_results?.some((r) => r.status === "quota_exceeded");
+    const unpaywallOff = pdf_results?.some((r) => r.reason === UNPAYWALL_EMAIL_MISSING);
     return formatJsonResult({
         success,
         failed,
         ...(pdf_results !== undefined ? { pdf_results } : {}),
         ...(quotaHit
             ? {
-                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Free up space at https://www.zotero.org/settings/storage or upgrade your plan.",
+                storage_quota_warning: "Zotero storage quota is full. Some PDF attachments were skipped. All items were created successfully (metadata only). Tell the user they can free up space or upgrade at https://www.zotero.org/settings/storage, then attach the PDFs with find_and_attach_pdfs.",
             }
             : {}),
+        ...(unpaywallOff ? { hint: UNPAYWALL_EMAIL_HINT } : {}),
     });
 }

package/build/tools/add-items.js

@@ -56,7 +56,7 @@ WHEN TO USE:
 - Mixed batch: if some items have DOIs and others don't, call add_items_by_doi for the DOIs and add_items for the rest (two separate calls)
 - Prefer add_items_by_doi when DOIs are available AND you don't need to override metadata (it auto-resolves everything and attaches OA PDFs)
 
-BATCH: Pass multiple items in the 'items' array (single API call).
+BATCH: Pass multiple items in the 'items' array (one tool call).
 
 COMMON FIELDS (available for most types):
 title, date, abstractNote, url, DOI, publisher, place, pages, volume, language, extra
@@ -130,7 +130,10 @@ export async function handleAddItems(zoteroApi, userId, args) {
     }));
     const failed = write.failed.map(({ index, error }) => ({ index, title: items[index].title, error }));
     if (success.length === 0 && failed.length > 0) {
-        return formatErrorResponse("All items failed to create", { failed });
+        return formatErrorResponse("All items failed to create", {
+            failed,
+            hint: "Nothing was created. failed[].error gives Zotero's reason per item: fix those items (an invalid collection_key: check it with get_collections) and call again; retrying unchanged will fail again.",
+        });
     }
     return formatJsonResult({
         success,

package/build/tools/add-linked-url-attachment.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT, ITEM_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "add_linked_url_attachment",
-    description: "Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone.",
+    description: "Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone. A linked URL stores no file and no full text (get_item_fulltext cannot read it): to store a PDF in Zotero use import_pdf_to_zotero.",
     inputSchema: {
         url: z.string().url().describe("URL of the resource to link"),
         title: z
@@ -18,7 +19,7 @@ export const toolConfig = {
             .describe('MIME type of the linked resource (e.g. "application/pdf", "text/html")'),
         parent_item: zoteroKey()
             .optional()
-            .describe("Item key of the parent item. If provided, the attachment becomes a child of that item."),
+            .describe("Key of the parent item (a regular item, not an attachment or note), from search_library or get_collection_items. If provided, the attachment becomes a child of that item."),
         collections: z
             .array(zoteroKey())
             .optional()
@@ -59,6 +60,9 @@ export async function handleAddLinkedUrlAttachment(zoteroApi, userId, args) {
         const errorMsg = formatWriteErrors(response.getErrors());
         return formatErrorResponse("Failed to create linked URL attachment", {
             details: errorMsg,
+            hint: parent_item
+                ? `details has Zotero's reason. parent_item must be an existing regular item, not an attachment or note: ${ITEM_KEY_HINT}`
+                : `details has Zotero's reason. Check the collections keys: ${COLLECTION_KEY_HINT}`,
         });
     }
     const created = response.getData();

package/build/tools/create-collection.js

@@ -3,9 +3,10 @@ import { zoteroKey } from "../utils/zotero-keys.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { formatWriteErrors } from "../utils/write-results.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
+import { COLLECTION_KEY_HINT } from "../utils/error-hints.js";
 export const toolConfig = {
     name: "create_collection",
-    description: "Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key with add_items_by_doi to organize imported papers.",
+    description: "Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key as collection_key in add_items_by_doi or add_items to organize imported papers.",
     inputSchema: {
         name: z.string().describe("Name of the new collection"),
         parent_collection: zoteroKey()
@@ -19,7 +20,7 @@ export async function handleCreateCollection(zoteroApi, userId, args) {
     const { name, parent_collection, library_type, library_id } = CreateCollectionSchema.parse(args);
     const { type: libraryType, id: libraryId } = resolveLibrary({ library_type, library_id }, userId);
     if (!name?.trim()) {
-        return formatErrorResponse("Collection name is required");
+        return formatErrorResponse("Collection name is required: pass a non-empty name.");
     }
     const collectionData = { name: name.trim() };
     if (parent_collection) {
@@ -33,6 +34,9 @@ export async function handleCreateCollection(zoteroApi, userId, args) {
         const errorMsg = formatWriteErrors(response.getErrors());
         return formatErrorResponse("Failed to create collection", {
             details: errorMsg,
+            hint: parent_collection
+                ? `details has Zotero's reason. Check that parent_collection exists: ${COLLECTION_KEY_HINT}`
+                : "details has Zotero's reason: fix the name if it is the cause and retry.",
         });
     }
     const created = response.getData();

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

@@ -1,19 +1,24 @@
+import { InvalidJsonResponseError, readJsonObject } from "../utils/json-response.js";
 import { z } from "zod";
 import { zoteroKey } from "../utils/zotero-keys.js";
 import { isZoteroApiError } from "../types/zotero-types.js";
 import { formatJsonResult, formatErrorResponse } from "../utils/error-formatter.js";
 import { resolveLibrary, libraryArgsSchema } from "../utils/library-context.js";
-import { findPdfAttachment, isPdfAttachment } from "../utils/attachments.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,
     },
 };
@@ -23,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
@@ -32,27 +37,37 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
             .items(item_key)
             .get();
         const itemData = itemResponse.getData();
-        // If the item itself is a PDF attachment, use it directly
+        // 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 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);
         }
-        const pdfAttachment = await findPdfAttachment(zoteroApi, { type: libraryType, id: libraryId }, item_key);
+        // Stored PDFs first: linked URLs never have server-side full text, even when listed first
+        const pdfs = await findPdfAttachments(zoteroApi, { type: libraryType, id: libraryId }, item_key);
+        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 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;
@@ -60,16 +75,39 @@ export async function handleGetItemFulltext(zoteroApi, userId, args) {
 }
 async function fetchFulltext(itemKey, attachmentKey, libraryType, userId, apiKey, maxCharacters) {
     const url = `https://api.zotero.org/${libraryType}s/${userId}/items/${attachmentKey}/fulltext`;
-    const response = await fetch(url, {
-        headers: { "Zotero-API-Key": apiKey },
-    });
+    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 {
+        data = await readJsonObject(response);
+    }
+    catch (err) {
+        if (err instanceof InvalidJsonResponseError) {
+            return formatErrorResponse(`Zotero fulltext API: ${err.message}`, { item_key: itemKey, attachment_key: attachmentKey });
+        }
+        if (!isTimeoutAbort(err))
+            throw err;
+        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.",
+        });
     }
-    const data = (await response.json());
     let text = data.content;
     let truncated = false;
     if (maxCharacters > 0 && text.length > maxCharacters) {

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