set_mixer

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

Annotations already declare this is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety bar is lower. The description adds genuinely useful context beyond that: settings take effect on the pedal immediately (no separate apply/save step), and pan is silently inert unless the master is stereo. It does not say whether settings survive power cycles, which is the remaining behavioral unknown.

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?

Two dense sentences with zero filler; the capability surface is front-loaded and the side-effect note closes it out. Nothing repeats structured data verbatim without adding meaning.

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 nested two-parameter schema with no output schema and no field descriptions, the definition covers the channel side adequately but leaves the entire master section opaque — the reader cannot tell what link_lr, left_db versus level_db, or mute do. In a high-complexity nested tool, that is a meaningful gap despite the good side-effect disclosure.

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 description coverage is 0%, so the description carries the burden. It does explain the dB range and pan range plus the stereo-master dependency for pan, but those ranges are already encoded as schema minimum/maximum. The master sub-fields (link_lr, left_db, right_db, mute, mode) and the channel enum values (instrument/vocal/bluetooth/usb) are not explained anywhere, so compensation is only partial.

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 names the resource (mixer) and enumerates exactly what is configurable: per-channel on/off, level, pan, plus the master section. It is clearly distinguishable from siblings such as set_vocal_fx or set_global, but the verb is implied rather than stated (the first word is a noun label), so it stops just short of a fully explicit verb+resource statement.

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?

There is no explicit guidance on when to call this versus related tools like set_global or set_vocal_fx, and no prerequisites are stated. The only conditional guidance is embedded in a parameter note ('pan only has effect with a stereo master'), which is about parameter behavior, not tool selection.

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