Clipform

Upload Media Asset

clipform_upload_media_asset

Put one or more media files into your workspace media library (max 10, uploaded sequentially). This is step one of attaching media to a node - follow up with clipform_attach_node_media to place the returned media_asset_id on a node.

When a public URL is provided, the media is fetched and stored automatically. The API picks where each asset is stored based on its size and type. Word-level captions from clipform_generate_tts enable per-word highlighting in the viewer once attached - pass the caption_ref it returned instead of hand-copying the captions array.

PDFs (media_type document) are for consent agreements: they return a document descriptor, not a media_asset_id.

Provide media via items (explicit type + URL), files (files attached by the host client), or both. At least one is required.

Input Schema

TableJSON Schema

Name	Required	Description
`files`	No	Files attached by the host client. Each becomes a video or still library asset (or a consent-agreement document for application/pdf) based on its declared mime_type.
`items`	No	One or more media items to create as workspace library assets
`context`	Yes	Describe the user's underlying goal in one sentence - not the tool you're calling.
`form_id`	No	The form this is for (from clipform_create_form) - a routing hint only, to pick the right workspace. The result still lands in the workspace library, not on a node. Required on an anonymous session, or this lands in a different workspace and clipform_attach_node_media will not find it.
`workspace_id`	No	Workspace to act in (id from clipform_whoami workspaces). Omit to use the connection's default workspace.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	Yes	One result per item, in order
`workspace_name`	No	Name of the workspace the media library entries were created in

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 6, 2026

changedInput schema / properties / files / items / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "download_url": {
-        "description": "Short-lived URL the server downloads the file's bytes from",
-        "type": "string"
-      },
-      "file_id": {
-        "description": "Host-assigned identifier for the attached file",
-        "type": "string"
-      },
-      "file_name": {
-        "type": "string"
-      },
-      "mime_type": {
-        "description": "Declared MIME type - determines whether the file becomes a video or still asset",
-        "type": "string"
-      },
-      "name": {
-        "type": "string"
-      },
-      "size": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "download_url"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": {},
+    "properties": {
+      "download_url": {
+        "description": "Short-lived URL the server downloads the file's bytes from",
+        "type": "string"
+      },
+      "file_id": {
+        "description": "Host-assigned identifier for the attached file",
+        "type": "string"
+      },
+      "file_name": {
+        "type": "string"
+      },
+      "mime_type": {
+        "description": "Declared MIME type - determines whether the file becomes a video or still asset",
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "size": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "download_url"
+    ],
+    "type": "object"
+  }
+]

addedInput schema / properties / form_id / pattern

Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

removedInput schema / properties / items / items / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / captions / items / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / captions / items / properties / words / items / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / workspace_id / pattern

Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

Changed1 schema field changedOct 4, 2026

addedInput schema / properties / form_id

Added value: +{
+  "description": "The form this is for (from clipform_create_form) - a routing hint only, to pick the right workspace. The result still lands in the workspace library, not on a node. Required on an anonymous session, or this lands in a different workspace and clipform_attach_node_media will not find it.",
+  "format": "uuid",
+  "type": "string"
+}

Changed2 schema fields changedOct 3, 2026

addedInput schema / properties / workspace_id

Added value: +{
+  "description": "Workspace to act in (id from clipform_whoami workspaces). Omit to use the connection's default workspace.",
+  "format": "uuid",
+  "type": "string"
+}

addedOutput schema / properties / workspace_name

Added value: +{
+  "description": "Name of the workspace the media library entries were created in",
+  "type": "string"
+}

Changed6 schema fields changedOct 2, 2026

changedInput schema / properties / files / description

Previous value: -"Files attached by the host client. Each becomes a video or still library asset based on its declared mime_type."New value: +"Files attached by the host client. Each becomes a video or still library asset (or a consent-agreement document for application/pdf) based on its declared mime_type."

addedInput schema / properties / items / items / properties / filename

Added value: +{
+  "description": "Display filename for a document (media_type document). Defaults to the URL's file name.",
+  "maxLength": 200,
+  "type": "string"
+}

changedInput schema / properties / items / items / properties / media_type / description

Previous value: -"Type of media"New value: +"Type of media. Use document for a consent-agreement PDF (url required, PDF only)."

changedInput schema / properties / items / items / properties / media_type / enum

Previous value: -[
-  "video",
-  "still"
-]New value: +[
+  "video",
+  "still",
+  "document"
+]

addedOutput schema / properties / results / items / properties / document

Added value: +{
+  "additionalProperties": false,
+  "description": "Consent-agreement descriptor (documents only) - set as consent_items[i].document via clipform_update_node",
+  "properties": {
+    "filename": {
+      "type": "string"
+    },
+    "storage_path": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "storage_path",
+    "filename",
+    "url",
+    "version"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / results / items / properties / media_asset_id / description
```
Added value: +"Absent for documents"
```

Changed3 schema fields changedSep 29, 2026

addedInput schema / properties / files

Added value: +{
+  "description": "Files attached by the host client. Each becomes a video or still library asset based on its declared mime_type.",
+  "items": {
+    "anyOf": [
+      {
+        "type": "string"
+      },
+      {
+        "additionalProperties": true,
+        "properties": {
+          "download_url": {
+            "description": "Short-lived URL the server downloads the file's bytes from",
+            "type": "string"
+          },
+          "file_id": {
+            "description": "Host-assigned identifier for the attached file",
+            "type": "string"
+          },
+          "file_name": {
+            "type": "string"
+          },
+          "mime_type": {
+            "description": "Declared MIME type - determines whether the file becomes a video or still asset",
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "size": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "download_url"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "maxItems": 10,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / items / items / properties / url / description

Previous value: -"Public URL of the media file. When provided, the server fetches and stores it directly."New value: +"Public URL that links directly to the media file itself. When provided, the server fetches and stores it directly."

changedInput schema / required

Previous value: -[
-  "items",
-  "context"
-]New value: +[
+  "context"
+]

Changed1 schema field changedSep 7, 2026

addedInput schema / properties / items / items / properties / caption_ref

Added value: +{
+  "description": "caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to this asset, resolved server-side. Preferred over captions.",
+  "type": "string"
+}

Changed4 schema fields changedSep 5, 2026

changedInput schema / properties / items / items / properties / captions / description

Previous value: -"Word-level captions from clipform_generate_tts. Required for per-word highlighting - pass the full objects including 'words' arrays."New value: +"Word-level captions from clipform_generate_tts. `words` is a required field on each caption (schema-enforced) - pass the full objects returned by clipform_generate_tts unmodified."

changedInput schema / properties / items / items / properties / captions / items / properties / words / description

Previous value: -"Per-word timestamps within the segment"New value: +"Per-word timestamps within the segment. Required - copy the full array from clipform_generate_tts verbatim."

addedInput schema / properties / items / items / properties / captions / items / properties / words / minItems
```
Added value: +1
```

changedInput schema / properties / items / items / properties / captions / items / required

Previous value: -[
-  "start",
-  "end",
-  "text"
-]New value: +[
+  "start",
+  "end",
+  "text",
+  "words"
+]

Changed3 schema fields changedAug 31, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / context

Added value: +{
+  "description": "Describe the user's underlying goal in one sentence - not the tool you're calling.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "items"
-]New value: +[
+  "items",
+  "context"
+]

Changed1 schema field changedJul 17, 2026

addedInput schema / properties / items / items / properties / ai_generated

Added value: +{
+  "description": "Whether this media was AI-generated. Drives the viewer's disclosure chip - set true for AI-rendered/synthesized media.",
+  "type": "boolean"
+}

AddedJul 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the annotations, it discloses sequencing (sequential uploads), automatic storage-location selection by size/type, URL auto-fetch behavior, and a notable return-shape exception (PDFs return a document descriptor instead of a media_asset_id). This is substantial operational context the structured fields do not carry.

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 action and is organized into short, scannable paragraphs, each carrying distinct information. It runs somewhat long and re-states the caption guidance in both the body and schema, but there is little pure filler.

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?

For a 5-parameter, non-idempotent upload tool with an output schema present, the description covers everything an agent needs: entry point in the chain, the follow-up tool, input-source options, and the exception return path. Return-value details are appropriately delegated to the output schema.

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 coverage is 100%, so the baseline is 3, but the description adds real cross-parameter guidance: media may come from items, files, or both (at least one required is not obvious since both are optional in the schema), and caption_ref should be preferred over manually copying the captions array.

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 specific verb and resource ('Put one or more media files into your workspace media library') with scope limits (max 10, uploaded sequentially). It explicitly distinguishes itself from the sibling clipform_attach_node_media by naming it as the required follow-up step.

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?

Gives explicit workflow placement ('step one of attaching media to a node'), names the alternative follow-up tool, explains the mutually-alternative input paths (items vs files vs both), and spells out the PDF/consent-agreement case and the caption_ref-vs-captions preference.

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

All Clipform 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.