clean_audio_input

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

With no annotations, the description carries the burden of disclosure. It clearly explains the filter order and why, states that existing filter kinds are skipped to avoid duplication, and notes that this is a one-shot setup. It does not cover failure modes or what happens if an existing filter has different settings, but the core side effects are transparent and reversible via the referenced removal tool.

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 well-structured with an overview, behavioral notes, and a detailed parameter list. It is longer than average because it must document 9 params without schema help, but every sentence adds value and the main purpose is front-loaded in the first sentence. The structure makes it 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?

For a tool with 9 params, no annotations, and no output schema, the description provides a remarkably complete picture: what it does, the chain order, dedup behavior, defaults, and parameter semantics. It stops short of error handling or edge cases, but for a setup utility this is sufficient and unlikely to leave the agent guessing.

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?

Since schema description coverage is 0%, the description fully compensates by giving each parameter purpose, units, ranges, defaults, and tuning guidance (e.g., 'Should sit slightly below your voice level', '5-8 dB below open threshold'). This goes far beyond the bare schema titles and provides actionable context for choosing values.

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 explicitly states the action ('Set up a standard mic-cleanup filter chain'), the resource ('mic/audio input'), and the exact composition ('Noise Gate -> Noise Suppression -> Compressor'). This clearly distinguishes it from sibling tools like create_source_filter or remove_source_filter, as it is a one-shot setup rather than a single-filter operation.

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 clearly indicates when to use the tool ('in one call' for a standard chain) and explicitly notes that removing a stage later is done via remove_source_filter, giving an alternative. However, it does not explicitly contrast with using create_source_filter for individual filter setup, so it lacks an explicit when-not scenario beyond the removal case.

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