set_mixer_panning

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

Annotations already flag destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description goes beyond them with 'Immediate edits; partial work retained without rollback/replay,' which is genuinely useful for an agent weighing a destructive mutation, plus the separate-confirmation hint for the mode vs. balance paths. It loses a point for the opaque 'Updated bridge; all profile' tail, which discloses nothing.

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 purpose is front-loaded, which is good, but the middle and tail are dense with undefined jargon ('native identities', 'separate confirmations', 'Updated bridge; all profile') that pads rather than informs. 'No timed sweep or audible image claim' is a useful exclusion, but the final fragment earns nothing and the whole is harder to parse than its length warrants.

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?

An output schema exists, so return values need not be explained, and 89% parameter coverage means the schema carries argument detail. For a destructive, non-idempotent 9-parameter mutation the description supplies prerequisites and the no-rollback failure mode, which is the key missing context. The vague 'separate confirmations' phrasing keeps it from a 5.

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 89%, so the schema already documents trackId, pan, left, right, dryRun, planHash, confirmationToken and expectedStateVersion. The description's mention of mode/balance/split-channel targets loosely maps to the oneOf structure but adds no format or constraint detail beyond the schema. 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 opening clause gives a specific verb and resource: 'Change one mixer panning mode or its active Stereo balance / Split Stereo channel positions.' It clearly distinguishes the three pannable targets (mode, balance, split channels) and is distinguishable from the read-side sibling get_mixer_panning_context. It stops short of a 5 because the sentence is entangled with prerequisite jargon rather than cleanly separating what-it-does from what-it-requires.

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?

Prerequisites are stated ('Recording/count-in off, unfrozen target, known inactive affected automation and native identities required'), which implies when the tool is invocable. There is one exclusion ('No timed sweep or audible image claim') but no named alternative such as get_mixer_panning_context for reading, and no explicit when-not guidance. Usage is implied rather than directed.

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