Clueso

Upload file

upload_file

Upload one or more files to Clueso. Pick a mode by client + where the file lives:

files — ChatGPT only: files the user attached in the conversation. ChatGPT fills each entry (download_url + file_id) itself; pass the attachments here rather than asking the user to re-upload. Returns one mcp_upload_id per file.
file_name — HOSTED upload, the default for any non-UI / programmatic upload (Claude Code, Cursor, Claude Desktop, scripts). Returns an upload URL on Clueso's OWN base domain + a ready-to-run curl that streams a single local file to it; Clueso relays the bytes to storage server-side. The PUT targets the base domain — NOT cloud storage directly — so it works on desktop/agent clients that can't reach or are blocked from S3. Requirement: the client must be able to PUT bytes to the Clueso base domain (run the returned curl, or any HTTP PUT). The agent (or the user at a shell prompt) runs the curl. Prefer this whenever there's no human at a browser. file_names (without request_hosted_upload) is the same for many files in ONE call: a token and URL per name plus ONE curl that sends them all. Run it from the folder the names are relative to (for edit_animation upload_ids, the folder holding manifest.json, names like 'entries/city.js').
file_url: Pass a public https URL. Server fetches and stages the file. Returns mcp_upload_id immediately. Use when the file is already on the open web — no user interaction needed.
request_hosted_upload (UI mode — use ONLY when a human should pick files in a browser: many files at once, or a host with no shell / no PUT capability): Returns a single upload_token + upload_page URL. Share the link with the user; they open it in a new browser tab, drop their files, click Done. Then call check_uploads(upload_token) to retrieve all mcp_upload_ids. Call once for all files.

Hosted uploads cover any number of files per call: one call issues one upload_token, and that token covers every file the user drops on the page. Repeat calls issue additional tokens, each tracking only its own files.

The returned mcp_upload_id (prefixed mup_) can be passed to:

add_elements / update_elements (image or video → an element ON a clip: pass it as type_data.mcp_upload_id, on either tool — this is how a local image becomes on-canvas content, and how an existing element's source is swapped). To fill an animation's image slot, pass it inside type_data.parameter_values on update_elements only — parameter_values is an update-path field and is stripped on add.
add_audio (audio → project music track that plays under all clips)
add_clips(kind='video') (video or audio → sequential clip with auto-transcription)
add_clips(kind='pptx') (.ppt/.pptx → slide clips)
add_article_media (image/GIF → article asset)
analyze_audio (audio → transcript / silences / beats / features / energy / sections)
edit_animation (a .js or .json file → files: [{path, upload_id}], or upload_ids when each upload is named by its path, so a big animation file never goes inline)

purpose: 'font' (with file_name, file_names, file_url or files; display_name optional) adds the file to this workspace's brand fonts once it arrives: the curl's reply (this reply for file_url and files, check_uploads for the hosted page) carries font: {name, family, format, converted_from} or font_error. TTF, OTF, WOFF or WOFF2; WOFF and WOFF2 are stored as TTF so the renderer and text measurer read them. The name is display_name, else the file's family without build dates or versions ("Cursor Mono 260406" → "Cursor Mono"); use it exactly in font_setting.font and animation manifests. One face per name; a name already in the workspace is refused. Needs an editor or admin, on a plan with custom fonts.

Input Schema

TableJSON Schema

Name	Required	Description
`files`	No	ChatGPT file attachments, one entry per file (filled by ChatGPT).
`purpose`	No	'font': add the file to this workspace's brand fonts once it arrives (see above). With request_hosted_upload, every file dropped on the page is one, reported by check_uploads.
`file_url`	No	Public URL to fetch the file from
`file_name`	No	File name with extension. Returns a Clueso upload URL + curl command that streams this single local file to us (single file).
`file_names`	No	Hosted mode: the file names the user will upload, shown on the page. Without request_hosted_upload: upload these local files in one call (one token + URL each, and one curl for all), max 50.
`display_name`	No	With purpose 'font' and one file (file_name, file_url, one files entry, or one file_names entry): the name to list the font under. Default: its family name without build dates or versions.
`request_hosted_upload`	No	If true, returns a hosted upload page. Call once for all files — the page accepts multiple uploads under one token.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 12, 2026

addedInput schema / properties / display_name

Added value: +{
+  "description": "With purpose 'font' and one file (file_name, file_url, one files entry, or one file_names entry): the name to list the font under. Default: its family name without build dates or versions.",
+  "maxLength": 100,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / file_names / description

Previous value: -"List of file names the user will upload (for hosted mode). Shown on the upload page as guidance."New value: +"Hosted mode: the file names the user will upload, shown on the page. Without request_hosted_upload: upload these local files in one call (one token + URL each, and one curl for all), max 50."

addedInput schema / properties / purpose

Added value: +{
+  "description": "'font': add the file to this workspace's brand fonts once it arrives (see above). With request_hosted_upload, every file dropped on the page is one, reported by check_uploads.",
+  "enum": [
+    "font"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 25, 2026

addedInput schema / properties / files

Added value: +{
+  "description": "ChatGPT file attachments, one entry per file (filled by ChatGPT).",
+  "items": {
+    "properties": {
+      "download_url": {
+        "description": "Temporary download URL supplied by ChatGPT",
+        "type": "string"
+      },
+      "file_id": {
+        "description": "ChatGPT file id",
+        "type": "string"
+      },
+      "file_name": {
+        "type": "string"
+      },
+      "mime_type": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "download_url",
+      "file_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed4 schema fields changedSep 22, 2026

removedInput schema / properties / context

Removed value: -{
-  "description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"",
-  "type": "string"
-}

removedInput schema / properties / conversation_id

Removed value: -{
-  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
-  "type": "string"
-}

removedInput schema / properties / llm_model

Removed value: -{
-  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
-  "type": "string"
-}

removedInput schema / required

Removed value: -[
-  "context",
-  "llm_model"
-]

Changed4 schema fields changedSep 22, 2026

addedInput schema / properties / context

Added value: +{
+  "description": "Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as \"a user\", \"the customer\", or \"an account\". Example: \"Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution.\"",
+  "type": "string"
+}

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.",
+  "type": "string"
+}

addedInput schema / properties / llm_model

Added value: +{
+  "description": "The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. \"claude-opus-4-8\", \"gpt-5.2\"). Used for analytics only. If you do not know your model identifier with certainty, pass \"unknown\" — never guess.",
+  "type": "string"
+}

addedInput schema / required

Added value: +[
+  "context",
+  "llm_model"
+]

Changed2 schema fields changedSep 17, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

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

First observedAug 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With annotations only declaring non-readOnly/openWorld/non-destructive, the description carries real behavioral content: it explains the returned artifacts (mcp_upload_id `mup_` prefix, upload URL + ready-to-run curl, upload_token), the server-side relay of bytes, font conversion (WOFF/WOFF2 stored as TTF), name-collision refusal ('a name already in the workspace is refused'), and the 'editor or admin on a plan with custom fonts' permission gate.

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 purpose and mode list in a scannable numbered structure, but it is very long and a few passages repeat themselves — the hosted-upload token semantics appear in mode 3 and again in the closing paragraph, and the mcp_upload_id consumer list is a long tangential block. Most sentences earn their place, but trimming is possible.

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?

No output schema exists, and the description compensates fully by describing every return shape (upload id, URL+curl, token+page URL, font/font_error) and the follow-up retrieval path. Given the four modes, cross-tool handoffs and permission requirements, nothing an agent needs to call it correctly is missing.

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 meaning the schema cannot: how purpose='font' interacts with display_name and each mode, the naming default ('Cursor Mono 260406' → 'Cursor Mono'), and the fact that file_names without request_hosted_upload means local multi-file upload while with it means the names shown on the page. The descriptions of the combination semantics are a genuine addition.

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 ('Upload one or more files to Clueso') and then enumerates the four mutually exclusive input modes (files / file_name·file_names / file_url / request_hosted_upload) plus the font purpose. It also names the downstream consumer tools (add_elements, add_clips, edit_animation, etc.), so an agent can distinguish upload_file from its siblings without opening a schema.

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 when-to-use rules per mode: file_name is 'the default for any non-UI / programmatic upload', file_url is for 'when the file is already on the open web', request_hosted_upload is 'ONLY when a human should pick files in a browser'. It states prerequisites (client must be able to PUT to the Clueso base domain) and the follow-up call (check_uploads(upload_token)) for the hosted path.

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

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

Upload file

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources