get_voice_input

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

With no annotations, the description fully carries the behavioral disclosure burden. It reveals long-poll timeout behavior, queue joining with ' / ', sentinel values, the session lock with PID, and the exact follow-up action for each sentinel. This is exceptionally transparent.

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 description is longer than most, but every sentence earns its place: purpose, loop context, queue joining, and each sentinel case. It is well-structured, front-loaded with the core purpose, and groups related behavioral details logically.

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?

There is no output schema, but the description documents every possible return value and the appropriate agent reaction, including edge cases like concurrent process lock and takeover. It also names the relevant sibling tool. No meaningful gaps remain for an agent to call it correctly.

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?

The tool has zero parameters)Skip, so the schema is trivially complete (100% coverage). The description adds no parameter details, but none are needed; the baseline for a zero-parameter tool is 4.

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 states a specific verb and resource: 'Returns the next voice utterance from the user as text.' It clearly frames the tool as a polling operation used in a loop during voice review sessionsasha. The sentinel behaviors and the mention of take_over_voice_session distinguish it from siblings.

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?

The description explicitly explains when to call the tool (in a loop during voice review) and how to react to each possible return value: retry on __NO_INPUT__, stop on __END_SESSION__, and ask the user then call take_over_voice_session on __ALREADY_RUNNING__. This is clear, actionable usage guidance with no ambiguity.

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