Claude API のツール使用では tool_choice パラメータでツール呼び出しの強制度を制御できます。また、ツールが「どこで実行されるか」によって必要な実装が大きく変わります。

tool_choice の4種類

値 動作
auto Claude が判断（デフォルト）
any 提供されたツールのうち必ずいずれかを使う
tool 指定した特定のツールを強制使用
none ツールを使わない（テキストのみで応答） 
# 特定のツールを強制使用する例
tools=[...],
tool_choice={"type": "tool", "name": "get_weather"},

auto では Claude が「リクエストがツールの説明した機能に対応し、答えがまだコンテキストにない場合」にツールを呼び出します。単純な会話や一般知識の質問には直接応答します。

any は「必ず何かのツールを使わせたい」場面で使います。たとえばすべての回答を特定のスキーマで構造化させたい場合に、スキーマを模したツールを定義して any を指定する手法があります。

thinking 有効時の制限

拡張思考（extended / adaptive thinking）が有効なとき、tool_choice は auto か none のみ使用できます。any や特定ツールの強制指定は、思考との組み合わせでエラーになります。

クライアントツールのエージェントループ

クライアントツール（ユーザー定義）はアプリケーション側で実行します。基本的なループパターンは次のとおりです。

messages = [{"role": "user", "content": "東京の天気と為替レートを調べて"}]

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    tools=tools,
    messages=messages,
)

while response.stop_reason == "tool_use":
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    # アシスタントの返答と全ツール結果をまとめて追加
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})
    response = client.messages.create(
        model="claude-opus-4-8", max_tokens=4096, tools=tools, messages=messages
    )

print(response.content[0].text)

並列ツール呼び出し時はすべての tool_result を単一のユーザーメッセージにまとめて返す必要があります。結果を別メッセージに分けると並列呼び出しの効率が落ちます。

サーバーツールはループ不要

web_search、web_fetch、code_execution、tool_search はAnthropicのインフラ上で実行されます。エージェントループを自分で実装する必要がなく、Claude が内部でツールを実行し最終応答を返します。

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "最新のニュースを調べて"}],
)
# ループ不要。response にはすでに検索結果を踏まえた回答が入っている

effort とツール呼び出しの関係

effort を低くすると、Claude はツール呼び出しを減らす・複数操作をまとめる傾向があります。これは意図的な設計で、低 effort では「前置き説明なしに直接アクションに進む」「完了後に簡潔な確認のみ」という挙動になります。

大量処理やサブエージェントでコストを抑えたい場合に有効ですが、品質が落ちる点は考慮が必要です。

まとめ

  • tool_choice: "auto" が基本。any でツール呼び出しを必須化、tool で特定ツールを強制
  • thinking 有効時は auto か none のみ使用可能
  • クライアントツールは stop_reason == "tool_use" を確認しながらループを回す
  • 並列呼び出しの結果はすべて単一のユーザーメッセージにまとめて返す
  • サーバーツールはエージェントループ不要。クライアントツールはループの実装が必要
  • effort を下げるとツール呼び出し回数が減る傾向がある