Skip to main content
Glama
Sign In
mcp-paperless-ngx

mcp-paperless-ngx

by tobee89
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Merge documents

merge_documents
Destructive

Consolidate several documents into a single PDF in the order given, while retaining originals unless deletion is requested.

Instructions

Merge several documents into one new PDF, in the order given. The originals stay unless delete_originals is set. Runs asynchronously — poll the returned task with get_task.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "documents": "<documents>"
    },
    "name": "merge_documents"
  }
}

Input Schema

NameRequiredDescriptionDefault
documentsYesDocument IDs in the order the pages should appear.
archive_fallbackNoFall back to the archived PDF/A version when an original cannot be merged.
delete_originalsNoDelete the source documents after a successful merge. Irreversible — confirm first.
metadata_document_idNoCopy tags, correspondent and type from this document onto the merged result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.4/5.0
Behavior4/5

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses the async execution model ('Runs asynchronously — poll the returned task with get_task') and the safe-by-default behavior ('The originals stay unless delete_originals is set'). These are material behavioral traits an agent must know before invoking, and they are consistent with the annotations. It does not discuss partial-failure behavior, but the archive_fallback parameter in the schema partially covers that.

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?

Three sentences with no filler: the first states the core operation and ordering requirement, the second the safety default, the third the async contract and follow-up. Each sentence carries unique information and the main verb is front-loaded.

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?

With no output schema, the description compensates by stating that a task is returned and how to follow up (get_task), which is the key missing piece. It covers purpose, ordering, safety default, and async flow. Gaps are minor: no statement of failure/partial-merge semantics and no permission prerequisites, though the destructive hint and archive_fallback schema description mitigate these.

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 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the default behavior of delete_originals ('The originals stay unless delete_originals is set'), which the schema's parameter description does not state (it only describes the effect and warns it is irreversible). This resolves a real ambiguity for an agent deciding whether to pass the flag.

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 states a specific verb and resource: 'Merge several documents into one new PDF, in the order given.' It names the output format (PDF), the ordering constraint, and by implication the resource (multiple documents → one new document). This cleanly distinguishes it from sibling PDF operations like rotate_documents and edit_pdf, which modify rather than combine.

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

Usage Guidelines4/5

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

The description gives clear usage context: ordering is the caller's responsibility, originals are preserved unless the flag is set, and the operation is asynchronous so the agent should poll with get_task. It provides a direct follow-up instruction referencing a sibling tool, though it does not name explicit when-not conditions or alternatives. Since no near-equivalent merge sibling exists among the listed tools, this is clear context without exclusions.

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