生成音频

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

With no annotations, the description carries full burden. It explains synchronous/asynchronous behavior and the need to consult describe_model. However, it does not disclose auth requirements, rate limits, or what the returned URL/task_id contain. The inline_image parameter description is irrelevant for audio and may confuse.

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 description is compact but includes an irrelevant detail about inline_image only applying to generate_image, which is noise for this tool. The structure is mostly front-loaded but could be streamlined.

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?

Covers the main workflow (submit, wait, fallback) and dependency on describe_model. Lacks details on return format (URL or task_id contents) and potential limitations like credit costs. Without output schema, more detail would improve completeness.

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%, but the description adds value: it explains the params object structure (e.g., {prompt, aspect_ratio}) and refers to describe_model for details, clarifies wait_seconds=0 behavior, and explains inline_image only applicable to generate_image. This goes beyond the schema.

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 clearly states it submits audio tasks (TTS, music, voice recognition, voice cloning) and mentions a dedicated endpoint for Suno. It distinguishes from sibling tools that handle other media types.

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?

Explicit guidance includes using describe_model first, default 60s wait, short tasks returning URL directly, long tasks returning task_id with get_task, and setting wait_seconds=0 for immediate task_id. It does not explicitly state when not to use, but context implies audio-only tasks.

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