generate_sound_effect

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

With no annotations, the description carries full burden and does disclose important behavioral traits: the output is a generation-only bed (not mixed), duration is limited to 0.5-30s, and loop=true creates a seamless bed. It does not explain prompt_influence or output behavior, but the key generation-only semantics are transparent.

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 sentences front-load the purpose and then provide actionable usage guidance without fluff. Every sentence earns its place, and the structure is easy to scan.

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?

The description covers the core workflow, duration limit, loop guidance, and separation of generation from mixing, which is sufficient for a 5-param tool with an output schema. It omits optional parameter semantics for output_path and prompt_influence, but those have self-explanatory names and defaults.

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 description adds meaning for prompt (describe concretely), duration_seconds (clip/ad runtime), and loop (seamless bed). However, it does not clarify output_path or prompt_influence, and since schema description coverage is 0%, these two parameters remain underdocumented.

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 opens with 'Generate an ambient/diegetic sound-effect bed (0.5-30s) from a text prompt,' clearly naming the verb, resource, and scope. It distinguishes this tool from siblings like generate_music and generate_elevenlabs_voiceover by specifying it produces sound-effect beds rather than music or voiceover.

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 provides clear when-to-use context: 'Generation only — the caller mixes the bed onto the video locally' and instructs to pass duration_seconds and keep loop=true for a seamless bed. It gives a when-not (don't expect mixing), though it does not explicitly name alternative tools.

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