Generate Music or Audio with Replicate

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

Annotations only declare the mutation/open-world profile; the description adds genuinely new behavior: the mandatory display requirement with `[Audio](URL)`, the ~24h URL expiry, per-model runtime estimates (~3-4 min for ace-step), timeout semantics with a poll-for-prediction recovery path, and default local download. These are operational traits an agent cannot infer from annotations or schema.

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?

Purpose and the display requirement are front-loaded, and the Models/Args/Examples sections are scannable. There is some duplication — the curated model list and the lyria "no duration" caveat appear in both the Models and Args blocks — which costs a bit of tightness in an otherwise well-structured definition.

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, yet the description states the return shape ("PredictionResult. local_paths contain audio files") and explains URL expiry and download behavior. With six parameters including a free-form nested `extra_input` and six model variants, the description supplies everything needed to select a model and invoke it 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 100%, so baseline would be 3, but the description goes well beyond it by mapping `prompt` to different backend fields per model ("tags" for ace-step, "prompt_a" for riffusion, inline lyrics/structure for lyria) and by flagging that `duration_seconds` is supported by musicgen/ace-step but ignored for riffusion and lyria. Concrete `extra_input` examples ({temperature, top_k}, {lyrics}) add further meaning the bare object schema lacks.

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?

Opens with a specific verb + resource + scope ("Generate music, ambient audio, or full songs from a text prompt") and the Models section makes clear how it differs from siblings like replicate_generate_speech and replicate_generate_image. An agent can tell instantly that this is the text-to-music path, not narration or sound effects.

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 Models table functions as explicit when-to-use-which guidance: ace-step for lyrics, riffusion for looping ambient, lyria-3-pro for sung vocals up to 3min, and it names the polling fallback (replicate_get_prediction) on timeout. It stops short of explicit exclusions or routing away to sibling tools (e.g. speech narration), so it is clear context without full when-not coverage.

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