`disallowed-tools` が減らすのは、コンテキストよりツールの選択肢

下書きについて。 実際の会話を大まかに書き起こした作業中の原稿です。どこで考えが変わったかがこの記事の主題なので、最初の思い込みから気づきまで、考えた道筋をそのまま残しています。名前と構文の例は Claude Code v2.1.153 のバンドルで確認しました。

勘違いしかけたこと

v2.1.152 のリリースノートを読んでいると、スキルのフロントマターに disallowed-tools というフィールドが追加されていました。フロントマターにはすでに許可リストの allowed-tools があったので、それに対応する拒否リストに見えます。最初に浮かんだのは 「Claude Code の初期コンテキストを削る設定が増えた。つい最近書いた記事に、スキルのコストを抑える4つ目の手段として追記しよう」 という考えでした。

仕組みを確認するため、v2.1.153 のバンドルから文字列を取り出すと、このフィールドの説明が見つかりました。

disallowed-tools
  → "Tools removed from the model while this file is active.
     Comma-separated string or YAML list. Cleared when the user
     sends the next message."

カンマ区切りの文字列か YAML のリストで、使用できないツールを指定します。初期コンテキストを削る設定だという考えが崩れたのは、説明の次の2箇所を読んだときでした。

  1. 「このファイルが有効な間」。対象は、そのスキルの呼び出し中です。
  2. 「ユーザーが次のメッセージを送ると解除される」。その場限りの設定です。

つまり、多く見積もっても disallowed-tools で容量を減らせるのは1ターンだけです。その後、ツールとその定義はすぐに戻ります。リクエストごとに働くフィルターということです。

さらに根本的な問題があります。そもそも削りたかったのは、ツールではありません。

MCP の指示文はなぜ減らせないのか

スキルや MCP でコンテキストが膨らむとき、コンテキストウィンドウには性質の異なる2種類のデータが入っています。下の図は、Claude Code が1回のリクエストで API に送るデータを示しています。

┌──────────────────────────────────────────────────────────────┐
│ What Claude Code sends to the API for one request            │
├──────────────────────────────────────────────────────────────┤
│ system: "[...]"                                              │
│                                                              │
│ tools: [                                                     │
│   { name: "mcp__foo__do_thing", description, input_schema }, │  ← disallowed-tools filters HERE
│   { name: "mcp__foo__other",   description, input_schema }, │
│ ]                                                            │
│                                                              │
│ messages: [                                                  │
│   { role: "user", content: [                                 │
│     { type: "text",                                          │
│       text: "# MCP Server Instructions                       │  ← MCP instructions live HERE
│              ## foo                                          │     (injected at connection time
│              <hundreds of tokens of guidance>",              │     as an isMeta:true block,
│       isMeta: true }                                         │     bypassing both the /context
│   ]},                                                        │     "System prompt" and "Messages"
│   ...                                                        │     counters)
│ ]                                                            │
└──────────────────────────────────────────────────────────────┘

disallowed-tools が絞り込むのは tools 配列です。MCP サーバーの # MCP Server Instructions ブロックは messages 配列にあります。接続時に内部チャネルの mcp_instructions_delta を通じて一度だけ、isMeta: true のブロックとして挿入されます。このブロックは /context の「System prompt」と「Messages」のどちらにも計上されません。ツールを除外するフィルターは、メッセージ履歴に触れません。

そのため、指示文の長い MCP サーバーのツールをすべて除外しても、指示文は丸ごと残り、同じ量のトークンを使い続けます。エージェントは説明を読めても、そこに書かれたツールを呼べません。トークンを消費したまま、ツールも使えなくなります。

目的disallowed-tools で達成できるか
起動時の 初期コンテキストを減らす❌ スキルの実行前に初期コンテキストが決まる
MCP サーバーの指示文のトークンを減らす❌ 指示文はフィルターの対象外
ツール定義を恒久的に除外する❌ ユーザーの次のメッセージで解除される
スキルが働きかけられる範囲を制限する✅ この用途のための機能
選択肢を減らして Claude の判断の質を上げる✅ 一見わかりにくいものの、ここが面白い

ツール選択に使う推論予算を抑える

ここから話が面白くなりました。disallowed-tools は、ツール選択に使う推論予算を抑える設定と考えられます。Claude Code のコミュニティでは、コンテキストの容量に比べると、ツールを選ぶのにどれだけ推論を費やすかはあまり話題になりません。

LLM エージェントはおおむね次の手順を繰り返します。いま起きたことと目標を読み取り、利用できるツールすべてに目を通し、次の操作に合うツールを判断して呼び出します。

1. Read the current state (what just happened, what the goal is)
2. Scan the available tool list — every single tool, every step
3. Reason about which tool best fits the next action
4. Call it

ステップ2と3にかかる負荷は、ツールの数とともに増えます。ツールが10個から100個に増えると、tools 配列に載る定義のトークンが増えます。/context で見えるのはそこまでです。実際には、選択が曖昧になるたびに「mcp__a__search、mcp__b__search、WebSearch のどれを使うか。Bash で自分で grep するか」と比較するための推論トークンも使います。

ツール一覧が膨らむことで起きるこの判断への影響は、トークンカウンターには出ません。代わりに、次のような挙動に表れます。

起きること原因
名前や説明が似ている候補から誤ったツールを選ぶ役割が重なるほど、どれを選ぶべきか判断しづらくなる
bash の1行で済む操作に、機能の多い MCP ツールを試す具体的な名前のツールが目につき、候補にあるだけで試しやすくなる
ツールAで失敗し、ツールBでも失敗し、ツールCを試すといった繰り返しに陥る「ツールがあるなら使うべきだ」と判断してしまう
複数の候補を延々と比べる推論が目に見える推論予算の多くを候補の比較に使う

Anthropic のツール利用ガイドでも、この問題を踏まえて、必要な機能を満たす最小限のツールを公開し、意味の重なる候補を避けるよう勧めています。disallowed-tools を使うと、この方針をスキル単位で適用できます。

役立つ使い方を二つ

使い方1。失敗したテストの原因調査に集中させる。 エラーの意味を Web で探しに行くことを避け、コードを読んでテストが失敗した根本原因を調べさせたいとします。

---
name: focused-debug
description: Investigate the root cause of a specific failing test
disallowed-tools:
  - WebSearch
  - WebFetch
  - mcp__firecrawl__*
  - mcp__exa__*
  - mcp__perplexity__*
---

Web 検索を選択肢から外します。Claude が根拠にできるのは、Read、Grep、Bash で確認できる実際のコードベースです。調べるための Web ツールがないので、「このエラーを検索しようか」と迷わなくなります。

使い方2。読み取り専用のレビュー。 コードレビューで気づいた点を先回りして「修正」できないようにし、観察と報告に集中させます。

---
name: read-only-review
disallowed-tools:
  - Write
  - Edit
  - NotebookEdit
  - Bash(git commit *)
  - Bash(git push *)
  - Bash(rm *)
---

これで「ついでにちょっと直しておく」が候補から消えます。エージェントは差分を作れないので、レポートにまとめることになります。指示文で頼む代わりに、選べる操作を制限します。

コンテキストの容量とツール選択の負荷

コンテキストの容量だけを考えると、disallowed-tools は目的に合いません。エージェントが実際の課題を解き始める前に候補の比較へ費やす推論量にも注目すると、この設定の役割がわかります。

設定減らすもの改善するもの
maxSkillDescriptionChars などスキルの説明文のバイト数初期コンテキストのサイズ
MCP サーバーをオフにするツール定義と指示文初期および実行中のコンテキストのサイズ
disallowed-toolsその場で使える選択肢の数ステップごとの選択の正確さと推論効率

コンテキストの容量は、どれだけの情報が収まるかです。ツール選択の負荷は、どれだけの候補を検討するかです。この二つを同じものとして扱ったので、最初はこの設定の用途を見誤りました。

今後の使い方

自分では、これから次のように扱います。

  • 「初期コンテキストを削る」目的で disallowed-tools を使うのはやめる。そこには効かず、測っても期待した結果は出ません。
  • スキルの役割がはっきりしていて、使えるツールの大半が無関係で判断を迷わせそうなときに使う。
  • v2.1.152 の追加は、Anthropic がエージェントの行動を制御する設定を提供したものと捉える。

最初に考えていたより狭い用途ですが、使いどころは明確になりました。


下書き。実際に考えながら話した内容をもとにしています。考えがまとまったら、改めて文章を整えます。