voicememos_second_read

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 well: it discloses asynchronous queuing and a returned job_id, the output format of disagreements ({a|b}), redo semantics, the realign mode that performs no new reading, and edge behavior for long recordings under only_uncertain. It stops short of mentioning permissions or how to poll the queued job.

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 purpose is front-loaded in the first sentence, followed by an organized Args list. It is appropriately sized for an eight-parameter tool, though the 'or:' formatting in since/until is slightly awkward and a few notes could be tightened.

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 an async job tool with no output schema, the description provides the essential return value (job_id), all parameter semantics, and important behavioral modes. It could be more complete by noting that memos must already be transcribed, what happens if they are not, or which sibling status tool to use to retrieve the job result.

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 compensate for all eight parameters, and it does: memos, since, until, model, redo, limit, only_uncertain, and realign are each explained with meaning and important nuances (date filtering is OR, limit applies oldest first, long recordings only in low-certainty parts).

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 action — queue a second, independent Gemini reading — on a specific resource: already transcribed memos. It also distinguishes the outcome from the primary engine by explaining that disagreements appear as {a|b} in the transcript, making it identifiable against siblings like voicememos_read or voicememos_compare_readers.

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?

Usage is implied by 'second, independent reading' and 'already transcribed memos', and parameter notes (redo, realign, only_uncertain) somewhat guide behavior. However, there is no explicit guidance on when to prefer this over voicememos_compare_readers, voicememos_read, or when a second reading is unnecessary.

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