Start Waveform

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the confirmation gate, that playback is asynchronous, and the non-obvious side effect that vibration persists after the waveform ends. Missing is error/edge behavior (nonexistent waveform name, no connected device) and how completion is observed.

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?

Two dense sentences, no filler. The precondition comes first, then the behavioral caveat, so the most decision-relevant information is front-loaded.

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 no explanation, and the safety/side-effect profile is well covered for a mutation-like action. The remaining gap is discoverability of async progress — an agent is told how to stop vibration but not how to check whether the waveform is still playing (get_waveform_status).

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 coverage is 0%, so the description must compensate. It explains confirm well — it must be true or the call does not actually start playback — but says nothing about the required 'name' parameter beyond implying it selects a 'saved waveform', leaving whether it is an ID, exact name, or partial match unstated.

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 (asynchronously play) plus resource (a saved waveform, on the connected device), which separates it cleanly from list_waveforms/save_waveform/get_waveform and from stop_waveform. The async qualifier and the confirm gate are both stated up front.

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?

Explicitly gives the precondition for invocation (confirm=true) and the follow-up action an agent must take (call stop_vibration separately, since stopping the waveform does not stop vibration). It does not name a when-not-to-use case or point at get_waveform_status for progressing an async run, so it stops short of full routing guidance.

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