umouse_audio_record

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

With no annotations, the description carries the load well: it discloses audio format, that WAVs are written to disk and kept out of the conversation stream, and notably that action=stop is idempotent — if the session was already auto-closed by key release or timeout it returns the most recent completed file instead of an error. It omits what happens if start is called while a recording is already active, and there is no permission/auth context.

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?

Single dense paragraph with the key facts (format, no chat stream, recommended alternative) front-loaded before the per-action breakdown. Slightly compressed by bracketed parentheticals, but every clause carries information and nothing is redundant.

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?

No output schema exists, and the description covers the important returns — WAV path on stop, and the idempotent file= fallback. It does not describe what action=status yields, which is the one remaining gap for a tool an agent must call blind.

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 67%, but the description compensates for the undocumented action enum by giving meaning to each value (start = begin continuous audio, stop = finalize with idempotent fallback, status = inspect in-progress session). device_id and max_seconds are already well documented in the schema, so the description adds the piece the schema could not.

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+resource (device recording to a WAV file at 16kHz/16bit/mono) and immediately distinguishes itself from the recommended voice-key path handled via umouse_wait_events. An agent can tell what this tool is and is not without opening the schema.

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 says the voice key + speechCaptured/umouse_wait_events flow is the default and recommended route, and this tool is only for manual scenarios such as long-running meeting capture. The when-not is as clear as the when.

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