A Practical Preflight Check for Claude Input Size

Long prompts rarely fail in a neat, predictable way, so this guide builds a small guardrail: estimate the input size before sending the real Claude request.

The preflight pattern

When an application starts with a single chat box, prompt size feels easy to reason about. Then the product grows. A system prompt is added. Tool definitions become longer. Conversation history accumulates. Users attach documents. Eventually, the text visible in the UI is only one part of the actual request.

A useful response is to add a preflight step immediately before generation:

1. Build the request you intend to send.
2. Estimate its input token count.
3. Compare that estimate with your own product threshold.
4. Continue, shorten, split, or reject the request.

This does not require a full agent framework. It is simply an HTTP check that gives the rest of your application a sizing signal.

Make the smallest useful request

The token-count route is:

POST https://api.acedata.cloud/v1/messages/count_tokens

The two required fields are model and messages. Each message contains a role and content. Authentication uses a bearer token in the Authorization header.

Here is a minimal request:

curl -X POST 'https://api.acedata.cloud/v1/messages/count_tokens' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

The response is intentionally small:

{"input_tokens": 11}

In application code, keep the wrapper equally small. Return input_tokens to the caller and let the surrounding workflow choose the policy. One product might warn users about unusually long input; another might summarize old conversation turns; a batch processor might split a document into smaller jobs.

Count more than the user message

The visible prompt is not necessarily the largest part of an AI request. The endpoint can also include these optional request components:

• system for the system prompt
• tools for tool definitions
• thinking for extended-thinking configuration
• tool_choice for tool-selection configuration
• cache_control at the top level or on content blocks

This matters most in tool-using applications. A weather question may be five words long, while the tool schema sent beside it contains names, descriptions, object properties, and required fields. Estimating only the user's sentence would give the wrong mental model of the request.

The practical approach is to pass the same system prompt and tool definitions to the count call that you plan to use for generation. That keeps your preflight close to the real payload instead of maintaining a second, simplified approximation in your own code.

Where to put the guardrail

There are three useful places for this check.

Before dynamic tool calls

If your application selects tools based on the current task, count after selection. This shows the size of the actual tool set rather than the size of every tool your product supports.

Before document workflows

Run the check after assembling the relevant messages and content blocks. It can help catch obviously large requests before they enter a slower workflow.

There is an important limitation: visual and document tokens for images and PDFs are not estimated precisely. Use the result as a rough signal, not as proof that a multimodal request will fit a particular boundary.

In request telemetry

Record the estimate next to non-sensitive operational metadata. Over time, the distribution can reveal whether request growth comes from conversation history, system instructions, or tool schemas. That evidence is more useful than guessing which prompt component needs trimming.

Treat the result as an estimate

The count endpoint calculates input size only; it does not generate a model response. Its current result comes from a local estimator rather than the official Anthropic tokenizer.

That distinction defines the right use cases. The value is suitable for rough sizing and application-level guardrails. It should not be used as a precise billing record, a definitive context-window decision, or a tokenizer comparison between Claude models. Tools, multimodal content, and model-specific tokenization can produce differences.

I tend to prefer guardrails like this because they are small enough to understand and easy to remove if the architecture changes. Start by logging the estimate, learn what normal requests look like, and only then add stricter behavior.

The exact request structure and supported options are listed in the Claude Messages Count Tokens API reference.