PaperDock

Upload a project file

upload_file

Destructive

Upload a new file or an explicitly approved binary replacement. For new editable UTF-8 text use content (legacy contentBase64 is text-only); existing text must use edit_file. Binary files up to 30 MiB use an out-of-band transfer or a host-provided attachment. No automatic source editing or compilation. For a binary file, use upload_file with transfer: direct and its exact sizeBytes, then send the original bytes by HTTP POST to upload.url with the returned headers. Never send multipart, JSON, Base64, or binary contents through MCP. An existing path returns confirmation_required without changing files. Name the project and file, explain that the previous binary is not recoverable through PaperDock history, and ask for explicit user approval. Only after approval repeat the same transfer with overwrite: true, expectedRevision and replacementTarget exactly as returned. These fields describe agent-reported consent and target preconditions, not server-verified human approval. If the target changed, stop and ask again; never silently refresh the revision or choose another path. Existing text must use edit_file and its Review changes flow. awaiting_upload is not success; only created or replaced confirms completion. After an uncertain transfer, check the same path and uploadId, at most twice before reporting pending. Do not create duplicate uploads. For ChatGPT attachments use the host-provided file object; never invent URLs or IDs. If file access or network policy blocks transfer, follow normal approvals or offer webUploadUrl (transfer: web); never bypass restrictions. Never expose upload authorization headers in replies or logs.

Input Schema

Name	Required	Description
`file`	No
`path`	Yes
`sha256`	No
`content`	No
`mimeType`	No
`transfer`	No	direct prepares raw HTTP upload and requires sizeBytes; web returns a file picker link when automatic transfer is unavailable.
`uploadId`	No	Check a previous upload after an uncertain transfer; do not start another transfer before checking.
`overwrite`	No	Set true only after explicit user approval of the named existing binary and the loss of its prior version. Requires the returned expectedRevision and replacementTarget.
`projectId`	Yes
`sizeBytes`	No
`contentBase64`	No
`expectedRevision`	No	The revision returned with confirmation_required; never refresh automatically after a conflict.
`replacementTarget`	No	Opaque target precondition returned with confirmation_required; not proof of human consent.

Output Schema

Name	Required	Description	Default
`file`	No
`status`	Yes
`upload`	No
`message`	No
`uploadId`	No
`webUploadUrl`	No
`expectedRevision`	No
`replacementTarget`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 29, 2026
- changedInput schema / properties / sizeBytes / maximum
```
Previous value: -26214400New value: +31457280
```

Changed17 schema fields changedOct 29, 2026

changedInput schema / oneOf

Previous value: -[
-  {
-    "required": [
-      "content"
-    ]
-  },
-  {
-    "required": [
-      "contentBase64"
-    ]
-  }
-]New value: +[
+  {
+    "required": [
+      "content"
+    ]
+  },
+  {
+    "required": [
+      "contentBase64"
+    ]
+  },
+  {
+    "required": [
+      "transfer"
+    ]
+  },
+  {
+    "required": [
+      "file"
+    ]
+  },
+  {
+    "required": [
+      "uploadId"
+    ]
+  }
+]

addedInput schema / properties / expectedRevision

Added value: +{
+  "description": "The revision returned with confirmation_required; never refresh automatically after a conflict.",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / file

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "download_url": {
+      "type": "string"
+    },
+    "file_id": {
+      "type": "string"
+    },
+    "file_name": {
+      "type": "string"
+    },
+    "mime_type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "download_url",
+    "file_id"
+  ],
+  "type": "object"
+}

addedInput schema / properties / overwrite

Added value: +{
+  "description": "Set true only after explicit user approval of the named existing binary and the loss of its prior version. Requires the returned expectedRevision and replacementTarget.",
+  "type": "boolean"
+}

addedInput schema / properties / replacementTarget

Added value: +{
+  "description": "Opaque target precondition returned with confirmation_required; not proof of human consent.",
+  "pattern": "^[a-f0-9]{64}$",
+  "type": "string"
+}

addedInput schema / properties / sizeBytes

Added value: +{
+  "maximum": 26214400,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / transfer

Added value: +{
+  "description": "direct prepares raw HTTP upload and requires sizeBytes; web returns a file picker link when automatic transfer is unavailable.",
+  "enum": [
+    "direct",
+    "web"
+  ],
+  "type": "string"
+}

addedInput schema / properties / uploadId

Added value: +{
+  "description": "Check a previous upload after an uncertain transfer; do not start another transfer before checking.",
+  "format": "uuid",
+  "type": "string"
+}

addedOutput schema / properties / expectedRevision
```
Added value: +{
+  "type": "integer"
+}
```
addedOutput schema / properties / message
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / replacementTarget
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / status / const
```
Removed value: -"created"
```

addedOutput schema / properties / status / enum

Added value: +[
+  "created",
+  "replaced",
+  "confirmation_required",
+  "awaiting_upload",
+  "manual_upload_required",
+  "uploading",
+  "failed",
+  "expired"
+]

addedOutput schema / properties / upload

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "expiresInSeconds": {
+      "type": "integer"
+    },
+    "headers": {
+      "additionalProperties": false,
+      "properties": {
+        "Authorization": {
+          "type": "string"
+        },
+        "Content-Type": {
+          "const": "application/octet-stream",
+          "type": "string"
+        }
+      },
+      "required": [
+        "Authorization",
+        "Content-Type"
+      ],
+      "type": "object"
+    },
+    "method": {
+      "const": "POST",
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "url",
+    "method",
+    "headers",
+    "expiresInSeconds"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / uploadId
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / webUploadUrl
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "file",
-  "status"
-]New value: +[
+  "status"
+]

First observedSep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already mark the tool as destructive and open-world, and the description adds crucial behavior: existing paths return confirmation_required without changing files, awaiting_upload is not success, uncertain transfers should be checked at most twice, and upload authorization headers must never be exposed. It also clarifies that expectedRevision and replacementTarget are preconditions, not server-verified human approval.

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 long but front-loaded with purpose and mode selection, then proceeds through safety-critical transfer and overwrite rules. Most sentences carry necessary operational detail, though the density is high and some warnings could be tightened.

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

Completeness5/5

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

Given the complex oneOf schema, 13 parameters, destructive annotation, and critical binary-transfer workflow, the description supplies the missing operational context: approval flow, conflict handling, retry limits, success states, and security constraints. An output schema exists, so it does not need to explain return values.

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 only 38%, but the description compensates by explaining the key mode-selection parameters, transfer semantics, size limit, overwrite approval requirements, expectedRevision conflict handling, replacementTarget meaning, and uploadId use. Some parameters such as sha256 and mimeType are not explained in prose, so it is strong but not exhaustive.

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 gives a specific verb and resource and distinguishes upload_file from create_file and edit_file: new UTF-8 text uses content, existing text must use edit_file, and binary replacement uses upload_file with an approved transfer. It also defines the scope as new file or explicitly approved binary replacement.

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?

It explicitly routes between content, contentBase64, transfer: direct, transfer: web, file attachments, uploadId checks, and edit_file. It also states the overwrite approval sequence and when to stop and ask again rather than refreshing the revision.

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

All PaperDock tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?