voice_batch

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

With no annotations the description carries the full burden, and it discloses meaningful traits: the call blocks until all jobs finish, it returns per-job status and output paths, and it exposes tuning knobs (batch_timeout_s, keep_executor, force). It omits failure semantics — what happens on partial failure or timeout — which keeps it from a 5.

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 behavior (run speech jobs on GPU, block until done, return status/paths) before the field details, and every clause carries information. The inline brace-list format is dense but readable; nothing is padded.

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 nested-object, no-output-schema, long-blocking batch tool, the description covers what it does, when it is safe to run, and what comes back, which is close to what an agent needs to call it. Remaining gap is error/partial-failure behavior, which matters for an all-jobs-blocking call.

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% and the nested job objects declare no properties at all, so the description is the only source for the job field names (text, out, profile_id, instruct, speed, language) and the option names. It names the options without explaining their effect, so it compensates well but not completely.

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 and resource ('Run VoiceStudio speech jobs') plus the key scope (GPU, on a batch of jobs), which is enough to separate it from the unrelated comfy_batch (image ecosystem) and gate_status siblings. It never explicitly names an alternative, so it stops short of a 5.

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 a real usage condition — the jobs run on the GPU 'while the local LLM is unloaded' — which tells the agent when this tool is appropriate versus other GPU work. It does not, however, state exclusions or route to a sibling for the non-batch case, so it is clear context rather than a full when/when-not rule.

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