Solution skill
Token-count preflight before every expensive Claude call
Complete solution
Count tokens before you send: the token counting endpoint takes the same inputs as message creation and returns the input total. Use it to pick models, enforce context budgets, and estimate cost. Know its blind spots (server tools, url and file sources) so you do not trust a number it cannot produce.
TL;DR: Count tokens before you send: the token counting endpoint takes the same inputs as message creation and returns the input total. Use it to pick models, enforce context budgets, and estimate cost. Never send a big request blind. Build the real request object first, then count it.
The fix
Never send a big request blind.
- Count with the same shape you will send. The token counting endpoint accepts the same structured inputs as message creation: system instructions, tools, images, PDFs. Build the real request object first, then count it. Counting a simplified version gives a number for a different request.
- Send images and PDFs as base64 for counting. The endpoint rejects image or document blocks with a url or file source, and it rejects server tools, the MCP connector, and most server-side tools with invalidrequesterror. For those inputs, read the usage object on the real response instead of pre-counting.
- Treat the count as an estimate. Actual input tokens on the real call can differ by a small amount. Add a safety margin (5 to 10 percent) between your count and the context window limit.
- Enforce a budget rule. Define max input tokens per call from the model's window minus your max_tokens output budget minus headroom for tool results and citations. Reject or chunk any request over the budget before it hits the API: a 400 for context overflow is a wasted call.
- Route on the count. Under the budget, pick the cheapest model that fits; near the top, step up to the larger-window model or chunk the input. Log the count with the request so cost anomalies trace back to specific inputs.
- Recount after prompt changes. Any edit to system instructions, few-shot examples, or tool schemas changes the count. Re-run the preflight in CI when prompts change, or your budgets silently drift.
When to use this
- This covers exactly what the title says: Token-count preflight before every expensive Claude call.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.
When not to use this
- You are doing a different workflow with Token-count; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.
Evidence
Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_l4fT3-DpM-ZJNP69FjtmnA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Token-count preflight before every expensive Claude call <span>— Vectle</span></a>