Play named waveform

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

Adds substantial behavior beyond annotations (readOnlyHint=false, destructiveHint=false): it discloses that playback 'replaces the channel's current waveform task', that it 'requires a safe nonzero intensity', and that it 'never changes intensity'. It also clarifies duration semantics via 'repeat or truncate'. No contradiction with annotations exists — the replacement is a task swap, not data destruction. Note: 'max 10000ms' conflicts with the schema's maximum of 30000, a description-vs-schema inconsistency, not an annotation contradiction.

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?

Three dense sentences with the primary verb-resource pair front-loaded in 'Play a named waveform'. Each sentence earns its place: matching semantics, duration option, intensity requirement, and replacement side effect. The first sentence's parenthetical is somewhat heavy but packs crucial matching information without bloat.

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?

Covers the essentials for a mutating tool with 5 params and no output schema: what it plays, where (channel), the precondition (safe nonzero intensity), what it does not do (never changes intensity), and side effect (replaces current task). Gaps remain: no behavior for missing waveforms or unsafe intensity, no acknowledgment/return expectations, and the durationMs max discrepancy leaves the agent uncertain which bound is authoritative.

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 100%, so the baseline is 3 with no obligation to compensate. The description does add value beyond the schema: case/separator-insensitive matching across ids and English/Chinese names for 'name', and repeat/truncate semantics for 'durationMs'. However, it introduces an error — 'max 10000ms' contradicts the schema's maximum of 30000 — which an agent could mistakenly trust, offsetting the added value.

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?

States a specific verb and resource — 'Play a named waveform ... on one channel' — and distinguishes itself from siblings: 'named waveform (built-in preset or hot-loaded .pulse file)' separates it from dglab_play_custom_waveform, while 'never changes intensity' separates it from dglab_set_intensity/dglab_adjust_intensity and 'replaces the channel's current waveform task' from dglab_stop_channel. The behavioral scope is unambiguous.

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?

Gives clear usage context: 'Requires a safe nonzero intensity on the channel' states a precondition, and 'never changes intensity' + 'Playback replaces the channel's current waveform task' convey when-not and consequences. However, it never explicitly names sibling alternatives or states 'use dglab_list_waveforms to discover names' or 'use dglab_play_custom_waveform for arbitrary patterns', so the exclusion logic is implied rather than explicit.

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