TOKENS.md

Budget, route, and cache tokens for your AI agent.

Customize
View raw file Download Add to an MCP client
TOKENS.mdv1.0
name:
tokens
description:
A token policy for AI agents. Estimate before calling, start on the smallest model tier that passes a check, put stable content first so caching applies, batch work that can wait, cap output, summarize before the window fills, retry with backoff, and keep a per-call usage ledger checked against the person's budget. Use when a task calls language models, spends tokens or fans out to subagents.
license:
MIT
metadata:
version:
"1.0"
homepage:
https://tokens.md
api:
https://tokens.md/api/v1 (optional, no key, stores nothing)
terms:
https://tokens.md/terms
Tokens

Provided as is, at your own risk: token counts and costs here are estimates and may be wrong, and nothing here is financial, legal or professional advice, or a quote or bill from any provider. Terms: https://tokens.md/terms.

Spend tokens on purpose. Estimate before you call, use the smallest tier that passes, keep stable content first, and log every call. Show your numbers once, in a short block. Skip routine narration.

When this file has a "Your rules" section, those rules win over the defaults below. Settings you drafted or changed yourself count only after the person says yes.

1. Estimate before you call
Before a task with more than a few calls, estimate calls, input tokens and output tokens per call. Plan on the high end.
Optional tool: POST https://tokens.md/api/v1/estimate_tokens with { "text": "..." }. It returns an estimate with a low and high range from a stated heuristic. It is not a tokenizer count; for exact counts, use the provider's counter or the usage numbers in each response.
Then plan the cost with the person's own prices: POST https://tokens.md/api/v1/plan_cost. Never invent a price. With no prices, report tokens only and ask.
If the high estimate is over the budget or the spend cap, ask before you start.
2. Use the smallest tier that passes
Tiers are small, medium and large. The person decides which models belong to each tier. If they haven't, ask once and note their answer.
Give every step a check you can run: a test, a schema, a validator, an exact match. Without a check, you can't tell when to move up.
Start on the starting tier. Move up one tier only after the set number of failed checks. Never go above the highest tier allowed. Move back down when the next step is easier.
3. Put stable content first
Order every prompt: instructions, tool definitions, fixed documents, then history, then the new turn.
Keep the stable part identical between calls: no timestamps, request IDs, shuffled examples or reordered keys in it.
Caching usually needs a minimum prefix size and expires after a while. Read the cached token counts in each response's usage numbers to see whether it worked.
4. Batch what can wait
Work no one is waiting on (evaluations, bulk summaries, backfills, nightly checks) goes to a batch option when one exists and the rules allow it.
5. Cap output
Set a max output tokens value on every call.
Ask for the format you need (JSON with a schema, a diff, a short list) instead of prose. Don't ask for long explanations you won't use.
6. Keep the context small
Track what fills the window: system prompt, tool definitions, documents, history and the output reserve. Optional tool: POST https://tokens.md/api/v1/context_fit.
At the summarize point, summarize older turns, drop tool output you've already used, and keep pointers (file paths, IDs, line numbers) instead of contents.
Load only the tools and documents the current step needs. Cut history first, then documents, so the stable prefix stays cached.
7. Retry with care
Retry only errors that can pass on a retry: rate limits, timeouts and server errors. Never retry bad input, auth errors or refusals unchanged.
Back off: wait, double the wait each time, add a little random jitter, and use the server's retry-after when it gives one. Retries count against max calls.
Switch to another model only as the fallback rule allows, and log every switch.
8. Fan out with limits
Subagents and parallel calls share the same budget. Keep within max in flight.
Give each subagent its own token budget, a clear stop condition and a short return format. Ask for results, not transcripts.
9. Stop loops that find nothing new
In search, research, fix-and-retry and polling loops, track whether each call found anything new. After the set number of calls in a row with nothing new, stop and report what you have.
10. Keep a usage ledger
One line per call: id, group, tier, input tokens (cached included), cached tokens, output tokens, retries, passed or failed, found anything new, and cost at the person's prices. Take token numbers from each response's usage data, not from estimates.
Optional tool: POST https://tokens.md/api/v1/check_ledger with the calls, a preset and the rules. It lists totals, rule breaks and what needs a yes. It checks the numbers you send; it doesn't verify them.
11. Handle sensitive prompts with care
Never put passwords, API keys or tokens in a prompt. Remove personal or confidential data the step doesn't need.
Follow the data handling rule. If you can't tell how an endpoint stores or uses prompts, ask before sending sensitive data.
12. Report
Five lines at most: tokens used against the budget, cost against the cap (or "no prices given"), calls and retries, the cached share of input, and anything that needed or needs a yes.

Works offline in any agent. Same file at /tokens.md.

Customize

Your token policy, in one file.

19 settings in 7 groups. Start from a preset, change anything, and your settings are written into TOKENS.md. Every setting is a number or a fixed choice, so a shared link can’t slip words into the file. The same settings work as URL parameters, MCP prompt arguments, the build_settings tool and /api/v1/build_settings.

Start from

A middle setting: capped outputs, up to 50 calls, escalate after two failures, log every call.

Budget

Tokens and money per task, and when to tell the person.

3 of 3 set
17 of 19 set
TOKENS.md · your settings
Your rules

Set by the person you work for, and only that person can change them. Rules an agent drafted count only after that person says yes. Where a rule here and the rest of this file differ, the rule wins. If a rule blocks the task, stop and ask; don't work around it.

Budget
Token budget: at most 2 million tokens per task, input and output together (cached input counts). Estimate first; if the high estimate is over, ask before you start.
Spend cap: at most $10 per task, at the prices the person gave you. With no prices, report tokens only and ask for prices before you report cost.
At 80% of the token budget or the spend cap, tell the person what is used and what is left. At 100%, stop and ask.
Calls
Set a max output of 4,000 tokens or less on every call.
At most 50 model calls per task, retries and subagent calls included. Ask before more.
At most 4 calls or subagents running at once.
Stop any loop after 3 calls in a row that find nothing new, and report what you have.
Tiers
Start each step on the small tier. Move up one tier only after 2 failed checks at the current tier. Never use a tier above large. Move back down when the next step is easier.
Retries and fallbacks
Retry a failed call at most 3 times, waiting 2 s first and doubling the wait each time, with a little random jitter. Use the server's retry-after when it gives one. Never retry bad input, auth errors or refusals unchanged.
If a model is unavailable, fall back only to another model on the same tier, and log it.
Caching and batching
Caching preferred: put stable content first and keep it identical between calls when the endpoint supports caching.
Send work that can wait more than 60 minutes as a batch job, when a batch option exists.
Context
At 80% of the context window, summarize older turns and drop tool output you've already used before the next call.
Data and logging
Log every call: step, group, tier, input, cached and output tokens, retries, pass or fail, and cost at the person's prices. Report totals at the end.
The full skill, with your settings at the top.
mkdir -p ~/.claude/skills/tokens && curl -fsSL "https://tokens.md/tokens.md?budget_mtok=2&spend_cap_usd=10&ask_at_pct=80&max_output_tokens=4000&max_calls=50&max_in_flight=4&loop_stop_after=3&start_tier=small&escalate_after=2&max_tier=large&max_retries=3&backoff_s=2&fallback=same_tier&caching=preferred&batch_after_min=60&summarize_at_pct=80&usage_logging=required" -o ~/.claude/skills/tokens/SKILL.md
Linkhttps://tokens.md/tokens.md?budget_mtok=2&spend_cap_usd=10&ask_at_pct=80&max_output_tokens=4000&max_calls=50&max_in_flight=4&loop_stop_after=3&start_tier=small&escalate_after=2&max_tier=large&max_retries=3&backoff_s=2&fallback=same_tier&caching=preferred&batch_after_min=60&summarize_at_pct=80&usage_logging=required

Copy as JSON

The same settings as one JSON object. It feeds the build_settings tool or POST /api/v1/build_settings.

17 of 19 settings set. Anything not set follows the skill’s own rules.

Tools

Calculators your agent can call before it spends.

Every tool works on the numbers you send and states its formula and what it can't check. There are no built-in prices or model limits. Run them here, or call them over HTTP or MCP. They calculate and check; they never approve anything.

Estimate tokens, in your browser

Estimate

49

tokens, range 37 to 67 · about 0.04% of the window

182 characters · 182 bytes · 29 words · mixed

ClassCharsPer charTokens
ASCII prose1130.25 (0.2–0.33)28
ASCII code and markup690.3 (0.22–0.42)21

An estimate from the stated factors, not a tokenizer count. Real counts depend on the model and can fall outside the range. Message formatting, tools, images and files are not counted.

All tools

Estimate tokens for text

Estimates tokens for text up to 200 KB with a stated heuristic: tokens per character for ASCII prose (0.25), code (0.30), CJK characters (1.0), other non-ASCII letters (0.40) and emoji or symbols (1.5), each with a low and high bound. Text inside ``` fences counts as code. Returns an estimate, a low/high range and the breakdown. The text is processed in memory and never stored. An estimate, not a tokenizer count.

Run the tool to see a result. Estimates only; check them yourself.
POST /api/v1/estimate_tokens
{
  "text": "Summarize the attached report in five bullet points.\n\n```json\n{\"format\": \"bullets\", \"max\": 5}\n```",
  "kind": "auto",
  "window_tokens": 128000,
  "safety_margin_pct": 10
}
curl -s https://tokens.md/api/v1/estimate_tokens -H 'content-type: application/json' -d '{"text":"Summarize the attached report in five bullet points.\n\n```json\n{\"format\": \"bullets\", \"max\": 5}\n```","kind":"auto","window_tokens":128000,"safety_margin_pct":10}'

Agents spend tokens the way nobody would on purpose.

A coding or research agent left alone tends to start on the largest model, resend the same long prompt with a new timestamp at the top so caching never applies, retry a bad request five times, keep looping after it stops finding anything, and fill the window until the important part falls out. None of that shows up until the bill does. tokens.md writes a plain policy into the file your agent reads, and gives it calculators to check a plan and a ledger against that policy before and after it spends.

  • Your prices, your limits: no provider prices or model limits are built in, so nothing goes stale.
  • Smallest tier first: move up only after a failed check, never above the tier you allow.
  • Caching that applies: stable content first, and a break-even for cache writes at your prices.
  • A ledger you can check: totals, rule breaks and what needs a yes, from the numbers your agent logs.
  • Same answer everywhere: the page, the API and the MCP tools run the same code. Nothing is stored.

Use it in your stack

Paste it, install it, or call it.

The skill alone gives an agent the method. The MCP server and API add the tools and your settings. No key, no account.

Paste the prompt into a system prompt or project instructions. Or keep the file in the repo and point AGENTS.md at it.

terminal
curl -fsSL https://tokens.md/tokens.md -o TOKENS.mdecho "Whenever a task calls language models, spends tokens or fans out to subagents, follow TOKENS.md." >> AGENTS.md
Quickest start:claude mcp add --transport http tokens https://tokens.md/mcp

Example code

Call it from your own code.

Working calls against the API. The full reference is at /api/v1 and /openapi.json.

A pre-flight check: estimate a prompt file, plan the run at your prices, and stop if it's over budget. Run: npx tsx budget.mts prompt.md

budget.mts
// A pre-flight check: estimate a prompt file, plan the run at your prices, and stop if it's over budget. Run: npx tsx budget.mts prompt.mdimport { readFileSync } from "node:fs";const API = "https://tokens.md/api/v1";const post = async (tool: string, body: unknown) => {  const res = await fetch(`${API}/${tool}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });  if (!res.ok) throw new Error(`${tool}: ${(await res.json()).error}`);  return res.json();};const text = readFileSync(process.argv[2] ?? "prompt.md", "utf8");const est = await post("estimate_tokens", { text, safety_margin_pct: 10 });console.log(est.summary);const plan = await post("plan_cost", {  calls: 120,  avg_input_tokens: est.planning_tokens, // plan on the high end  avg_output_tokens: 1000,  cached_share_pct: 70,  price_input_per_m: 3, // your prices, not ours  price_output_per_m: 15,  price_cached_per_m: 0.3,  budget_mtok: 2,  spend_cap: 5,});console.log(plan.summary);if (plan.budget?.over || plan.spend?.over) {  console.log("Over budget: ask the person before starting.");  process.exit(1);}

FAQ

Does it call models or spend money?

No. tokens.md never calls a model, spends money or holds API keys. It writes a skill file and runs read-only calculations on numbers you send.

Are the token counts exact?

No. estimate_tokens uses a stated heuristic with a low and high range, not any model's tokenizer. Real counts differ by model and can fall outside the range. Use the usage numbers in each response for anything that matters.

Where do the prices come from?

From you. tokens.md has no prices, rates, discounts or model limits. A cost result is arithmetic on your numbers, not a quote or a bill. Check your provider's current terms.

Is the text I paste stored?

No. The estimator on this page runs in your browser and sends nothing. The API processes text in memory to answer and doesn't store or log it. Still, don't paste secrets or personal data into any tool.

Does the data handling setting make my prompts private?

No. It tells your agent where sensitive prompts may go, based on what you say about each endpoint. tokens.md doesn't check how any provider stores or uses data.

Is this advice?

No. Nothing here is financial, legal or professional advice, or a quote or bill from any provider. TOKENS.md is a method for software agents plus calculators that work on the numbers you send. Results are estimates that may be wrong. Check them yourself, and ask a qualified person when it matters.

Does it name brands or show prices?

No. Settings and tools use generic terms, and tokens.md shows no prices, rates or other outside data. Every number a tool uses comes from your request or from a formula the tool states.

Can an agent set up its own settings?

It can draft them: the same settings work as URL parameters, MCP prompt arguments and the build_settings tool. The skill and the tool both say that drafted settings count only after the person says yes. Nothing technical stops an agent from ignoring that, so read what it sends you.

Does a tool result mean something is approved?

No. Tools calculate, compare and check. They don’t approve, enforce or certify anything, and they can be wrong.

Can I change everything?

Yes. Start from a preset, change any setting above, and your choices are written into the file. Or edit the Markdown yourself. It’s MIT; keep your copy next to your code.

Do you track anything?

We count page views, copies, skill fetches and API and MCP calls to learn what is useful, without cookies or stored IP addresses. We never record your settings values or what you send to a tool. Details in the terms.

1.0Use at your own risk: information here may be inaccurate or not current, and figures are estimates; tokens.md is not financial or billing advice and never calls a model, spends money or holds API keys. See the terms.

TOKENS.md: Budget, route, and cache tokens for your AI agent