Paperboy is an MCP server that helps you discover, manage, and deliver research papers to your e-reader (Kindle, PocketBook, or Kobo), with optional Zotero integration for library and queue management.
Search papers across OpenAlex or arXiv by query, returning refs (arXiv ID, DOI, etc.) for use in other tools.
Get recommendations via citation-graph discovery (Semantic Scholar, seeded from your Zotero library or explicit refs) and keyword-based discovery (OpenAlex) — papers you already own are excluded.
Send papers to your e-reader by arXiv ID, DOI, URL, or title; delivered via email (Kindle/PocketBook) or Dropbox (Kobo), with dry-run previews, deduplication, force re-send, and automatic batch splitting for large sets.
Queue papers in Zotero without immediate sending, optionally filing them into topical collections for later bulk delivery.
List Zotero collections to see existing collections (name, item count, parent) and make informed filing decisions.
File queued papers into topical Zotero collections (created on demand) without affecting their delivery state.
View the reading queue with per-item delivery status: unsent, sent, or no-open-access-pdf.
Remove papers from the Zotero Reading Queue by arXiv ID, DOI, URL, or title.
Flush the queue to send all unsent papers at once, auto-batching to respect attachment/size limits and skipping already-sent or inaccessible items.
Check setup status to see which features and credentials are configured and what's still missing — without exposing secrets.
Enables searching and resolving papers on arXiv by ID or general query using the arXiv Atom API.
Facilitates delivery of papers to Kobo e-readers by uploading PDFs to a Dropbox folder synced with the device.
Provides paper recommendations based on citation-graph analysis from Semantic Scholar, seeded from the user's Zotero library.
Manages a reading queue, collections, and tags in Zotero, allowing papers to be filed, queued for delivery, and tracked with tags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@paperboy find recent papers on quantum machine learning and send to my Kindle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that delivers research papers and books to your e-reader, with Zotero as the source of truth. Ask Claude for a reading list, then say "queue them and send to my Kindle." (MCP is the plugin protocol Claude uses: this program runs on your machine or your cloud project, and Claude calls its tools during conversation.) Works locally in Claude Code and Claude Desktop; a Cloud Run deployment adds claude.ai and the Claude mobile app, so papers can be sent from a phone (docs/deploy.md).
Two things are kept separate: delivering a paper to your device and cataloguing a work in Zotero. You can do either. A book you own, a paywalled reference, or a PDF you already have can all be tracked in the library without being staged for the e-reader.
Zotero itself is optional: without it you can still search and send papers one-off. The reading queue, collections, and duplicate protection across sessions need it.
You ask Claude for papers; it uses paperboy's tools to find, queue, and deliver them. What that looks like in practice:
Papers you queue land in a Reading Queue collection in Zotero, created on demand.
Once a paper reaches your device, paperboy tags it sent-to-ereader
in Zotero, so it skips papers already sent to your e-reader, even in
a later conversation. (Without Zotero there's no memory between
sends, so this protection needs it.)
Claude can file papers into your topical collections too. It proposes one from the paper's topic and your existing collection names, and asks you when the fit is unclear. A paper can sit in several collections at once, so filing never disturbs the queue.
Papers are found by arXiv id, DOI, or title (a close-enough title match, so a reading list Claude wrote in the chat can be sent as-is). When a title matches only loosely, paperboy offers the closest candidate to confirm rather than guessing or failing silently.
Books work too: add_book resolves an ISBN, a book DOI, or a title
into a proper Zotero book item (publisher, edition, ISBN, pages).
Books are catalogued, not delivered.
Have the PDF already (a working paper, lecture notes, an open-access
textbook)? attach_pdf files it in Zotero with the PDF attached,
using metadata you give it, and can send it to the e-reader in the
same step.
When a reference can't be resolved, the receipt says why and which tool fits, rather than sending you hunting for a better URL. A paper with no open-access PDF is a normal library record, not an error.
Zotero holds all of this, so the server keeps no state of its own: no database to run, and safe to redeploy at any time.
Backend | Devices | How |
| Kindle, PocketBook, anything with an email intake | SMTP to the device address. Kindle constraints enforced: 25 attachments / 50 MB per email; sender must be on the Approved Personal Document E-mail List |
| Kobo (native Dropbox sync on the device) | Uploads via the Dropbox API. Kobo only syncs |
Related MCP server: Academic Paper Search MCP Server
Tool | What it does |
| Search OpenAlex (general) or arXiv ( |
| Discover related or new papers: citation-graph recommendations (Semantic Scholar) seeded from your Zotero library, plus keyword discovery from interests Claude distills out of the conversation. Excludes papers you already have |
| One-off send by arXiv id, DOI, URL, or title (also records in Zotero if configured) |
| Add papers to the Zotero Reading Queue without sending (optionally filed into topical collections) |
| Track papers in Zotero without queueing or sending them (owned, paywalled, or read-later); a missing OA PDF is not treated as a failure |
| Catalogue a book by ISBN, book DOI, or title as a Zotero |
| Ingest a PDF you already have (grey literature, open-access textbooks) with the PDF attached and metadata you supply; optionally send it |
| List Zotero collections so Claude can propose where to file a paper, or ask you |
| File queued papers into a topical collection (created on demand; queue membership unaffected) |
| Remove papers from one collection (for misfiled items); the papers themselves and their queue/sent state are untouched |
| Show the queue with per-item status (unsent / sent / no-open-access-pdf) |
| Delete queue items by exact ref or title |
| Send every unsent queue item (auto-split under email limits), then tag as sent |
| Report what's configured and what's missing (no secrets) so Claude can guide setup |
Run the interactive wizard. It asks which e-reader you have, walks through only the credentials that device needs, and validates each one as you enter it: SMTP login test, Zotero key check with automatic library ID lookup, full Dropbox OAuth exchange.
uv sync && uv run paperboy setupdocs/setup.md is the step-by-step version: where to find each credential in Zotero, Amazon, Gmail, and Dropbox, with links to the official page for every step.
How much setup you need depends on the device:
You have | Credentials needed |
Kindle | 2 — Send-to-Kindle address + an SMTP app password |
PocketBook | 2 — Send-to-PocketBook address + an SMTP app password |
Kobo | a Dropbox app (key/secret + one OAuth approval) + a contact email |
+ Zotero queue (optional) | 1 — a Zotero API key (library ID auto-detected) |
If you'd rather set up by hand, cp .env.example .env and fill it in;
every variable is documented there. Then register with Claude Code:
claude mcp add paperboy -- uv run --directory /path/to/paperboy paperboy--directory matters: the server loads .env from its working
directory (set PAPERBOY_ENV=/path/to/.env to point elsewhere).
If paperboy is added but half-configured, ask Claude to "check my
paperboy setup". The setup_status tool reports what's missing and
what to do next, without passing secrets through the chat.
If someone shared their deployment with you, this is your whole setup:
claude mcp add --transport http paperboy <URL>/mcp \
--header "Authorization: Bearer <token>"The URL needs the /mcp path suffix. Treat the token like a password:
it lets you act fully as the owner: send email from their address,
deliver to their e-reader, and read and edit their Zotero library.
There is no reduced-permission mode; if that's not what you both want,
deploy your own instance.
One script creates a locked-down, single-tenant Cloud Run service. You need the gcloud CLI and a Google Cloud account with billing enabled, so a card has to be on file. What you pay depends on how much you use it: a personal deployment sending papers now and then usually falls inside Cloud Run's free tier and costs nothing, but heavy or shared use can go past it. The script sets a $1/month budget alert so you hear about it if your bill ever starts to climb.
uv run paperboy setup && ./deploy/deploy.sh my-paperboy-projectHow a client connects to the deployed server depends on the client:
Claude Code and the API use a bearer token the script generates.
You paste it into an Authorization header, as in the section above.
claude.ai and the Claude mobile app usually can't send a bearer token from their connector dialog, so they sign in with Google instead. That needs a one-time Google OAuth client, which you create in your own Cloud project (a Web-application client with one redirect URI). Sign-in is restricted to your own email address, and because paperboy only asks Google for your email, the sign-in doesn't expire.
docs/deploy.md has the full procedure for both, including the OAuth console steps, the security model, and cost bounds. The deploy script also prints the exact OAuth steps with your project's URLs already filled in, so you're not copying them from here.
uv for packaging, ruff (Google style), ty, pytest behind an enforced
80% coverage gate. uv sync && uv run pre-commit install, then
uv run pytest. The suite runs entirely offline; no credentials
needed to develop.
Contributions are welcome. CONTRIBUTING.md covers setup, testing conventions, and what makes a change easy to merge; SECURITY.md covers how to report vulnerabilities (privately, please).
reMarkable delivery backend (real cloud API)
arXiv HTML → EPUB via pandoc for reflowable reading (opt-in per paper; conversion is lossy for dense math, so PDF stays the default)
Kindle highlights → Zotero notes round-trip (My Clippings.txt
parser with fuzzy title matching)
Ideas paperboy builds on: the tag-driven Zotero→Kindle idea from stakats/zotero-to-kindle (circa 2011, by one of Zotero's original directors); wahiggins3/send-to-kindle-mcp; openags/paper-search-mcp; and 54yyyu/zotero-mcp, the model for our setup wizard; paperboy leaves library management to it.
Thank you to arXiv for use of its open access interoperability. Paper metadata and open-access links come from OpenAlex, Crossref, and Unpaywall, all run as open scholarly infrastructure. Recommendations via the Semantic Scholar Recommendations API (Allen Institute for AI). Library management via the Zotero web API. Built on FastMCP, pyzotero, and httpx.
paperboy was built with Claude Code.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ||
| collections | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits: it resolves identifiers into a proper Zotero book item, does not queue/deliver, creates collections on demand, deduplicates by ISBN, and returns closest candidate for loose matches. It warns about corrupting citations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient; each sentence adds value. It is front-loaded with the purpose and structured logically: input methods, output type, exclusions, parameter usage, and dedup behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, no annotations, but output schema present), the description covers input, behavior, error handling, dedup, and relationships to other tools. The output schema handles return values, so completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds rich meaning: identifier can be ISBN-10/13, book DOI, or title; collections are for filing topically and created on demand. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb-resource pair ('Catalogue a book in Zotero') and lists explicit identifiers (ISBN, book DOI, title), clearly distinguishing the tool from siblings like attach_pdf.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides both when to use (cataloging books) and when not to (never a journalArticle), and gives an alternative (attach_pdf) for putting PDFs on the e-reader. It also explains behavior for loose matches and deduplication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| collections | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: the tool never adds to the Reading Queue, never sends, treats no-OA-PDF papers as normal library records (no 'no-oa-pdf' tag), reports duplicates with existing collections, and creates collections on demand.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement, a contrast to siblings, and detailed behavioral notes. Every sentence adds value, but it is slightly lengthy; a more concise version could be trimmed without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, no enums) and presence of an output schema, the description is comprehensive. It covers purpose, usage context, parameter semantics, behavioral quirks (duplicates, no-OA handling), and error handling (unresolvable refs).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by specifying that 'refs' can be 'arXiv id, DOI, URL, or title' and that 'collections' are optional and 'created on demand'. This provides significant context beyond the raw schema, though a bit more detail on parameter formats would be ideal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's action: 'Track papers in Zotero WITHOUT staging them for e-reader delivery.' It identifies the resource (papers in Zotero/library) and distinguishes itself from the sibling tool queue_papers by explicitly stating the 'just catalogue it' path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('for references you want to keep ... rather than deliver') and contrasts with an alternative (queue_papers). It also instructs the agent to relay unresolvable refs to the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| send | No | ||
| year | No | ||
| title | Yes | ||
| authors | Yes | ||
| item_type | No | journalArticle | |
| collections | No | ||
| url_or_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the download from URL/local path, creation of Zotero item from supplied metadata, PDF attachment, on-demand collection creation, and optional send-to-reader. It does not detail duplicate handling or error behavior, but covers core behavioral traits adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action and is structured logically. Each sentence adds value, but it is somewhat dense and could be more concise by grouping related info. Still, it avoids wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, input expectations, and behavior well. With an output schema present, return values need not be explained. It mentions the prerequisite 'Requires Zotero' and contrasts with queue_papers. Minor gaps remain regarding error conditions and idempotency, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It adds context for item_type (lists valid values), send (delivers to e-reader), collections (created on demand), and url_or_path (explains http(s) or local). However, it omits doi and year parameters entirely, and does not systematically describe each field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ingests a PDF into Zotero with attachment, specifies it's for grey literature, and distinguishes itself from sibling tool queue_papers by noting it does not queue. The verb 'ingest' and resource 'PDF into Zotero' are specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (grey literature, no registry indexes) and contrasts with queue_papers. It also mentions using 'book' item type for open-access textbooks. However, it does not explicitly exclude other sibling tools like add_book or list alternative scenarios, so some guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| collection | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and discloses key traits: collection creation on demand (only if papers match), items stay in queue, delivery state unaffected, and matching method. Missing details on error handling or authentication, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences with no wasted words. The main purpose is front-loaded, and every sentence adds essential information (prerequisite, alternative, side effects, matching behavior). Very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two-parameter tool and presence of an output schema, the description covers prerequisites, side effects, matching, and edge cases (empty collection not created). It is nearly complete; the output structure is covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It explains that 'refs' uses exact matching (arXiv id, DOI, URL, title) and implies 'collection' is a name. The description adds value beyond the schema, though collection format is not detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'file' and resource 'already-queued papers into a Zotero collection', and it distinguishes from siblings like queue_papers (which queues) and unfile_papers (implied inverse). The matching method and prerequisite are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (only for papers already in the queue), when not to (for fresh papers, use queue_papers), and provides an alternative (pass collections to queue_papers). Also covers the condition that collection creation only occurs if papers match.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as authentication needs, rate limits, error cases, or side effects beyond listing. The description is minimal on behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core function. The second sentence is detailed but earned, providing critical usage guidance. Could be slightly shorter, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema, the description covers the essential purpose and usage context. It lacks details on output format or edge cases, but the output schema fills that gap. Overall fairly complete for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. The description adds no parameter-specific information but provides valuable usage context. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Zotero collections with specific fields (name, item count, parent), and it distinguishes from siblings like list_queue and search_papers by its specific resource and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this before queueing or sending new papers, provides clear decision logic for passing collections or asking the user, and contrasts with silent guessing. This strongly guides when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses behavioral traits: statuses ('unsent', 'sent', 'no-open-access-pdf'), key uniqueness for duplicates, and UTC dates. It fully covers what the tool returns and its read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place. First sentence states purpose, second lists statuses, third gives usage and key details, fourth mentions dates. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no params and an output schema (not shown), the description sufficiently explains return fields and behavior. It covers purpose, usage, statuses, keys, and dates, making it complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is irrelevant. Description adds no parameter info, but baseline is 4 since there are no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists the reading queue with delivery status per item. It distinguishes from siblings by mentioning usage before send_queue and for remove_from_queue, and highlights unique key and date fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: 'Use this to show the user their queue, before send_queue ... or to find refs for remove_from_queue.' This tells when to use this tool versus alternatives like send_queue or remove_from_queue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| collections | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses key behaviors: non-destructive addition, duplicate avoidance, optional collection creation on demand, and reporting of unresolvable papers. All behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (five sentences), front-loaded with the main purpose, and efficiently provides all necessary details without redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple input types, optional collections, error handling), the description is complete. It covers all aspects an agent needs to know: input, behavior, edge cases, and interaction instructions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining that 'refs' accepts various identifiers and that 'collections' is optional for filing papers, including guidance to use list_collections. Adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds papers to the Zotero Reading Queue without sending them. It specifies accepted input types and distinguishes from siblings by mentioning it does not send, contrasting with send_papers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on accepted inputs (arXiv ids, DOIs, URLs, titles), duplicate handling, optional collections, and error reporting. Instructs to check list_collections when placement is unclear, but does not explicitly state when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| interests | No | ||
| seed_refs | No | ||
| max_results | No | ||
| recent_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool blends two signals, excludes papers already in the user's library (queue + 100 most recent), caps max_results at 20, and returns picks with a 'via' field and a problems array. It also notes that interests lead results and that problems should be relayed. It does not mention any destructive side effects or authentication requirements, but the tool appears to be read-only, so this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, then explains the signals, parameters, output format, and important usage notes. It is front-loaded with purpose. While slightly verbose, each sentence adds value and no information is redundant. A minor improvement could be tighter phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and zero schema coverage, the description provides a comprehensive overview: it explains the two discovery arms, the output format (picks and problems), the 'via' field semantics, and the exclusion of library papers. It also mentions an upstream limit (computer science only). It lacks information about error states (e.g., if all seeds fail) or rate limits, but for a recommendation tool it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains each parameter: interests (2-4 short phrases), seed_refs (for citation graph seeding), max_results (capped at 20), and recent_only (new vs all-time). It also clarifies defaults (uses library if no interests) and constraints (computer science only upstream). This adds meaningful context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as discovering papers the user may want to read, blending citation-graph and keyword signals. It specifies sources (Semantic Scholar, OpenAlex) and states that it excludes already-in-library papers. This distinguishes it from sibling tools like search_papers (which likely returns exact matches) and queue/send operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get paper recommendations) and how to provide inputs (interests as phrases, seed_refs for explicit seeds). It also advises to present picks and let the user choose, not send unasked. However, it does not explicitly state when not to use it, e.g., if the user wants a simple keyword search rather than a blended recommendation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description fully discloses behavioral traits: items filed elsewhere keep their library record, items without other collections move to Trash (restorable ~30 days), trashed items no longer count for duplicate protection, and nothing is permanently deleted from Zotero or the e-reader. This richly supplements the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear lead sentence followed by bullet-like paragraphs. Every sentence serves a purpose (behavioral details, edge cases, user guidance), but the flow could be tightened slightly (e.g., merging duplicate-handling into a single sentence) without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple single-parameter schema, the tool has complex side effects (trashing, collection membership, duplicate protection). The description covers all these scenarios, including behavior on duplicate matches and instructions for user interaction. An output schema exists, so return value explanation is unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines 'refs' as an array of strings without descriptions. The tool description compensates by specifying acceptable formats (arXiv id, DOI, URL, exact title) and explains matching behavior, uniqueness constraints, and the need for disambiguation—adding essential semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove papers from the Zotero Reading Queue by ref or title', a specific verb-resource pair that clearly distinguishes this tool from siblings like list_queue (listing), queue_papers (adding), and send_queue (sending). It leaves no ambiguity about the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use (removing items from the queue) and explains behavior on duplicate matches, but it does not explicitly list when this tool should be avoided or name direct alternatives. The guidance within (e.g., 'Relay the choice to the user — never pick for them') adds operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| source | No | all | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses source fallback behavior, max_results clamping, output fields (ref, open_access_pdf), and notes potential delivery failures for OA links. Lacks rate limits or permissions, but covers key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose. Each sentence adds value, though the structure could be slightly improved by separating parameter explanations more cleanly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of output schema, the description adequately covers parameter semantics and output expectations. It does not mention error handling or empty results, but overall provides sufficient context for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the source options and behavior, max_results clamping range, and the meaning of output fields. The query parameter is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches for papers across scholarly literature. While it does not explicitly contrast with sibling tools, the purpose is specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use 'all' vs 'arxiv' source, including trade-offs. It does not explicitly state when to use this tool over siblings, but the distinct operation (search vs. file/queue/send) is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| force | No | ||
| dry_run | No | ||
| collections | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It details deduplication, skipping already-sent papers, auto-splitting batches, handling of open-access PDFs, Zotero integration, and dry_run behavior. This is comprehensive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the main purpose. Each sentence adds value, covering edge cases and behaviors. It could be slightly more concise, but it remains informative without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, output schema exists), the description is complete. It covers input formats, behaviors, side effects, error handling, and expected output (receipt). The existing output schema obviates the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates. It explains the accepted formats for refs, the effect of force, dry_run, and the optionality of collections. While it doesn't restate defaults, it adds practical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends papers to an e-reader by arXiv id, DOI, or title. It uses specific verbs ('send') and resources ('papers'), and distinguishes from siblings like 'file_papers' and 'send_queue' which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the tool, including using dry_run for previews, checking list_collections for placement, and noting limitations like no duplicate protection without Zotero. It lacks explicit 'when not to use' but the context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses critical behaviors: skipped tags (sent, no-oa-pdf), auto-tagging of unavailable PDFs to prevent retries, and automatic batch splitting under email limits. This fully informs the agent of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: main action in first sentence, followed by essential behavioral details and sibling reference. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema (implied), the description covers all necessary aspects: action, scope, exclusions, side effects, and alternative tool. It is fully sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so description need not explain them. Baseline 4 applies since schema coverage is trivially 100% and no parameter details are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Send EVERY unsent paper in the Zotero Reading Queue.' It distinguishes from sibling tool send_papers by stating 'for specific papers use send_papers,' making the tool's scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('flush the whole queue') and when not to ('for specific papers use send_papers'). Also advises checking list_queue first when unsure, providing clear guidance on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that the tool 'Returns configuration state only — never secret values,' a critical behavioral trait for a status-checking tool, ensuring the agent knows it is safe and read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three concise sentences. The first sentence front-loads the primary purpose. Every sentence adds unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown but indicated), the description provides sufficient context: what it returns, how to use it, and security guidance. It is complete for a simple status-check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (schema coverage 100% trivially). The description does not add parameter-specific detail (none needed), but it clarifies the tool's purpose, which helps an agent understand no input is required. Given the baseline of 4 for zero parameters, this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Report' and specifies the resource: 'which paperboy features are configured and what's missing.' This clearly distinguishes it from sibling tools that deal with papers, collections, or queue management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this to guide the user through finishing setup.' Also provides clear guidance on what not to do: 'Credentials themselves must be entered by running 'paperboy setup' in a terminal, never pasted into the chat.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | Yes | ||
| collection | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently discloses that only membership in the named collection is dropped, while other collections and sent-state remain untouched. It also explains the behavior for ambiguous refs (removes nothing).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise for the amount of detail, but it could be slightly shorter. The key action is front-loaded, and additional context is provided in subsequent sentences. The structure is logical but includes some extra detail that might be condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and partial schema, the description covers purpose, usage guidelines, behavioral details, parameter semantics, and edge cases (e.g., ambiguous refs, refusal of Reading Queue). It is complete enough for an AI agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines refs (array of strings) and collection (string) with 0% coverage. The description adds meaning by explaining that refs match exact arXiv id, DOI, URL, or title, and that collection is the target collection. This compensates for the schema's lack of description, though more detail on collection identification would be helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes papers from one Zotero collection, using the verb 'Remove' and specifying the resource 'papers from one Zotero collection'. It distinguishes itself from siblings like file_papers and remove_from_queue by highlighting its inverse nature and specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool (for misfiled items) and when not (Reading Queue is refused as a target, with a pointer to remove_from_queue for that purpose). It also provides instructions for moving papers between collections and clarifies ambiguous ref handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.1add_bookadd_to_libraryattach_pdfv0.2.1unfile_papersv1.0.0file_paperslist_collectionslist_queuequeue_papersrecommend_papersremove_from_queuesearch_paperssend_paperssend_queuesetup_statusScored across 14 tools
Each tool targets a distinct workflow step: search, recommend, queue, send, catalogue, attach PDF, manage collections, and check status. Overlapping actions like send_papers vs send_queue or add_to_library vs queue_papers are explicitly differentiated in their descriptions.
Most tool names follow a clear verb_noun snake_case pattern (search_papers, send_papers, queue_papers, list_collections). Minor deviations like remove_from_queue and setup_status break the simple two-word pattern but remain stylistically consistent.
14 tools is well-scoped for a scholarly literature manager spanning discovery, queueing, delivery, cataloguing, and collection organization. Each tool serves a clear purpose with no obvious redundancy or bloat.
The toolset covers the full workflow lifecycle: find papers, add to queue, send to e-reader, catalogue items, organize collections, and inspect setup state. Only deep library editing operations like metadata updates or permanent deletion are absent, which is reasonable for this domain.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
MCP server for Project Gutenberg — 75,000+ public-domain ebooks with full plain-text retrieval.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction