Tool call strategy

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:

• Content search ran before targeted read when looking for specific content
• Independent tool calls were batched in the same message
• Scripts replaced N+1 individual calls for deterministic bulk operations
• No re-reads or re-searches for information already in context
• Targeted reads with explicit line ranges were used for large files
• Verbose command outputs were piped through head or tail
• Tool results were summarised into durable evidence and raw verbose output was not carried forward unnecessarily
• Shell fallback used fast, narrow search/read commands when structured harness tools were unavailable
• Total tool calls fall within the benchmark range for this task type, or there is a documented reason they exceed it
• Subagents were used for context-heavy exploration, not for trivial single calls

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