Common Paper

upload-attachment_multipart_form_data

Upload a PDF attachment without sending file bytes through this tool. Required: attachment.filename (local PDF path; no control characters). Optional: attachment.name only if the Common Paper attachment name should differ from the file basename; attachment.description. Do not send uploaded_by — the OAuth-authenticated MCP user is recorded as the uploader. Returns JSON with curl_command where the path is already shell-escaped — run that command exactly as returned. Do not base64-encode the PDF into this tool and do not use generate-api-key for uploads.

Input Schema

Name	Required	Description	Default
`body`	Yes

Output Schema

Name	Required	Description	Default
`curl_command`	Yes	Ready-to-run curl that POSTs the local PDF to the signed upload URL. The @path is shell-escaped by the server. Execute the string exactly as returned; do not re-quote or modify arguments.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 30, 2026

changedInput schema / properties / body / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "MCP clients: send metadata only. Returns a curl_command to POST the local PDF bytes. Do not send pdf/base64. uploaded_by is taken from the OAuth-authenticated MCP user — do not pass it.",
-    "properties": {
-      "attachment": {
-        "additionalProperties": {},
-        "properties": {
-          "description": {
-            "description": "Optional description of the file",
-            "type": "string"
-          },
-          "filename": {
-            "description": "Local PDF path on the client machine (e.g. ./Cloud Service Agreement.pdf). Must not contain control characters (newlines, null bytes, etc.). The server shell-escapes this value when building curl_command (including apostrophes); run the returned command exactly as-is and do not re-quote or edit the @path.",
-            "maxLength": 1024,
-            "minLength": 1,
-            "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
-            "type": "string"
-          },
-          "name": {
-            "description": "Optional Common Paper attachment name. Supply only when it should differ from the basename of filename.",
-            "type": "string"
-          }
-        },
-        "required": [
-          "filename"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "attachment"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "description": "application/json body for API clients. Pass the PDF as base64 in `attachment.pdf` (not a filesystem path).",
-    "properties": {
-      "attachment": {
-        "additionalProperties": {},
-        "description": "The attachment to create",
-        "properties": {
-          "description": {
-            "description": "Optional description of the file",
-            "type": "string"
-          },
-          "name": {
-            "description": "Display name for the uploaded file, including the .pdf extension",
-            "type": "string"
-          },
-          "pdf": {
-            "description": "Base64-encoded PDF file contents. Must be the raw file bytes encoded as base64 — not a filesystem path, data URI, or filename. Example: open the PDF, base64-encode its bytes, and pass that string here.",
-            "type": "string"
-          },
-          "uploaded_by": {
-            "description": "Email of a Common Paper user associated with your organization. Required for API-key uploads; not used for MCP (OAuth identity is used instead).",
-            "format": "email",
-            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
-            "type": "string"
-          }
-        },
-        "required": [
-          "pdf",
-          "name",
-          "uploaded_by"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "attachment"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "description": "multipart/form-data body. Send fields as `attachment[pdf]`, `attachment[name]`, `attachment[description]`, and `attachment[uploaded_by]`.",
-    "properties": {
-      "attachment": {
-        "additionalProperties": {},
-        "description": "The attachment to create. In multipart/form-data, send each field as `attachment[pdf]`, `attachment[name]`, `attachment[description]`, and `attachment[uploaded_by]`.",
-        "properties": {
-          "description": {
-            "description": "Optional description of the file",
-            "type": "string"
-          },
-          "name": {
-            "description": "Name of the file",
-            "type": "string"
-          },
-          "pdf": {
-            "description": "The PDF file to upload as a multipart file part",
-            "type": "string"
-          },
-          "uploaded_by": {
-            "description": "Email of a Common Paper user associated with your organization. Required for API-key uploads; not used for MCP (OAuth identity is used instead).",
-            "format": "email",
-            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
-            "type": "string"
-          }
-        },
-        "required": [
-          "pdf",
-          "name",
-          "uploaded_by"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "attachment"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "MCP clients: send metadata only. Returns a curl_command to POST the local PDF bytes. Do not send pdf/base64. uploaded_by is taken from the OAuth-authenticated MCP user — do not pass it.",
+    "properties": {
+      "attachment": {
+        "additionalProperties": {},
+        "properties": {
+          "description": {
+            "description": "Optional description of the file",
+            "type": "string"
+          },
+          "filename": {
+            "description": "Local PDF path on the client machine (e.g. ./Cloud Service Agreement.pdf). Must not contain control characters (newlines, null bytes, etc.). The server shell-escapes this value when building curl_command (including apostrophes); run the returned command exactly as-is and do not re-quote or edit the @path.",
+            "maxLength": 1024,
+            "minLength": 1,
+            "pattern": "^[^\\u0000-\\u001F\\u007F]+$",
+            "type": "string"
+          },
+          "name": {
+            "description": "Optional Common Paper attachment name. Supply only when it should differ from the basename of filename.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "filename"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "attachment"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "description": "application/json body for API clients. Pass the PDF as base64 in `attachment.pdf` (not a filesystem path).",
+    "properties": {
+      "attachment": {
+        "additionalProperties": {},
+        "description": "The attachment to create",
+        "properties": {
+          "description": {
+            "description": "Optional description of the file",
+            "type": "string"
+          },
+          "name": {
+            "description": "Display name for the uploaded file, including the .pdf extension",
+            "type": "string"
+          },
+          "pdf": {
+            "description": "Base64-encoded PDF file contents. Must be the raw file bytes encoded as base64 — not a filesystem path, data URI, or filename. Example: open the PDF, base64-encode its bytes, and pass that string here.",
+            "type": "string"
+          },
+          "uploaded_by": {
+            "description": "Email of a Common Paper user associated with your organization. Required for API-key uploads; not used for MCP (OAuth identity is used instead).",
+            "format": "email",
+            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "pdf",
+          "name",
+          "uploaded_by"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "attachment"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "description": "multipart/form-data body. Send fields as `attachment[pdf]`, `attachment[name]`, `attachment[description]`, and `attachment[uploaded_by]`.",
+    "properties": {
+      "attachment": {
+        "additionalProperties": {},
+        "description": "The attachment to create. In multipart/form-data, send each field as `attachment[pdf]`, `attachment[name]`, `attachment[description]`, and `attachment[uploaded_by]`.",
+        "properties": {
+          "description": {
+            "description": "Optional description of the file",
+            "type": "string"
+          },
+          "name": {
+            "description": "Name of the file",
+            "type": "string"
+          },
+          "pdf": {
+            "description": "The PDF file to upload as a multipart file part",
+            "type": "string"
+          },
+          "uploaded_by": {
+            "description": "Email of a Common Paper user associated with your organization. Required for API-key uploads; not used for MCP (OAuth identity is used instead).",
+            "format": "email",
+            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "pdf",
+          "name",
+          "uploaded_by"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "attachment"
+    ],
+    "type": "object"
+  }
+]

First observedSep 29, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations cover safety (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower, and the description adds real context beyond them: the tool returns JSON with a pre-shell-escaped curl_command, the OAuth-authenticated user is recorded as uploader, and filename must be free of control characters. It stops short of saying what happens on a repeat upload (no idempotency discussion) despite idempotentHint=false.

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?

Front-loads the core mechanic in the first clause, then lists required/optional fields and prohibitions in a compact sequence with no filler. Slightly overlaps the nested schema text, but each sentence carries an operational instruction an agent needs.

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?

An output schema exists, so return-value documentation is unnecessary, yet the description still flags the one return field the agent must act on (curl_command) and warns against editing it. Combined with the identity and escaping rules, an agent has everything needed to invoke this correctly via the metadata path.

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?

Adds meaning beyond the schema: filename is a local PDF path (not bytes), name is only needed when it should differ from the file basename, description is free-form, and uploaded_by must be omitted because the server derives it. It does not explain the other two schema branches (base64 and multipart variants), leaving that mode selection undocumented in the description.

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?

States a specific verb and resource ('Upload a PDF attachment') plus the unusual mechanic ('without sending file bytes through this tool'), which is the key thing an agent must understand. It does not name the sibling upload-attachment_application_json, so the split between the metadata/curl path and the base64 path is left to the schema's anyOf branches.

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?

Gives concrete when-not rules: don't send uploaded_by (OAuth identity is used), don't base64-encode the PDF, don't use generate-api-key for uploads, and run the returned curl_command verbatim. These are clear operating conditions, though it never explicitly routes to an alternative tool for the case where a direct byte upload is required.

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

All Common Paper 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.