Web Fetchツールのuse_cacheでキャッシュを回避する方法

Claude APIのweb_fetchツールは、パフォーマンス向上のため取得結果をキャッシュします。既定ではキャッシュされたコンテンツが返るため、更新頻度の高いページを何度取得してもClaudeには古い内容が渡ることがあります。この挙動を上書きするパラメータが use_cache です。web_fetch_20260309 以降のツールバージョンで使え、"use_cache": false を指定するとキャッシュを迂回して常に新しい内容を取得します。

use_cacheが必要になる場面

web_fetchはURLの内容を取得してClaudeの文脈に挿入するサーバーツールです。公式ドキュメントは、キャッシュの挙動を次のように説明しています。

The web fetch tool caches results to improve performance and reduce redundant requests. The content returned may not always reflect the latest version available at the URL.

キャッシュの管理方法や対象は自動で最適化され、時間とともに変わる可能性があるとも明記されています。つまり「このURLはキャッシュされない」と決め打ちできる固定ルールはなく、常に新しい情報が必要なら明示的にキャッシュを回避する必要があります。

想定される用途は次の2つです。

• 価格ページ、在庫状況、ステータスページなど、数分〜数時間単位で内容が変わるページを取得するとき
• ユーザーが「最新の内容を取ってきて」「今の状態を確認して」のように明示的に鮮度を要求しているとき

逆に言えば、変更頻度の低いドキュメントや長期参照する記事の取得では、既定の true(キャッシュ利用)のままにしておくのが公式の推奨です。スクリーンショットやPDF化まで必要な取得には、Cloudflare Browser RenderingのMCPのような専用サーバーが向いています。

設定方法

use_cache はツール定義の中で false を指定します。ツールタイプは web_fetch_20260309 以降を使う必要があります(web_fetch_20260318 でも有効)。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "https://example.com/status を確認して、現在の障害有無を教えて"
      }
    ],
    "tools": [{
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }]
  }'

tools 配列の web_fetch エントリーに use_cache: false を1行足すだけで、その呼び出しはキャッシュを使わずに常に新規取得します。use_cache を書かない場合の既定値は true です。

レイテンシとのトレードオフ

公式ドキュメントは use_cache: false の代償を明確に書いています。

Only disable caching when the user explicitly requests fresh content or when fetching rapidly changing sources, because bypassing the cache increases latency.

キャッシュを迂回すると、Claudeは毎回そのURLへ実際にリクエストを送るため、キャッシュヒット時より応答が遅くなります。すべての web_fetch 呼び出しに一律で use_cache: false を付ける運用は、レイテンシを常に最大化する選択になるため推奨されません。鮮度が必要な呼び出しだけ個別に false を指定するのが公式の想定する使い方です。

ツールバージョンと機能の対応

use_cache は web_fetch のどのバージョンでも使えるわけではありません。バージョンごとに使える機能が積み上がっているので、まず自分がどのツールタイプを指定しているかを確認します。

web_fetch_20250910 や web_fetch_20260209 を指定したまま use_cache を書いても効果は保証されません。use_cache を使う目的で web_fetch を導入するなら、type は web_fetch_20260309 以降にする必要があります。dynamic filteringだけが目的なら web_fetch_20260209 でも足り、use_cache は追加の要件です。

use_cacheを使うときに見落としやすい点

• use_cacheはツール定義全体に効く: tools 配列の web_fetch エントリーに1度書く設定であり、個々のURLごとに「このURLだけキャッシュを回避する」という指定はできません。同じリクエスト内で複数のURLを取得する場合、use_cache: false はそのリクエストのすべてのweb_fetch呼び出しに適用されます
• URL事前出現の制約は変わらない: use_cache: false にしても、web_fetchが持つ「会話に事前に出現したURLしか取得できない」というURL検証の制約はそのまま残ります。Claude自身の出力にしか出ていないURLや、システムプロンプトだけに書いたURLは、キャッシュ設定に関わらず取得できません。動的なURLを毎回渡す構成にしている場合、キャッシュより先にこの制約でエラーになっていないかを確認します(発生しがちなエラーコードはurl_not_in_prior_contextエラーの原因にまとめています)
• max_uses・allowed_domainsとは独立したパラメータ: use_cache を false にしても、max_uses の上限や allowed_domains によるドメイン制限は変わりません。キャッシュを回避した分だけ実際のフェッチ回数は増えるため、max_uses の上限に達しやすくなる点は考慮が要ります

使い分けの早見表

dynamic filteringやコスト面との関係

use_cache はキャッシュの利用有無だけを制御するパラメータで、同じ web_fetch_20260309 以降のツールが備えるdynamic filtering(取得したコンテンツをコンテキストに載せる前にコード実行でフィルタする機能)とは独立しています。dynamic filteringはトークン消費を抑える仕組み、use_cache は内容の鮮度を保証する仕組みという役割分担です。両方を同時に使う制約はなく、仕組みの詳細はweb_searchのdynamic filteringがZDR対象外になる仕組みが扱っています。

料金面では、web_fetchツール自体の呼び出しに追加費用はかからず、取得した内容が会話の文脈に入った分だけ通常のトークン費用がかかります。use_cache: false にしてもツール利用料が変わるわけではなく、変わるのはレイテンシと(キャッシュが効かない分)取得のたびに実際のページを読みにいく点です。dynamic filteringが動くコード実行ツール自体の費用についてはコード実行ツールが無料になる条件にまとめています。

web_searchと組み合わせたときの扱い

web_searchとweb_fetchを同時に有効にすると、ユーザーがURLを直接渡さない場合でも取得が成立します。「〇〇について調べて、詳しく分析して」のような依頼でも、Claudeはまずweb_searchで対象ページを見つけ、続けてweb_fetchでその内容を取得します。このときも web_fetch エントリー側の use_cache 設定はそのまま効きます。検索結果から見つけた同じURLに何度もアクセスするような使い方(定期的なニュース追跡や価格モニタリングなど)では、use_cache: false を組み合わせないと、web_searchが毎回新しいURLを見つけてきても、web_fetch側で古いキャッシュ内容を返してしまう可能性があります。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "量子コンピューティングの最新記事を探して、一番関連性の高いものを詳しく分析して"
      }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 3
      },
      {
        "type": "web_fetch_20260309",
        "name": "web_fetch",
        "max_uses": 5,
        "use_cache": false
      }
    ]
  }'

よくある質問

Claude CodeのWebFetchツールでもuse_cacheは使えますか

いいえ。ここで扱っている use_cache はClaude API(messages エンドポイント)のweb_fetchサーバーツール専用のパラメータです。Claude Code(CLI)が内蔵するWebFetchツールはキャッシュの既定TTLが別途決まっており、use_cache パラメータは存在しません。

use_cache: trueを明示的に書く意味はありますか

既定値がすでに true なので、動作は変わりません。リクエストの意図をコードレビューで明示したい場合や、チーム内の設定テンプレートで全パラメータを明示する方針にしている場合に書く程度の効果です。

citationsを有効にしたままuse_cache: falseにできますか

できます。citations と use_cache は独立したパラメータで、互いを無効化する制約はありません。キャッシュを回避して取得した新しい内容に対しても、引用機能はそのまま動作します。

実際に新しい内容が返ったかどうかはどう確認しますか

web_fetch_tool_resultには retrieved_at フィールドが含まれ、そのURLをいつ取得したかのタイムスタンプが入ります。use_cache: false を指定したリクエストで retrieved_at がリクエスト直前の時刻に近ければ、実際にキャッシュを回避して新規取得したと確認できます。逆に古い日時が返ってきた場合は、ツールタイプが web_fetch_20260309 以降になっているか、use_cache の綴りや配置(tools 配列内のweb_fetchエントリー直下)を見直します。パラメータ名の打ち間違い(use_cache を usecache や cache と書く等)は動作確認だけでは気づきにくく、retrieved_at の比較が最短の切り分け方法です。

利用できる面

web_fetchツールはClaude APIのほか、Claude Platform on AWSとMicrosoft Foundryで利用できます。ただしMicrosoft FoundryのうちAzureでホストされたデプロイは基本版の web_fetch_20250910 のみをサポートし、use_cache が要求する web_fetch_20260309 以降には対応していません。Anthropicがホストするデプロイではすべてのバージョンが使えます。Amazon BedrockとGoogle Cloudでは、web_fetchツール自体が提供されていません。

まとめ

web_fetchのキャッシュは既定で有効になっており、公式ドキュメントもキャッシュ対象や保持期間を固定値として示していません。更新頻度の高いページをClaudeに確認させたいときは、ツールタイプを web_fetch_20260309 以降にし、"use_cache": false を明示します。ただしキャッシュ回避はリクエストのたびに実際のフェッチが走る分レイテンシが増えるため、すべての呼び出しに機械的に付けるのではなく、鮮度が要る呼び出しだけに絞って使うのが公式の想定する運用です。