Allows interaction with a Paperless-ngx server, providing tools for searching, tagging, and organizing documents with privacy tiers, including metadata-only operations, local extraction of fields, and full document content retrieval.
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., "@paperlessngx-mcp find recent utility bills"
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.
A privacy-first Model Context Protocol (MCP) server for Paperless-ngx. It lets an LLM agent search, organize, tag, and reference your documents without the full text of those documents entering the model's context window — unless you explicitly ask for it.
Built with the official @modelcontextprotocol/sdk as a stdio server, TypeScript/ESM, Node 20+.
The whole point of this server is to enforce a boundary between document metadata and document content. Most document management — "find my 2024 tax return", "tag this as an invoice", "what did the electric company send me" — needs metadata, not the OCR'd text of the document. Yet the naive Paperless API call (GET /api/documents/{id}/) returns the entire OCR content field by default, which would silently dump full document text into the model's context.
Every tool here falls into exactly one tier, and the tier dictates what data reaches the calling model:
Returns titles, dates, tags, correspondents, document types, custom fields, page counts, file sizes. Never returns OCR content. This covers the large majority of practical use cases. Search runs server-side inside Paperless and comes back as metadata.
Two mechanisms enforce this:
List/search calls pass Paperless's sparse fieldset (fields=id,title,correspondent,...) so the content field is never even serialized by the server.
The single-document metadata tool calls the detail endpoint (which includes content) but explicitly deletes the content field before returning.
The MCP server fetches content into its own process, runs a local parser (regex today; a local LLM in the future), and returns only the extracted value(s). The full text never leaves the server. Example: extract every dollar amount, or the "amount due" line, from an invoice — without the invoice body entering the model context.
This is the extensibility point: paperless_extract_field is designed so a future local-model extraction backend drops in behind the same contract (read content locally → parse → return only the field).
Returns the full OCR text or the document binary to the calling model. These tools are clearly named and their descriptions carry a privacy_warning. Reserve them for when the user explicitly asks to read, summarize, or analyze a document's contents.
The tiers are deliberately not collapsed. A tool that searches returns metadata; a tool that fetches content is a separate, clearly-marked tool.
Related MCP server: KnowledgeMCP
Tool | Tier | Returns |
| 1 | Matching docs as metadata (id, title, names, tags, dates, page_count) |
| 1 | One doc's full metadata (content stripped), incl. checksum, size, custom fields, notes |
| 1 | All tags: id, name, document_count |
| 1 | All correspondents: id, name, document_count |
| 1 | All document types: id, name, document_count |
| 1 | Totals, inbox count, type & tag breakdowns |
| 1 | Sets a document's tags (by name) |
| 1 | Sets a document's correspondent (by name) |
| 1 | Sets a document's type (by name) |
| 1 | Paperless's own server-side suggestions (no content to the model) |
| 2 | Only the field(s) extracted locally from content |
| 3 | Full OCR text ⚠ |
| 3 | Saves the binary PDF to disk, returns the path ⚠ |
All Tier 1 tools resolve IDs to human-readable names. There is exactly one tool that returns OCR text (paperless_get_document_content) and one that materializes the binary (paperless_download_document).
All config is via environment variables.
Variable | Required | Default | Description |
| yes | — | e.g. |
| yes | — | Paperless API token ( |
| no |
| Set |
| no |
| Where Tier 3 downloads are written |
Get an API token in Paperless under Settings → My Profile → API Token.
npm install
npm run build
PAPERLESS_BASE_URL=http://localhost:8000 \
PAPERLESS_API_TOKEN=xxxxxxxx \
node dist/index.jsThe server speaks JSON-RPC over stdio; it is launched by your MCP client, not run as a standalone HTTP service.
Example MCP client config:
{
"mcpServers": {
"paperless": {
"command": "node",
"args": ["/path/to/paperless-mcp/dist/index.js"],
"env": {
"PAPERLESS_BASE_URL": "http://localhost:8000",
"PAPERLESS_API_TOKEN": "xxxxxxxx",
"PAPERLESS_VERIFY_SSL": "false"
}
}
}
}Because this is a stdio server (JSON-RPC over stdin/stdout, exits when stdin closes), it is not a long-lived HTTP service. Two patterns:
Pattern A — on-demand container (recommended). Build the image, then have hermes launch a fresh container per session:
docker run -i --rm --env-file .env paperless-mcp:latestThe -i is essential — it keeps stdin open for the JSON-RPC stream.
Pattern B — persistent container you exec into. Deploy the included docker-compose.yml as a Portainer Stack. It builds the image and keeps a container alive (via a sleep loop) so hermes can attach the MCP entrypoint on demand:
docker exec -i paperless-mcp node /app/dist/index.jsIn Portainer: Stacks → Add stack.
Paste the contents of docker-compose.yml (or point it at this repo).
Add the environment variables (PAPERLESS_BASE_URL, PAPERLESS_API_TOKEN, PAPERLESS_VERIFY_SSL) in the stack's Environment variables section, or upload your .env.
Deploy. If Paperless runs in the same Docker network, use its service name as the host (e.g. http://paperless-ngx:8000).
Then point hermes' MCP configuration at whichever launch command matches your chosen pattern (docker run -i ... or docker exec -i ...).
Tier 1 list/search calls send fields= so Paperless never serializes content.
paperless_get_document_metadata deletes content from the detail response in-process before returning.
paperless_extract_field reads content only inside the server process and returns just the extracted value, with a privacy_note confirming content was not returned.
Only paperless_get_document_content and paperless_download_document surface full content; both carry an explicit privacy_warning.
This server controls what it returns. It cannot stop a client/agent from separately calling the Tier 3 tools — that's exactly why those tools are named and described to make the privacy cost obvious to the model and the user.
src/tools.ts contains an EXTRACTORS registry of named, dependency-free regex extractors (dollar_amounts, dates, emails, phone_numbers, addresses, total_amount). extraction_pattern also accepts a raw regex.
To plug in a local LLM (the design goal): keep the same contract — fetch content into the process, run your local model, return only the requested field(s). Replace the body of paperless_extract_field's handler (or add a new named extractor that calls your local inference endpoint). The privacy boundary is preserved as long as only the extracted value is returned.
paperless-mcp/
├── src/
│ ├── index.ts # entrypoint: stdio transport, tool registration, dispatch
│ ├── paperless-client.ts # REST client: auth, pagination, TTL cache, ID↔name resolution
│ └── tools.ts # tool defs + handlers, grouped by privacy tier
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml # Portainer stack
├── .env.example
└── README.mdMIT
PRIVACY TIER 3: Download the original document binary (PDF) to the server's filesystem and return the saved file path. Use only when the user explicitly needs the actual file rather than metadata or text. privacy_warning: This materializes the full document file on the MCP server host.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. | |
| original | No | Download the original file instead of the archived PDF (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the materialization of the file on server host, includes privacy tier warning. Annotations are minimal (only title), so description carries full burden and does so effectively.
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 concise sentences plus a warning line. No wasted words. Front-loaded with purpose.
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?
Covers purpose, usage, and behavioral details. No output schema, but return value (file path) is mentioned. Could elaborate on path format, but sufficient for the simple 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?
Input schema has 100% description coverage for both parameters. Description adds little beyond 'original document binary (PDF)' which is already implied by the 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?
Description clearly states it downloads document binary to server filesystem and returns file path. Verb 'download' and resource 'document' are specific. Distinguishes from sibling tools that handle metadata, text extraction, or tagging.
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 'Use only when the user explicitly needs the actual file rather than metadata or text.' Provides clear when-to-use guidance, though doesn't name alternative tools directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 2 (local extraction): Extract ONLY a specific field from a document. The OCR text is fetched into the MCP server process, parsed LOCALLY, and only the extracted value(s) are returned — the full content never enters the model context. extraction_pattern may be a named built-in extractor (dollar_amounts, dates, emails, phone_numbers, addresses, total_amount) or a custom JavaScript-style regular expression. This is the extensibility point where a future local LLM extraction backend would plug in.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. | |
| extraction_pattern | Yes | Named built-in extractor (dollar_amounts, dates, emails, phone_numbers, addresses, total_amount) OR a raw regex. If a raw regex, all matches (capture group 1 if present) are returned. | |
| regex_flags | No | Optional flags for a raw-regex pattern (default 'gi'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations beyond title, so description carries full burden. Discloses that OCR text is fetched into MCP server, parsed locally, only extracted values returned, and full content never enters model context. Also explains extraction_pattern behavior. Does not cover error scenarios or performance, but privacy aspect is well-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?
Single focused paragraph, front-loads privacy tier and purpose. Every sentence adds value; no fluff. Could benefit from slight structuring (e.g., separating usage notes) but overall efficient.
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 output schema, description adequately explains return values (extracted value(s) or matches for regex). Covers privacy, examples of extraction patterns, and extensibility. Missing details on error handling or performance, but sufficient for a focused extraction 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?
Schema coverage 100%, but description adds significant value: explains that extraction_pattern can be built-in named extractors (listing examples) or custom regex, and that regex returns all matches with capture group 1 if present. This goes beyond 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?
Description states specific verb ('extract') and resource ('specific field from a document'), distinguishes from siblings like paperless_get_document_content by emphasizing local extraction and privacy tier.
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?
Clearly indicates when to use: for extracting specific fields from a document, with privacy restrictions. Implicitly excludes full-document retrieval (siblings handle that). Lacks explicit when-not-to-use but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 3: Returns FULL document content. The calling model will see the ENTIRE OCR text of this document. Only use this when the user has EXPLICITLY asked to read, summarize, or analyze a document's contents. For finding, organizing, or referencing documents, use the Tier 1 metadata tools instead. privacy_warning: This returns full document content into the model's context.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses PRIVACY TIER 3 and warns that full OCR text enters model context. No annotations to contradict; description adds crucial privacy context.
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 concise sentences with front-loaded purpose and key information. No 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?
Covers purpose, privacy, and usage guidelines adequately. Lacks mention of return format or error handling, but sufficient for a simple one-parameter 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?
Schema description coverage is 100% for the single parameter 'document_id'. Description adds no extra parameter details beyond schema, achieving baseline.
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?
Explicitly states 'Returns FULL document content' and specifies usage for reading, summarizing, or analyzing documents. Clearly distinguishes from sibling metadata tools.
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 when to use (user asked to read/summarize/analyze) and when not to use (finding/organizing, refer to Tier 1 metadata tools).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): Return full metadata for one document — title, correspondent, document type, tags, dates, page count, checksum, file size, mime type, storage path, custom fields, and notes. The underlying Paperless detail endpoint includes OCR content, but this tool STRIPS the content field before returning. Use paperless_get_document_content if you actually need the text.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the underlying endpoint includes OCR content but the tool strips it before returning. This adds behavioral context beyond the 'readOnlyHint' annotation, which is consistent with the safe read nature of the 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 concise, front-loaded with a critical privacy tier warning, and organized in a clear, readable format. Every sentence adds necessary context without verbosity.
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 simplicity (1 parameter, no output schema), the description fully covers what the tool returns, what it strips, and how to use it. It is contextually complete for an agent to invoke 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?
The single parameter 'document_id' is fully described in the schema with 100% coverage. The description does not add new semantic information beyond what the schema provides, so it meets the baseline with no extra value.
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 returns full metadata for one document and lists specific fields (title, correspondent, etc.). It also distinguishes itself from the sibling tool 'paperless_get_document_content' by noting that this tool strips the OCR content field.
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 this tool (for metadata only) and when to use the alternative 'paperless_get_document_content' (if actual text is needed). This provides clear guidance to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): Library-wide statistics — total documents, total file size, inbox count, and breakdowns by document type and tag. No document content involved.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond the readOnlyHint annotation by detailing the privacy tier and confirming no document content involvement. It lists the specific statistics returned, giving a clear picture of behavior without surprises.
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?
Single sentence, front-loaded with the key privacy tier indicator, followed by a succinct list of what is returned. No extraneous 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 tool's simplicity (no parameters, no output schema), the description provides a complete overview of the returned statistics. It lacks explicit mention of return format, but that is standard. Sufficient for an agent to select and invoke 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?
With zero parameters and 100% schema coverage, there is no parameter info to add. However, the description adds value by explaining what the tool returns, which is not evident from the empty schema alone. Baseline is 4 for zero parameters.
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?
Description clearly states the tool returns library-wide statistics including totals and breakdowns. It distinguishes itself from sibling tools by explicitly noting 'metadata only' and 'no document content involved', differentiating from document-level tools like paperless_get_document_metadata.
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?
While it doesn't explicitly state when to use versus alternatives, the description implies this is for aggregate statistics and safe metadata queries. The sibling tool names provide context, but more explicit guidance on when not to use (e.g., for document specifics) would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): List all correspondents with id, name, and document_count. Optional case-insensitive name filter.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional substring filter on correspondents name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds two behavioral traits: the 'metadata only' privacy disclosure and the case-insensitive filter behavior. No contradictions exist.
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 extremely concise: a single sentence with a prefix that adds essential privacy context. No unnecessary words or 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?
For a simple list tool with one optional parameter and no output schema, the description fully covers the purpose, returned fields, privacy implications, and filter behavior. It leaves no significant gaps.
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 100% schema coverage, the baseline is 3. The description adds the value 'case-insensitive' to the filter parameter, which is not in the schema description, providing meaningful extra context.
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's action ('list all correspondents'), the specific resource, and the fields returned (id, name, document_count). It is distinct from sibling tools like paperless_list_document_types and paperless_list_tags due to the explicit resource name.
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 usage context via 'PRIVACY TIER 1 (metadata only)', indicating it is safe for privacy-sensitive use. It does not explicitly mention when not to use or contrast with sibling tools like paperless_search_documents, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): List all document types with id, name, and document_count. Optional case-insensitive name filter.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional substring filter on document types name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that it returns only metadata (id, name, document_count) and is privacy tier 1, providing useful behavioral context beyond annotations without contradiction.
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 a single sentence with an additional note about privacy tier. It is front-loaded with the main action and key details, with no unnecessary 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?
For a simple listing tool with one optional parameter and no output schema, the description covers the essential: what it lists, fields returned, privacy level, and filter behavior. It does not mention ordering or pagination, which is acceptable.
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 100% with a description for the 'search' parameter. The description adds that the filter is case-insensitive and substring-based, which adds meaningful nuance beyond the schema's substring filter description.
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 lists all document types with specific fields (id, name, document_count). However, it does not explicitly differentiate from sibling listing tools like paperless_list_correspondents or paperless_list_tags, missing a chance to distinguish purpose.
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?
No explicit guidance on when to use this tool versus alternatives. The privacy tier mention hints at data sensitivity but does not provide when/when-not conditions or reference sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): List all tags with id, name, and document_count. Optional case-insensitive name filter.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional substring filter on tags name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds that it returns only metadata (Privacy Tier 1) and lists the fields. No further behavioral details like pagination or rate limits, which may be relevant but not required given the tool's simplicity.
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?
Extremely concise: two sentences with key information front-loaded (privacy tier). Every phrase adds 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?
For a simple list tool with one optional parameter, the description covers the core functionality. However, it omits potential details like pagination, sorting, or handling of large result sets, which could be beneficial.
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 100%. The description adds that the search filter is case-insensitive, which slightly enhances the schema's description. No other parameters to elaborate.
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 all tags with id, name, and document_count. It specifies the optional case-insensitive name filter. However, it doesn't explicitly distinguish from sibling tools like paperless_list_correspondents, though the resource is different.
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?
No guidance on when to use this tool versus alternatives. The description only mentions an optional filter but does not specify any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): Search documents and return METADATA ONLY — never OCR content. Full-text search runs server-side inside Paperless; this tool returns only titles, dates, tags, correspondent and document-type names. Use this to find and reference documents without pulling their text into context. Returns id, title, correspondent_name, document_type_name, tags, created_date, added_date, page_count.
| Name | Required | Description | Default |
|---|---|---|---|
| search_query | No | Full-text search across OCR content + title (matching happens on the server; content is NOT returned). | |
| correspondent_name | No | Filter by correspondent name. | |
| tag | No | Filter by a single tag name. | |
| document_type | No | Filter by document type name. | |
| created_after | No | ISO date YYYY-MM-DD (created on/after). | |
| created_before | No | ISO date YYYY-MM-DD (created on/before). | |
| inbox_only | No | Only documents currently in the inbox. | |
| limit | No | Max results (default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds valuable context: privacy tier, server-side full-text search, and explicit statement that OCR content is never returned. No contradictions.
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 single paragraph but well-structured and front-loaded with purpose. It contains all essential information without unnecessary words, though could be slightly more organized with bullet points.
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 8 optional parameters, no output schema, and high schema coverage, the description sufficiently explains what the tool returns and how it operates. It mentions privacy and server-side search, which are important contextual details.
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 100%, so baseline is 3. The description does not add parameter-specific semantics beyond the schema. It lists return fields but that does not compensate for parameter details.
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 documents and returns metadata only, with a specific list of returned fields. It distinguishes itself from siblings by emphasizing that it never returns OCR content, unlike paperless_get_document_content.
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?
Explicit guidance: 'Use this to find and reference documents without pulling their text into context.' This implies when to use and suggests not using when text is needed, but does not explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (management): Set the correspondent of a document by name (resolved to an ID internally). No content is read or returned.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. | |
| name | Yes | correspondent name to assign. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims to 'set' the correspondent, implying a write operation, but the annotations declare readOnlyHint=true. This is a direct contradiction, and the description does not clarify the actual behavior.
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 two sentences, front-loaded with the privacy tier, and every sentence adds 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 contradiction between description and annotations, and no output schema, the description does not provide complete behavioral context. It lacks information about return values, side effects, or prerequisites.
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 100% with descriptions for both parameters. The description adds that the name is resolved to an ID internally, which is slight additional 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 'Set the correspondent of a document by name (resolved to an ID internally)', providing a specific verb and resource, and distinguishes from sibling tools like paperless_set_document_type.
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 mentions 'PRIVACY TIER 1 (management)' but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (management): Set the document type of a document by name (resolved to an ID internally). No content is read or returned.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. | |
| name | Yes | document type name to assign. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a write operation ('Set the document type'), but the annotation readOnlyHint=true claims read-only behavior. This is a direct contradiction. Additionally, the description states 'No content is read or returned,' which adds context but does not resolve the contradiction.
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 a single, concise sentence that efficiently conveys the purpose and key behavior without unnecessary 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 is mostly complete for a simple set tool, but it lacks information about the return value or success indication. The contradiction with annotations also reduces completeness.
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 schema already describes both parameters (document_id and name) with clear descriptions, so the schema coverage is 100%. The description adds value by explaining that the name is 'resolved to an ID internally,' which clarifies the mapping.
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 action ('Set the document type'), the resource ('a document'), and the method ('by name, resolved to an ID internally'), which distinguishes it from sibling tools like paperless_set_correspondent and paperless_tag_document.
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 does not explicitly state when to use this tool vs alternatives or when not to use it. The context of 'management' is implied but no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (metadata only): Return Paperless-ngx's OWN built-in suggestions for tags, correspondents, document types, dates, and storage paths for a document. These are computed server-side inside Paperless; no OCR content enters the model context. IDs are resolved to names.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true. Description adds that IDs are resolved to names and that no OCR content is used, providing extra behavioral context beyond what annotations convey.
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, each adding value. Front-loaded with main purpose, immediately followed by key behavioral note. No 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?
Given the tool's simplicity (single integer parameter, no output schema), the description covers the functionality and privacy concern. Lacks detail on output format, but for a suggestion tool this is acceptable.
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?
Only one parameter (document_id) with 100% schema coverage (description 'Paperless document ID.'). The description does not add additional meaning beyond the schema, but baseline is 3 due to high coverage.
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?
Clearly states the tool returns built-in suggestions for multiple fields (tags, correspondents, etc.) for a document. The verb 'suggest' and resource are specific, and it distinguishes from siblings like paperless_list_tags or paperless_tag_document.
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 useful context: suggestions are server-side, no OCR content enters context. This implies appropriate use cases (when you need suggestions without exposing content). Could be more explicit about alternatives or when not to use, but current guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIVACY TIER 1 (management): Set the tags on a document. Accepts tag NAMES (resolved to IDs internally). This REPLACES the document's tag set with exactly the tags provided. Returns the applied tags. No document content is read or returned.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Paperless document ID. | |
| tag_names | Yes | Tag names to apply. Unknown names are reported in `unresolved`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool 'Sets' tags and 'REPLACES' the tag set, indicating a mutation, but annotations declare readOnlyHint=true. This is a direct contradiction, severely undermining transparency and trust.
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 three sentences long and front-loaded with the privacy tier. It is concise but could omit 'PRIVACY TIER 1 (management)' as it adds little. Overall, good structure with no unnecessary 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 explains the return value (applied tags) and the resolution of tag names, making it fairly complete given the tool's simplicity. However, the annotation contradiction introduces uncertainty about actual behavior, reducing completeness.
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 100%, and the description adds useful context: tag names are resolved to IDs internally, and unknown names are reported in 'unresolved'. This goes beyond the schema, providing clear semantics for each parameter.
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 sets tags on a document, specifies that it accepts tag names resolved to IDs, and emphasizes that it replaces the entire tag set. This is specific and distinguishes from potential alternatives like adding or removing individual tags.
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 implies usage for setting tags but does not explicitly contrast with sibling tools like paperless_suggest_tags or provide when-to-use/when-not-to-use guidance. The 'PRIVACY TIER 1 (management)' label is vague.
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.
v1.0.0paperless_download_documentpaperless_extract_fieldpaperless_get_document_contentpaperless_get_document_metadatapaperless_get_statisticspaperless_list_correspondentspaperless_list_document_typespaperless_list_tagspaperless_search_documentspaperless_set_correspondentpaperless_set_document_typepaperless_suggest_tagspaperless_tag_documentScored across 13 tools
Each tool has a clearly distinct purpose, from downloading full documents to extracting specific fields or setting metadata. The descriptions explicitly differentiate between returning full content, metadata only, or specific extracted fields, leaving no ambiguity.
All tools follow a consistent `paperless_verb_noun` pattern using snake_case. Verbs like `get`, `list`, `set`, `search`, `extract`, `download` clearly indicate the action, and nouns are precise and consistent.
With 13 tools, the set is well-scoped for a document management server. The number is sufficient to cover essential operations without being overwhelming, though it slightly borders on the higher end of the ideal range.
The tools cover most common operations: listing, searching, reading metadata/content/downloading, extracting fields, and updating metadata. Missing are create/delete document tools, but the core workflow for managing documents is well supported.
DocBase MCP server for AI agents
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Agentic search over your Dewey document collections from any MCP-compatible client.
