Select a default audio device

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

Given that no annotations are provided, the description carries the full burden of behavioral disclosure, and it does so well. It explicitly states the side effects: 'move active streams through Omarchy' (affecting currently active audio streams), 'verify the default' (validation), and 'roll back on mismatch' (error handling). It also mentions support for dry-run, which is a crucial safety feature. This exceeds typical descriptions by providing a clear picture of what happens during execution.

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 two sentences with no wasted words. The primary action is stated first, followed by the key behavioral details and a note on dry-run. Every sentence adds essential information; there is no filler or repetition. This is an exemplar of concise, structured tool documentation.

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 tool that modifies system state and has no output schema, the description covers the needed behavioral context: what it does, stream migration, verification, rollback, and dry-run support. It does not explicitly reference how to obtain the enumerated names (e.g., via audio_devices), but this is reasonably implied by 'exactly enumerated' and the presence of sibling tools. Given no annotations, the description is thorough enough for an agent to use it correctly, though it could benefit from an explicit note about prerequisite enumeration.

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 schema description coverage is 0%, meaning the description must explain parameters, but it does so only minimally. The phrase 'exactly enumerated local output sink or input source' hints that 'name' must match an existing device from an enumeration, and 'kind' is sink or source. However, it does not clarify the 'dryRun' parameter beyond mentioning 'Supports dry-run.' The description adds little over the schema's enum and pattern, failing to fully compensate for the lack of per-parameter documentation.

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 action—'Select an exactly enumerated local output sink or input source'—and further specifies the workflow (move streams, verify, roll back). This clearly distinguishes it from sibling tools like audio_output_switch or media_source_switch, which likely handle temporary switching rather than setting a persistent default. The verb 'select' and resource 'default audio device' are precise and unambiguous.

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 when to use this tool: when you have an 'exactly enumerated' device name, suggesting you should first list devices (e.g., via audio_devices). However, it does not explicitly mention alternatives or when not to use it, such as switching output temporarily vs. setting a default. The guidance is implied but not explicit, leaving some ambiguity about the appropriate context relative to similar tools.

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