Tokenomics & Token Economics for LLMs & AI Agents
Spend fewer tokens without making your AI tools worse.
TOKENOMICS & TOKEN ECONOMICS · PRACTICAL LLM & AI AGENT PLAYBOOK LLM & Agent Tokenomics (Token Economics)
Spend fewer tokens,
LLM & Agent Tokenomics (Token Economics)
Spend fewer tokens,
without making your AI tools worse.
Practical tokenomics (token economics) for developers using GitHub Copilot in VS Code (Track A) and engineers who build or operate LLM agents (Track B). Cut lookup tokens and accelerate coding tasks with the cctx VS Code Marketplace extension, and profile agent LLM calls with tokprof without changing agent code.
MEASURE THEN IMPROVE TRACK A & TRACK B
T
Reported in TokenEconomizer 18.4–30.9% lower mean cost on SWE-Bench across 5 agent–model pairs (as reported).
Reported ZERO-CODE LLM TOKEN PROFILER · TOKPROF
Run tokprof start to measure token usage and inspect the HTML report
tokprof captures supported LLM requests via a local gateway, in-process hooks, or Linux eBPF depending on your environment (when eBPF is unavailable, run eval "$(tokprof env)" so new processes route through the gateway). The terminal session and HTML report preview below are a synthetic example based on examples/sample-requests.jsonl (7 calls).
01 / INSTALL (PyPI) Linux · macOS · Win
pip install tokprof Installs the prebuilt native binary from PyPI with no Rust or Go toolchain required (or use uv tool install tokprof / uvx tokprof). 02 / START SESSION Background / CLI
tokprof start Starts a background session (auto-attaches eBPF on supported Linux hosts), or run a single command with tokprof -- python app.py. 03 / CHECK STATUS Live Count
tokprof status Run the agent task you want to measure, then check the active session and recorded LLM call count. 04 / STOP & REPORT CLI + HTML + CSV
tokprof stop Stops the session, prints the terminal breakdown, and writes the HTML report (.tokprof/latest.html). $ tokprof start
tokprof: session started (pid 48210, gateway 127.0.0.1:41932, eBPF: all processes & Docker containers, max 3m/180s)
recording to: /workspace/.tokprof/20261106-synthetic.jsonl
Running host processes, background services, and Docker containers are captured automatically.
Check progress: tokprof status | Live view: tokprof report --watch | Finish & report: tokprof stop
# Run the agent task you want to profile.
$ tokprof status
tokprof: active session pid 48210, gateway 127.0.0.1:41932, eBPF: all processes & Docker containers
requests seen: 7, LLM calls recorded: 7, errors: 0
$ tokprof stop
tokprof: session stopped (recorded 7 call(s) in /workspace/.tokprof/20261106-synthetic.jsonl)
╭──────────────────────────────────────────────────────────────────────────────────────────╮
│ tokprof — LLM Token Profile (Per-Session · Per-Turn · Prompt Inspector) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
Sessions: 1 Turns: 3 Calls: 7 Input: 73,000 Output: 1,580 Cached: 47,700 (65.3%)
First-call overhead: 9,200 tok Median input/call: 9,600 tok Fan-out: median 2, max 4 calls/turn
1. Input token breakdown (total)
────────────────────────────────────────────────────────────────────────────────────────────
System prompt 44,800 61.4% ████████████████░░░░░░░░░░
Tools: definitions 16,800 23.0% ██████░░░░░░░░░░░░░░░░░░░░
Tools: results 4,620 6.3% █▋░░░░░░░░░░░░░░░░░░░░░░░░
History: user turns 2,670 3.7% █░░░░░░░░░░░░░░░░░░░░░░░░░
Current user prompt 1,870 2.6% ▋░░░░░░░░░░░░░░░░░░░░░░░░░
History: assistant turns 1,400 1.9% ▌░░░░░░░░░░░░░░░░░░░░░░░░░
Unattributed (template/hidden) 840 1.2% ▎░░░░░░░░░░░░░░░░░░░░░░░░░
3. Per-Turn breakdown & prompt summary (System / History / User Prompt / Tools & Schema)
────────────────────────────────────────────────────────────────────────────────────────────
turn calls system history user_prompt tools/schema total_in cached output
S1·T1 4 25,600 2,230 930 9,960 39,200 28,400 680
User prompt: Fix the failing discount boundary test in checkout.py
Assistant: {"tool":"read_file","path":"src/checkout.py"}
S1·T2 1 6,400 1,440 540 6,600 15,100 10,300 420
User prompt: Patch >= 100 boundary and verify with .venv/bin/pytest -q
Assistant: Patched boundary check (`>= 100`) and verified with `.venv/bin/pytest -q` (14 passed).
S1·T3 2 12,800 400 400 4,860 18,700 9,000 480
User prompt: Run test suite for currency rounding module
Assistant: All 8 rounding tests passed in 0.09s.
Findings & recommendations
────────────────────────────────────────────────────────────────────────────────────────────
[HIGH] 2 tool definition(s) were sent but never called (14,000 tokens, 19.2% of input): browser_open, notebook_edit
[HIGH] Tool call 'run_tests' was repeated 3 times in a row (28,800 input tokens): add a loop guard
[MEDIUM] Unfiltered read_file tool output (4,200 tokens) pushed Turn 2 input to 15,100 tokens
tokprof: HTML dashboard written to .tokprof/latest.html
tokprof: Report server live at http://127.0.0.1:18765/latest.html http://127.0.0.1:18765/latest.html (.tokprof/latest.html — Edition Dossier)
T
tokprof
Edition Report · LLM Token Composition & Prompt Inspector Example
SYNTHETIC REPORT EXAMPLE
Sessions: 1 · Turns: 3 · Calls: 7 · Total Input: 73,000 tok · Cached: 47,700 (65.3%) · Output: 1,580 tok
01 / SESSIONS & TURNS 1 / 3 7 total LLM calls
02 / INPUT TOKENS 73,000 median 9,600 / call
03 / CACHED INPUT 47,700 65.3% cache hit rate
04 / OUTPUT TOKENS 1,580 generated by model
05 / FIXED OVERHEAD 9,200 first call input
06 / FAN-OUT 2 median calls/turn (max 4)
1. Input Token Breakdown (Total)
| Component | Tokens | Share | Distribution |
|---|---|---|---|
| System prompt | 44,800 | 61.4% | |
| Tools: definitions | 16,800 | 23.0% | |
| Tools: results | 4,620 | 6.3% | |
| History: user turns | 2,670 | 3.7% | |
| Current user prompt | 1,870 | 2.6% | |
| History: assistant turns | 1,400 | 1.9% |
Detected Token Waste & Next Steps
HIGH
2 tool definitions (browser_open, notebook_edit) were sent on every call but never used — 14,000 tokens (19.2% of total input).
Stage 2: Isolate unused tools → HIGH
Tool call 'run_tests' repeated 3 times in a row with the same error (pytest: command not found), consuming 28,800 input tokens.
Stage 4: Add a loop guard → MEDIUM
Reading the full file in Turn 1 added 4,200 tool-result tokens and pushed Turn 2 input to 15,100 tokens.
Stage 4: Trim tool output → EDITION LINEAGE / TOKEN FLOW CANVAS
Token flow example Baseline → Turn Progression → Individual Calls
ORIGIN / 01
8,800 tok System (6,400) + Tools (2,400) First call: 9,200 tok
TURNS / 02
39,200 tok Hist 2,230 · User 930 · Tools 9,960 4 calls · Cached 28,400
15,100 tok Hist 1,440 · Tool Result 4,200 1 call · Cached 10,300
EXECUTION / 03
9,200 tok m-large · Cold prefix (0 cached) Cached 0 · Out 310
15,100 tok m-large · +4,200 read_file result Cached 10,300 · Out 420
03 / TURN LINEAGE & PROMPT INSPECTOR
3. Per-Turn Token Usage & Captured Prompts / Tool Schemas
| Turn | Calls | System | History | User | Tools | Input | Cached | Out |
|---|---|---|---|---|---|---|---|---|
| s1 · Turn 1 | 4 | 25,600 (65%) | 2,230 (6%) | 930 (2%) | 9,960 (25%) | 39,200 | 28,400 72% | 680 |
| s1 · Turn 2 | 1 | 6,400 (42%) | 1,440 (10%) | 540 (4%) | 6,600 (44%) | 15,100 | 10,300 68% | 420 |
| s1 · Turn 3 | 2 | 12,800 (68%) | 400 (2%) | 400 (2%) | 4,860 (26%) | 18,700 | 9,000 48% | 480 |
SYSTEM PROMPT (CALL #1) 6,400 tok
[system#agent-rules] # Coding Agent System Prompt 1. Inspect target files before editing. 2. Run focused tests to verify every fix.
TOOLS & SCHEMA (4 DEFINED) 2,400 tok
[read_file: 220 tok] [run_tests: 180 tok] [notebook_edit: 900 tok — UNUSED] [browser_open: 1,100 tok — UNUSED]
USER PROMPT & OUTPUT (T2) 540 + 420 tok
User: Patch >= 100 boundary and verify with .venv/bin/pytest -q Assistant: Patched boundary check (>= 100); 14 passed.
TWO TRACKS FOR DEVELOPERS & AGENT ENGINEERS
Choose your track: everyday VS Code Copilot or LLM agent engineering
Each guide walks through the problem, what to change, how to verify the effect, and the trade-offs.
TRACK A · VS CODE GITHUB COPILOT
Track A — Copilot Tokenomics
For developers using GitHub Copilot in VS Code. Understand AI Credits and premium-request multipliers, inspect Agent Debug Logs, and trim context, instruction files, and MCP tool definitions.
- 01. How Usage Is Charged→
- 02. Measure Usage→
- 03. Context Hygiene→
- 04. Instructions & Tools→
- 05. Models, Planning & Delegation→
- 06. Prompt & Output Style→
- 07. Language & Tokenization→
- 08. Agent Modes & Budget→
- 09. MCP Server Audit→
- 10. One-Page Checklist→
- 11. cctx: Token Saver & Accelerator (VS Code)→
TRACK B · LLM AGENT TROUBLESHOOTING
Track B — Agent Tokenomics
For engineers who build or operate LLM agents. Understand how requests are billed and cached, diagnose current token usage, confirm the cause of waste, apply one fix at a time, and verify both cost and quality.
TRACK B · 6-STAGE TROUBLESHOOTING
Read TokenEconomizer Case Study → From core concepts to diagnosis, proof, improvement, and verification
STAGE 00 Concepts Understand stateless re-sending, prompt caching, context windows, and tool costs. STAGE 01 Diagnose Measure system prompt, history, tool tokens, and fixed overhead with tokprof. STAGE 02 Isolate Examine unused tools, repeated errors, and large tool outputs one variable at a time. STAGE 03 Prove Run a fixed task set repeatedly to quantify token waste and confidence intervals. STAGE 04 Improve Apply one targeted change at a time: micro-skills, tool pruning, or loop guards. STAGE 05 Result Re-measure cost, task success rate, and latency to decide whether to keep or revert.
CORE PRINCIPLES & REFERENCES
Principles
01 / MEASURE FIRST
1. Measure first.
Measure current usage from your own sessions before changing anything.
02 / QUALITY GUARDRAIL
2. Quality is a guardrail.
Fewer tokens only count when task success rate and output quality hold.
03 / SINGLE VARIABLE
3. One change at a time.
Change one variable per experiment so you know which action worked.
04 / CITE OR MEASURE
4. Cite or measure.
Link every number to a primary source or a reproducible log and script.
DEFINITION & FOUR PILLARS · AI TOKENOMICS & TOKEN ECONOMICS
What Is Tokenomics (Token Economics) in AI, LLMs, and Coding Agents?
In AI engineering, tokenomics (also called AI token economics) is the discipline of measuring, pricing, budgeting, and optimizing the tokens a language model reads and generates (input, cached input, output, and reasoning tokens) so teams reduce cost and latency per completed task without sacrificing quality. It is distinct from cryptocurrency/Web3 tokenomics, which studies digital asset supply.
PILLAR 01 / TOKEN UTILITY & ROI
1. Cost per completed task
Optimize for total tokens spent per successful outcome — not raw price per token — verified against a Golden Dataset & Rubric.
PILLAR 02 / PROMPT CACHING PREFIX
2. Prefix stability & caching
Keep system instructions and tool schemas stable at the start of every request to maximize prompt cache hit rates and cut prefill latency.
PILLAR 03 / CONTEXT & TOOL TAX
3. Context & tool schema hygiene
Prune unused MCP tool schemas, clamp code lookups with cctx, and compact rules with BPE-aligned formula prompts.
PILLAR 04 / AGENT LOOP & PROFILING
4. Agent loop fan-out & profiling
Because agent loops re-send history on every step (n × prefix + Σ history), profile calls with tokprof and bound failure loops.
FREQUENTLY ASKED QUESTIONS · KEY FACTS
Frequently Asked Questions
What is tokenomics (token economics) in LLMs and AI agents?
In AI and large language models, tokenomics (token economics) is the engineering discipline of measuring, pricing, budgeting, and optimizing input, cached, output, and reasoning tokens across model calls and multi-turn agent loops without degrading answer quality. agent-tokenomics organizes this into two tracks: Track A (VS Code Copilot Tokenomics with cctx) and Track B (6-stage Agent Tokenomics with tokprof).
How do I install and run tokprof to profile LLM agent tokens?
Install prebuilt native wheels from PyPI with pip install tokprof or uv tool install tokprof (or run directly via uvx tokprof). Run tokprof start, execute your agent workload, and run tokprof stop to get a terminal breakdown and an interactive HTML Edition Dossier (.tokprof/latest.html) attributing input tokens to system prompt, history, user prompt, and tool schemas/results.
What are the highest-impact ways to save tokens and speed up coding in VS Code GitHub Copilot?
Start a new chat per task (or use /fork for side questions) so stale history is not re-sent on every turn, disable unused MCP servers and tool definitions, and scope attachments with #file and #selection. In addition, install Code Context (cctx) from the VS Code Marketplace to replace multi-turn grep + view loops with single-call block-clamped lookups (15.20× faster warm retrieval and 24.7% faster task completion, as reported) and track live AIC/USD savings in the status bar and cctx usage.
How do you troubleshoot high token cost in a custom LLM agent?
Follow a 6-stage engineering procedure: 0. Concepts → 1. Diagnose (measure baseline with tokprof) → 2. Isolate (one variable at a time) → 3. Prove (fixed task set) → 4. Improve (micro-skills, tool pruning, loop guards, prompt caching) → 5. Result & 6. Golden Dataset Rubric.