Song in, video plan out: beat grid, best moments, timed lyrics, story and a beat-synced shot plan.
Scored across 7 tools
analyze_song (start) vs get_song (poll/retrieve) is a clear distinction, and get_example_analysis vs get_example_shot_plan are reasonably separated by granularity. get_pricing and get_account both touch credits/pricing, creating minor overlap, but descriptions clarify general vs key-specific.
Consistent verb_noun snake_case throughout (analyze_song, get_song, get_account, get_pricing, list_example_songs, get_example_*). The example-prefixed tools follow a predictable nested pattern.
Seven tools is well-scoped for a song-analysis API with poll-based workflow and example/pricing helpers. Each tool maps to a distinct need and none feels redundant.
Covers the core lifecycle: start analysis, poll for result, plus account, pricing, and example data for onboarding. Minor gaps like listing a user's prior analyses or canceling an in-flight job, but core workflows are covered.
Start the analysis of a song at a public audio URL (MP3, WAV, FLAC, M4A, AAC, OGG or AIFF; 30 s to 10 min). Needs an API key on the MCP connection. Returns a song_id; poll get_song until status is 'done' (typically 60–90 seconds, up to ~2 minutes when busy). Uses one free song or 25 credits.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| artist | No | ||
| audio_url | Yes | Public http(s) URL of the audio file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the auth requirement (API key on the MCP connection), the asynchronous return contract (song_id), realistic completion timing including a busy-case bound, and the cost model (one free song or 25 credits). That is exactly the mutation/latency/billing context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense clauses, zero filler: input constraints, auth, return/polling contract, cost. The essential action and its constraints are front-loaded before the follow-up polling instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description supplies the return value (song_id) and the follow-up loop needed to get results, plus auth and billing preconditions. Nothing an agent needs to invoke and correctly follow up is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%: audio_url is described in the schema, but title and artist are undocumented there. The description compensates partially by constraining the URL (public http(s), formats, 30 s–10 min) but says nothing about the semantics of title/artist, so the gap is only half closed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('start the analysis of a song') plus the accepted input scope (public audio URL, formats, duration). It also names the sibling it hands off to (get_song), so an agent can distinguish this from the retrieval tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear workflow guidance: call this to kick off analysis, then poll get_song until status is 'done', with expected latency given. It does not state when-not to use it (e.g., re-analyzing an already-complete song_id), so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free songs left this month, credit balance and price per song for the connected key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results are scoped to the 'connected key', implying authentication, but says nothing about rate limits, freshness, or failure modes. With annotations carrying the safety burden, this is an adequate but not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact fragment that front-loads the three returned quantities. It is efficient, though it reads as a noun phrase rather than a sentence stating the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does list the key fields returned. For a zero-parameter read it is essentially complete, missing only scope nuances like whether quota resets monthly per key.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; schema coverage is 100% and there is nothing for the description to compensate for. The description adds no parameter detail because none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource and its returned fields (free songs remaining, credit balance, per-song price), so the agent knows this is an account-status read. It does not differentiate from the sibling get_pricing, which could plausibly overlap on 'price per song'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no mention of alternatives such as get_pricing. The agent must infer that this is the tool for checking remaining quota or balance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full analysis of an example song: Song DNA, beat grid and sections, best moments, lyrics, scores, story and shot plan. No API key needed. Summary view by default (no per-word timings or beat arrays); set view='full' for everything.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | summary | |
| sections | No | Only these sections (default: all) | |
| example_id | Yes | id from list_example_songs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds genuinely new behavioral detail: the auth requirement ('No API key needed') and exactly what the default summary view omits (per-word timings, beat arrays). That is useful return-shape disclosure beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences: purpose, auth note, then the view default and escalation. The section enumeration slightly overlaps the schema enum, but it earns its place by telling the agent what 'analysis' actually contains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description bears the return-value burden and does a reasonable job by listing sections and noting what summary omits. It stops short of describing result size, pagination, or error behavior, but nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with example_id pointing to list_example_songs and sections carrying an inline description. The description adds real meaning for the view enum by contrasting summary versus full content, though it says nothing about the sections filter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb and resource ('Full analysis of an example song') and enumerates the exact payload (Song DNA, beat grid, sections, best moments, lyrics, scores, story, shot plan). The 'example' qualifier implicitly separates it from the sibling analyze_song, though no sibling is named outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operational context: no API key is required, summary is the default, and view='full' is the escalation path. It does not, however, state when to prefer this over analyze_song or get_example_shot_plan, so exclusions/alternatives are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The beat-synced shot plan of an example song: every scene with start and end seconds, its act (setup, turn or payoff), the image/video prompt, framing, motion and the lyric sung under it, plus the story, world and palette. No key needed.
| Name | Required | Description | Default |
|---|---|---|---|
| example_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond them — 'No key needed' — but says nothing about errors, pagination, or size limits, so it stays at an adequate level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the resource and then enumerates returned fields compactly. Dense but every clause earns its place; no filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so thoroughly, listing all major fields. The remaining gap is the provenance of example_id, which should route the agent to the listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One parameter with 0% schema description coverage. The description only alludes to 'an example song' and never explains what example_id is or where to obtain it (e.g., from list_example_songs), so it does not compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and its content precisely: a beat-synced shot plan for an example song, enumerating scenes, timings, act, prompts, framing, motion and lyrics. However, it never distinguishes itself from the close sibling get_example_analysis or get_song, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use statement and no named alternatives. The only routing-adjacent cue is 'No key needed,' which speaks to auth, not to which tool to pick among get_example_analysis, get_song or list_example_songs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Songbrain API prices (free songs per month, price per song) and limits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond the data it names — nothing about whether pricing is account-specific or global, caching, or freshness, which matters for a pricing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the key contents front-loaded and no filler. It is terse to the point of being slightly clipped, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the burden of describing the return, and it does so only at a high level. For a simple read-only zero-param tool that is adequate but leaves the exact shape of the response unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The content list (free songs per month, price per song, limits) usefully previews what the parameterless call returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource and the specific contents (free songs per month, price per song, limits), which is enough to distinguish it from siblings like get_account or get_song. No explicit verb, but the 'get' semantics are unambiguous for a zero-param info tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to call this versus get_account or any other sibling, and no prerequisites or conditions are mentioned. The agent must infer that this is the pricing/limits lookup from the name and content list alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a song started with analyze_song, then its full analysis once done. Summary view by default; view='full' adds word timings and beat arrays.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | summary | |
| song_id | Yes | ||
| sections | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value: the tool returns a status object first and only yields the full analysis once processing completes, which tells the agent to expect a not-ready state. It stops short of noting rate limits or error behavior for unknown song_ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, with the status-then-analysis lifecycle front-loaded and the view semantics following. No filler, no restatement of the tool name, and every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% schema description coverage, the description should do more. It adequately covers the async lifecycle and the view modes, but omits what the sections parameter filters and what fields the summary view returns, leaving real gaps for an agent composing a call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the parameter burden. It explains the view parameter well (default 'summary', 'full' adds word timings and beat arrays) and song_id is self-evident, but the sections array and its seven enum values are never mentioned, leaving a third of the parameters undocumented anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: retrieves the status and then the full analysis of a song, and distinguishes itself from the sibling analyze_song by framing itself as the polling/retrieval counterpart. It doesn't say what the analysis actually contains beyond the 'full' extras, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'started with analyze_song' implies this is the follow-up call to poll an existing job, which is useful context. However, it never states when to use it vs. get_example_analysis, nor what to do if the song is still processing or invalid, so the routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List real Songbrain analyses of Songbrain's own songs (no API key needed). Use one to show what the API returns before analysing a user's song.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious auth detail "(no API key needed)", which is genuinely useful behavioral context not present in structured fields; return format/pagination remain unstated, which is minor for a static example list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the identity of the resource and followed by the usage scenario. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-arg, read-only list tool with annotations covering safety, the description plus annotations give an agent enough to call it correctly. The absence of an output schema is fine since results are examples, though it doesn't hint at the shape or count of returned items.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no argument semantics to convey; the baseline for 0-param tools is 4. The description correctly implies no inputs are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (real Songbrain analyses of Songbrain's own songs), and clarifies the ownership scope so it's not confused with analyses of user songs. It does not explicitly differentiate from the sibling get_example_analysis, so an agent must infer the list-vs-single distinction from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use one to show what the API returns before analysing a user's song" gives a concrete when-to-use context (onboarding/demo). It doesn't name exclusions or explicitly compare against get_example_analysis, but the intended scenario is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
analyze_songget_accountget_example_analysisget_example_shot_planget_pricingget_songlist_example_songsSong in, video plan out: beat grid, best moments, timed lyrics, story and a beat-synced shot plan.
Create and track AI music videos and audio-reactive visuals from songs.
Turn audio or text into a finished AI music video: narrative, multi-provider clips, final cut.
Create and edit AI videos from chat: plan shots, generate scenes, and export stories and ads.
Add one secure layer between your agents and this server.
