upload_am_wav

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

Adds substantial context beyond annotations: verifies every uploaded byte, uses E443xB offset-14-bit big-endian format, turns RF/ARB OFF and leaves them off, may take minutes with a 900s timeout recommendation, and leaves partial files on failure with no retry or deletion. This richly complements the destructiveHint/openWorldHint 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?

Front-loads the core action and follows with dense, relevant constraints. Nearly every sentence earns its place, though the sequence of constraints reads as a list rather than tightly organized prose.

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 mutation tool with no output schema, it covers input format requirements, side effects on RF/ARB, failure behavior, and the separate play_waveform step. An agent has enough to invoke it correctly and warn about recomputation costs.

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 the burden. It explains depth (fraction, 0.5 = 50% peak, range 0.001–0.99) and overwrite (set true for existing names), but says nothing about name or path semantics, leaving half the parameters undocumented.

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 (upload), resource (local mono 16-bit PCM WAV), and output form (conventional AM via separate I/Q files). It is clearly distinguishable from siblings like configure_am_tone and play_waveform, which it explicitly routes to.

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 operational routing: 'Call play_waveform separately' and 'Existing names require overwrite=True'. It does not explicitly frame when to pick this over configure_am_tone, so it stops short of full when/when-not guidance, but context is clear.

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