Skip to main content
Glama

Morpha

by ai.morphareels
OverviewDiscussionsAdmin

Upload audio

upload_audio
Destructive

Upload an audio track into a project by fetching a public http(s) URL server-side — the ONLY way to get an audio file's bytes into a project over MCP/HTTP (add_audio_overlay / update_audio_overlay only reference a file that is already uploaded). The target is the URL you pass and nothing else: Morpha's Worker fetches it with a plain HTTP GET, following redirects, and identifies itself as "Morpha/1.0 (+https://morphareels.ai; hello@morphareels.ai)". No third-party API is involved. The worker downloads the .mp3/.m4a/.wav/.ogg/.aac, stores it in the project's asset bucket under a new id, and returns { filename, name, sizeBytes, contentType }. Then pass the returned filename (the file's id, never shown to a person) to add_audio_overlay (add a second track) or update_audio_overlay { id, filename } (replace an existing track's file — find the id via describe_video's audio_overlays), with name as the track's name. The url must be a direct, publicly-fetchable http(s) link (not an auth-walled page). Buffered in Worker memory, so capped at 50 MB. For a file on the caller's own disk, use create_upload_link instead. Reference: https://morphareels.ai/docs/tools#uploadaudiourl-name

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesDirect, publicly-fetchable http(s) URL of the audio file (.mp3/.m4a/.wav/.ogg/.aac).
nameNoOptional display name, what people see (e.g. Theme.mp3). Defaults to the URL's file name. It never decides where the file is stored.
projectIdYesProject to add the audio to.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYesWhether the call succeeded.
dataNoThe payload, shaped by the tool.
noteNoWhat to do next when not ready.
errorNoWhy it failed.
statusNoFor cache-backed readers: whether the answer was ready.
editorUrlNoOpens this project in the editor.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • removedInput schema / properties / filename
      Removed value: -{
-  "description": "Optional stored filename (.mp3/.m4a/.wav/.ogg/.aac). Defaults to the basename of the URL path; sanitised to lowercase a-z0-9._-.",
-  "type": "string"
-}
    • addedInput schema / properties / name
      Added value: +{
+  "description": "Optional display name, what people see (e.g. Theme.mp3). Defaults to the URL's file name. It never decides where the file is stored.",
+  "type": "string"
+}
  2. Changed2 schema fields changed
    • removedInput schema / properties / anonymousToken
      Removed value: -{
-  "description": "The token create_anonymous_account returned. This connection has no Morpha key, so every call carries it.",
-  "type": "string"
-}
    • changedInput schema / required
      Previous value: -[
-  "projectId",
-  "url",
-  "anonymousToken"
-]New value: +[
+  "projectId",
+  "url"
+]
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "description": "The result envelope every Morpha tool returns.",
+  "properties": {
+    "data": {
+      "description": "The payload, shaped by the tool.",
+      "type": [
+        "object",
+        "array",
+        "string",
+        "number",
+        "boolean",
+        "null"
+      ]
+    },
+    "editorUrl": {
+      "description": "Opens this project in the editor.",
+      "type": "string"
+    },
+    "error": {
+      "description": "Why it failed.",
+      "type": "string"
+    },
+    "note": {
+      "description": "What to do next when not ready.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "Whether the call succeeded.",
+      "type": "boolean"
+    },
+    "status": {
+      "description": "For cache-backed readers: whether the answer was ready.",
+      "enum": [
+        "ready",
+        "not-ready"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}
  4. Changed2 schema fields changed
    • addedInput schema / properties / anonymousToken
      Added value: +{
+  "description": "The token create_anonymous_account returned. This connection has no Morpha key, so every call carries it.",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "projectId",
-  "url"
-]New value: +[
+  "projectId",
+  "url",
+  "anonymousToken"
+]
  5. First observed

TDQS

A5/5.0
Behavior5/5

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

Despite annotations providing readOnlyHint=false and destructiveHint=true, the description goes far beyond them: it details the HTTP GET fetch, redirect following, User-Agent identification, absence of third-party APIs, buffering in Worker memory with a 50 MB cap, storage in the asset bucket under a new id, and the exact return object. This is rich behavioral context that the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place: it opens with the core purpose, then details the fetch mechanics, return value, and downstream usage, followed by constraints and alternatives. It is front-loaded with the primary action and avoids filler. The structure is logical and scannable despite its length.

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 tool with an output schema and rich annotations, the description is thoroughly complete: it explains the return format, how to use the returned filename with add/update overlay tools, the 50 MB limit, the requirement for public URLs, the user-agent, and even provides a documentation reference. 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.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description adds substantial meaning: url is constrained to direct, publicly-fetchable http(s) links with allowed formats; name is clarified as optional, defaults to the URL's file name, and 'never decides where the file is stored'; projectId is straightforward. The description enhances the schema by explaining the role of the returned filename and how it flows into overlay tools.

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 states a specific verb ('upload'), resource ('audio track into a project'), and method ('fetching a public http(s) URL server-side'). It explicitly distinguishes itself from sibling tools by noting it is the ONLY way to get audio bytes into a project over MCP/HTTP, and clarifies that add_audio_overlay/update_audio_overlay only reference already-uploaded files. This leaves no ambiguity about the tool's purpose.

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?

Provides explicit guidance: it is the only way to upload audio via URL, and contrasts with create_upload_link for local files. It also explains the workflow: after upload, pass the returned filename to add_audio_overlay or update_audio_overlay. The 'ONLY way' and 'For a file on the caller's own disk, use create_upload_link instead' give clear when-to-use and when-not-to-use conditions.

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

All Morpha 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