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

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.

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

When tool calls beat scripts

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

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

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.

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

For file modification

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

For tool-result lifecycle

Subagent Delegation for Context Protection

Subagents run in separate contexts. Use them to prevent context pollution from exploratory work.

When to use subagents

When NOT to use subagents

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.

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.

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

Skill Graph context

<!-- skill-graph-context:start (generated — do not edit by hand) -->

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

<!-- skill-graph-context:end -->