Source: https://docs.claude.com/en/docs/agents-and-tools/tool-use/token-efficient-tool-use

Agent Skills are now available! Learn more about extending Claude's capabilities with Agent Skills .

Claude Docs home page

English

Search...

Ctrl K

Search...

Navigation

Tools

Token-efficient tool use

Home Developer Guide API Reference Model Context Protocol (MCP) Resources Release Notes

Starting with Claude Sonnet 3.7, Claude is capable of calling tools in a token-efficient manner. Requests save an average of 14% in output tokens, up to 70%, which also reduces latency. Exact token reduction and latency improvements depend on the overall response shape and size.

Token-efficient tool use is a beta feature that only works with Claude 3.7 Sonnet. To use this beta feature, add the beta header token-efficient-tools-2025-02-19 to a tool use request. This header has no effect on other Claude models.All Claude 4 models support token-efficient tool use by default. No beta header is needed.

Token-efficient tool use does not currently work with disable_parallel_tool_use .

Here’s an example of how to use token-efficient tools with the API in Claude Sonnet 3.7:

Shell

Python

TypeScript

Java

Copy

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: token-efficient-tools-2025-02-19" \
  -d '{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [\
      {\
        "name": "get_weather",\
        "description": "Get the current weather in a given location",\
        "input_schema": {\
          "type": "object",\
          "properties": {\
            "location": {\
              "type": "string",\
              "description": "The city and state, e.g. San Francisco, CA"\
            }\
          },\
          "required": [\
            "location"\
          ]\
        }\
      }\
    ],
    "messages": [\
      {\
        "role": "user",\
        "content": "Tell me the weather in San Francisco."\
      }\
    ]
  }' | jq '.usage'

The above request should, on average, use fewer input and output tokens than a normal request. To confirm this, try making the same request but remove token-efficient-tools-2025-02-19 from the beta headers list.

To keep the benefits of prompt caching, use the beta header consistently for requests you’d like to cache. If you selectively use it, prompt caching will fail.

Was this page helpful?

YesNo

How to implement tool use Fine-grained tool streaming

Assistant

Responses are generated using AI and may contain mistakes.