add_soundfield_effect_to_submix

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the save-to-disk requirement, the duplicate-skip semantics with exact flags returned, and the failure mode when no concrete subclass ships. This is exactly the kind of mutation/side-effect context the annotations cannot carry.

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 action and its persistence constraint, then the skip case, then the failure case, then the return shape. Every sentence carries distinct information with no padding.

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, but the description enumerates the return object's fields, and it covers the write path, duplicate handling, and the no-subclass failure mode. An agent has everything needed to invoke and interpret the call.

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 both parameters are already documented in the schema, including the note that a bare class name does not resolve. The description only restates that a concrete USoundfieldEffectBase class is required, adding no syntax or format detail 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?

States a specific verb (append) plus the exact resource (a concrete USoundfieldEffectBase class into a USoundfieldSubmix effect chain) and adds the save side effect. The agent can distinguish this from the generic add_submix_effect_to_chain and the sibling remove_soundfield_effect based on the name and opening clause alone.

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 description gives clear situational conditions: an addition only succeeds if the submix reaches disk, duplicate classes are skipped, and the call fails when no concrete subclass is loaded. It does not, however, explicitly point to the generic add_submix_effect_to_chain alternative, so the agent must infer which sibling applies.

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