# TOKENS.md

> A token policy for AI agents: a skill file with your budget and rules, plus calculators to estimate, plan and check token use. Version 1.0. MIT.

A provider-neutral token policy for AI agents. One skill file with your budget, tiers, caching, retry and data rules written in, plus calculators an agent can call before it spends: estimate tokens, plan cost at your own prices, check context fit, and check a usage ledger against your rules. 19 settings in 7 groups, numbers or fixed choices only. Presets: core, lean, balanced, research, sensitive. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.

Use at your own risk. tokens.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is financial, legal or professional advice, or a quote or bill from any provider. tokens.md never calls a model, spends money or holds API keys. Check everything yourself before you act on it.

## Skill

- [TOKENS.md](https://tokens.md/tokens.md): load into your agent's instructions or save as ~/.claude/skills/tokens/SKILL.md (sha256 43ede633060ad537075809a7552742e07b9113d8dd456e4eb98633e910b3f92b)
- [TOKENS.md with settings](https://tokens.md/tokens.md?preset=lean): a preset plus any settings; each setting overrides the preset

## API (no key, CORS open, nothing stored)

- [estimate_tokens](https://tokens.md/api/v1/estimate_tokens?text=Summarize+the+attached+report+in+five+bullet+points.%0A%0A%60%60%60json%0A%7B%22format%22%3A+%22bullets%22%2C+%22max%22%3A+5%7D%0A%60%60%60&kind=auto&window_tokens=128000): 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.
- [plan_cost](https://tokens.md/api/v1/plan_cost?calls=200&avg_input_tokens=12000&avg_output_tokens=800&cached_share_pct=75&price_input_per_m=3&price_output_per_m=15&price_cached_per_m=0.3&price_cache_write_per_m=3.75&cache_writes=4&batch_share_pct=50&batch_discount_pct=50&retry_rate_pct=5&budget_mtok=3&spend_cap=10): Plan token use and cost. Plans a task's tokens and cost from your own numbers: calls, average input and output tokens, the share of input that is a stable cached prefix, a retry rate, and your prices per million input, output, cached-read and cache-write tokens. Returns totals, cost without savings, with caching, with batching (your discount) and with both, the cache break-even, and a comparison with your token budget and spend cap. It has no prices of its own; arithmetic only.
- [context_fit](https://tokens.md/api/v1/context_fit?window_tokens=200000&system_tokens=3000&tools_tokens=6000&documents_tokens=60000&history_tokens=85000&output_reserve_tokens=8000&summarize_at_pct=80&turn_tokens=4000): Check what fits in a context window. Adds up a call's parts (system prompt, tool definitions, documents, history) plus an output reserve against a window size you give. Returns whether it fits, the headroom, the summarize point, turns left before it, and how much to cut from history first, then documents. Your numbers or estimates only; no model limits are built in.
- [check_ledger](https://tokens.md/api/v1/check_ledger): Check a usage ledger against your rules. Checks a list of calls (tokens in and out, cached tokens, tier, retries, group, pass or fail, whether it found anything new, optional cost and timing) against your token rules: the same settings as the skill, from a preset and a rules object. Returns totals, totals by tier and group, rule breaks, warnings and what needs the person's yes. It checks the numbers you send; it doesn't verify them or approve anything.
- [build_settings](https://tokens.md/api/v1/build_settings?preset=lean): Write your settings into the skill. Turns a preset and settings into the sections written at the top of TOKENS.md. Every setting is a number or a fixed choice; the catalog is at https://tokens.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.
- [Settings catalog](https://tokens.md/api/v1/settings): every setting with its unit, range, options and default, plus the presets
- [API index](https://tokens.md/api/v1) and [OpenAPI](https://tokens.md/openapi.json)

## MCP

- https://tokens.md/mcp: Streamable HTTP, stateless, no auth. Tools: estimate_tokens, plan_cost, context_fit, check_ledger, build_settings. Prompt: tokens, with an optional preset and any setting. Resources: the skill and the settings catalog.

Feedback: POST https://tokens.md/feedback with {"message": "..."} (GET it for the fields). Delivered to the site owner's feedback inbox; messages aren't stored (only short-lived, hashed counters that enforce limits).

## Terms

- [Terms of use and disclaimer](https://tokens.md/terms)

## Optional

- [Full text](https://tokens.md/llms-full.txt): the skill plus the tool and settings reference
- [Manifest](https://tokens.md/.well-known/tokens.json)