generate_music_stream

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

With no annotations, the description carries the entire behavioral burden. It does disclose two useful traits — this is a paid operation with two gates, and it writes a file locally — but it never names the gates, explains cost risk, describes streaming progress behavior, or states whether an existing file at `filename` is overwritten.

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?

The single sentence is tight and front-loads the action, so there is no padding. However, brevity here is achieved by deferring to a "documented endpoint" rather than by saying anything substantive, so the compactness buys little.

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?

This is a nine-parameter, nested-object, paid, file-writing tool with no output schema and no annotations, so the description needed to do real work. Instead it covers only the paid-gate mention and the local save, leaving the composition_plan structure, model choice, length limits, and the two boolean gates entirely unexplained.

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% across nine parameters, including a nested composition_plan with per-chunk style and adherence fields, yet the description mentions no parameter at all. The agent gets no meaning for seed, prompt, model_id, music_length_ms, force_instrumental, or the paid-gate flags beyond their schema keys.

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?

"Call the documented streaming music endpoint, then save the completed result locally" conveys the streaming-plus-local-save shape, which loosely separates it from generate_music and generate_music_detailed. But "documented streaming music endpoint" is a circular reference rather than a statement of what the tool produces, and nothing distinguishes it from generate_music_detailed_stream among the siblings.

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 guidance is offered: the description never says to prefer this over generate_music or generate_music_detailed_stream, nor what the tradeoff (streaming vs. one-shot, file output vs. returned asset) is. The only hint is "paid-operation gates," which gestures at cost without explaining when the agent should enable those gates or avoid them.

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