Claudeでのツール使用

ツール使用により、Claudeはあなたが定義した関数やAnthropicが提供する関数を呼び出すことができます。Claudeはユーザーのリクエストとツールの説明に基づいて、いつツールを呼び出すかを判断します。その後、あなたのアプリケーションが実行する（クライアントツール）、またはAnthropicが実行する（サーバーツール）構造化された呼び出しを返します。

以下は、Anthropicが代わりに実行するサーバーツールであるWeb検索ツールを使用した最小限の例です：

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

ClaudeはAnthropicのインフラストラクチャ上で検索を実行し、同じレスポンスで引用付きの結果を返します。あなたが定義した関数をClaudeに呼び出させるには、input_schemaを持つツールを渡し、Claudeがtool_useブロックを返したときにその呼び出しを実行します。ツール使用の仕組みでは、そのラウンドトリップをエンドツーエンドで示しています。ツールの定義とツール呼び出しの処理について詳しく学びましょう。



ツール使用の仕組み

ツールは主にコードが実行される場所によって異なります。クライアントツール（ユーザー定義ツールや、bashやtext_editorなどのAnthropic定義スキーマを持つツールを含む）は、あなたのアプリケーション内で実行されます。Claudeはstop_reason: "tool_use"と1つ以上のtool_useブロックで応答します。あなたのコードが操作を実行し、tool_resultを送り返します。サーバーツール（web_search、web_fetch、code_execution、tool_searchなど）はAnthropicのインフラストラクチャ上で実行されます。Claudeがクライアントツールの1つと同じ並列ツール呼び出しのグループ内でそのツールを呼び出す場合を除き、実行を処理することなく結果を直接確認できます（停止理由とフォールバックを参照）。

以下は、クライアントツールのラウンドトリップの全体像です。最初のリクエストでget_weatherツールを定義し、Claudeはそれを呼び出して質問に答えます。レスポンスにはtool_useブロックが含まれ、あなたのコードが検索を実行し、2番目のリクエストで結果をtool_resultブロックで送り返すことで、Claudeが回答を返せるようになります。

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claudeはツール名と引数を含むtool_useブロックで応答します。
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # 1ターンにつき最大1回のツール呼び出しを要求します。
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# ツールを実行し、その結果をtool_resultブロックで送り返します。
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claudeはその結果を使って元の質問に回答します。
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

ツール呼び出しの処理では、結果のフォーマットやエラーの通知を含む各ステップを詳しく説明しています。並列ツール使用では、複数のツールを一度に呼び出すレスポンスについて説明しています。このラウンドトリップを自分で書くのを省略するには、Tool Runnerを使用してください。SDKがツールを実行し、結果を自動的に送り返します。

エージェントループや各アプローチをいつ選択するかを含む完全な概念モデルについては、ツール使用の仕組みを参照してください。

Model Context Protocol（MCP）サーバーへの接続については、MCPコネクタを参照してください。独自のMCPクライアントを構築するには、Model Context ProtocolガイドのMCPクライアントの構築を参照してください。



Claudeがツールを使用するタイミング

デフォルトのtool_choiceである{"type": "auto"}では、Claudeは各ターンでツールを呼び出すか直接応答するかを判断します。リクエストがそのツールの説明された機能に対応し、答えがまだコンテキストにない場合にツールを呼び出します。安定した知識、創造的なタスク、会話のターンに対しては直接応答します。

この境界はシステムプロンプトで調整できます。期待するときにClaudeがツールを呼び出さない場合、"Use the tools to investigate before responding."のような軽い指示でツール使用が増加します。"Always call a tool first before responding."のようなより強い形式はさらに促進します。逆に、"Use your judgment about whether to call a tool or respond directly."はトリガー動作を控えめに保ちます。

プロンプトに頼るのではなくツール呼び出しを必須にするには、tool_choiceを設定してください。

各サーバーツールのページでは、それぞれのトリガー境界についてより詳しく説明しています。



ツールの選択

type文字列、バージョン、ベータヘッダーについては、ツールリファレンスを参照してください。



独自のツール

あなたが定義するツールでは、あなたがスキーマを書き、あなたのアプリケーションが各呼び出しを実行します。



Anthropicスキーマのクライアントツール

Anthropicがスキーマを公開し、Claudeをそれに基づいて訓練しています。あなたのアプリケーションが引き続き各呼び出しを実行し、tool_resultを返します。



サーバーツール

サーバーツールはAnthropicのインフラストラクチャ上で実行され、あなたのアプリケーションにハンドラコードは必要ありません。共通の仕組みについてはサーバーツールを参照してください。



料金

ツール使用リクエストの料金は、以下に基づいて計算されます：

1. モデルに送信される入力トークンの総数（toolsパラメータ内のものを含む）
2. 生成される出力トークンの数
3. サーバーサイドツールの場合、追加の使用量ベースの料金（例：ウェブ検索は実行された検索ごとに課金）

クライアントサイドツールは他のClaude APIリクエストと同じ料金体系ですが、サーバーサイドツールはその特定の使用量に基づいて追加料金が発生する場合があります。

ツール使用による追加トークンは以下から発生します：

• APIリクエスト内のtoolsパラメータ（ツール名、説明、スキーマ）
• APIリクエストおよびレスポンス内のtool_useコンテンツブロック
• APIリクエスト内のtool_resultコンテンツブロック

toolsを使用すると、APIはツール使用を可能にするための特別なシステムプロンプトをモデルに自動的に含めます。各モデルに必要なツール使用トークン数は以下のとおりです（上記の追加トークンは除く）。なお、この表は少なくとも1つのツールが提供されていることを前提としています。toolsが提供されていない場合、ツール選択がnoneであれば追加のシステムプロンプトトークンは0になります。

これらのトークン数は、リクエストの総コストを計算するために、通常の入力トークンと出力トークンに加算されます。

現在のモデルごとの価格については、モデル概要の表を参照してください。

ツール使用プロンプトを送信すると、他のAPIリクエストと同様に、レスポンスには報告されるusageメトリクスに入力トークン数と出力トークン数の両方が含まれます。

一部のサーバーツールは、トークンに加えて使用量ベースの料金が発生します。料金についてはWeb検索ツールとコード実行ツールを参照してください。



次のステップ