Skip to main content
Glama
cubinet-code

paperless-ngx-mcp

by cubinet-code
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

update_document

Idempotent

Modify a single document's fields like title, tags, or correspondent, changing only the values you provide. Ideal for fixing metadata or content without altering other properties.

Instructions

Update fields on ONE document (PATCH — only fields you supply are changed). To change tags, prefer add_tags / remove_tags: they leave the other tags alone. tags REPLACES the whole list — any tag you leave out is removed. Every tag change returns tag_changes {added, removed}. Editable fields: title, correspondent, document_type, storage_path, tags, add_tags, remove_tags, content (raw searchable text), created (document date, YYYY-MM-DD), archive_serial_number, owner, custom_fields. For applying the same change to MANY documents, see edit_documents_bulk. To add a comment/annotation rather than change a field, see create_document_note.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesThe ID of the document to update
tagsNoREPLACES all tags with exactly this list — tags not listed are removed. To add or remove single tags use add_tags / remove_tags.
ownerNoThe ID of the user who owns the document
titleNoThe new title for the document (max 128 characters). Paperless also derives the stored file name from it and replaces characters that aren't allowed in file names (such as /), so archived_file_name can differ from the title.
contentNoThe raw text content of the document (used for searching)
createdNoThe creation date in YYYY-MM-DD format
add_tagsNoTag IDs to add; the document's other tags are kept
remove_tagsNoTag IDs to remove; the document's other tags are kept
storage_pathNoThe ID of the storage path to assign
correspondentNoThe ID of the correspondent to assign
custom_fieldsNoArray of custom field values to assign
document_typeNoThe ID of the document type to assign
archive_serial_numberNoThe archive serial number (0-4294967295)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv3.2.1
    • addedInput schema / properties / add_tags
      Added value: +{
+  "description": "Tag IDs to add; the document's other tags are kept",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / remove_tags
      Added value: +{
+  "description": "Tag IDs to remove; the document's other tags are kept",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / tags / description
      Previous value: -"Array of tag IDs to assign to the document"New value: +"REPLACES all tags with exactly this list — tags not listed are removed. To add or remove single tags use add_tags / remove_tags."
    • changedInput schema / properties / title / description
      Previous value: -"The new title for the document (max 128 characters)"New value: +"The new title for the document (max 128 characters). Paperless also derives the stored file name from it and replaces characters that aren't allowed in file names (such as /), so archived_file_name can differ from the title."
  2. First observedv3.2.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds important mutation semantics: PATCH only changes supplied fields, `tags` replaces the entire list, and every tag change returns tag_changes {added, removed}. It does not cover auth requirements or rate limits, but for a partial-update tool this is solid added context.

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 core operation is front-loaded in the first sentence, followed by tag-specific caveats, return info, field list, and routing. It is dense but every sentence serves tool selection or correct invocation; the field list is somewhat lengthy but earned by the 13-parameter surface.

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?

For a 13-parameter mutation tool with no output schema, the description covers the partial-update contract, tag side effects, return payload for tag changes, and sibling alternatives. It omits permission or error details, but an agent has enough to invoke and route correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so all 13 parameters are documented in the schema. The description lists the editable fields and repeats the tag-replacement warning, but adds little semantic detail beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the parameter documentation.

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?

States a precise verb and resource: 'Update fields on ONE document (PATCH — only fields you supply are changed).' It distinguishes the partial-update behavior and singles out the single-document scope, which separates it from edit_documents_bulk. An agent can identify the operation and scope immediately.

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?

Explicitly routes to alternatives: use add_tags/remove_tags instead of tags for non-replacing tag changes, use edit_documents_bulk for many documents, and use create_document_note for comments. It names the situations that select sibling tools, so the agent knows when not to use this tool.

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

Deploy Server

Other Tools