Start a batch PDF job

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

With no annotations, the description fully covers behavioral traits: it returns a job id, runs rendering in the background, and poll get_job is required. It also discloses the side-effect that filename_template and group_by are saved to the template/project, altering defaults for future runs—critical for an agent to know.

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?

The description is well-structured: it opens with a one-sentence system context, then the tool's specific action, followed by usage conditions, a behavioral note, and a parameter warning. Every sentence serves a purpose and the information is front-loaded with the core purpose. While not extremely short, it is efficient and free of fluff.

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?

Given no output schema, the description explains the return value (job id) and how to retrieve results via get_job. It covers prerequisites, background execution, and side-effects, making it fully self-contained for an agent to correctly invoke and interpret the results.

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?

The input schema already provides complete descriptions for all four parameters, including the persistence side-effect for group_by and filename_template. The description adds usage guidance ('Only pass them when...'), but does not introduce new semantic meaning about what each parameter does beyond the schema. Given 100% schema coverage, the description meets but does not exceed the baseline.

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 clearly states the tool's function: it queues a batch job that renders one PDF per row of an uploaded dataset and returns a job id. It also distinguishes itself from siblings by mentioning the batch scenario ('many documents at once') versus single renders, making it specific and differentiating.

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?

Explicitly states when to use it ('Use it when the user wants many documents at once'), provides a prerequisite (dataset must already be uploaded, cannot upload), and directs the agent to poll get_job for progress. This is clear guidance on when and how to use the tool.

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