tool-economy

Minimize tool call overhead. Every tool call costs tokens and latency. This skill teaches agents to batch independent calls, avoid redundant reads, cache results within a session, prefer single powerful commands over multiple weak ones, and track a 'tool budget'.

Every tool call is an expense. Spend wisely.

Tool Economy is a discipline for AI agents: treat each tool invocation as a costed operation (tokens + latency) and minimize total overhead while preserving correctness. The goal is not to avoid tool use — it is to make every call count.

When to Use

Activate this skill whenever you are:

• About to issue multiple tool calls in a single turn
• Reading files or data you may have already read this session
• Considering whether to call a tool at all
• Planning a multi-step workflow where calls can be parallelized
• Reviewing your own agent behavior for efficiency

Core Principles

1. Batch Independent Calls

If two or more tool calls do not depend on each other's output, issue them in the same turn (parallel). Do not serialize calls that could run concurrently.

Bad (3 serial round-trips, 3x latency):

text

read_file(A)  -> wait
read_file(B)  -> wait
read_file(C)  -> wait

Good (1 round-trip, 1x latency):

text

[ read_file(A), read_file(B), read_file(C) ]   # one turn

See references/batching.md.

2. Avoid Redundant Reads

If you already read a file this session and it has not changed, do not read it again. Track what you have seen. Prefer session_search or in-context memory over a fresh fetch. If a file was modified by your own action, you already know its new state — patch in place, don't re-read.

3. Cache Within Session

Treat the current session as a short-lived cache. The first expensive query (search, web fetch, build) populates it; subsequent identical needs reuse it. This does not mean stale data — invalidate when the underlying source changes (e.g. you edited the file you previously read).

4. Prefer One Powerful Command Over Many Weak Ones

• read_file over a chain of cat, head, tail
• search_files (content mode) over manual grep + find + wc
• A single patch over sed + awk + redirect
• One web_extract with 5 URLs over 5 separate fetches
• gh repo clone over manually git init + git remote add + git pull

Each "weak" command adds a full round-trip of tokens + latency for a sub-result you could have gotten in one call.

5. Track a Tool Budget

Before a multi-step task, estimate how many calls it should take, and compare against reality during and after. The companion script scripts/analyze_session.py computes:

• Total calls and redundant calls (duplicates within a window)
• Serializable-but-parallel calls (independent calls you issued serially)
• Estimated overhead: extra round-trips × per-call latency cost
• A tool economy score from 0 (worst) to 100 (best)

Run it on any session log to see where you leaked budget.

Quick Reference

Situation	Anti-pattern	Economy pattern
Need N independent reads	N serial calls	1 batched turn
Re-reading a static file	Fresh read_file	Reuse what's in context
Searching then counting	grep + find + wc	search_files(output_mode='count')
Editing 3 spots in a file	3 terminal sed calls	1 patch (or replace_all)
Fetching 5 pages	5 web_extract calls	1 call, urls=[...]
Unsure if data changed	Re-read "just in case"	Check mtime/hash, else reuse cache

How to Apply (Checklist)

Before issuing a turn's tool calls, ask:

1. Can these be batched? If none depend on another's output → yes, combine.
2. Have I read this before? If yes and unchanged → reuse, don't re-fetch.
3. Is there a single stronger command? Replace a chain with one call.
4. Is this call necessary at all? Can the answer be derived from context?
5. Am I within budget? If calls >> estimate, stop and replan.

Files

• references/batching.md — deep dive on parallelizing tool calls
• references/budgeting.md — how to estimate and track a tool budget
• references/antipatterns.md — catalog of wasteful patterns and fixes
• scripts/analyze_session.py — analyze a session log, report efficiency metrics
• scripts/sample_session.json — example input for the analyzer

License

MIT © Denis Voronin