get_batch_image_task

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

Adds real behavior beyond the annotations: read-only HTTP with bounded retries, automatic write-to-disk, local-status fallback without resubmission, and that cloud failure surfaces as a tool error monitored via result.save_status. This meaningfully explains why readOnlyHint is false despite read-only upstream calls. It stops short of describing timing/polling semantics.

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 operation and keying inputs, then packs retry, fallback, and error-handling notes into two dense clauses. No filler, though the second half is run-on enough that the error-handling guidance is easy to skim past.

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 values need not be enumerated, and the description correctly points at result.save_status for the one field that matters. Persistence, retry, fallback, and error semantics are all covered; polling/wait behavior relative to wait_image_task is the only notable omission.

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 80%, so the per-parameter docs already carry most weight (baseline 3). The description contributes the non-obvious constraint that all three keys must be the ORIGINAL values from submission, not arbitrary IDs, and links the save/output_dir behavior to 'automatic persistence'.

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: query the supplier's async result keyed by the original (checkpointer, thread_id, task_id) triple, with automatic persistence. It implicitly separates itself from the submit_* siblings by noting it never resubmits, but it never names wait_image_task or get_image_task directly, so sibling differentiation is only partial.

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 one useful conditional: when no supplier ID is present it returns local status instead of resubmitting. It also tells the agent where to look on failure (result.save_status). However, it never says when to prefer this over wait_image_task or get_image_task, so the routing 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.