Kalpana Batch

List jobs in a batch

get_batch_jobs

Read-onlyIdempotent

Lists a batch's jobs in row order, one page at a time (page from 1, up to 20 jobs a page; a page past the end is empty), with each job's ID, template, current row (keyed and shaped as rows are written), status, render error, and whether it can still be edited. These job IDs and values are the input for update_batch and update_job, and error explains why a render failed. Download URLs are not included (get_batch_outputs has them), and get_batch is lighter for overall progress. Needs batches:read.

Input Schema

Name	Required	Description
`page`	No	Page number, starting at 1
`limit`	No	Results per page (default 10); values above 20 are capped at 20
`batchId`	Yes	Batch ID returned by create_batch or list_batches

Output Schema

Name	Required	Description
`page`	Yes
`items`	Yes
`limit`	Yes	Page size actually applied
`total`	Yes	Count of all matches across every page
`batchStatus`	Yes	draft until run_batch first succeeds; update_batch adds and removes jobs only in drafts

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 30, 2026

changedOutput schema / properties / items / items / properties / rowIndex / description

Previous value: -"The job's row in the batch, from 0, in the order rows were given"New value: +"The job's row in the batch, from 0, in the order rows were given. One row's jobs across pages or flows share it"

Changed1 schema field changedOct 30, 2026

addedOutput schema / properties / items / items / properties / flowId

Added value: +{
+  "anyOf": [
+    {
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The flow this job renders as a video, if any"
+}

Changed11 schema fields changedOct 30, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / batchId / pattern

Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"

addedInput schema / properties / limit / maximum
```
Added value: +9007199254740991
```
addedInput schema / properties / page / maximum
```
Added value: +9007199254740991
```

addedOutput schema / properties / items / items / properties / id / pattern

Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"

addedOutput schema / properties / items / items / properties / row / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / items / items / properties / rowIndex / maximum
```
Added value: +9007199254740991
```

changedOutput schema / properties / items / items / properties / templateId / anyOf

Previous value: -[
-  {
-    "format": "uuid",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "format": "uuid",
+    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / limit / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / page / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / total / maximum
```
Added value: +9007199254740991
```

First observedOct 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses pagination edge-case behavior ('a page past the end is empty'), the permission prerequisite ('Needs batches:read'), and what 'error' actually means. These are operational facts the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and payload, then alternatives, then the permission note — a sensible ordering. It is one dense multi-clause sentence, though every clause (pagination cap, empty page, error meaning, auth scope) carries information, so nothing is wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema covers return shape, annotations cover the safety profile, and the description still fills the remaining gaps: pagination limits, empty-page behavior, auth requirement, and where the returned IDs are consumed downstream. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so page/limit/batchId are already documented, but the description adds the non-obvious outcome of an out-of-range page and reinforces the 20-item cap for limit. Marginal added value over the schema rather than full compensation, so slightly above the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+ordering ('Lists a batch's jobs in row order') and enumerates the exact payload fields the caller receives. It is immediately distinguishable from get_batch (progress) and get_batch_outputs (download URLs), which it names explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives forward routing ('these job IDs and values are the input for update_batch and update_job') and two explicit exclusions with the sibling that covers each case: get_batch_outputs for download URLs, get_batch for lighter overall progress. No inference is required to choose among the three.

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

All Kalpana Batch tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?