play_waveform

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

Annotations only declare it is a non-readonly, idempotent, non-destructive, non-open-world mutation. The description goes well beyond that by enumerating the instrument state it resets (internal I/Q and clock, master modulation, continuous trigger, crest mode, no gating/blanking or competing analog modulation, ALC off, fixed-reference power search) and by clarifying it does not alter samples and that modulation depth comes from the waveform rather than the AM menu.

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 key facts (purpose, worked parameter example, rf_on rule) are front-loaded and every later sentence conveys state-setup or scope information. It is slightly redundant in restating 'Restore... Restores...', but no sentence is filler.

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 non-readonly, no-output-schema state-restoration tool, the description covers what state is changed, what is left untouched, and how to invoke it with concrete values. Missing only edge-case behavior such as error handling for an unknown waveform name or interaction with prior playback, which is minor given the annotation coverage.

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 must carry parameter meaning, and it does: it supplies concrete values for all four required parameters (name='VOICE_T12', sample_rate_hz=16000, frequency_hz=750000, level_dbm=-10) and explains rf_on's semantics. It does not state units, ranges, or what happens if the waveform name does not exist, so it is strong-but-not-complete compensation.

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+resource+scope: 'Restore a complete continuous I/Q playback setup using an existing waveform.' That is clearly distinguishable from siblings like upload_am_wav, inspect_waveform, and list_waveforms, since playback state restoration is a different action from uploading or inspecting.

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?

It gives an explicit conditional instruction for rf_on ('Specify rf_on=True only when output is requested') and a negative scope statement ('Does not upload or modify samples'), which steers the agent away from upload tools. It never names an alternative sibling or prerequisites (e.g. that the waveform must first be listed), so it stops short of full when/when-not routing.

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