create_audio_bus

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

Annotations already cover the write/destructive/non-open-world profile, and the description still adds real behavior: create-or-load semantics with already_exists, that a different asset class at the path is an error, that an invalid channels value is refused before any asset is created or loaded, and the full result shape including save_error. The only soft spot is idempotency: the described re-save-on-existing behavior reads as closer to idempotent than the declared idempotentHint=false, though re-writing the package each call makes that defensible rather than contradictory.

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?

Front-loaded with the core create-or-load action, and every subsequent clause (defaults, validation order, sibling routing, return shape) carries information an agent needs. It is dense and long for a 3-parameter tool, with the first sentence packing several facts via semicolons, but there is no 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?

There is no output schema, and the description compensates by enumerating every returned field including applied_channels, created, already_exists, saved and save_error, along with the error and default conditions. Combined with annotations covering the safety profile, an agent has everything needed to call this correctly on the first try.

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% and the channels field already documents the enum set and that the default applies only to a new bus, so the baseline is 3. The description goes further by spelling out the omitted-channels behavior for both new and existing buses, the pre-creation rejection of invalid values, and how name and package_path combine into the asset path, which is meaningful added meaning for all three parameters, though some of it restates 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?

States a specific verb and resource (creates a UAudioBus asset at package_path/name and saves it) and immediately explains the create-or-load duality, so an agent knows exactly what object it is producing. It also names the sibling tools it is not (set_audio_bus_channels, get_audio_bus, create_sound_source_bus), which makes it distinguishable from the crowded audio-asset tool set without opening any 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 explicit routing: use set_audio_bus_channels to change the layout later, get_audio_bus to read it, and create_sound_source_bus for a source bus that plays this bus. It also states the when-not condition indirectly by explaining that omitting channels preserves an existing bus's layout, so the agent can tell when a call is a no-op layout-wise.

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