Skip to main content
Glama
enesjakoruzh
baruchiro

paperless-mcp

by baruchiro
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Hybrid

Paperless-NGX MCP Server

CodeRabbit Pull Request Reviews

An MCP (Model Context Protocol) server for interacting with a Paperless-NGX API server. This server provides tools for managing documents, tags, correspondents, and document types in your Paperless-NGX instance.

Quick Start

Install MCP Server

Installation

Add these to your MCP config file:

// STDIO mode (recommended for local or CLI use)

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

// HTTP mode (recommended for Docker or remote use)

"paperless": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/baruchiro/paperless-mcp:latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

  1. Get your API token:

    1. Log into your Paperless-NGX instance

    2. Click your username in the top right

    3. Select "My Profile"

    4. Click the circular arrow button to generate a new token

  2. Replace the placeholders in your MCP config:

    • http://your-paperless-instance:8000 with your Paperless-NGX URL

    • your-api-token with the token you just generated

    • https://your-public-domain.com with your public Paperless-NGX URL (optional, falls back to PAPERLESS_URL)

Environment Variables

Variable

Required

Default

Description

PAPERLESS_URL

Yes

—

Base URL of your Paperless-NGX instance

PAPERLESS_API_KEY

Yes

—

API token from your Paperless-NGX profile

PAPERLESS_PUBLIC_URL

No

PAPERLESS_URL

Public-facing URL for document links

PAPERLESS_API_VERSION

No

9

Paperless-ngx REST API version. 9 works on Paperless-ngx v2.x (recent) and v3.x. Paperless-ngx v3.0.0 dropped support for versions below 9, so older defaults now return HTTP 406. If you see HTTP 406 errors, set this to a version your server supports.

PAPERLESS_MCP_UPLOAD_PATHS

No

—

Colon-separated list of allowed directories for file_path uploads. Recommended for security. Example: /var/uploads:/tmp/scans

That's it! Now you can ask Claude to help you manage your Paperless-NGX documents.

Example Usage

Here are some things you can ask Claude to do:

  • "Show me all documents tagged as 'Invoice'"

  • "Search for documents containing 'tax return'"

  • "Create a new tag called 'Receipts' with color #FF0000"

  • "Download document #123"

  • "List all correspondents"

  • "Create a new document type called 'Bank Statement'"

Related MCP server: paperless-mcp

Available Tools

Document Operations

list_documents

Get a paginated list of documents with simple filters. Use this for straightforward listing tasks. For full-text queries, structured custom field filtering, or advanced Paperless filters, use query_documents.

Parameters:

  • page (optional): Page number

  • page_size (optional): Number of documents per page

  • search (optional): Simple Paperless search term

  • correspondent (optional): Correspondent ID

  • document_type (optional): Document type ID

  • tag (optional): Tag ID

  • storage_path (optional): Storage path ID

  • created__date__gte (optional): Created date on or after YYYY-MM-DD

  • created__date__lte (optional): Created date on or before YYYY-MM-DD

  • ordering (optional): Paperless ordering field

  • archive_serial_number (optional): Archive serial number

  • archive_serial_number__isnull (optional): Whether the archive serial number is empty

  • custom_field_query (optional): Raw JSON-encoded Paperless custom field query string

  • custom_fields__icontains (optional): Case-insensitive substring match across custom field values

list_documents({
  page: 1,
  page_size: 25
})

query_documents

Canonical document query tool. Supports full-text querying, simple Paperless search, custom field filters, and documented /api/documents/ Paperless query parameters.

Parameters:

  • page (optional): Page number

  • page_size (optional): Number of documents per page

  • ordering (optional): Paperless ordering field

  • query (optional): Full-text query string

  • search (optional): Simple Paperless search term

  • more_like_id (optional): Find documents similar to this document ID

  • correspondent (optional): Correspondent ID

  • document_type (optional): Document type ID

  • tag (optional): Tag ID

  • storage_path (optional): Storage path ID

  • created__date__gte (optional): Created date on or after YYYY-MM-DD

  • created__date__lte (optional): Created date on or before YYYY-MM-DD

  • custom_field_query (optional): Structured Paperless custom field query using [field_name_or_id, operator, value] leaves or ["AND" | "OR", [clause1, clause2]] groups

  • paperless_filters (optional): Additional documented /api/documents/ Paperless query parameters, passed as key/value pairs

// Full-text query
query_documents({
  query: "invoice 2024"
})

// Simple search term
query_documents({
  search: "acme"
})

// Custom field exact match
query_documents({
  custom_field_query: ["Invoice Number", "exact", "12345"]
})

// Custom field empty
query_documents({
  custom_field_query: ["OR", [
    ["Invoice Number", "isnull", true],
    ["Invoice Number", "exact", ""]
  ]]
})

// Custom field missing
query_documents({
  custom_field_query: ["Invoice Number", "exists", false]
})

// Combined filters
query_documents({
  query: "invoice",
  tag: 5,
  created__date__gte: "2024-01-01",
  custom_field_query: ["Invoice Number", "exists", true]
})

// One documented Paperless filter that is not a first-class argument
query_documents({
  paperless_filters: {
    id__in: [101, 202, 303]
  }
})

get_document

Get a specific document by ID.

Parameters:

  • id: Document ID

get_document({
  id: 123
})

search_documents

Deprecated compatibility wrapper for full-text search. Prefer query_documents({ query: ... }) for new integrations.

Parameters:

  • query: Search query string

search_documents({
  query: "invoice 2024"
})

download_document

Download a document file by ID.

Parameters:

  • id: Document ID

  • original (optional): If true, downloads original file instead of archived version

download_document({
  id: 123,
  original: false
})

get_document_thumbnail

Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.

Parameters:

  • id: Document ID

get_document_thumbnail({
  id: 123
})

bulk_edit_documents

Perform bulk operations on multiple documents.

Parameters:

  • documents: Array of document IDs

  • method: One of:

    • set_correspondent: Set correspondent for documents

    • set_document_type: Set document type for documents

    • set_storage_path: Set storage path for documents

    • add_tag: Add a tag to documents

    • remove_tag: Remove a tag from documents

    • modify_tags: Add and/or remove multiple tags

    • delete: Delete documents

    • reprocess: Reprocess documents

    • set_permissions: Set document permissions

    • merge: Merge multiple documents

    • split: Split a document into multiple documents

    • rotate: Rotate document pages

    • delete_pages: Delete specific pages from a document

  • Additional parameters based on method:

    • correspondent: ID for set_correspondent

    • document_type: ID for set_document_type

    • storage_path: ID for set_storage_path

    • tag: ID for add_tag/remove_tag

    • add_tags: Array of tag IDs for modify_tags

    • remove_tags: Array of tag IDs for modify_tags

    • set_permissions: Object for set_permissions with view/change users and groups ({"view": {"users": [], "groups": []}, "change": {...}}). Omitted actions/lists are left untouched

    • owner: User ID (or null to remove) for set_permissions. Unless merge is true, omitting owner clears the current owner

    • merge: Boolean for set_permissions — true adds to existing permissions and keeps the owner; false (default) replaces the listed users/groups

    • metadata_document_id: ID for merge to specify metadata source

    • delete_originals: Boolean for merge/split

    • pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"

    • degrees: Number for rotate (90, 180, or 270)

Examples:

// Add a tag to multiple documents
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

// Set correspondent and document type
bulk_edit_documents({
  documents: [4, 5],
  method: "set_correspondent",
  correspondent: 2
})

// Merge documents
bulk_edit_documents({
  documents: [6, 7, 8],
  method: "merge",
  metadata_document_id: 6,
  delete_originals: true
})

// Split document into parts
bulk_edit_documents({
  documents: [9],
  method: "split",
  pages: "[1-2,3-4,5]"
})

// Modify multiple tags at once
bulk_edit_documents({
  documents: [10, 11],
  method: "modify_tags",
  add_tags: [1, 2],
  remove_tags: [3, 4]
})

// Modify custom fields
bulk_edit_documents({
  documents: [12, 13],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 2, value: "year" }
  ],
  remove_custom_fields: []
})

// Set an empty custom field value, e.g. a date field used as a pending marker
bulk_edit_documents({
  documents: [14],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 9, value: "" }
  ],
  remove_custom_fields: []
})

post_document

Upload a new document to Paperless-NGX.

Two upload modes:

  1. Base64 mode (traditional): Provide file (base64-encoded content) + filename

  2. Filesystem mode (efficient): Provide file_path (absolute path on server)

Security Note: When using file_path, set the PAPERLESS_MCP_UPLOAD_PATHS environment variable (colon-separated list of allowed directories) to restrict uploads to specific locations. Without this, any file on the server's filesystem could be uploaded.

Parameters:

  • file (optional): Base64 encoded file content. Either file or file_path required.

  • file_path (optional): Absolute path to file on server's filesystem. Either file or file_path required.

  • filename (optional): Name of the file. Required with file, optional with file_path (derives from path).

  • title (optional): Title for the document

  • created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")

  • correspondent (optional): ID of a correspondent

  • document_type (optional): ID of a document type

  • storage_path (optional): ID of a storage path

  • tags (optional): Array of tag IDs

  • archive_serial_number (optional): Archive serial number

  • custom_fields (optional): Array of custom field IDs

File size limit: 100MB for both modes

// Base64 mode (traditional)
post_document({
  file: "base64_encoded_content",
  filename: "invoice.pdf",
  title: "January Invoice",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001",
  custom_fields: [1, 2]
})

// Filesystem mode (more efficient for large files)
post_document({
  file_path: "/var/uploads/invoice.pdf",
  title: "January Invoice",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3]
})

Document Notes

list_document_notes

List all notes attached to a document.

Parameters:

  • id: Document ID

list_document_notes({
  id: 123
})

create_document_note

Add a note to a document. Returns the document's full list of notes.

Parameters:

  • id: Document ID

  • note: The note text to add

create_document_note({
  id: 123,
  note: "Invoice paid on 2026-06-30 from Commerzbank account."
})

delete_document_note

⚠️ Delete a single note from a document by its note ID. This operation is irreversible.

Parameters:

  • id: Document ID

  • note_id: The ID of the note to delete

  • confirm: Must be true to confirm this destructive operation

delete_document_note({
  id: 123,
  note_id: 5,
  confirm: true
})

Tag Operations

list_tags

Get all tags.

list_tags()

create_tag

Create a new tag.

Parameters:

  • name: Tag name

  • color (optional): Hex color code (e.g. "#ff0000")

  • match (optional): Text pattern to match

  • matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: 5
})

Correspondent Operations

list_correspondents

Get all correspondents.

list_correspondents()

create_correspondent

Create a new correspondent.

Parameters:

  • name: Correspondent name

  • match (optional): Text pattern to match

  • matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: 5
})

Document Type Operations

list_document_types

Get all document types.

list_document_types()

create_document_type

Create a new document type.

Parameters:

  • name: Document type name

  • match (optional): Text pattern to match

  • matching_algorithm (optional): Number between 0 and 6: 0 - None 1 - Any word 2 - All words 3 - Exact match 4 - Regular expression 5 - Fuzzy word 6 - Automatic

create_document_type({
  name: "Invoice",
  match: "invoice total amount due",
  matching_algorithm: 1
})

Custom Field Operations

list_custom_fields

Get all custom fields.

list_custom_fields()

get_custom_field

Get a specific custom field by ID.

Parameters:

  • id: Custom field ID

get_custom_field({
  id: 1
})

create_custom_field

Create a new custom field.

Parameters:

  • name: Custom field name

  • data_type: One of "string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"

  • extra_data (optional): Extra data for the custom field, such as select options

create_custom_field({
  name: "Invoice Number",
  data_type: "string"
})

update_custom_field

Update an existing custom field.

Parameters:

  • id: Custom field ID

  • name (optional): New custom field name

  • data_type (optional): New data type

  • extra_data (optional): Extra data for the custom field

update_custom_field({
  id: 1,
  name: "Updated Invoice Number",
  data_type: "string"
})

delete_custom_field

Delete a custom field.

Parameters:

  • id: Custom field ID

delete_custom_field({
  id: 1
})

bulk_edit_custom_fields

Perform bulk operations on multiple custom fields.

Parameters:

  • custom_fields: Array of custom field IDs

  • operation: One of "delete"

bulk_edit_custom_fields({
  custom_fields: [1, 2, 3],
  operation: "delete"
})

Mail Operations

Tools for managing Paperless mail accounts and the mail rules that drive automatic email ingestion. Account passwords/tokens are never exposed: they are redacted from every tool response.

list_mail_accounts

List mail accounts so you can pick the account ID needed when creating a mail rule. Passwords are redacted.

Parameters:

  • page (optional): Page number

  • page_size (optional): Number of results per page

list_mail_accounts()

get_mail_account

Get a single mail account by ID. Password/token fields are redacted.

Parameters:

  • id: Mail account ID

get_mail_account({
  id: 1
})

process_mail_account

Manually trigger Paperless mail processing for one account. This can consume matching mails according to the account's enabled mail rules.

Parameters:

  • id: Mail account ID

process_mail_account({
  id: 1
})

list_mail_rules

List mail rules with optional pagination.

Parameters:

  • page (optional): Page number

  • page_size (optional): Number of results per page

list_mail_rules()

get_mail_rule

Get a single mail rule by ID.

Parameters:

  • id: Mail rule ID

get_mail_rule({
  id: 1
})

create_mail_rule

Create a mail rule. Use list_mail_accounts first to choose the account.

Required parameters:

  • name: Rule name

  • account: Mail account ID

  • folder: IMAP folder to scan (e.g. "INBOX")

Common optional parameters:

  • enabled (default true): Whether the rule is active

  • filter_from / filter_to / filter_subject / filter_body: Match incoming mail

  • maximum_age: Only process mail newer than this many days

  • action: 1=Delete, 2=Move to folder, 3=Mark as read, 4=Flag, 5=Tag

  • action_parameter: Target folder/tag for the chosen action

  • assign_title_from: 1=Subject, 2=Attachment filename, 3=Do not assign

  • assign_tags / assign_correspondent / assign_document_type: Metadata to apply

  • assign_correspondent_from: 1=None, 2=Mail address, 3=Sender name, 4=Use assign_correspondent

  • attachment_type: 1=Attachments only, 2=All files incl. inline

  • consumption_scope: 1=Attachments only, 2=Full mail as .eml, 3=Both

  • pdf_layout: 0=System default, 1=Text+HTML, 2=HTML+text, 3=HTML only, 4=Text only

create_mail_rule({
  name: "Invoices",
  account: 1,
  folder: "INBOX",
  filter_subject: "invoice",
  action: 3,
  attachment_type: 1
})

update_mail_rule

Patch an existing mail rule. Only the fields you supply are changed.

Parameters:

  • id: Mail rule ID

  • ...any of the create_mail_rule fields to update

update_mail_rule({
  id: 1,
  enabled: false
})

delete_mail_rule

Delete a mail rule. Requires an explicit confirmation flag. This changes future mail ingestion behavior but does not delete any existing documents.

Parameters:

  • id: Mail rule ID

  • confirm: Must be true to confirm deletion

delete_mail_rule({
  id: 1,
  confirm: true
})

Error Handling

The server will show clear error messages if:

  • The Paperless-NGX URL or API token is incorrect

  • The Paperless-NGX server is unreachable

  • The requested operation fails

  • The provided parameters are invalid

Testing

Unit tests

Run the unit test suite (no external dependencies required):

npm test

E2E tests

The E2E suite boots an empty Paperless-ngx instance, runs the compiled MCP server, and drives a deterministic serial scenario through tools/call requests — creating a tag, correspondent, and document type, uploading a PDF, then exercising list / get / search / download / thumbnail / bulk-edit on the same document. No LLM and no Paperless REST client outside MCP.

Prerequisites: Docker, Docker Compose, and jq.

# 1. Build the MCP server
npm run build

# 2. Start Paperless-ngx
docker compose -f docker-compose.e2e.yml up -d

# 3. Wait for Paperless to be ready, then get a token
TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')

# 4. Start the MCP server
node build/index.js --http --port 3001 \
  --baseUrl http://localhost:8000 --token "$TOKEN" &
MCP_PID=$!

# 5. Run the E2E tests
MCP_URL=http://localhost:3001/mcp \
PAPERLESS_URL=http://localhost:8000 \
PAPERLESS_TOKEN="$TOKEN" \
npm run test:e2e

# 6. Cleanup
kill "$MCP_PID"
docker compose -f docker-compose.e2e.yml down -v

E2E tests also run automatically in CI on every pull request and push to main, covering both the build/index.js CLI and the published Docker image.

Development

Want to contribute or modify the server? Here's what you need to know:

  1. Clone the repository

  2. Install dependencies:

npm install

  1. Make your changes to server.js

  2. Test locally:

node server.js http://localhost:8000 your-test-token

The server is built with:

  • litemcp: A TypeScript framework for building MCP servers

  • zod: TypeScript-first schema validation

API Documentation

This MCP server implements endpoints from the Paperless-NGX REST API. For more details about the underlying API, see the official documentation.

Running the MCP Server

The MCP server can be run in two modes:

1. stdio (default)

This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.

npm run start -- <baseUrl> <token>

2. HTTP (Streamable HTTP Transport)

To run the server as an HTTP service, use the --http flag. You can also specify the port with --port (default: 3000). This mode requires Express to be installed (it is included as a dependency).

npm run start -- <baseUrl> <token> --http --port 3000

  • The MCP API will be available at POST /mcp on the specified port.

  • Each request is handled statelessly, following the StreamableHTTPServerTransport pattern.

  • GET and DELETE requests to /mcp will return 405 Method Not Allowed.

Per-request API token (HTTP/Docker mode)

In HTTP mode, clients authenticate by supplying a Paperless-NGX API token via the standard Authorization header:

Authorization: Bearer <paperless-ngx-api-token>

The token is passed straight through to Paperless-NGX, so each client's own Paperless permissions are enforced end-to-end. This lets a single server instance serve multiple users, each with their own token. The same behaviour applies to both /mcp and /sse endpoints.

⚠️ Breaking change in v2.0.0 — HTTP mode is now authenticated by default.

Previously, a request with no Authorization header silently fell back to the server-configured PAPERLESS_API_KEY, which left the HTTP endpoint open to anyone who could reach the port. As of v2.0.0, requests without a Bearer token are rejected with 401 Unauthorized. The server token is never used for unauthenticated requests unless you explicitly opt in with --no-auth.

Scenario

--no-auth off (default)

--no-auth on

Client sends Authorization: Bearer <tok>

<tok> (client-supplied)

<tok> (client-supplied)

No header, PAPERLESS_API_KEY / --token set

401 Unauthorized

server token

No header, no server token

401 Unauthorized

401 Unauthorized

Migrating from v1.x: if you relied on the old fallback (a single shared PAPERLESS_API_KEY with clients that don't send a token), you have two options:

  1. Recommended: have each client send Authorization: Bearer <paperless-token>.

  2. Restore the old behaviour (trusted/local networks only): start the server with the --no-auth flag, e.g. append it to the Docker command/args or your CLI invocation. This requires a server token (PAPERLESS_API_KEY or --token) to be configured.

The MCP server can be deployed using Docker and Docker Compose. The Docker image automatically runs in HTTP mode with SSE (Server-Sent Events) support on port 3000.

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  paperless-mcp:
    container_name: paperless-mcp
    image: ghcr.io/baruchiro/paperless-mcp:latest
    environment:
      - PAPERLESS_URL=http://your-paperless-ngx-server:8000
      - PAPERLESS_API_KEY=your-paperless-api-key
      - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
    ports:
      - "3000:3000"
    restart: unless-stopped

Then run:

docker-compose up -d

Using with Continue VS Code Extension

If you're using the Continue VS Code extension, you can configure it to use the Dockerized MCP server via SSE.

Create or edit .continue/mcpServers/paperless-mcp.yaml at your workspace root:

name: Paperless
version: 0.0.1
schema: v1
mcpServers:
  - name: Paperless
    type: sse
    url: http://localhost:3000/sse

Notes:

  • Replace localhost with your Docker host's IP address or hostname if running on a remote server

  • The Docker container handles authentication via environment variables, so no credentials are needed in the Continue config

  • The SSE endpoint is available at /sse on the configured port (default: 3000)

Credits

This project is a fork of nloui/paperless-mcp. Many thanks to the original author for their work. Contributions and improvements may be returned upstream.

Debugging

To debug the MCP server in VS Code, use the following launch configuration:

{
    "type": "node",
    "request": "launch",
    "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
    "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
    "args": [
        "--esm",
        "src/index.ts",
        "--http",
        "--baseUrl",
        "http://your-paperless-instance:8000",
        "--token",
        "your-api-token",
        "--port",
        "3002"
    ],
    "env": {
        "NODE_OPTIONS": "--loader ts-node/esm",
    },
    "console": "integratedTerminal",
    "skipFiles": [
        "<node_internals>/**"
    ]
}

Important: Before debugging, uncomment the following line in src/index.ts (around line 175):

// await new Promise((resolve) => setTimeout(resolve, 1000000));

This prevents the server from exiting immediately and allows you to set breakpoints and debug the code.

Available Tools

23 tools
bulk_edit_correspondentsD
ParametersJSON Schema
NameRequiredDescriptionDefault
correspondent_idsYes
mergeNo
operationYes
ownerNo
permissionsNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_edit_documentsD
ParametersJSON Schema
NameRequiredDescriptionDefault
add_tagsNo
correspondentNo
degreesNo
delete_originalsNo
document_typeNo
documentsYes
metadata_document_idNo
methodYes
pagesNo
permissionsNo
remove_tagsNo
storage_pathNo
tagNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_edit_document_typesD
ParametersJSON Schema
NameRequiredDescriptionDefault
document_type_idsYes
mergeNo
operationYes
ownerNo
permissionsNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bulk_edit_tagsD
ParametersJSON Schema
NameRequiredDescriptionDefault
mergeNo
operationYes
ownerNo
permissionsNo
tag_idsYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_correspondentD
ParametersJSON Schema
NameRequiredDescriptionDefault
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_document_typeD
ParametersJSON Schema
NameRequiredDescriptionDefault
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_tagD
ParametersJSON Schema
NameRequiredDescriptionDefault
colorNo
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_correspondentD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_document_typeD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_tagD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_documentD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
originalNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_correspondentD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_documentD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_document_typeD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_correspondentsD
ParametersJSON Schema
NameRequiredDescriptionDefault
name__icontainsNo
name__iendswithNo
name__iexactNo
name__istartswithNo
orderingNo
pageNo
page_sizeNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_documentsA

List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST use the relevant tool (e.g., 'list_tags', 'list_correspondents', 'list_document_types', 'list_storage_paths') to find the correct ID, and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results.

ParametersJSON Schema
NameRequiredDescriptionDefault
correspondentNo
created__gteNo
created__lteNo
document_typeNo
orderingNo
pageNo
page_sizeNo
searchNo
storage_pathNo
tagNo

TDQS

A4.5/5.0
Behavior4/5

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 key behavioral traits: it's a read operation (implied by 'list'), supports pagination (via 'page' and 'page_size' parameters), and emphasizes accuracy trade-offs between ID filters and free-text search. However, it doesn't mention rate limits, authentication needs, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. The second sentence provides crucial usage guidelines, and every sentence adds value. However, it could be slightly more concise by integrating the 'IMPORTANT' note more smoothly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, 0% schema coverage, no annotations, no output schema), the description does well. It covers purpose, usage guidelines, parameter semantics, and behavioral context. The main gap is lack of output format details, but with no output schema, this is a minor omission in an otherwise thorough description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 explains the semantics of parameters by listing filterable fields (title, correspondent, document type, tag, storage path, creation date) and clarifies that 'search' is for free-text when no field applies. It also implies that parameters like 'correspondent' expect IDs obtained from sibling tools. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more.' This is specific (verb+resource+scope) and distinguishes it from siblings like 'search_documents' by emphasizing field-based filtering versus free-text search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 versus alternatives. It specifies to use sibling tools (e.g., 'list_tags') first to find IDs for filtering, and to use 'search' only for free-text when no field applies. It also warns that using correct IDs yields more accurate results, clearly differentiating from 'search_documents'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_document_typesA

List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.

ParametersJSON Schema
NameRequiredDescriptionDefault
name__icontainsNo
name__iendswithNo
name__iexactNo
name__istartswithNo
orderingNo
pageNo
page_sizeNo

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses important behavioral traits: that this is a listing/fetching operation (implied read-only), recommends caching strategy, mentions pagination parameters ('large enough page_size'), and suggests this reduces redundant requests. It doesn't explicitly state whether this is read-only or has side effects, but the 'list' verb and context imply safe reading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized (two sentences) but not optimally structured. The first sentence states the purpose clearly, but the second sentence contains complex guidance that might be better separated. While every sentence earns its place, the front-loading could be improved by separating basic usage from advanced caching strategy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a listing tool with 7 undocumented parameters and no output schema, the description provides good behavioral context but insufficient parameter information. The guidance about caching and session strategy is valuable, but the complete lack of parameter documentation leaves significant gaps. Without annotations or output schema, the description should do more to explain what this tool returns and how to use its filtering parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for all 7 parameters, and the description provides no information about any parameters. It mentions 'page_size' generically in usage guidance but doesn't explain what it does, its format, or default values. The description fails to compensate for the complete lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List all document types' - a specific verb+resource combination. It distinguishes itself from sibling tools like 'get_document_type' (singular) and 'bulk_edit_document_types' (mutation). However, it doesn't explicitly differentiate from 'list_documents' or 'list_tags' beyond the resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'When a user query may refer to a document type or tag, you should fetch all document types and all tags up front... cache them for the session, and search locally.' It gives clear context about when to use this tool (for initial data gathering) and mentions the alternative resource ('tags'), though it doesn't name specific sibling tools for comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsA

List all tags. IMPORTANT: When a user query may refer to a tag or document type, you should fetch all tags and all document types up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.

ParametersJSON Schema
NameRequiredDescriptionDefault
name__icontainsNo
name__iendswithNo
name__iexactNo
name__istartswithNo
orderingNo
pageNo
page_sizeNo

TDQS

A3.7/5.0
Behavior4/5

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 key behavioral traits: it's a read operation (implied by 'List'), supports pagination (via 'page_size'), and includes caching strategies to reduce API calls. It doesn't cover error handling or rate limits, but adds substantial context beyond basic listing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: one states the purpose, and the other provides detailed usage guidelines. It's front-loaded with the core function but includes verbose caching instructions that might be better suited for general agent guidance rather than tool-specific description. Some redundancy exists in emphasizing efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, 7 parameters with 0% schema coverage, and no output schema, the description is incomplete. It covers usage context and caching well but lacks parameter explanations and return value details. For a list tool with many filter parameters, this leaves significant gaps in understanding how to invoke it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 for 7 undocumented parameters. It only mentions 'page_size' indirectly in the caching advice but doesn't explain any parameters like 'name__icontains' or 'ordering'. This leaves most parameter meanings unclear, failing to adequately address the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List all tags.' This is a specific verb ('List') and resource ('tags'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_correspondents' or 'list_document_types' beyond the resource name, which is why it's not a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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: 'When a user query may refer to a tag or document type, you should fetch all tags and all document types up front...' It mentions caching for efficiency and handling ambiguity with document types, though it doesn't name specific alternative tools. This is comprehensive usage advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

post_documentD
ParametersJSON Schema
NameRequiredDescriptionDefault
archive_serial_numberNo
correspondentNo
createdNo
custom_fieldsNo
document_typeNo
fileYes
filenameYes
storage_pathNo
tagsNo
titleNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_documentsA

Full text search for documents. This tool is for searching document content, title, and metadata using a full text query. For general document listing or filtering by fields, use 'list_documents' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

TDQS

A4.4/5.0
Behavior3/5

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 describes the search behavior (full text across content, title, metadata) but lacks details on permissions, rate limits, pagination, or result format. The description is adequate but has gaps in behavioral context for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by a clear usage guideline. Both sentences earn their place by adding value, with no wasted words or redundancy, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (search operation with 1 parameter), no annotations, and no output schema, the description provides good contextual coverage. It explains the tool's purpose, usage, and parameter semantics, though it could benefit from more behavioral details like result format or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 1 parameter with 0% description coverage. The description adds meaningful context by explaining that the 'query' parameter is for 'full text search' across multiple document aspects, which compensates well for the schema's lack of detail, though it doesn't specify query syntax or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('full text search') and resources ('documents'), and explicitly distinguishes it from its sibling 'list_documents' by specifying it searches content, title, and metadata rather than general listing or field filtering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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 searching document content, title, and metadata using a full text query') and when to use an alternative ('For general document listing or filtering by fields, use 'list_documents' instead'), clearly differentiating between search and listing operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_correspondentD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_document_typeD
ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_tagD
ParametersJSON Schema
NameRequiredDescriptionDefault
colorNo
idYes
matchNo
matching_algorithmNo
nameYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 23 tool updatesv1.0.0
    • First observedbulk_edit_correspondents
    • First observedbulk_edit_document_types
    • First observedbulk_edit_documents
    • First observedbulk_edit_tags
    • First observedcreate_correspondent
    • First observedcreate_document_type
    • First observedcreate_tag
    • First observeddelete_correspondent
    • First observeddelete_document_type
    • First observeddelete_tag
    • First observeddownload_document
    • First observedget_correspondent
    • First observedget_document
    • First observedget_document_type
    • First observedlist_correspondents
    • First observedlist_document_types
    • First observedlist_documents
    • First observedlist_tags
    • First observedpost_document
    • First observedsearch_documents
    • First observedupdate_correspondent
    • First observedupdate_document_type
    • First observedupdate_tag
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.3/5.0

Scored across 23 tools

Disambiguation5/5

Every tool has a clearly distinct purpose targeting specific resources and actions with no ambiguity. For example, list_documents and search_documents are clearly differentiated by their descriptions, and bulk_edit operations are separate from individual CRUD tools. The tool set covers correspondents, document types, tags, and documents with no overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case throughout. Verbs like create, delete, get, list, update, bulk_edit, download, post, and search are applied consistently across different nouns (e.g., correspondent, document_type, tag, document), making the naming highly predictable and readable.

Tool Count4/5

With 23 tools, the count is slightly high but reasonable for a document management system like Paperless, which needs to handle multiple entities (documents, correspondents, tags, document types). It's well-scoped with each tool earning its place, though it borders on being heavy compared to typical 3-15 tool ranges.

Completeness5/5

The tool set provides complete CRUD/lifecycle coverage for the domain, including create, get, list, update, and delete operations for correspondents, document types, and tags, plus document management with post, download, list, and search. There are no obvious gaps, and the descriptions for list_documents and search_documents clarify their roles, ensuring agents can handle all core workflows without dead ends.

Maintenance

ActivityActive
ResponsivenessWithin a week

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches