raw_change_audio

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

With no annotations provided, the description carries the burden, and it partially does: it warns 'May open a dialog or change project state' and advises inspecting the command name first. However, it is vague about side effects, return behavior, or exactly what state may change. No contradiction with annotations.

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, each earning its place: what it does, static nature, and behavioral caution. It could arguably drop the final 'inspect the command name first' warning, but it is useful for a raw command-style tool.

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?

For a zero-argument, no-output-schema tool, the description is mostly complete. However, given the large sibling set and the ambiguity of 'change_project_state,' an agent would benefit from knowing whether this is safe to invoke or what typical response it returns. Still, minimal viable for a simple static action.

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 tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description correctly emphasizes 'no-argument' action, which is useful confirmation.

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 states a specific verb+resource: 'Open the audio host/interface selection dialog' and identifies it as a static no-argument Audacity action. The tool name 'raw_change_audio' is somewhat opaque, but the description clarifies its function and distinguishes it from typical audio-editing operations among the large sibling list.

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 implies this is a raw/static action with no arguments, but it does not explicitly say when to use it vs alternatives. It notes 'inspect the command name first,' which hints at caution but doesn't provide clear when-to-use guidance compared to sibling tools like raw_output_device or raw_input_device.

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