Create audio spectrum

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

Annotations already state readOnlyHint=false and openWorldHint=true, so creation is expected. The description adds valuable context: it may trigger a macOS microphone-permission dialog, exposes channels in a specific naming pattern, includes a Sensitivity knob (if expose_controls is true), and supports multiple audio source types. This goes beyond the annotation-derived baseline and surfaces non-obvious side effects.

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 dense but not verbose. It packs a clear definition, a usage example, a sensitivity knob note, source options, a security caution, and sibling tool guidance into one compact paragraph. Every sentence contributes a distinct piece of information, and the opening sentence immediately answers 'what does it do?'.

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?

Because there is no output schema, the description fully covers what the agent will get: a Null CHOP with band0..band{N-1} channels, how to bind them (via op('…/spectrum/spectrum')['band0']), what the Sensitivity knob does, the four source modes, and a macOS permission caveat. It also positions the tool relative to its siblings, making the context complete for selection and invocation.

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 each parameter already has a descriptive comment (e.g., bands, source, parent_path). The description reinforces the bands/channel naming and shows a binding example, but it doesn't add meaning beyond the schema's existing parameter descriptions. Baseline 3 is appropriate.

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 opens with a specific verb ('Build an FFT audio-spectrum analyzer') and includes the concrete deliverable: N bindable frequency-bin channels (band0..band{N-1}) on a Null CHOP. It also names sibling tools and explicitly frames itself as the per-band complement, making differentiation clear from the outset.

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 explicit when-to-use vs alternatives: 'Use extract_audio_features when you want coarse level/bass/mid/treble bands instead of N fine bins, create_audio_reactive for a ready-made spectrum visual, and feed this Null into bind_audio_reactive to drive a COMP.' This is textbook usage guidance—it tells the agent when to choose this tool versus its siblings.

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