disable_parallel_tool_useの効果はtool_choiceで変わる

disable_parallel_tool_useはトップレベルでなくtool_choiceの中に置く

並列ツール呼び出しは既定で有効です。これを止めたいときに置く場所を間違えやすいパラメータがdisable_parallel_tool_useで、名前の見た目からトップレベルのブール値だと誤解されがちです。リクエストのトップレベルに書いても効きません。tool_choiceオブジェクトの内側にネストして置く必要があります。

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "tools": [{ "name": "get_weather", "...": "..." }],
  "tool_choice": { "type": "auto", "disable_parallel_tool_use": true },
  "messages": [
    { "role": "user", "content": "What is the weather in San Francisco and New York?" }
  ]
}

toolsやmessagesと横並びの独立したキーではなく、tool_choiceの子要素であることが、このパラメータでもっとも見落とされやすい点です。効かないと感じたときは、まず配置がトップレベルになっていないかをリクエストのJSONで確認します。

この設計になっている理由は、disable_parallel_tool_useが単独の機能ではなく、「ツール呼び出しをどう選ばせるか」というtool_choiceの設定全体の一部だからです。tool_choice自体がauto・any・tool・noneという複数のtypeを持ち、それぞれで意味が変わる設定です。並列可否の指定もその内側にまとめて置くほうが、他のパラメータとの整合が取りやすくなります。トップレベルの独立したブール値として存在するわけではない、という前提が他のクライアントライブラリのドキュメントを読むときの手がかりにもなります。

tool_choiceがautoなら最大1回、any/toolなら厳密に1回

disable_parallel_tool_use: trueを設定したときの挙動は、tool_choiceのtypeによって変わります。同じ1つのパラメータでも、隣接するtype次第でまったく異なる意味を持つため、どちらの設定で使っているかを常に意識する必要があります。

autoのときは、Claudeがツールを呼ばずにテキストだけで答える選択肢がそのまま残ったうえで、複数ツールの同時呼び出しだけを抑える設定になります。一方anyやtoolで強制呼び出しにしている場合、disable_parallel_tool_use: trueは「複数呼ばせない」ではなく「必ず1つだけ呼ばせる」という意味になります。テキストのみの応答は選べません。同じキーと同じ値の組み合わせでも、隣り合うtypeが違うだけで期待する挙動は正反対になりえます。

この違いを理解しておかないと、「並列を止めたつもりが、ツールを呼ばない自由まで奪ってしまった」あるいは逆に「1回だけツールを呼ばせたつもりが、テキスト応答で済まされてしまった」という食い違いが起きます。設計の意図が「同時に複数呼ばせたくない」だけならautoのまま、「必ずどれか1つは呼ばせたい」まで含むならanyかtoolを選びます。disable_parallel_tool_use単体でなくtool_choiceのtypeとセットで意図を決めることが大切です。

実装のレビューでは、disable_parallel_tool_use: trueという行だけを見て「並列を止める設定」とひとくくりに読んでしまいがちです。これは名前だけを見れば自然な誤解ですが、実際の効果は隣のtype次第で変わります。コードレビューやドキュメント化の際は、typeとdisable_parallel_tool_useをセットで確認する習慣が意図と実装のずれへの一番の対策です。

any/toolとstrict tool useを組み合わせて確実性を上げる

disable_parallel_tool_use: trueとanyを組み合わせれば「ツールを厳密に1回呼ぶ」ことは保証できますが、これだけでは呼び出しの引数がスキーマ通りである保証にはなりません。確実性をさらに上げたい場合は、strict tool useと組み合わせます。ツール定義にstrict: trueを設定すれば、Claudeが生成する入力がスキーマに厳密に従うことも同時に保証される仕組みです。「ツールが必ず1回呼ばれる」ことと「その入力が必ずスキーマ通りである」ことは別々の保証なので、両方が必要な設計では2つを組み合わせて初めて成立します。

強制ツール呼び出しを避けて自然文の説明も欲しい場合は、別の選択肢もあります。tool_choiceをauto(既定)のままにして、ユーザーメッセージ側に「get_weatherツールを使って答えてください」のように明示的な指示を加える方法です。公式のテストでは、この方法でも性能が落ちないことが確認されています。強制呼び出しの仕組みを使わずに済ませたい場面では、この代替も検討する価値があります。候補ツール自体が多すぎてany/toolでの強制呼び出しが安定しない場合は、そもそもの絞り込みを見直すAgent SDKのTool Searchというアプローチもあります。

設定するタイミングを間違えると効かない

disable_parallel_tool_useにはもう1つ見落としやすい制約があります。トップレベルの配置ミスを直したのに、それでもまだ効かないという相談の大半は、この2つ目の制約が原因です。tool_useを返すことになるリクエストそのものに設定しないと効きません。会話が進んだあとのリクエストで後付けで設定しても、すでに返ってきた過去のツール呼び出しには一切影響しません。

これはtool_choiceまわりのトラブルシューティングで報告される典型的な症状で、「設定したのに効かない」という相談の多くは設定タイミングのずれが原因です。Claude Codeのように複数ツールの実行結果を1ターンでまとめて後続処理に渡す仕組みを組んでいる場合は、PostToolBatch hookのようにリクエスト単位・ターン単位で状態を扱う実装パターンが参考になります。

さらに見落としやすいのは、disable_parallel_tool_useが会話全体に効く設定ではなく、リクエストごとに評価される点です。複数ターンの会話を続けている場合、あるターンで並列呼び出しを抑えたいなら、そのターン用のリクエストにtool_choiceごと明示する必要があります。1度設定したから以降のターンにも自動で引き継がれる、という挙動ではありません。会話の途中でこの設定を外し忘れたまま送り続けると、逆に「意図せずずっと並列を抑制したまま」になっていることもあります。ターンごとにリクエストの中身を組み立てるコードでは、この設定を毎回明示的に決める作りにしておきます。

any/toolのtool_choiceが使えないケースが2つある

disable_parallel_tool_useをanyやtoolと組み合わせる設計をする前に、そもそも対象のモデルや設定がこれらのtypeに対応しているかを確認しておく必要があります。制限は2つあります。

Claude Fable 5.1とClaude Mythos 5.1は、強制ツール呼び出しにあたるtool_choiceのanyとtoolに対応していません。具体的にはtool_choice: {"type": "any"}やtool_choice: {"type": "tool", "name": "..."}を指定すると400エラーになります。このモデルでツール呼び出しをほぼ確実にしたい場合の代替は、autoとstrict tool useの組み合わせです。スキーマに沿った入力を保証しつつ、tool_choiceのtype自体はautoのまま使えます。固定のJSON形式で応答を受け取りたいだけなら、structured outputsという選択肢もあります。

もう1つの制限は、モデルではなく設定側にあります。thinking: {type: "enabled"}で拡張思考を手動指定しているリクエストでは、モデルの種類にかかわらずanyとtoolは使えません。autoかnoneに切り替える必要があります。ただしOpus 5のように、拡張思考が既定で有効になっているモデルのadaptive thinkingはこの制限の対象外です。any/toolも通常どおり使えます。手動指定かどうかで挙動が変わる点を見落とすと、「同じOpusなのに片方はエラーになる」という現象に遭遇します。

この2つの制限に共通しているのは、失敗するのがdisable_parallel_tool_useそのものではない点です。そのさらに外側にあるtool_choiceのtype指定自体が、リクエスト全体を400エラーで止めてしまいます。切り分けでまず見るべきは、エラーメッセージがtool_choiceのtypeに関するものかどうかです。そうであればモデルの対応状況と拡張思考の設定を疑います。エラーメッセージがdisable_parallel_tool_useそのものを指していない場合、原因はこの2つの制限ではなく、前段で扱った配置ミスやタイミングのずれである可能性のほうが高くなります。

none(ツールを一切呼ばせない)はどちらの制限があっても通常どおり使えます。disable_parallel_tool_useを絡めた設計をする前に、対象モデルと拡張思考の設定がどのtool_choiceのtypeに対応しているかを先に確認します。

もう1つ、モデルや拡張思考とは別枠の非対応があります。programmatic tool calling(コード実行環境からツールを呼ぶ方式)では、disable_parallel_tool_use: true自体がサポート対象外です。strict tool useのstrict: trueもこの方式では非対応で、いずれも公式ドキュメントに明記されています。programmatic tool callingを使っている実装でdisable_parallel_tool_useが効かないときは、配置ミスやタイミングのずれを疑う前に、そもそもこの呼び出し方式では対応していない設定だという前提を確認してください。

tool_choiceの4つのtypeとdisable_parallel_tool_useの組み合わせ早見表

ここまでの内容を、実装するときに参照しやすい形でまとめておきます。tool_choiceにはauto・any・tool・noneの4つのtypeがあり、disable_parallel_tool_useが意味を持つのは前者3つです。

公式ドキュメントは「typeがanyまたはtoolのときdisable_parallel_tool_use: trueでツール呼び出しは厳密に1回になる」とだけ述べており、toolとanyを挙動の面で区別していません。toolは呼ぶツールを名指しで固定する設定、anyはどれか1つを選ばせる設定という違いはありますが、disable_parallel_tool_use: trueが保証する「厳密に1回」という効果自体は両者で同じです。実務で組み合わせを検討する価値があるのは、主にautoとany/toolの2パターンです。

noneは少し性格が異なります。ツールを一切呼ばせない設定なので、複数呼び出しを抑えるかどうかという論点そのものが発生しません。会話の一部だけ一時的にツールを無効化したい場面(たとえば確認の対話だけ自然文で完結させたいターン)で使う設定で、並列制御の文脈では対象外です。実装では4つのtypeを1つの列挙型やswitch文にまとめ、どの分岐でdisable_parallel_tool_useが意味を持つかをコード上でも明示します。

まとめ

disable_parallel_tool_useを実際に使うときに確認しておくべき点は、次の4つです。

• tool_choiceオブジェクトの内側に置くこと
• autoとany/toolで効果の意味が変わること
• tool_useを返すリクエストそのものに設定しないと効かないこと
• Fable 5.1・Mythos 5.1や手動の拡張思考ではany/tool自体が使えないこと

設定した直後に「効いていない」と感じたら、まずこの4点のどれに当てはまるかを順に確認します。

並列呼び出しを止めるのではなく積極的に増やしたい場合の設計は並列ツール呼び出しを増やすシステムプロンプトの書き方にまとめています。