The additional tokens from tool use come from:

  • The tools parameter in API requests (tool names, descriptions, and schemas)
  • tool_use content blocks in API requests and responses
  • tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above):

ModelTool choiceTool use system prompt token count
Claude 3 Opusauto530 tokens
Claude 3 Opusany, tool281 tokens
Claude 3 Sonnetauto159 tokens
Claude 3 Sonnetany, tool235 tokens
Claude 3 Haikuauto264 tokens
Claude 3 Haikuany, tool340 tokens
Claude 3 Opus (legacy beta: tools-2024-04-04)auto395 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request. Refer to our models overview table for current per-model prices.

When you send a tool use prompt, just like any other API request, the response will output both input and output token counts as part of the reported usage metrics.

Keep in mind that tool use often requires multiple round-trips between your code and Claude (to execute tools and return results), so a single end-user query may result in several API requests and associated token costs. Design your tools and prompts to be as concise as possible while still providing enough information for Claude to effectively use the tools.