Tools¶

Tools are generated from the OpenAPI spec of your Paperless, one per API operation, and named after the spec's operation IDs: documents_list, documents_retrieve, tags_create, correspondents_partial_update, and so on. Each tool's description starts with its HTTP method and path, so PATCH /api/documents/{id}/ tells you (and the model) what it does.

Toolsets¶

A toolset is the first path segment after /api/: everything under /api/documents/ is the documents toolset. MCP_TOOLSETS picks which ones become tools.

On by default (80 tools on Paperless-ngx with API version 10):

Toolset	What it covers
`documents`	List, filter and full-text search; read content and metadata; edit; notes; history; suggestions; bulk edit; merge, rotate and other PDF operations; upload, download, preview and thumbnail
`search`	Global search and autocomplete
`correspondents`, `document_types`, `tags`, `storage_paths`, `custom_fields`	Create, list, read, update and delete each
`saved_views`, `share_links`	Saved views and public share links
`tasks`	Background tasks: what is being consumed, what failed
`trash`	List, restore and empty the trash
`statistics`	Counts for the whole archive
`bulk_edit_objects`	Bulk delete and permission changes for tags, correspondents and the like

Off by default: users, groups, profile, config, mail_accounts, mail_rules, processed_mail, workflows, workflow_actions, workflow_triggers, share_link_bundles, logs, status, remote_version, ui_settings.

# Only what a read-mostly assistant needs
MCP_TOOLSETS=documents,search,tags,correspondents,document_types

# The defaults plus workflows
MCP_TOOLSETS=documents,search,correspondents,document_types,tags,storage_paths,custom_fields,saved_views,share_links,tasks,trash,statistics,bulk_edit_objects,workflows,workflow_actions,workflow_triggers

# Everything (139 tools)
MCP_TOOLSETS=all

Setting MCP_TOOLSETS replaces the default list, it doesn't add to it. Every tool takes up room in the model's context, so more is not better: turn on what you use.

Toolsets decide which tools exist. What a tool may do is still decided by Paperless: a user without permission to delete documents gets Paperless's 403 from documents_destroy.

What is left out, in every toolset¶

Credential operations. /api/token/, /api/profile/generate_auth_token/, the two-factor endpoints and disconnect_social_account. Regenerating the API token would disconnect every client of that user, including the one making the call.
PUT where PATCH exists. A full update needs every field re-sent; the partial update (…_partial_update) does the same job without accidental resets.
bulk_download (a ZIP of binaries) and update_version (a file upload the generated tool can't express).
/api/oauth/callback/, a browser redirect target.

Tools that are written by hand¶

Four operations can't work as generated and are replaced by tools of the same name:

Tool	What it does
`documents_post_document_create`	Uploads a document. Takes `filename` and either `content` (text) or `content_base64` (anything else), plus optional title, date, correspondent, document type, storage path, tags, serial number and custom fields. Returns the task ID; Paperless consumes the file in the background.
`documents_download_retrieve`	Returns the file: the archived PDF, or the original with `original=true`.
`documents_preview_retrieve`	Returns the inline preview.
`documents_thumb_retrieve`	Returns the thumbnail as an image.

Files are returned inside the tool result, so they are capped at 10 MB. To read a document, the model doesn't need the file: documents_retrieve returns the extracted text in its content field.

Tips for prompts¶

documents_list returns the full text of every document on the page. Ask for fields (for example id, title, created, correspondent) and a small page_size when you only need an overview.
Full-text search is the query parameter of documents_list; title__icontains, correspondent__id, tags__id__all, created__date__gte and the other filters narrow by metadata.
Metadata is referenced by ID. To tag a document, look the tag up with tags_list first, then pass its ID to documents_partial_update or bulk_edit.