Clipia

generate_music

Generate background music / a soundtrack from a text description: instrumental (no vocals) by default — ideal to play under narration — or a song with your own words (pass lyrics). Returns request_id and cost in credits immediately; music takes ~1–3 min, so poll with wait_generation until COMPLETED, then output.audio.url is the mp3. Pass the resulting request_id as audio_request_id in compose_video to score a multi-scene video, or use the mp3 on its own. Describe mood/genre/tempo/instruments in the prompt (English works best).

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": {
      "prompt": "<prompt>"
    },
    "name": "generate_music"
  }
}

Input Schema

Name	Required	Description
`input`	No	Model-specific parameters from get_model input_schema.parameters, keyed by parameter name and merged with the fields above. Some parameters can change the cost of the call — get_model shows the reference pricing. A misspelled name, or a parameter this model is known not to apply, is rejected before the generation starts; the error lists the parameters the model declares.
`model`	No	Model slug from list_models (a text-to-music model). Omit to use the default music model.
`style`	No	Musical style kept separate from the description: genre, mood, instruments, tempo (default model: up to 1,000 characters). Only for models with a custom mode, such as the default one; a model without it rejects the call.
`lyrics`	No	Your own song text, sung as written (default model: up to 5,000 characters). Makes the track vocal — instrumental is set to false unless you pass it yourself. Omit to let the model write the words. Only for models with a custom-lyrics mode, such as the default one; a model without it rejects the call.
`prompt`	Yes	Description of the music: mood, genre, tempo, instruments, e.g. "warm lo-fi hip-hop, mellow Rhodes piano, soft vinyl crackle, 80 bpm". English works best. On the default model: up to 3,000 characters, and a description longer than 1,000 characters also needs style or lyrics. A request that breaks the limits is rejected with 400 before anything is charged.
`instrumental`	No	true (default) = instrumental, no vocals — best as a soundtrack under narration. false = allow vocals / a full song. Do not combine true with lyrics.
`wait_seconds`	No	How long to wait inline for completion before returning a request_id (music usually needs polling with wait_generation).
`idempotency_key`	No	Optional stable key (up to 255 characters) to safely retry without creating a duplicate generation. Reuse the same key only when retrying the same request: the same key with a different model or input is rejected with idempotency_key_reuse.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 5, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Optional stable key to safely retry without creating a duplicate generation. Reuse the same key when retrying the same request."New value: +"Optional stable key (up to 255 characters) to safely retry without creating a duplicate generation. Reuse the same key only when retrying the same request: the same key with a different model or input is rejected with idempotency_key_reuse."

addedInput schema / properties / idempotency_key / maxLength
```
Added value: +255
```

First observedNov 2, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the synchronous-return shape (request_id and cost in credits returned immediately), realistic latency (~1–3 min), and that limit violations are rejected with 400 before anything is charged. It also explains the idempotency_key retry contract, which is consistent with idempotentHint=false since deduplication is opt-in via the key rather than inherent.

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 selection, then workflow, then prompt tips — a sensible ordering. It is a dense, clause-heavy run-on, but each clause (latency, polling, cost, compose_video hand-off) carries information an agent needs.

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 an 8-parameter generation tool with a nested input object and no output schema, the description covers the async lifecycle, cost, return location (output.audio.url), and cross-tool usage. Nothing an agent needs to call it correctly and retrieve the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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

Schema coverage is 100%, so the parameters are already fully documented. The description reinforces prompt content guidance (mood/genre/tempo/instruments, English works best) and the lyrics→vocal interaction, but largely restates what the schema already says rather than adding new syntax or constraints.

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 ("Generate background music / a soundtrack from a text description") and immediately disambiguates two modes (instrumental vs. song with lyrics). This clearly separates it from siblings like generate_audio and compose_video, which it names in a downstream role.

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?

States the default-to-instrumental rationale ("ideal to play under narration") and the condition for the other mode ("pass lyrics"). It also prescribes the follow-up workflow explicitly: poll with wait_generation until COMPLETED, then read output.audio.url, or feed the request_id into compose_video as audio_request_id.

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

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