download_batch_output

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

Annotations already declare the safety profile (idempotent, non-destructive, open-world), and the description adds meaningful behavior beyond them: it writes to the local filesystem, returns only path/size/count and never contents, and that extract also unpacks into a subdirectory. The one-download-at-a-time concurrency limit is a genuinely useful disclosure not present in annotations; the only gap is that overwrite behavior on an existing dest_dir is unstated.

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-loaded with the core action and output artifact, then progressively adds extraction and concurrency detail. Slightly cluttered by internal implementation references ('Get tarred output files', 'get_output3.php') that most callers do not need, but 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?

An output schema exists, so return details are optional, yet the description helpfully frames them (path, size, file count, never contents). Combined with the extraction behavior and concurrency limit, an agent has enough to call it correctly; only filesystem preconditions and overwrite semantics are missing.

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?

With 0% schema description coverage the description must carry parameter meaning, and it largely does: extract=true is explained as unpacking into dest_dir/batch_<id>/, while dest_dir and batch_id are both located in the documented output path. It does not say whether dest_dir must already exist or whether paths are absolute, leaving a minor gap.

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 ('download the batch's output') plus the exact artifact produced (dest_dir/batch_<id>.tar) and the operation it wraps (Get tarred output files / get_output3.php). An agent can immediately distinguish this from siblings such as batch_status or list_batches.

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 applicability ('works for batch-collect apps such as BUDA') and an operational constraint ('the server allows one download of a batch at a time'), which is exactly the kind of context that guides correct invocation. It stops short of explicitly naming alternatives or stating when not to use it, so it is clear but not complete routing guidance.

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