Clueso

Add audio track

add_audio

Add a music track or sound effect that plays as a project-level audio layer over all clips. Does NOT consume a clip slot. Use this for background music or a soundtrack that should play under the existing timeline. Sound for an HTML animation goes here, not in its page: guide_start_time = the element's start + the cue's t. (For inserting an audio file as its own sequential clip with auto-transcription, use add_clips(kind='video') with an audio mime_type instead.)

type="music": requires src. src is the src from a find(type='music') result (pass with its name and duration as source_duration), or an upload: an mcp_upload_id (mup_) from upload_file or a Clueso upload_id, whose name and duration are filled in for you. For a Freesound result the src is an opaque handle; pass it through unchanged and Clueso downloads + hosts the original server-side (do not try to fetch it yourself). Anything not from find has its duration probed. Optional: guide_start_time, guide_end_time, music_start_time, music_end_time (trim the source track), volume, loop, fade_in, fade_out. A user's own upload is also saved to the project's media panel (saved_to_media_panel).
type="sfx": pass the src, name, and source_duration from a find(type='sfx') result (or an upload as src), plus guide_start_time (Freesound src is an opaque handle, resolved server-side just like music). Optional: volume. (Legacy: a fixed-library sfx_key like 'whoosh' still works instead of src.)

Concurrency: whole-project mutation (conflict domain: the entire project) — serialize; do not run in parallel with ANY other mutation on the same project_id (including element/voiceover edits). Size your clips BEFORE calling add_audio, or pass guide_end_time explicitly — the default ('end of project') is captured at call time and will NOT auto-extend if clips are added or resized afterwards.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "type": "<type>"
    },
    "name": "add_audio"
  }
}

Input Schema

Name	Required	Description
`src`	No	Audio source. For type='music' (required) or a stock type='sfx': the `src` from a find(type='music'\|'sfx') result (may be an opaque Freesound handle — pass as-is), or an upload id (mcp_upload_id 'mup_…' or a Clueso upload_id). Not needed for legacy fixed-library sfx (use sfx_key).
`loop`	No	Loop the track if project is longer than the source. Music only. (default: false)
`name`	No	Track/effect name. From the find result; for an upload it defaults to the file name.
`type`	Yes	Audio type: 'music' or 'sfx'
`volume`	No	Volume as percent (0–100). Default: 20 for music (under narration), 80 for sfx.
`fade_in`	No	Fade-in duration in seconds. Music only. (default: 0.5)
`sfx_key`	No	LEGACY fixed-library SFX key (e.g. 'whoosh', 'pop', 'click'). Optional alternative to src for type='sfx'. Prefer the src/name/source_duration from a find(type='sfx') result.
`fade_out`	No	Fade-out duration in seconds. Music only. (default: 0.5)
`project_id`	Yes	The project ID
`guide_end_time`	No	When to stop playing (seconds). Music only. Default = end of project AT CALL TIME — captured once at insert and NOT recomputed when clips are later added or resized. Pass an explicit value (e.g. the intended final project duration) when adding audio before clips are sized.
`music_end_time`	No	Out-point within the SOURCE track (seconds) — trims where playback ends in the music file. Music only. Default = source_duration.
`source_duration`	No	Source duration in seconds, from the find result. Uploads and other URLs are probed.
`guide_start_time`	No	When to start playing in the guide timeline (seconds). Required for type='sfx', optional for music (default 0).
`music_start_time`	No	In-point within the SOURCE track (seconds) — trims where playback begins in the music file. Music only. Default 0 (start of source).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 22, 2026

changedInput schema / properties / name / description

Previous value: -"Track/effect name. From the find result, or any descriptive label when using mcp_upload_id. Required for type='music' and for stock type='sfx' (passed via src)."New value: +"Track/effect name. From the find result; for an upload it defaults to the file name."

changedInput schema / properties / source_duration / description

Previous value: -"Source duration in seconds. From the find result, or analyze_audio mode='features' (data.duration_ms / 1000). Required for type='music' and for stock type='sfx' (passed via src)."New value: +"Source duration in seconds, from the find result. Uploads and other URLs are probed."

changedInput schema / properties / src / description

Previous value: -"Audio source. For type='music' (required) or a stock type='sfx': the `src` from a find(type='music'|'sfx') result (may be an opaque Freesound handle — pass as-is), or an mcp_upload_id (prefixed 'mup_') from upload_file. Not needed for legacy fixed-library sfx (use sfx_key)."New value: +"Audio source. For type='music' (required) or a stock type='sfx': the `src` from a find(type='music'|'sfx') result (may be an opaque Freesound handle — pass as-is), or an upload id (mcp_upload_id 'mup_…' or a Clueso upload_id). Not needed for legacy fixed-library sfx (use sfx_key)."

changedInput schema / properties / volume / description

Previous value: -"Volume as percent (0–100). Default: 50 for music, 80 for sfx."New value: +"Volume as percent (0–100). Default: 20 for music (under narration), 80 for sfx."

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"
-}

changedInput schema / required

Previous value: -[
-  "project_id",
-  "type",
-  "context",
-  "llm_model"
-]New value: +[
+  "project_id",
+  "type"
+]

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"
+}

changedInput schema / required

Previous value: -[
-  "project_id",
-  "type"
-]New value: +[
+  "project_id",
+  "type",
+  "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?

Annotations only declare it is a non-read-only, non-destructive, closed-world mutation; the description adds far more: the project-wide conflict domain requiring serialization, that uploads get persisted to the project media panel, that non-find sources have duration probed, and that Freesound handles are opaque and resolved server-side. Most importantly it discloses that the default guide_end_time is captured at call time and will NOT auto-extend, which is exactly the kind of silent behavior that trips agents up.

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, exclusions, and the sibling alternative before any parameter detail, then cleanly split into per-type bullets and a separate concurrency warning. It runs long for a tool with full schema coverage and repeats the Freesound opaque-handle point in both bullets, plus re-lists optional parameters the schema already documents.

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 14-parameter mutation tool with no output schema, the description covers everything an agent needs to call it safely: source provenance rules, per-type required fields, trimming versus placement time semantics, defaults that behave surprisingly, and the serialization requirement. Nothing material about correctness of the call is left to inference.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning on top: it spells out per-type requirements (music requires src; sfx takes src/name/source_duration or a legacy sfx_key), clarifies that music_start/end_time trim within the SOURCE while guide_start/end_time position in the timeline, and supplies a derivation rule not present in the schema (guide_start_time = element start + the cue's t). Minor overlap with the schema's own wording keeps it short of a 5.

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 opens with a specific verb and resource ("Add a music track or sound effect that plays as a project-level audio layer over all clips") and immediately names the boundary conditions that distinguish it from siblings: it does not consume a clip slot, background music goes here, and per-element sound belongs to the element, not its page. It also explicitly routes the alternate case to add_clips(kind='video'), so an agent can separate add_audio from add_clips without opening either 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 framing (background music/soundtrack under an existing timeline), an explicit when-not (an HTML animation's sound does not go in its page), and a named alternative with the condition that selects it (add_clips with an audio mime_type for a sequential clip with auto-transcription). Concurrency guidance adds a second usage constraint — serialize, never run in parallel with any other mutation on the same project.

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.