Songbrain

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

Annotations only flag it as a non-read-only, non-destructive write. The description adds the cost (15 credits), the refund-on-failure policy, the asynchronous latency (~30 seconds), and the required post-call polling of get_song. That is exactly the operational context an agent needs beyond the annotation set.

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 dense sentences with no filler: precondition, effect and cost, then the required follow-up. The precondition and the follow-up action are both front-loaded where an agent will read them.

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 correctly explains that results arrive indirectly via polling get_song, and covers cost, failure handling, and timing. It stops short of saying where the shot plan surfaces in the get_song response, which would fully close the loop.

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% for the single song_id parameter, so the schema documents nothing about format or source. The description implies the song must already carry a mode 'dna' analysis but never states how to obtain or format the song_id, leaving most parameter meaning to inference. Adequate but thin.

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 and artifact: it 'builds its story and beat-synced shot plan (scenes with seconds and image/video prompts) from the existing analysis.' The precondition 'For a finished song analysed with mode dna' makes it distinguishable from sibling analyze_song, so an agent can route without opening the schema.

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?

Gives an explicit precondition (finished song already analysed with mode 'dna') and a follow-up step ('Then poll get_song'), naming the sibling to use next. It does not state the negative case — e.g. run analyze_song first if no analysis exists — so it falls just short of full when/when-not guidance.

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

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

Annotations only declare readOnlyHint=false/openWorldHint=true/destructiveHint=false; the description goes well beyond, disclosing the API-key requirement on the connection, credit billing impact (1 free song, or 25/10 credits), asynchronous job semantics, and expected completion time. That is exactly the operational context an agent needs before committing spend.

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 sentences, front-loaded with the action and input, then workflow, then cost. The credit figures partly restate the mode enum description in the schema, which is mild redundancy, but nothing is filler.

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 contract by naming song_id and the polling loop, plus auth, cost, format constraints, and timing. For a 5-parameter job-starter tool with only 60% schema coverage, this is complete enough to invoke correctly.

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 60% and the description adds real value for audio_url (accepted formats, 30 s–10 min bound) and reinforces the mode cost split. It says nothing about title, artist, or how lyrics interacts beyond what the schema already notes, so a small gap remains for the undocumented title/artist fields.

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 action ('Start the analysis of a song') and the exact input resource ('at a public audio URL'), including accepted formats and duration bounds. It implicitly but effectively separates itself from get_song, which the description casts as the polling reader rather than the starter.

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?

Gives an explicit workflow: call this, get a song_id, then poll get_song until status is 'done'. It even sets latency expectations (60–90 s typical, up to ~2 min busy) and distinguishes the two modes by what they produce and cost, so the agent knows when to pick each.

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

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.

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.

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.

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.

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.

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.