Claude APIツールのバージョン管理(_YYYYMMDD)の読み方と使い分け

_YYYYMMDDは「新しい方が常に正しい」を意味しない

Anthropic-provided(Anthropic純正)のツールはWeb Search・Web Fetch・Code Execution・Advisor Tool・Tool Search Tool・MCPコネクタ・Memory・Bash・Text Editor・Computer use・Browser useと多岐にわたり、それぞれが独自のバージョン系列を持ちます。ユーザー定義ツールにはこの命名規則自体が存在しないため、本記事が扱うのはAnthropicが提供する側のツールに限られます。

Claude APIが提供するツールのtype文字列には、code_execution_20260521のように末尾へ_YYYYMMDDが付きます。この日付はツールの挙動・スキーマ・対応モデルのいずれかが変わったタイミングを示すリリース日で、単純な連番ではありません。古いバージョンも並行して提供され続けるため、既存の実装をそのまま動かし続けられます。

重要なのは、この日付が新しい番号ほど高機能とは限らないことです。日付が示す関係は「機能追加」「モデル別」「並行する変種」「レガシー」「後継」の5パターンに分かれ、どのパターンかによって「新しい番号に切り替えるべきか」の判断が変わります。

5つの関係パターンをどう見分けるか

typeのバージョンは、tools配列の各要素に文字列として書きます。たとえばCode Executionの最新版を指定する最小構成は次の形です。

{
  "tools": [
    { "type": "code_execution_20260521", "name": "code_execution" }
  ]
}

このようにtypeの日付部分を書き換えるだけでバージョンを切り替えられますが、書き換えていいかどうかはツールごとに違う5パターンで決まります。

機能追加型(capability-keyed): 新旧が同格で共存する

新旧どちらも現役で、必要な機能次第で選ぶパターンです。web_search_20260209とweb_fetch_20260209は動的フィルタリング(結果をコード実行で絞り込んでからコンテキストに載せる機能)を追加し、web_fetch_20260309はキャッシュバイパスのオプションを、web_search_20260318とweb_fetch_20260318はレスポンスの内容を出力から除外できるresponse_inclusion制御を追加しています。code_execution_20260120はサンドボックス内からのプログラム的呼び出しを追加し、code_execution_20260521はツールの説明文自体にセル単位の実行時間制限を明記するようになりました。いずれも必要な機能があるかどうかで選びます。

モデル別型(model-keyed): 対応モデルで選ぶ

text_editor_20250728はClaude 4以降向け、text_editor_20250124はそれ以前のモデル向けです。どちらが「新しい」かではなく、使うモデルがどちらに対応しているかで決まります。

変種型(variant): クエリの形式そのものが違う

tool_search_tool_regex_20251119とtool_search_tool_bm25_20251119は同時にリリースされた2つの検索アルゴリズムで、どちらが他方を置き換えるものでもありません。regex変種はClaudeがPythonのre.search()パターン(例: "get_.*_data")を書いて検索する方式で、パターン長の上限は200文字です。BM25変種は自然言語のクエリ(例: 「天気を取得するツール」に近い表現)で検索する方式で、クエリ長の上限は500文字です。ツール名や説明文が構造化された命名規則に従っているならregex変種が絞り込みやすく、説明文が自然文中心ならBM25変種の方が拾いやすい、という向き不向きがあります。

レガシー型(legacy): 機能が段階的に積み上がる

code_execution_20250522はPythonのみに対応し、code_execution_20260120はBashとファイル操作を追加しました。番号が進むほど対応範囲が広がっていく点で、機能追加型よりも「新しい方が基本的に有利」に近いパターンです。

後継型(successor): ベータから安定版への移行

computer_toolset_20260801はベータだったcomputer_20251124・computer_20250124の安定後継です。旧バージョンは既存の実装やそのツールセットに未対応のモデル向けに残っています。browser_toolset_20260801はBrowser useツールの最初のバージョンです。

Code Executionの4バージョンは何が違うか

Code Executionツールは現在4つのバージョンが並存しており、レガシー型と機能追加型が混在する分かりやすい例です。

code_execution_20260521が挙動としてcode_execution_20260120と違うのは、実行の中身ではなくClaudeに渡す説明文の情報量です。90秒の制限自体は両バージョンに存在しますが、20260521はその制限をツールの説明文でClaudeに伝えるため、Claudeが長時間かかりそうなセルの処理を事前に分割するような計画を立てやすくなります。制限を超えたセルは、ツール呼び出し全体を落とすexecution_time_exceededエラーとは別に、そのセル単体がdetection_timeoutというステータスを伴う結果を返す点も両バージョン共通です。

Claude Haiku 4.5では事情が異なり、code_execution_20260120とcode_execution_20260521のどちらを指定してもプログラム的呼び出しとREPL状態の永続化が使えず、実質的にcode_execution_20250825と同じ挙動になります。バージョン番号を新しくしただけでは機能が有効にならないモデルがある、という点は見落としやすい落とし穴です。

レガシー版から現行版への移行で変わるもの

code_execution_20250522から現行の3バージョンへ移行する際は、ツールのtype文字列を書き換えるだけでなく、周辺の前提もいくつか変わります。

既存のPython実行コードは現行バージョンでもそのまま動きますが、レスポンスをプログラムでパースしている場合は新しいレスポンス型への対応が必要です。ベータヘッダーが不要になった点は見落としやすく、レガシー版からの移行時にヘッダーを外し忘れても動作自体は変わらないため、気づかないまま不要なヘッダーを送り続けているケースもあります。

バージョン選びが料金に直結するケース

Web Search・Web Fetchの動的フィルタリングは内部でCode Executionを使いますが、web_search_20260209以降・web_fetch_20260209以降と組み合わせた場合、その範囲のCode Execution呼び出しに追加料金はかかりません。標準トークン費用だけで済みます。これは動的フィルタリングが自動的に呼ぶCode Executionだけでなく、同じリクエスト内でClaudeが直接実行するコードにも及びます。組み合わせを外れて単体でCode Executionを使う場合は、通常のCode Execution料金が適用されます。

つまり、「古いバージョンのWeb Searchを使い続けている」ことが、意図せずCode Executionの課金対象を広げている場合があります。バージョンの選択は機能差だけでなく、料金体系の適用範囲にも直結します。

ベータヘッダーの要不要もバージョンで変わる

typeのバージョン番号とは別に、リクエストへanthropic-betaヘッダーが必要かどうかもツールごと・バージョンごとに違います。Web Search・Web Fetch・Code Execution・Tool Search Toolはどのバージョンでもベータヘッダーが不要ですが、Advisor Toolはadvisor-tool-2026-03-01ヘッダーが必須で、MCPコネクタはmcp-client-2025-11-20が必須です。Computer useの旧バージョンはcomputer_20251124がcomputer-use-2025-11-24、computer_20250124がcomputer-use-2025-01-24とバージョンごとに異なるヘッダーを要求しますが、後継のcomputer_toolset_20260801はヘッダー不要です。

MCPコネクタを使う場合、リクエストのヘッダーは次のように書きます。

POST /v1/messages
anthropic-beta: mcp-client-2025-11-20

type側にバージョン番号が付かないぶん、対応を管理する場所がヘッダーのこの1行に集約されます。

「バージョンを最新にしたのにベータヘッダー関連のエラーが消えない」という場合、原因はツールのtypeではなくヘッダー側の設定漏れであることが多く、この2つは別々に確認する必要があります。

mcp_toolsetだけは日付でバージョン管理されない

mcp_toolset(MCPコネクタ)は例外で、type文字列に_YYYYMMDDが付きません。バージョン管理はanthropic-betaヘッダー側で行われます。他のツールのtypeを見慣れていると、MCPコネクタも同じ命名規則だと錯覚しがちですが、確認する場所がそもそも違います。

後継型のツールセットは構造そのものが変わっている

Computer use / Browser useの後継型は、単なるバージョン番号の更新ではなくエントリの構造自体が変わっています。旧computer_20251124・computer_20250124は1つのツールが1つの機能に対応するのに対し、computer_toolset_20260801は1つのエントリが複数のメンバーツールを束ねるクライアントツールセットです。名前・説明・入力スキーマはAnthropicが固定して定義し、呼び出しの実行だけをアプリケーション側が担います。

この構造変化にともない、ツールセットのエントリにはstrict: trueやinput_examplesを設定できない、defer_loadingはエントリではなくconfigs内のメンバー単位で指定する、といった単体ツールとは異なる制約が付きます。同じツールセットを2つ同時に宣言したり、computerという名前の別ツールをcomputer_toolset_20260801と併用したりすることもできません。旧バージョンのcomputer_20251124・computer_20250124は、既存実装の互換性維持と、ツールセット自体に未対応のモデル向けに引き続き使えます。

どのバージョンを使うべきかの早見表

バージョン番号を固定した実装はいつ壊れるか

すべてのツールバージョンは、Anthropicが新しいバージョンを出しても古いバージョンをそのまま動かし続ける設計です。したがって、typeに具体的な日付を書いたコードがある日突然動かなくなることは基本的にありません。壊れるとすれば、古いバージョンが対応していない機能(動的フィルタリングやプログラム的呼び出しなど)を、別の新しいツールと組み合わせて使おうとしたときです。たとえばWeb Search・Web Fetchのweb_search_20260209以降は動的フィルタリングの実行にcode_execution_20260120以降を要求するため、Code Execution側だけ古いバージョンのまま据え置いていると、動的フィルタリングが機能しません。

バージョン番号を意図的に固定運用する場合は、①そのツール単体の互換性だけでなく、②組み合わせて使う他のツールが要求する最低バージョンも合わせて確認する必要があります。defer_loadingでプロンプトキャッシュを壊さずツールを追加する仕組みで触れたとおり、tools配列の変更はキャッシュ全体を無効化するため、バージョンを上げる作業自体もキャッシュ設計と切り離せません。

まとめ

_YYYYMMDDのバージョン番号は、ツールごとに「機能追加型・モデル別型・変種型・レガシー型・後継型」のいずれかの関係で並んでおり、新しい番号を選べば常に正解とは限りません。Code Executionのように機能が段階的に積み上がるツールもあれば、Text Editorのように対応モデルで選ぶツールもあります。mcp_toolsetだけは日付でなくanthropic-betaヘッダーでバージョン管理される点も忘れやすいポイントです。ツール定義の設計をコード実行のオーケストレーション込みで組んでいる場合は、Advanced Tool UseでProgrammatic Tool Callingの実装イメージもあわせて確認してください。