submit_batch

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

With no annotations, the description carries the full behavioral burden, and it does disclose the core model: tasks are queued (async, not blocking) and scheduled across distinct accounts under quota awareness. However, it says nothing about failure/isolation semantics, what happens to partially failed batches, concurrency or the 100-task cap, or what identifier the caller gets back for later tracking.

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?

A single front-loaded sentence with no filler; the scheduling intent leads and each clause adds information. It is slightly dense with jargon ('quota-aware parallel execution'), but nothing is redundant or wasteful.

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?

This is a complex, mutation-capable batch-scheduling tool with no annotations and no output schema, so the description should explain return/failure behavior and constraints. It omits what the tool returns for tracking, how failures are reported, and the interaction between write_paths locking and parallel scheduling. Too thin for the tool's complexity.

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?

Top-level schema description coverage is only 25% (workspace documented; tasks, timeout_sec, permission_mode not). The description mentions 'across distinct accounts', which loosely ties to the per-task account param and its omit-for-scheduling behavior, but it never explains the tasks array, the required prompt, batch size limits, or permission_mode. It does not compensate for the coverage gap, though the nested item properties are documented by the schema itself.

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 gives a specific verb (queue/submit) and resource (tasks), plus a scope qualifier: independent tasks, parallel, quota-aware, across accounts. That is far more informative than the bare name 'submit_batch'. It does not, however, explicitly differentiate itself from sibling submit_job, so an agent still has to infer why batch is preferred over a single job.

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 phrase 'independent tasks' implicitly states the eligibility condition for this tool, which is real usage guidance. But it never names submit_job, submit_workflow, or submit_workflow as alternatives, nor does it state when a caller should avoid batching (dependent tasks, shared write paths). Guidance is implied rather than explicit.

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