Batch your tool calls

Batching means running independent tool calls together in a single step instead of one at a time.

When PromptConduit flags this

PromptConduit computes a batching score: total tool calls divided by tool steps. Each PostToolUse, PostToolBatch, or PostToolUseFailure hook event counts as one step, which is one round-trip to the model. A PostToolBatch fires after a full batch of parallel tool calls resolves, so a step that read four files at once contributes four calls and one step.

The “Batch related tool calls” note (severity: info) fires in the editor extension when:

• the batching score is above 0 and below 1.4 calls per step, and
• the session has at least 60 tool calls, and
• the session has at least 3 prompts.

A score of 1.0 means every call ran on its own. The web Trends view reports the batching score as a metric but does not raise this note.

Why it matters

Every step is a model request. When the agent reads file A, waits, reads file B, waits, then reads file C, that is three requests, each resending the conversation so far and each producing its own output tokens to decide the next call. Reading A, B, and C in one step is one request.

The cost is mostly wall-clock time and repeated overhead, not the reads themselves. With prompt caching, the repeated context is billed at the cached rate, but it is still billed, and every step still waits on a full model turn. Long serial chains also make sessions feel slow and push you toward interrupting.

A low score with high volume usually means one of these:

• Prompts that hand the agent one thing at a time (“now read B”).
• Exploration that could have been one search but ran as many small reads.
• Edits split into many tiny changes to the same file.

What to do

Ask for related work together. Name everything that’s needed in one prompt:

Read src/auth/refresh.ts, src/auth/session.ts, and their tests, then explain
how a token refresh flows through them.

The agent can request all four reads in one response. Compare with sending four prompts that each name one file.

Say that the work is independent. If the order doesn’t matter, say so: “these checks are independent; run them in parallel.” Agents batch more readily when nothing suggests the calls depend on each other.

Search before reading. One search across the codebase, followed by reading only the hits, beats opening candidate files one by one. For typed languages, Claude Code’s code intelligence plugins give precise go-to-definition and find-references, which Anthropic notes can replace a grep followed by reading several files.

Prefer fewer, larger edits. When several changes in one file belong to the same change, ask for them as one edit rather than a series of one-line edits.

Delegate breadth. When a task fans out into independent branches, hand each branch to a subagent in a single message. Several subagent calls launched together count as one batched step, and the reading inside each one stays out of your main context.

Don’t force it. Calls that depend on each other, such as “run the migration, then check the schema”, should stay sequential. The goal is to stop serializing work that was never dependent.

How to check it worked

In the editor extension’s coaching tab, the Batching cell under “How you drove the agent” shows the live session’s score as calls per step (for example 1.8×). It reads as good at 1.6 or higher and as a warning below 1.2 once the session has 30 or more tool calls. The note stops firing once the score reaches 1.4.

Watch the total too. Batching should cut the number of steps without raising the number of calls. If tool volume keeps climbing, look at tool success rate: repeated failures inflate call counts. To see what the session cost, run promptconduit cost. Extension setup is in /docs/editor-extension.