read many sync jobs

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, yet the description still adds a lot: exact return shape per job in input order, error entries for unreadable jobs, aggregate counts, the full status lifecycle, progress notifications, and the ~50 second server-side cap on wait. It does not explain why readOnlyHint is false for a tool framed as 'Read', which is the one behavioural loose end.

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?

Purpose is front-loaded in the first clause and every block earns its place, but the per-kind id rules are crammed into one long parenthetical bullet list inside a single paragraph, which makes the definition dense to scan. Structuring the kind-to-id mapping as its own listed block would improve it without adding words.

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?

Despite having only two parameters, this tool has a non-trivial contract (batched heterogeneous ids, partial failures, polling). The description covers id sourcing, batching limits, error entries, counts, status transitions, and wait/retry semantics, so an agent can call it correctly without further context.

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 coverage is 100%, so the baseline would be 3, but the description carries information the schema explicitly defers to it ('see the tool description per kind'): the source of each kind's id, and which kinds additionally require projectId, projectIntent, or videoAssetId. That mapping is the whole difficulty of using this tool and exists nowhere else.

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 opening clause gives a specific verb, resource, and bounded scope: 'Read up to 50 Sync jobs of any kind at once ... by kind and id'. It also anchors the tool to the producer that creates these jobs (jobs_create-many), which is exactly what distinguishes it from the single-job jobs_get and the blocking jobs_wait.

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 spelled out concretely: pass jobs_create-many's jobs list as-is, per-kind id derivation rules, 'never create it again' while status is PENDING/PROCESSING, and 'call again with wait: true instead of sleeping'. The only gap is that it never names jobs_get or jobs_wait as the alternatives for a single job or a pure blocking wait.

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