get_track

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

The annotations already declare readOnly, idempotent, and non-destructive, so they cover the safety profile. The description adds substantial behavioral context beyond that: volume/panning are normalized not dB, arm is conditionally read to avoid Live exceptions, and counts are measured by probing batches and may be inexact. This is exactly the kind of non-obvious behavior an agent needs to trust the result.

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 front-loaded with a one-sentence summary, followed by scoping guidance, then a structured return list, then a compact notes paragraph. Every section earns its place and is grouped logically. Despite length, the density of useful behavioral caveats makes the complexity justified.

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?

Given the output schema exists and the annotations cover safety, the description fills all remaining gaps: return content, normalization caveats, conditional arm handling, batch-probed counts, and when to prefer sibling tools. An agent has everything needed to invoke get_track correctly and interpret the result without trial and error.

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 already documents both parameters fully with descriptions and enum values, so schema coverage is 100% and the baseline is 3. The description does not add much directly about the parameters themselves, but it does explain the meaning of 'track' in context and how certain values behave per track type. Since the schema carries the heavy lifting, a 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 first sentence names a specific verb ('Read'), the exact resource ('one track'), and enumerates the content: mixer state, flags, device chain, sends and clip slots. It explicitly contrasts with get_session (whole set) and get_devices (device chain only), so an agent can distinguish it from siblings immediately.

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 guidance: 'One track in one round trip, where get_session covers the whole set' and 'Use this to read a mixer before writing it with set_mix, and get_devices when the device chain is the only thing wanted.' It also warns against using this tool on group tracks for the arm field, which is a practical usage constraint.

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