Deterministic Token Counting

What it does

count_tokens_approximately is LangChain’s approximate token counter used for prompting, cost estimation, and context management. The bug fix in langchain-core 1.5.1 (PR #39020) corrects how tool_call_schema is cached when counting tokens for BaseTool objects. Before the fix, BaseTool token counts could be inaccurate or recomputed on every call due to a stale or missing cache lookup. After it, the cache is used correctly, making counts consistent and faster for tools in AgentExecutor or ToolCallingAgent chains.

Why it matters

If your tool-augmented agent shows fluctuating token counts, or seems to blow past context windows on simple calls, this fix targets exactly that. Tools defined via BaseTool or @tool now cache their schema properly so token counting is deterministic and efficient. It matters most when you have many tools in one agent, run agents in production tracking per-call cost, or debug context-length issues in complex multi-tool chains.

Example

$ @tool
def get_weather(city: str) -> str:
    """Get the current weather for a given city."""
    return f"The weather in {city} is sunny."

tokens_1 = count_tokens_approximately([HumanMessage(content=get_weather.description)])
print(f"First call tokens: {tokens_1}")
tokens_2 = count_tokens_approximately([HumanMessage(content=get_weather.description)])
print(f"Second call tokens (cached): {tokens_2}")
tool_call_msg = ToolMessage(name="get_weather", content="The weather in Vienna is sunny.", tool_call_id="abc123")
print(f"Tool-use call tokens: {count_tokens_approximately([HumanMessage(content="What’s the weather?"), tool_call_msg])}")

First call tokens: 12
Second call tokens (cached): 12
Tool-use call tokens: 18

Common flags

count_tokens_approximately()

Approximate token counter for messages/tools

@tool decorator

Converts a Python function into a LangChain BaseTool

tool_call_schema

Property on BaseTool returning the cached JSON schema