Skip to main content
Glama
Sign In

Common Paper

by com.commonpaper
OverviewDiscussionsAdmin

upload-attachment_application_json

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

NameRequiredDescriptionDefault
bodyYes

Output Schema

NameRequiredDescriptionDefault
curl_commandYesReady-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.

  1. Changed1 schema field changed
    • 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"
+  }
+]
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Adds substantial behavior beyond the annotations: the call returns a curl_command with a shell-escaped path that must be run verbatim, and the uploader is taken from the OAuth identity so uploaded_by must be omitted. Annotations only give the generic mutation profile (readOnly=false, destructive=false, idempotent=false); the description covers the two-step flow and auth. It does not say what happens on re-upload or whether the returned command can fail independently, which keeps it short of a 5.

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-loaded with the key constraint, then requirements, then pitfalls. Dense and mostly waste-free, though the trailing run of 'do not' instructions (base64, generate-api-key, uploaded_by) partially repeats what earlier sentences already implied.

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 an output schema present, the description doesn't need to enumerate return fields — yet it still flags the one non-obvious return element, curl_command. For a tool with a three-branch anyOf body and a mandatory post-step, coverage is strong; a sentence on which schema branch an MCP client should target would make it complete.

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?

Top-level schema coverage is 0% (the single `body` param is undocumented), so the description must carry the field semantics, and it does: filename is a required local PDF path with no control characters, name is optional and only for overriding the basename, description is optional, uploaded_by is forbidden. It stops short of explaining how the anyOf body variants map to the three schema branches.

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?

Opens with a specific verb + resource and a scope-defining mechanism: 'Upload a PDF attachment without sending file bytes through this tool.' The last sentence distinguishes it from the base64 path and names the sibling generate-api-key as the wrong tool, so an agent can route correctly without opening any schema.

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?

Clear usage context: send metadata only, don't base64-encode, don't use generate-api-key. It implicitly excludes the multipart/base64 variants of the upload but never names upload-attachment_multipart_form_data as the alternative, so the when-to-use-vs-sibling choice is inferred rather than stated.

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

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