Catalogue a book in Zotero by ISBN, book DOI, or title.

Resolves an ISBN-10/13, a book DOI, or a title (Crossref, then Open Library, then Google Books) into a proper Zotero book item with publisher, edition, ISBN, series, and page count — never a journalArticle, which would corrupt citations. Books are catalogued, NOT queued or delivered: to put an open-access textbook PDF on the e-reader, use attach_pdf with item_type="book". Pass collections to file it topically (created on demand). A title that matches only loosely returns the closest candidate for you to confirm rather than guessing. Deduplicates by ISBN.

Track papers in Zotero WITHOUT staging them for e-reader delivery.

The "just catalogue it" path, distinct from queue_papers: resolves each ref (arXiv id, DOI, URL, or title) and files it into the library (and any collections, created on demand) but never adds it to the Reading Queue and never sends it. A paper with no open-access PDF is catalogued normally here — it is a library record, not a delivery failure, so nothing is tagged no-oa-pdf. Use this for references you want to keep (owned, paywalled, or read-later) rather than deliver. Duplicates report the collections they already live in. Relay any unresolvable refs to the user.

Ingest a PDF you already have into Zotero, with the PDF attached.

For grey literature and works no registry indexes (author-circulated preprints, lecture notes, working papers, open-access textbooks). Downloads the PDF from an http(s) URL (or reads a local path when running locally), creates a Zotero item of item_type from the metadata YOU supply, and attaches the PDF to it — no registry lookup, so a title/authors the model already knows is enough. item_type is one of journalArticle, book, bookSection, report, thesis, preprint, conferencePaper, manuscript, document (default journalArticle); use 'book' for an open-access textbook PDF. Files into collections (created on demand) and, unlike queue_papers, does NOT queue. With send=True it also delivers the PDF to your e-reader in the same call. Requires Zotero.

File already-queued papers into a Zotero collection.

Only papers ALREADY in the Reading Queue can be filed — to file a fresh paper, queue_papers it first, or pass collections=[...] to queue_papers to queue and file in one step. The collection is created on demand, but only if at least one paper matches (a call that files nothing leaves no empty collection behind). Items stay in the queue — Zotero items can live in many collections — so delivery state is unaffected. Refs match like remove_from_queue: exact arXiv id, DOI, URL, or title.

List the user's Zotero collections (name, item count, parent).

Check this before queueing or sending new papers: if a topical collection clearly fits the paper, pass it via collections=[...]; if several could fit or none do, ask the user where to file — never guess silently. Naming a new collection in other tools creates it on demand.

List the Zotero Reading Queue with delivery status per item.

Status is 'unsent', 'sent', or 'no-open-access-pdf'. Use this to show the user their queue, before send_queue (which flushes every unsent item), or to find refs for remove_from_queue. Each entry also carries key, the Zotero item key — the one id that stays unique when the queue holds duplicate entries of the same paper; every ref-taking tool accepts it. added dates are UTC.

Add papers to the Zotero Reading Queue without sending them.

Accepts arXiv ids, DOIs, URLs, or paper titles. Papers already in the queue are reported as such, not re-added. collections optionally files the papers into topical Zotero collections (created on demand) as well — check list_collections and ask the user when placement is unclear. Unresolvable papers are reported back — relay those to the user.

Discover papers the user may want to read — old or new.

Blends two signals: citation-graph recommendations (Semantic Scholar) seeded from seed_refs, or — by default — the user's Zotero library (what they queue and read IS their interest profile); and keyword discovery (OpenAlex) from interests — pass 2-4 short phrases distilled from the current conversation. recent_only=True favors newly published work; False searches the all-time pool (computer science only, an upstream limit). Papers already in the user's library are excluded (the queue plus the 100 most recently added items). max_results is capped at 20.

Returns {"picks": [...], "problems": [...]}: picks carry refs for send_papers / queue_papers, and each pick has a via field saying why it appeared — 'interest-keyword' (matched a stated interest), 'related-to-seeds' (citation graph of explicit seeds), or 'related-to-library' (citation graph of the OWNER'S Zotero library; can look off-topic to anyone else). When interests are given they lead the results. problems reports any discovery arm that failed or seed that didn't resolve — ALWAYS relay problems, or a stated interest may silently go uncovered. Present picks and let the user choose; don't send unasked.

Remove papers from the Zotero Reading Queue by ref or title.

Matches each ref (arXiv id, DOI, URL, or exact title) against queue items. Items filed into other collections keep their library record (and sent-state) and only leave the queue; items that live nowhere else are moved to Zotero's Trash (restorable in the Zotero app for ~30 days). Trashed items no longer count for duplicate protection — sending those again later will deliver them again. Nothing is ever deleted from the e-reader, and nothing is ever permanently deleted from Zotero.

A ref that matches more than one queue item (duplicate titles or a duplicated record) removes nothing; the receipt lists each candidate's Zotero item key, which is accepted as a ref and is unique even for exact duplicates. Relay the choice to the user — never pick for them.

Search for papers across the scholarly literature.

source is 'all' (OpenAlex: journals, conferences, and preprint servers including arXiv — broad coverage, but ranking can miss on arXiv-native topics) or 'arxiv' (arXiv's own search — better for recent preprints or when 'all' returns off-topic results); unknown values fall back to 'all'. max_results is clamped to the 1-25 range. Each result has a ref (arXiv id, DOI, or exact title) to pass to send_papers / queue_papers. open_access_pdf means an OA PDF link was found; delivery can still fail if the link is dead (arXiv-hosted papers are the most reliable).

Send papers to the e-reader by arXiv id, DOI, or title.

refs accepts arXiv ids ('2401.12345', 'arXiv:...'), arXiv abs/pdf URLs, DOIs, doi.org URLs, and paper titles — the same ref values search and recommendation results carry. Publisher landing-page URLs are NOT resolvable — use the DOI or title. Version suffixes ('2401.12345v2') are ignored; the latest arXiv version is delivered. collections optionally files the papers into topical Zotero collections (created on demand) in addition to the Reading Queue — check list_collections and ask the user when placement is unclear.

Refs are deduplicated, and papers already tagged as sent in Zotero are skipped unless force=True. Large batches are split automatically to fit the 25-attachment / 50 MB per-email limits. dry_run=True previews what would be sent, with estimated sizes, without downloading or delivering — use it before big sends.

Papers without an open-access PDF are not sent; if Zotero is configured they are still queued (tagged no-oa-pdf) so they can be delivered manually later. Without Zotero there is NO cross-call duplicate protection — re-sending the same ref ships another copy. Relay the full receipt — sizes, skips, and failures — to the user.

Send EVERY unsent paper in the Zotero Reading Queue.

This flushes the whole queue — for specific papers use send_papers. Items tagged sent or no-oa-pdf are skipped; items whose PDF turns out to be unavailable are tagged no-oa-pdf so they are not retried forever. Batches are split under the email limits automatically. Check list_queue first when unsure what will go.

Report which paperboy features are configured and what's missing.

Returns configuration state only — never secret values. Use this to guide the user through finishing setup. Credentials themselves must be entered by running 'paperboy setup' in a terminal, never pasted into the chat.

Remove papers from one Zotero collection, and nothing else.

The inverse of file_papers, for misfiled items: membership in the named collection is dropped, while the item, its other collections (including the Reading Queue), and its sent-state are untouched. The Reading Queue itself is refused as a target — leaving the queue is remove_from_queue's job, with its keep-or-trash safeguards. To move a paper between collections, file it into the new one and unfile it from the old. Refs match like remove_from_queue: exact arXiv id, DOI, URL, or title, against the collection's items; an ambiguous ref (matching several items) removes nothing.