token-efficiency

Token Efficiency

Overview

Reduce token consumption by being intentional about what goes into context. Every token costs money and fills the context window. Smart context management can reduce costs by 30-50% without sacrificing quality.

Core principle: Only put in context what's needed for the current task. Everything else is noise.

When to Use

• Context is approaching the window limit
• You notice tool outputs are getting large
• Before dispatching subagents (don't send all context)
• When working on a long-running session (many turns)
• When the user mentions cost concerns
• Before and after context compaction

Techniques

1. Deferred Reading

Don't read files until you need them:

# ❌ Bad: read everything upfront
read_file("src/models/user.py")  # 200 lines
read_file("src/models/product.py")  # 300 lines
read_file("src/models/order.py")  # 250 lines
# → 750 lines in context before you even start

# ✅ Good: read only what you need now
# Start with just the file structure
search_files("*.py", target="files", path="src/models/")
# Read only the file you're about to modify
read_file("src/models/user.py")

2. Summarize Before Saving

Instead of saving raw tool output, summarize:

# ❌ Bad: save raw terminal output
# 200 lines of irrelevant log messages

# ✅ Good: save only the summary
# "Build completed: 45 passed, 0 failed, 3 warnings (all pre-existing)"

3. Use delegate_task for Heavy Lifting

Heavy operations burn token in a separate context, not the main session:

# ❌ Bad: do heavy search in main session
# browser_navigate → browser_snapshot → browser_scroll × 10
# → hundreds of lines of HTML in main context

# ✅ Good: delegate to subagent
delegate_task(goal="Search GitHub trending...", toolsets=['browser'])
# → only the summary enters main context

4. Progressive Disclosure for Skills

Skills should use progressive disclosure (load metadata first, full content only when needed):

# Skill name + 1-line description → Agent decides if relevant
# → Only then load full SKILL.md
# → Only then load reference files