get_wavetable_state

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

The description begins with 'Read', which clearly signals a read-only operation with no side effects. It also specifies exactly what data is returned (modulation matrix, wavetable selection, voicing) and clarifies that this data is not available through get_device_parameters, providing full transparency without relying on annotations.

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 structured with a clear purpose statement, a contextual note about where the data lives, and a concise parameter list. It uses bullet-like formatting that aids quick scanning. No fluff or unnecessary details.

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 benot shown but indicated, the description covers purpose, usage differentiation with a sibling, and parameter semantics fully. It also clarifies that the tool reads data not available via get_device_parameters, giving the agent enough context to decide when to invoke it. The absence of annotations is compensated by the explicit read-only nature implied by the verb 'Read' and the clear scope.

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 description includes a Parameters section explaining each parameter's meaning and indexing conventions: 'track_index: Track number (1-based)', 'device_index: Device number on the track (1-based)', 'chain_index: Chain number inside a rack (1-based, 0 = not in a rack)'. This clarifies the semantics beyond the schema's default values and types, reducing ambiguity for the agent.

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 'Read a Wavetable's modulation matrix, wavetable selection and voicing', a specific verb-resource pair that clearly identifies the tool's purpose. It explicitly contrasts with get_device_parameters, distinguishing this tool from a close sibling and clarifying its unique scope.

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 explicitly states 'None of this appears in get_device_parameters - it lives on the WavetableDevice object itself', giving clear when-to-use guidance and naming the alternative tool. This contrasts the tool with a sibling and implies when not to use it, which is ideal.

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