Skip to main content
Glama

Upload a song

create_song

Add a song: master audio, and square cover art if it has one Audio: MP3, WAV or M4A up to 250 MB. Cover (optional): a square JPEG or PNG, 1000–6000 px (3000×3000 recommended), up to 20 MB; it is kept at 1536, 640 and 160 px, not as uploaded. Without one the song has no cover (cover_art null) and every video still works; set_song_cover adds one later. The song is analyzed next (lyrics, beats, sections): poll get_song until analysis.status is "ready", usually about a minute. Pass lyrics (or set them later with set_song_lyrics) to have the videos spell every word right. The file’s tags fill what is left out: its title, ISRC, embedded lyrics and embedded cover (a square one, 1000 px or more). The same song already in the workspace (the same audio file, or the same ISRC) is refused with 409, code duplicate, and its song_id. A released song of a linked artist can be imported instead of uploaded (import_songs). Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_song"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNoThe song title; left out, the file’s title tag, then its file name
lyricsNoOptional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos, and its section tags set the song’s sections (a chorus sung once is still a chorus). A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status "mismatch")
languageNoLyrics language (ISO 639-1, e.g. "en"); detected when omitted
artist_idNoThe artist id. An artist workspace may leave it out: its songs are its artist's
audio_urlNoA public https URL of the master audio (a file on your computer: create_upload, then its file_url)
instrumentalNoDeprecated: the analysis hears whether a song has vocals (get_song: instrumental). true still skips transcription: lyric videos have no words and music videos never lip-sync (no lyrics with it). Stops working on 2027-04-30.
cover_art_urlNoOptional: a public https URL of the square cover art (a file on your computer: create_upload's file_url, or upload it with the CLI). Leave it out for a song without cover art

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / title / description
      Previous value: -"The song title"New value: +"The song title; left out, the file’s title tag, then its file name"
    • removedInput schema / required
      Removed value: -[
      -  "title"
      -]
  2. Changed2 schema fields changed
    • changedInput schema / properties / audio_url / description
      Previous value: -"A public https URL of the master audio"New value: +"A public https URL of the master audio (a file on your computer: create_upload, then its file_url)"
    • changedInput schema / properties / cover_art_url / description
      Previous value: -"A public https URL of the square cover art"New value: +"Optional: a public https URL of the square cover art (a file on your computer: create_upload's file_url, or upload it with the CLI). Leave it out for a song without cover art"
  3. Changed1 schema field changed
    • changedInput schema / properties / lyrics / description
      Previous value: -"Optional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos. A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status \"mismatch\")"New value: +"Optional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos, and its section tags set the song’s sections (a chorus sung once is still a chorus). A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status \"mismatch\")"
  4. Changed1 schema field changed
    • addedInput schema / properties / instrumental
      Added value: +{
      +  "deprecated": true,
      +  "description": "Deprecated: the analysis hears whether a song has vocals (get_song: instrumental). true still skips transcription: lyric videos have no words and music videos never lip-sync (no lyrics with it). Stops working on 2027-04-30.",
      +  "type": "boolean",
      +  "x-sunset": "2027-04-30"
      +}
  5. Changed2 schema fields changed
    • changedInput schema / properties / artist_id / description
      Previous value: -"The artist id"New value: +"The artist id. An artist workspace may leave it out: its songs are its artist's"
    • changedInput schema / required
      Previous value: -[
      -  "artist_id",
      -  "title"
      -]New value: +[
      +  "title"
      +]
  6. Changed1 schema field changed
    • addedInput schema / properties / lyrics
      Added value: +{
      +  "description": "Optional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos. A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status \"mismatch\")",
      +  "maxLength": 100000,
      +  "type": "string"
      +}
  7. First observed

TDQS

A4.6/5.0
Behavior4/5

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

The annotations only declare write/open-world/non-idempotent semantics, but the description adds real behavioral detail: duplicate detection returns 409 code duplicate with the existing song_id, 402 plan_required and storage_full gates, async analysis with a ~1 minute wait on get_song, cover art downscaled to 1536/640/160 rather than stored as uploaded, and post-analysis lyric mismatch refusal. It could say more about whether a failed upload leaves a partial song, but it is far richer than the annotations require.

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?

Content is front-loaded and nearly every sentence carries unique facts (duplicate 409, analysis polling, cover resizing, tag fallback), with zero filler. The cost is density: one long paragraph mixing file constraints, error codes, and follow-up tools, which slows scanning compared with a short list.

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 7-parameter async write with no output schema and no required params, the description covers the full lifecycle: input formats, cover art handling, downstream analysis polling, duplicate and payment failure modes, and the import alternative. Nothing an agent needs to call it correctly or interpret failure 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?

With 100% schema coverage the baseline is 3, and the description adds meaning the schema does not: the file's tags fill in title, ISRC, embedded lyrics and embedded cover, and the same audio file or same ISRC is treated as a duplicate. Most other per-parameter detail (format, size, deprecation of instrumental) is already in the schema, so the lift over the schema is real but partial.

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 and resource: "Add a song: master audio, and square cover art if it has one." It immediately separates itself from siblings by naming import_songs, set_song_cover, set_song_lyrics and get_song, so an agent can pick it out of the catalog without opening any 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?

It states explicit when-to-use and when-to-do-it-differently conditions: omit cover art and call set_song_cover later, pass lyrics now or call set_song_lyrics later, import_songs instead of uploading for a released track from a linked artist, and check get_account plan/storage before calling. The only thing left implicit is the exact precedence between uploading and importing when both are possible.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources