Review a prepared batch

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

Annotations declare readOnlyHint=true, and the description adds meaningful output details: it returns the manifest hash needed for approval and describes the listing structure including blocking questions. This goes beyond what the annotation alone provides, with no contradictions.

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?

Two tightly written sentences deliver complete information without waste. The opening word 'Lists' immediately states the action, and the output details are efficiently packed, making it easy to scan.

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?

The description gives a solid overview of what the tool returns, including applications, readiness, and the manifest hash. However, it omits any explanation of the includeReady parameter and potential edge cases. Given no output schema, it covers most essentials for a preview tool but has a notable gap.

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 only 50%: batchId is documented, but includeReady is not. The description does not explain includeReady or how it filters the listing. Since the schema does not cover this parameter, the description should compensate but fails to do so.

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 uses a specific verb 'Lists' and clearly identifies the resource: every application in a batch with company, role, resume variant, and readiness. It also notes the return of the manifest hash for approval, which distinguishes it from related tools like preview_application (single app) and list_batches (batch list).

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 title 'Review a prepared batch' and the description imply this is for inspecting a batch before approval. It doesn't explicitly mention alternatives or exclusions, but the context is clear given the workflow with approve_batch and prepare_batch siblings.

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