Tool Call Strategy
Concept of the skill
Tool-call strategy is the query planner for an agent's external actions. Treat every call as an expensive, stateful evidence-acquisition operation with three costs: latency, tokens, and context pollution.
Coverage
- The three costs of every tool call: token cost (schema overhead and result size), latency cost (round-trip and decision time), context pollution (results persist in attention window)
- The script-vs-call decision gate: deterministic bulk work belongs in a script; reasoning-dependent work belongs in individual tool calls with the agent in the loop
- Tool selection decision tree: file-search vs content-search vs targeted-read vs full-read, harness-native structured tools vs shell fallback, and the harness-agnostic capability map
- Batching independent calls in a single message vs sequential round-trips, and the dependency-detection heuristic
- Redundancy avoidance: the conversation-as-cache mental model, recognising re-reads, re-searches, and re-runs
- Context-efficient patterns: targeted line ranges, bounded verification output, dedicated-tool defaults, provenance notes, and tool-result lifecycle
- Subagent delegation for context protection: when exploration belongs in a disposable subagent context vs the main session
- The poka-yoke principle: design tool usage to prevent mistakes, not just optimise speed
- Cost benchmark heuristics: rough call-count ranges per task type and the "stop and reconsider" red flag
Philosophy of the skill
Every tool call has three simultaneous costs: tokens (schema overhead plus result), latency (network round-trip plus decision time), and context pollution (results persist in the attention window and degrade subsequent reasoning). Agents that issue 12 calls where 3 would suffice are not merely slower — they are measurably less accurate, because noise accumulated in the context window pushes useful signal further from the attention window.
The optimal strategy is not "minimise calls." Under-calling causes hallucination and skipped verification. The objective is information gained per unit cost: a single well-targeted grep that returns five matching lines is worth more than reading three entire files to find the same information. A script that processes fifty files in one shell call is worth more than fifty individual edit calls. The conversation history acts as a cache; information already retrieved does not need to be retrieved again.
A tool call is like a SQL query against a slow, expensive, noisy database — plan it before you run it, do not re-run queries whose results are already in the result set, and reach for set-based operations (scripts) when you catch yourself doing the same row-level work N times.
The Three Costs of Every Tool Call
| Cost |
Mechanism |
Magnitude |
| Token cost |
Tool schemas sent with every request (~500 tokens per declared tool). Each result adds to conversation. Ten available tools = ~5,000 tokens of overhead before any user input. |
Scales with number of available tools and result size |
| Latency cost |
Network round-trip, tool execution time, model decision time per call |
~200–2000 ms per call; compounds for sequential calls |
| Context pollution |
Every result stays in conversation history. Failed attempts, verbose outputs, and redundant reads all persist |
Degrades reasoning quality as context fills |
The compound effect: five unnecessary reads do not just cost five times the tokens — they push useful context further from the attention window, degrading the quality of subsequent reasoning. Context is not just a budget; it is a signal-to-noise ratio.
Source Notes
This skill treats vendor tool protocols as evidence for the strategy, not as its whole scope. OpenAI's function-calling guide frames tool calling as a multi-step conversation where the application supplies tools, executes requested calls, and returns outputs for the next model turn; it also notes that large tool surfaces consume context and can be narrowed with mechanisms such as tool search or allowed-tool subsets. Anthropic's tool-use docs describe the same model/runtime separation and document parallel tool use for independent work plus context-management patterns for keeping tool output from overwhelming the conversation. Those protocol facts support the portable strategy here: plan calls, keep independent work parallel, keep dependent work sequential, and shape tool outputs as first-class context.
Harness-Agnostic Tool Capability Map
Every modern coding-agent harness exposes the same five abstract tool capabilities under different concrete names. Substitute your harness's equivalents when applying this skill.
| Abstract capability |
Claude Code |
Cursor / Copilot / Continue |
OpenCode |
Shell-only fallback |
| File-pattern search (find files by name/path glob) |
Glob |
file_search |
glob |
rg --files, then find |
| Content search (find text inside files) |
Grep |
grep_search |
grep |
rg, then grep -r |
| Targeted read (read specific lines of a file) |
Read (with offset/limit) |
read_file (with line range) |
read |
sed -n 'A,Bp' |
| Diff-based edit (modify part of a file) |
Edit / MultiEdit |
replace_string_in_file / apply_patch |
edit |
sed -i (avoid) |
| Shell execution (run an arbitrary command) |
Bash |
run_in_terminal |
bash |
direct shell |
The principles in this skill apply uniformly across all of them. Examples below use the Cursor/Copilot names because they are the most descriptive; the same advice applies to whichever set of names your harness exposes.
The Script-vs-Call Decision Gate
The single most impactful optimisation: use scripts for deterministic work, tool calls for reasoning-dependent work.
Is the operation deterministic (known input → known output)?
YES → Can it be expressed as a shell command or script?
YES → Write a script, run once via a shell-execution tool
NO → Single tool call with structured output
NO → Does the operation require reasoning about intermediate results?
YES → Individual tool calls with the agent in the loop
NO → Batch into a script that returns structured data the agent can reason about
When scripts beat tool calls
| Scenario |
Tool-call approach |
Script approach |
Savings |
| Rename a variable across 20 files |
20 diff-based edit calls |
One project-owned script via shell execution |
19 fewer calls |
| Check which files import a module |
10 targeted-read calls |
One content-search call |
9 fewer calls |
| Run lint + typecheck + test |
3 sequential shell calls |
pnpm lint && pnpm typecheck && pnpm test |
2 fewer calls |
| Create 5 similar test files |
5 file-creation calls |
Script that generates all 5 |
4 fewer calls |
| Collect metrics from multiple sources |
N targeted-read calls |
Script that aggregates and returns JSON |
N−1 fewer calls |
When tool calls beat scripts
| Scenario |
Why a script fails |
| Edit depends on understanding the code around it |
The agent needs to read, reason, then decide what to change |
| Search result determines next action |
The search path cannot be predicted in advance |
| Error in one step changes the approach for the next |
Scripts cannot reason about failures mid-flight |
| Output needs human or agent review before proceeding |
Scripts execute blindly |
Tool Selection Decision Tree
Choose the right tool for the information need. Wrong tool choice is the largest single source of wasted calls.
Need to find files by name or path pattern?
→ file-pattern search; if shell is the available search surface, use `rg --files` before `find`
Need to find content inside files?
→ Need the matching lines themselves?
YES → content search with matching lines (returns content)
NO → Just need file paths? content search or file-pattern search
Need to read file contents?
→ Know which lines you need?
YES → targeted read with line range
NO → Need the whole file?
YES → full read (default)
NO → content search for the specific function or class first, then targeted read of the section
Need to modify a file?
→ Targeted change to existing content?
YES → diff-based edit (sends only the diff; fails if the old string does not match)
NO → Complete rewrite or new file?
YES → file-creation tool
NO → diff-based edit
Need to run a command?
→ Is there a structured harness tool for this? (read tool, content search, file-pattern search)
YES → use the structured tool
NO → shell execution
Critical rules
| Rule |
Why |
| Prefer structured read/search tools when the harness provides them |
They usually return line numbers, respect workspace permissions, and keep output easier to inspect |
In shell-first harnesses, prefer rg and rg --files before grep -r, find, or ls |
Ripgrep is faster, has better defaults for code search, and makes it easier to narrow output |
Use head, tail, or line-range reads to bound output, not as a blind substitute for targeted search |
Output shaping protects context; blind file dumping pollutes it |
Never default to inline sed or awk edits in shell |
Prefer diff-based edits for reviewable changes; reserve raw sed for cases where a script would be disproportionate |
| Content search before full read |
Content search returns only matching lines; full read returns the entire file |
| File-pattern search before content search |
If you know the file pattern, narrow the search space first |
Batching and Parallelization
Independent calls: batch in a single message
If two or more tool calls do not depend on each other's output, make them all in the same message.
Sequential (bad):
Message 1: read file A → wait for result
Message 2: read file B → wait for result
Message 3: search for pattern → wait for result
Total: 3 round-trips
Parallel (good):
Message 1: read file A + read file B + search for pattern
Total: 1 round-trip (wall-clock = max of individual calls)
Dependency detection
| Calls are independent when |
Calls are dependent when |
| Different files, no shared state |
Second call uses first call's output |
| Read-only operations |
First call creates or modifies what second reads |
| Verification checks (lint, type, test) |
Error in first determines whether to run second |
Batching heuristic
Before making a tool call, ask: "Is there another call I need to make that does not depend on this one's result?" If yes, batch them.
Avoiding Redundant Operations
The information-cache mental model
Treat the conversation context as a cache. Information already retrieved does not need to be retrieved again.
| Redundancy type |
Example |
Fix |
| Re-reading a file |
Read file A, make an edit, re-read file A to verify |
The edit tool confirms what changed; trust it |
| Re-searching for the same pattern |
Two identical content searches in one conversation |
Reference the earlier result |
| Reading a file just written |
Create file, then read it to confirm contents |
File creation confirms success; trust it |
| Running the same verification twice |
pnpm typecheck after edit, then again before commit |
Once is enough if no other changes were made |
| Exploring broadly then narrowly |
Search all files, then search the same pattern in a subdirectory |
Start narrow; widen only if needed |
The "Do I already know this?" check
Before every tool call, answer: "Is this information already in my context from a previous call?" If yes, reference it instead of re-fetching.
Context-Efficient Patterns
For file reading
| Need |
Efficient pattern |
Wasteful pattern |
| Find a specific function |
Content search for the function name, then targeted read of the 30-line section |
Full read of the entire 2000-line file |
| Check if a pattern exists |
Content search (returns match count) |
Full read of the entire file and search manually |
| Read multiple small sections |
Multiple targeted reads with explicit line ranges |
One full read that includes irrelevant code |
| Compare two files |
Targeted reads of both with relevant line ranges |
Full reads of both |
For file modification
| Need |
Efficient pattern |
Wasteful pattern |
| Change one line |
Diff-based edit with minimal old/new string |
Full file rewrite |
| Change N similar lines |
Diff-based edits batched in one message |
N separate sequential edit calls |
| Change across many files |
Project-owned script (Node, Python) — see note below |
N separate edit calls |
| Create a new file |
File-creation tool |
Diff-based edit (cannot edit what does not exist) |
Bulk-edit note: for "change across many files", prefer a project-owned script (Node, Python) that produces a reviewable diff rather than inline sed -i or awk in a shell call. Inline sed -i bypasses agent review and is hard to audit. Reserve raw sed for cases where a proper script would be disproportionate overhead.
For verification
| Need |
Efficient pattern |
Wasteful pattern |
| Check if tests pass |
pnpm test 2>&1 | tail -20 |
Full unbounded test output in context |
| Check if a server is running |
curl -sf URL > /dev/null && echo up || echo down |
Full curl output with headers and body |
| Check types |
pnpm typecheck 2>&1 | head -30 |
Unbounded typecheck output |
| Run multiple checks |
pnpm lint && pnpm typecheck && pnpm test (one call) |
Three separate shell calls |
For tool-result lifecycle
| Need |
Efficient pattern |
Wasteful pattern |
| Preserve evidence |
Summarise the result with file paths, line numbers, command names, and pass/fail status |
Keep a full raw transcript in the main context after the useful facts have been extracted |
| Retry after failure |
Change one variable before retrying and record what changed |
Re-run the identical failing call hoping for a different result |
| Continue after broad exploration |
Compact to the decision, evidence path, and open questions |
Carry every exploratory hit forward as if it were still active context |
| Hand off to a user or reviewer |
Report the smallest reproducible command and the decisive lines |
Paste unbounded logs with no interpretation |
Subagent Delegation for Context Protection
Subagents run in separate contexts. Use them to prevent context pollution from exploratory work.
When to use subagents
| Scenario |
Why subagent |
| Exploring an unfamiliar part of the codebase |
Exploration reads many files; main context stays clean |
| Running a broad search that may return many results |
Results stay in subagent context; only the summary returns |
| Reviewing code (writer/reviewer pattern) |
Reviewer has fresh context without implementation bias |
| Parallel independent investigations |
Each runs in its own context without cross-contamination |
When NOT to use subagents
| Scenario |
Why direct |
| Single targeted read or content search |
Subagent overhead exceeds the call itself |
| Work that requires multiple back-and-forth decisions |
Subagent cannot ask clarifying questions mid-task |
| Simple file edits |
Direct is faster |
Subagent context-efficiency rule
Brief subagents with the minimum context they need. Include: what to find, where to look, what format to report back in. Do not include: full conversation history, unrelated background, or "figure out what I need."
The Poka-Yoke Principle
Design tool usage to prevent mistakes, not just optimise speed. Poka-yoke (Japanese: "mistake-proofing") is the lean-manufacturing principle of designing the work so the wrong action is hard or impossible.
| Poka-yoke |
Why it prevents errors |
| Use absolute file paths |
Relative paths break when working directory changes |
| Prefer diff-based edit over full-file rewrite for existing files |
Diff-based edit fails if the old string does not match; full rewrite silently overwrites |
| Run a content search before a full read |
Confirms the file exists and contains the pattern before reading the full content |
| Run verification after edits, not before |
Pre-edit verification is wasted if the edit changes the result |
Pipe long outputs through tail or head |
Prevents context overflow from verbose commands |
Cost Benchmark Heuristics
Rough guideline ranges for different task types. These are heuristic targets, not empirically calibrated thresholds — actual counts vary by task complexity, codebase familiarity, and how much context is already in the session. Treat them as "should I stop and reconsider?" thresholds, not hard limits.
| Task type |
Guideline range |
Typical tools |
| Simple bug fix (1 file) |
3–5 calls |
Content search, targeted read, diff-based edit, verify |
| Feature addition (2–3 files) |
5–10 calls |
Read existing patterns, write new code, verify |
| Refactor (many files) |
3–8 calls |
Content search to find all sites, script to batch-edit, verify |
| Investigation / exploration |
5–15 calls |
Multiple content searches and targeted reads |
| Complex multi-file feature |
10–20 calls |
Plan, read patterns, implement, verify |
Red flag: if a task is taking more than 20 tool calls, stop and ask: "Am I using the right approach?" Consider scripting, subagent delegation, or a different strategy. The fact that 20 calls feels like a lot is itself a useful signal — listen to it.
Verification
After applying this skill, verify:
Do NOT Use When
| Use instead |
When |
prompt-craft |
The fix is in the wording of one instruction (clarity, format, few-shot examples), not how the surrounding tool calls are sequenced |
context-engineering |
The question is about the entire information stack (system prompt, memory, rules, skills) reaching the model, not per-call efficiency |
debugging |
A tool is returning errors at runtime — that is a bug, not an efficiency problem |
refactor |
The deliverable is a behaviour-preserving code transformation; the tool-call efficiency of getting there is a means, not the end |
skill-router |
Deciding which skill should activate for a query, not which tool call the activated skill should make next |
documentation |
Writing prose for a human reader explaining how the agent's tool usage works |
Skill Graph context
Classification
- Subject:
ai-engineering
- Public:
true
- Domain:
ai-engineering/tool-use
- Scope: Teaches efficient tool-use protocol design for agents: cost accounting across tokens, latency, and context pollution; script-vs-call decisions; search/read selection; batching and parallelization; redundancy avoidance; output-shaping; and delegation when exploration would overflow the main context. Portable across CLI, MCP, and harness-driven agents. Excludes prompt wording, broader context-stack architecture, runtime failure debugging, and behavior-preserving refactor mechanics.
When to use
- the agent made 17 read_file calls when 3 greps would have done — what should it have done?
- we're renaming a variable across 40 files — script or tool calls?
- the agent re-reads the same file three times in one task — fix the policy
- should I batch these reads into one message or wait for each result?
- design a tool-use protocol for our new agent harness — what rules matter?
- the context window is filling with verbose terminal output — how do I cut it?
- is it worth delegating this exploratory search to a subagent?
- what's a reasonable tool-call budget for a single-file bug fix?
Not for
- improve this prompt's wording to get better outputs
- design what skills get loaded for which prompts
- the test suite is failing after my change — find the cause
- extract this repeated string-concat into a helper function
- scaffold a new SKILL.md for our team's tool-use rules
- review this AI-generated PR for correctness
Related skills
- Verify with:
code-review, pattern-recognition, problem-locating-solving
- Related:
context-engineering, refactor, debugging, prompt-craft, autonomous-loop-patterns
Concept
- Mental model: Tool-call strategy is the query planner for an agent's external actions. Treat every call as an expensive, stateful evidence-acquisition operation with three costs: latency, tokens, and context pollution. The goal is sufficient evidence with minimum noise: pick the narrowest tool that can answer the question, batch independent calls, keep dependent calls sequential, use scripts for deterministic bulk work, preserve reviewability for edits, and stop re-fetching facts already present in the conversation.
- Purpose: This skill prevents agents from wasting time and context with redundant reads, serial searches, unbounded terminal output, or hand-driven N+1 edits while also preventing the opposite failure of under-calling and hallucinating. It gives a portable decision framework for choosing tools, scripts, batching, subagents, and output-shaping patterns.
- Boundary: This skill decides when, how many, and which external operations an already-running agent should use. It does not describe the protocol mechanics of tool-call messages, the whole context stack around the agent, prompt wording, runtime failure debugging, or the correctness mechanics of a refactor deliverable.
- Analogy: Tool-call strategy is like planning queries against a slow, expensive database: ask the smallest question that returns the needed evidence, combine independent queries when possible, avoid repeating a query whose result is already in hand, and use set-based operations for bulk deterministic work.
- Common misconception: The common mistake is treating efficiency as fewer calls at all costs. Good strategy is not tool abstinence; it is evidence discipline. A necessary verification call is cheap compared with a hallucinated answer, while an unbounded log dump or a repeated file read can make every later decision worse.
Grounding
- Mode:
hybrid
- Truth sources:
https://developers.openai.com/api/docs/guides/function-calling, https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview, https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context, https://github.com/jacob-balslev/skills/blob/main/skills/tool-call-flow/SKILL.md, https://github.com/jacob-balslev/skills/blob/main/skills/context-engineering/SKILL.md
Keywords
tool call optimization, reduce tool calls, too many tool calls, script vs tool call, batching tool calls, parallel tool calls, parallelize calls, independent calls, redundant reads, re-reading file
1---2name: tool-call-strategy3description: Use when an agent is making too many tool calls, when context is filling from verbose tool outputs, when the same operation could be a script instead of N individual calls, or when designing a tool-use protocol for a new agent or harness. Covers the three costs of every call (token, latency, context pollution), the script-vs-call decision gate, tool-selection decision trees (file-search vs content-search vs targeted-read vs full-read), call batching and parallelization, redundancy avoidance, the poka-yoke principle, subagent delegation for context protection, and cost-benchmark heuristics by task type. Do NOT use for prompt wording (use `prompt-craft`), broader context stack design across the five layers (use `context-engineering`), runtime tool failures or production debugging (use `debugging`), or behaviour-preserving refactor mechanics (use `refactor`). Do NOT use for improve this prompt's wording to get better outputs. Do NOT use for design what skills get loaded for which prompts.4license: MIT5---6# Tool Call Strategy78## Concept of the skill910Tool-call strategy is the query planner for an agent's external actions. Treat every call as an expensive, stateful evidence-acquisition operation with three costs: latency, tokens, and context pollution.1112## Coverage1314- The three costs of every tool call: token cost (schema overhead and result size), latency cost (round-trip and decision time), context pollution (results persist in attention window)15- The script-vs-call decision gate: deterministic bulk work belongs in a script; reasoning-dependent work belongs in individual tool calls with the agent in the loop16- Tool selection decision tree: file-search vs content-search vs targeted-read vs full-read, harness-native structured tools vs shell fallback, and the harness-agnostic capability map17- Batching independent calls in a single message vs sequential round-trips, and the dependency-detection heuristic18- Redundancy avoidance: the conversation-as-cache mental model, recognising re-reads, re-searches, and re-runs19- Context-efficient patterns: targeted line ranges, bounded verification output, dedicated-tool defaults, provenance notes, and tool-result lifecycle20- Subagent delegation for context protection: when exploration belongs in a disposable subagent context vs the main session21- The poka-yoke principle: design tool usage to prevent mistakes, not just optimise speed22- Cost benchmark heuristics: rough call-count ranges per task type and the "stop and reconsider" red flag2324## Philosophy of the skill25Every tool call has three simultaneous costs: tokens (schema overhead plus result), latency (network round-trip plus decision time), and context pollution (results persist in the attention window and degrade subsequent reasoning). Agents that issue 12 calls where 3 would suffice are not merely slower — they are measurably less accurate, because noise accumulated in the context window pushes useful signal further from the attention window.2627The optimal strategy is not "minimise calls." Under-calling causes hallucination and skipped verification. The objective is **information gained per unit cost**: a single well-targeted grep that returns five matching lines is worth more than reading three entire files to find the same information. A script that processes fifty files in one shell call is worth more than fifty individual edit calls. The conversation history acts as a cache; information already retrieved does not need to be retrieved again.2829> A tool call is like a SQL query against a slow, expensive, noisy database — plan it before you run it, do not re-run queries whose results are already in the result set, and reach for set-based operations (scripts) when you catch yourself doing the same row-level work N times.3031## The Three Costs of Every Tool Call3233| Cost | Mechanism | Magnitude |34|---|---|---|35| **Token cost** | Tool schemas sent with every request (~500 tokens per declared tool). Each result adds to conversation. Ten available tools = ~5,000 tokens of overhead before any user input. | Scales with number of available tools and result size |36| **Latency cost** | Network round-trip, tool execution time, model decision time per call | ~200–2000 ms per call; compounds for sequential calls |37| **Context pollution** | Every result stays in conversation history. Failed attempts, verbose outputs, and redundant reads all persist | Degrades reasoning quality as context fills |3839**The compound effect:** five unnecessary reads do not just cost five times the tokens — they push useful context further from the attention window, degrading the quality of subsequent reasoning. Context is not just a budget; it is a signal-to-noise ratio.4041## Source Notes4243This skill treats vendor tool protocols as evidence for the strategy, not as its whole scope. OpenAI's function-calling guide frames tool calling as a multi-step conversation where the application supplies tools, executes requested calls, and returns outputs for the next model turn; it also notes that large tool surfaces consume context and can be narrowed with mechanisms such as tool search or allowed-tool subsets. Anthropic's tool-use docs describe the same model/runtime separation and document parallel tool use for independent work plus context-management patterns for keeping tool output from overwhelming the conversation. Those protocol facts support the portable strategy here: plan calls, keep independent work parallel, keep dependent work sequential, and shape tool outputs as first-class context.4445## Harness-Agnostic Tool Capability Map4647Every modern coding-agent harness exposes the same five abstract tool capabilities under different concrete names. Substitute your harness's equivalents when applying this skill.4849| Abstract capability | Claude Code | Cursor / Copilot / Continue | OpenCode | Shell-only fallback |50|---|---|---|---|---|51| File-pattern search (find files by name/path glob) | `Glob` | `file_search` | `glob` | `rg --files`, then `find` |52| Content search (find text inside files) | `Grep` | `grep_search` | `grep` | `rg`, then `grep -r` |53| Targeted read (read specific lines of a file) | `Read` (with `offset`/`limit`) | `read_file` (with line range) | `read` | `sed -n 'A,Bp'` |54| Diff-based edit (modify part of a file) | `Edit` / `MultiEdit` | `replace_string_in_file` / `apply_patch` | `edit` | `sed -i` (avoid) |55| Shell execution (run an arbitrary command) | `Bash` | `run_in_terminal` | `bash` | direct shell |5657The principles in this skill apply uniformly across all of them. Examples below use the Cursor/Copilot names because they are the most descriptive; the same advice applies to whichever set of names your harness exposes.5859## The Script-vs-Call Decision Gate6061The single most impactful optimisation: use scripts for deterministic work, tool calls for reasoning-dependent work.6263```64Is the operation deterministic (known input → known output)?65 YES → Can it be expressed as a shell command or script?66 YES → Write a script, run once via a shell-execution tool67 NO → Single tool call with structured output68 NO → Does the operation require reasoning about intermediate results?69 YES → Individual tool calls with the agent in the loop70 NO → Batch into a script that returns structured data the agent can reason about71```7273### When scripts beat tool calls7475| Scenario | Tool-call approach | Script approach | Savings |76|---|---|---|---|77| Rename a variable across 20 files | 20 diff-based edit calls | One project-owned script via shell execution | 19 fewer calls |78| Check which files import a module | 10 targeted-read calls | One content-search call | 9 fewer calls |79| Run lint + typecheck + test | 3 sequential shell calls | `pnpm lint && pnpm typecheck && pnpm test` | 2 fewer calls |80| Create 5 similar test files | 5 file-creation calls | Script that generates all 5 | 4 fewer calls |81| Collect metrics from multiple sources | N targeted-read calls | Script that aggregates and returns JSON | N−1 fewer calls |8283### When tool calls beat scripts8485| Scenario | Why a script fails |86|---|---|87| Edit depends on understanding the code around it | The agent needs to read, reason, then decide what to change |88| Search result determines next action | The search path cannot be predicted in advance |89| Error in one step changes the approach for the next | Scripts cannot reason about failures mid-flight |90| Output needs human or agent review before proceeding | Scripts execute blindly |9192## Tool Selection Decision Tree9394Choose the right tool for the information need. Wrong tool choice is the largest single source of wasted calls.9596```97Need to find files by name or path pattern?98 → file-pattern search; if shell is the available search surface, use `rg --files` before `find`99100Need to find content inside files?101 → Need the matching lines themselves?102 YES → content search with matching lines (returns content)103 NO → Just need file paths? content search or file-pattern search104105Need to read file contents?106 → Know which lines you need?107 YES → targeted read with line range108 NO → Need the whole file?109 YES → full read (default)110 NO → content search for the specific function or class first, then targeted read of the section111112Need to modify a file?113 → Targeted change to existing content?114 YES → diff-based edit (sends only the diff; fails if the old string does not match)115 NO → Complete rewrite or new file?116 YES → file-creation tool117 NO → diff-based edit118119Need to run a command?120 → Is there a structured harness tool for this? (read tool, content search, file-pattern search)121 YES → use the structured tool122 NO → shell execution123```124125### Critical rules126127| Rule | Why |128|---|---|129| Prefer structured read/search tools when the harness provides them | They usually return line numbers, respect workspace permissions, and keep output easier to inspect |130| In shell-first harnesses, prefer `rg` and `rg --files` before `grep -r`, `find`, or `ls` | Ripgrep is faster, has better defaults for code search, and makes it easier to narrow output |131| Use `head`, `tail`, or line-range reads to bound output, not as a blind substitute for targeted search | Output shaping protects context; blind file dumping pollutes it |132| Never default to inline `sed` or `awk` edits in shell | Prefer diff-based edits for reviewable changes; reserve raw `sed` for cases where a script would be disproportionate |133| Content search before full read | Content search returns only matching lines; full read returns the entire file |134| File-pattern search before content search | If you know the file pattern, narrow the search space first |135136## Batching and Parallelization137138### Independent calls: batch in a single message139140If two or more tool calls do not depend on each other's output, make them all in the same message.141142**Sequential (bad):**143```144Message 1: read file A → wait for result145Message 2: read file B → wait for result146Message 3: search for pattern → wait for result147Total: 3 round-trips148```149150**Parallel (good):**151```152Message 1: read file A + read file B + search for pattern153Total: 1 round-trip (wall-clock = max of individual calls)154```155156### Dependency detection157158| Calls are independent when | Calls are dependent when |159|---|---|160| Different files, no shared state | Second call uses first call's output |161| Read-only operations | First call creates or modifies what second reads |162| Verification checks (lint, type, test) | Error in first determines whether to run second |163164### Batching heuristic165166Before making a tool call, ask: *"Is there another call I need to make that does not depend on this one's result?"* If yes, batch them.167168## Avoiding Redundant Operations169170### The information-cache mental model171172Treat the conversation context as a cache. Information already retrieved does not need to be retrieved again.173174| Redundancy type | Example | Fix |175|---|---|---|176| Re-reading a file | Read file A, make an edit, re-read file A to verify | The edit tool confirms what changed; trust it |177| Re-searching for the same pattern | Two identical content searches in one conversation | Reference the earlier result |178| Reading a file just written | Create file, then read it to confirm contents | File creation confirms success; trust it |179| Running the same verification twice | `pnpm typecheck` after edit, then again before commit | Once is enough if no other changes were made |180| Exploring broadly then narrowly | Search all files, then search the same pattern in a subdirectory | Start narrow; widen only if needed |181182### The "Do I already know this?" check183184Before every tool call, answer: *"Is this information already in my context from a previous call?"* If yes, reference it instead of re-fetching.185186## Context-Efficient Patterns187188### For file reading189190| Need | Efficient pattern | Wasteful pattern |191|---|---|---|192| Find a specific function | Content search for the function name, then targeted read of the 30-line section | Full read of the entire 2000-line file |193| Check if a pattern exists | Content search (returns match count) | Full read of the entire file and search manually |194| Read multiple small sections | Multiple targeted reads with explicit line ranges | One full read that includes irrelevant code |195| Compare two files | Targeted reads of both with relevant line ranges | Full reads of both |196197### For file modification198199| Need | Efficient pattern | Wasteful pattern |200|---|---|---|201| Change one line | Diff-based edit with minimal old/new string | Full file rewrite |202| Change N similar lines | Diff-based edits batched in one message | N separate sequential edit calls |203| Change across many files | Project-owned script (Node, Python) — see note below | N separate edit calls |204| Create a new file | File-creation tool | Diff-based edit (cannot edit what does not exist) |205206> **Bulk-edit note:** for "change across many files", prefer a project-owned script (Node, Python) that produces a reviewable diff rather than inline `sed -i` or `awk` in a shell call. Inline `sed -i` bypasses agent review and is hard to audit. Reserve raw `sed` for cases where a proper script would be disproportionate overhead.207208### For verification209210| Need | Efficient pattern | Wasteful pattern |211|---|---|---|212| Check if tests pass | `pnpm test 2>&1 \| tail -20` | Full unbounded test output in context |213| Check if a server is running | `curl -sf URL > /dev/null && echo up \|\| echo down` | Full curl output with headers and body |214| Check types | `pnpm typecheck 2>&1 \| head -30` | Unbounded typecheck output |215| Run multiple checks | `pnpm lint && pnpm typecheck && pnpm test` (one call) | Three separate shell calls |216217### For tool-result lifecycle218219| Need | Efficient pattern | Wasteful pattern |220|---|---|---|221| Preserve evidence | Summarise the result with file paths, line numbers, command names, and pass/fail status | Keep a full raw transcript in the main context after the useful facts have been extracted |222| Retry after failure | Change one variable before retrying and record what changed | Re-run the identical failing call hoping for a different result |223| Continue after broad exploration | Compact to the decision, evidence path, and open questions | Carry every exploratory hit forward as if it were still active context |224| Hand off to a user or reviewer | Report the smallest reproducible command and the decisive lines | Paste unbounded logs with no interpretation |225226## Subagent Delegation for Context Protection227228Subagents run in separate contexts. Use them to prevent context pollution from exploratory work.229230### When to use subagents231232| Scenario | Why subagent |233|---|---|234| Exploring an unfamiliar part of the codebase | Exploration reads many files; main context stays clean |235| Running a broad search that may return many results | Results stay in subagent context; only the summary returns |236| Reviewing code (writer/reviewer pattern) | Reviewer has fresh context without implementation bias |237| Parallel independent investigations | Each runs in its own context without cross-contamination |238239### When NOT to use subagents240241| Scenario | Why direct |242|---|---|243| Single targeted read or content search | Subagent overhead exceeds the call itself |244| Work that requires multiple back-and-forth decisions | Subagent cannot ask clarifying questions mid-task |245| Simple file edits | Direct is faster |246247### Subagent context-efficiency rule248249Brief subagents with the minimum context they need. Include: what to find, where to look, what format to report back in. Do not include: full conversation history, unrelated background, or "figure out what I need."250251## The Poka-Yoke Principle252253Design tool usage to prevent mistakes, not just optimise speed. *Poka-yoke* (Japanese: "mistake-proofing") is the lean-manufacturing principle of designing the work so the wrong action is hard or impossible.254255| Poka-yoke | Why it prevents errors |256|---|---|257| Use absolute file paths | Relative paths break when working directory changes |258| Prefer diff-based edit over full-file rewrite for existing files | Diff-based edit fails if the old string does not match; full rewrite silently overwrites |259| Run a content search before a full read | Confirms the file exists and contains the pattern before reading the full content |260| Run verification *after* edits, not before | Pre-edit verification is wasted if the edit changes the result |261| Pipe long outputs through `tail` or `head` | Prevents context overflow from verbose commands |262263## Cost Benchmark Heuristics264265Rough guideline ranges for different task types. These are heuristic targets, not empirically calibrated thresholds — actual counts vary by task complexity, codebase familiarity, and how much context is already in the session. Treat them as "should I stop and reconsider?" thresholds, not hard limits.266267| Task type | Guideline range | Typical tools |268|---|---|---|269| Simple bug fix (1 file) | 3–5 calls | Content search, targeted read, diff-based edit, verify |270| Feature addition (2–3 files) | 5–10 calls | Read existing patterns, write new code, verify |271| Refactor (many files) | 3–8 calls | Content search to find all sites, script to batch-edit, verify |272| Investigation / exploration | 5–15 calls | Multiple content searches and targeted reads |273| Complex multi-file feature | 10–20 calls | Plan, read patterns, implement, verify |274275**Red flag:** if a task is taking more than 20 tool calls, stop and ask: *"Am I using the right approach?"* Consider scripting, subagent delegation, or a different strategy. The fact that 20 calls feels like a lot is itself a useful signal — listen to it.276277## Verification278279After applying this skill, verify:280281- [ ] Content search ran before targeted read when looking for specific content282- [ ] Independent tool calls were batched in the same message283- [ ] Scripts replaced N+1 individual calls for deterministic bulk operations284- [ ] No re-reads or re-searches for information already in context285- [ ] Targeted reads with explicit line ranges were used for large files286- [ ] Verbose command outputs were piped through `head` or `tail`287- [ ] Tool results were summarised into durable evidence and raw verbose output was not carried forward unnecessarily288- [ ] Shell fallback used fast, narrow search/read commands when structured harness tools were unavailable289- [ ] Total tool calls fall within the benchmark range for this task type, or there is a documented reason they exceed it290- [ ] Subagents were used for context-heavy exploration, not for trivial single calls291292## Do NOT Use When293294| Use instead | When |295|---|---|296| `prompt-craft` | The fix is in the wording of one instruction (clarity, format, few-shot examples), not how the surrounding tool calls are sequenced |297| `context-engineering` | The question is about the entire information stack (system prompt, memory, rules, skills) reaching the model, not per-call efficiency |298| `debugging` | A tool is returning errors at runtime — that is a bug, not an efficiency problem |299| `refactor` | The deliverable is a behaviour-preserving code transformation; the tool-call efficiency of getting there is a means, not the end |300| `skill-router` | Deciding which *skill* should activate for a query, not which *tool call* the activated skill should make next |301| `documentation` | Writing prose for a human reader explaining how the agent's tool usage works |302303## Skill Graph context304305<!-- skill-graph-context:start (generated — do not edit by hand) -->306307**Classification**308- Subject: `ai-engineering`309- Public: `true`310- Domain: `ai-engineering/tool-use`311- Scope: Teaches efficient tool-use protocol design for agents: cost accounting across tokens, latency, and context pollution; script-vs-call decisions; search/read selection; batching and parallelization; redundancy avoidance; output-shaping; and delegation when exploration would overflow the main context. Portable across CLI, MCP, and harness-driven agents. Excludes prompt wording, broader context-stack architecture, runtime failure debugging, and behavior-preserving refactor mechanics.312313**When to use**314- the agent made 17 read_file calls when 3 greps would have done — what should it have done?315- we're renaming a variable across 40 files — script or tool calls?316- the agent re-reads the same file three times in one task — fix the policy317- should I batch these reads into one message or wait for each result?318- design a tool-use protocol for our new agent harness — what rules matter?319- the context window is filling with verbose terminal output — how do I cut it?320- is it worth delegating this exploratory search to a subagent?321- what's a reasonable tool-call budget for a single-file bug fix?322323**Not for**324- improve this prompt's wording to get better outputs325- design what skills get loaded for which prompts326- the test suite is failing after my change — find the cause327- extract this repeated string-concat into a helper function328- scaffold a new SKILL.md for our team's tool-use rules329- review this AI-generated PR for correctness330331**Related skills**332- Verify with: `code-review`, `pattern-recognition`, `problem-locating-solving`333- Related: `context-engineering`, `refactor`, `debugging`, `prompt-craft`, `autonomous-loop-patterns`334335**Concept**336- Mental model: Tool-call strategy is the query planner for an agent's external actions. Treat every call as an expensive, stateful evidence-acquisition operation with three costs: latency, tokens, and context pollution. The goal is sufficient evidence with minimum noise: pick the narrowest tool that can answer the question, batch independent calls, keep dependent calls sequential, use scripts for deterministic bulk work, preserve reviewability for edits, and stop re-fetching facts already present in the conversation.337- Purpose: This skill prevents agents from wasting time and context with redundant reads, serial searches, unbounded terminal output, or hand-driven N+1 edits while also preventing the opposite failure of under-calling and hallucinating. It gives a portable decision framework for choosing tools, scripts, batching, subagents, and output-shaping patterns.338- Boundary: This skill decides when, how many, and which external operations an already-running agent should use. It does not describe the protocol mechanics of tool-call messages, the whole context stack around the agent, prompt wording, runtime failure debugging, or the correctness mechanics of a refactor deliverable.339- Analogy: Tool-call strategy is like planning queries against a slow, expensive database: ask the smallest question that returns the needed evidence, combine independent queries when possible, avoid repeating a query whose result is already in hand, and use set-based operations for bulk deterministic work.340- Common misconception: The common mistake is treating efficiency as fewer calls at all costs. Good strategy is not tool abstinence; it is evidence discipline. A necessary verification call is cheap compared with a hallucinated answer, while an unbounded log dump or a repeated file read can make every later decision worse.341342**Grounding**343- Mode: `hybrid`344- Truth sources: `https://developers.openai.com/api/docs/guides/function-calling`, `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview`, `https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context`, `https://github.com/jacob-balslev/skills/blob/main/skills/tool-call-flow/SKILL.md`, `https://github.com/jacob-balslev/skills/blob/main/skills/context-engineering/SKILL.md`345346**Keywords**347- `tool call optimization`, `reduce tool calls`, `too many tool calls`, `script vs tool call`, `batching tool calls`, `parallel tool calls`, `parallelize calls`, `independent calls`, `redundant reads`, `re-reading file`348349<!-- skill-graph-context:end -->
jacob-balslev