# なぜToolsが最初に表示されるのか？

cc-viewerのContextパネルでは、**ToolsはSystem PromptとMessagesより前に表示されます**。この順序は、**Anthropic APIのKV-Cacheプレフィックスシーケンス**を正確に反映しています。

## KV-Cacheプレフィックスシーケンス

Anthropic のAPIがKV-Cacheを構築する際、コンテキストを以下の**固定された順序**でプレフィックスとして連結します：

```
┌─────────────────────────────────────────────────┐
│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
│ 2. System Prompt                                 │
│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
└─────────────────────────────────────────────────┘
```

つまり、**ToolsはSystem Promptより前、キャッシュプレフィックスの最先頭に位置します**。

## なぜToolsはSystemよりキャッシュの重みが大きいのか？

KV-Cacheのプレフィックスマッチングでは、**前方のコンテンツほど重要**です — 変更が発生すると、それ以降のすべてが無効化されます：

1. **プレフィックスマッチングは先頭から開始される**：KV-Cacheは現在のリクエストをキャッシュされたプレフィックスと先頭からtoken単位で比較します。不一致が見つかった瞬間、それ以降のコンテンツはすべて無効化されます。

2. **Toolsの変更 = キャッシュ全体が無効化**：Toolsは最前列にあるため、tool定義の変更（MCP toolの追加・削除1つでも）は**プレフィックスを最先頭から破壊し**、キャッシュされたSystem PromptとMessagesすべてを無効化します。

3. **Systemの変更 = Messagesキャッシュが無効化**：System Promptは中間に位置するため、その変更は後続のMessages部分のみを無効化します。

4. **Messagesの変更 = 末尾部分のみ影響**：Messagesは末尾にあるため、新しいmessageの追加は小さな末尾セグメントのみを無効化します — ToolsとSystemのキャッシュはそのまま保持されます。

## 実際の影響

| 変更の種類 | キャッシュへの影響 | 典型的なシナリオ |
|-------------|-------------|-----------------|
| Tool追加/削除 | **完全無効化** | MCPサーバーの接続/切断、IDEプラグインの切り替え |
| System Promptの変更 | Messagesキャッシュが失われる | CLAUDE.mdの編集、system reminderの挿入 |
| 新しいmessageの追加 | 末尾の増分のみ | 通常の会話フロー（最も一般的、最もコストが低い） |

これが、[CacheRebuild](CacheRebuild.md)における`tools_change`が最もコストの高いリビルド理由になりやすい理由です — プレフィックスチェーンを最前部から破壊するからです。

## なぜツール定義が「脳」より先に配置されるのか？

キャッシュの仕組みから言えば、Toolsが最前列に位置するのは技術的な事実です。しかし認知設計の観点からも、この順序は理にかなっています —— **Toolsは手足であり、System Promptは脳です**。

人は行動する前に、自分がどんな手足や道具を使えるかを感知する必要があります。赤ちゃんは最初に世界のルール（System）を理解してから手を伸ばすのではなく、まず自分に手や足があることを感知し、環境との相互作用を通じて徐々にルールを理解していきます。同様に、LLMはタスク指示（System Prompt）を受け取る前に、どんなツールを呼び出せるか（ファイル読み取り、コード記述、検索、コマンド実行）を知っておく必要があります。そうすることで、指示を処理する際に「何ができるか」「どうすべきか」を正確に判断できるのです。

もし逆だったら —— まずモデルに「このモジュールをリファクタリングせよ」と伝え、次に「Read、Edit、Bashなどのツールがある」と伝える —— モデルはタスクを理解する際に重要な能力境界の情報が欠けてしまい、非現実的な計画を立てたり、利用可能な手段を見落としたりする可能性があります。

**手持ちのカードを知ってから、どう切るかを決める。** これがToolsがSystemより先に来る認知的論理です。

## なぜMCPツールもこの位置にあるのか？

MCP（Model Context Protocol）ツールは、組み込みツールと同様にTools領域の最前列に配置されます。MCPのコンテキスト内での位置を理解することは、その実際のメリットとコストを評価するのに役立ちます。

### MCPの利点

- **能力拡張**：MCPにより、モデルは外部サービス（データベースクエリ、API呼び出し、IDE操作、ブラウザ制御など）にアクセスでき、組み込みツールの境界を超えることができます
- **オープンエコシステム**：誰でもMCPサーバーを実装でき、モデルは再トレーニングなしで新しい能力を獲得できます
- **オンデマンド読み込み**：タスクのシナリオに応じてMCPサーバーを選択的に接続/切断でき、ツールセットを柔軟に構成できます

### MCPのコスト

- **キャッシュキラー**：各MCPツールのJSON Schema定義はKV-Cacheプレフィックスの最前列に連結されます。MCPツールを1つ追加/削除するだけで = **キャッシュ全体が最初から無効化**されます。MCPサーバーの接続/切断を頻繁に行うと、キャッシュヒット率が大幅に低下します
- **プレフィックスの肥大化**：MCPツールのSchemaは通常、組み込みツールより大きくなります（詳細なパラメータ説明、列挙値などを含む）。多数のMCPツールはTools領域のトークン数を大幅に増加させ、Messagesに使えるコンテキスト空間を圧迫します
- **レイテンシオーバーヘッド**：MCPツール呼び出しにはプロセス間通信（JSON-RPC over stdio/SSE）が必要で、組み込み関数呼び出しより1桁遅くなります
- **安定性リスク**：MCPサーバーは外部プロセスであり、クラッシュ、タイムアウト、予期しないフォーマットの返却が起こりうるため、追加のエラーハンドリングが必要です

### 実践的な推奨事項

| シナリオ | 推奨 |
|----------|------|
| 長い会話、高頻度のやり取り | MCPツールの数を最小限にし、キャッシュプレフィックスの安定性を保護 |
| 短いタスク、一回限りの操作 | MCPツールを自由に使用可能；キャッシュへの影響は限定的 |
| MCPサーバーの頻繁な追加/削除 | 変更のたびにキャッシュが全面再構築される；ツールセットの固定を検討 |
| 過大なTool Schema | descriptionとenumを削減し、プレフィックスのトークン消費を削減 |

cc-viewerのContextパネルでは、MCPツールは組み込みツールと並んでTools領域に表示され、各ツールのSchemaサイズとキャッシュプレフィックスへの寄与を直感的に確認できます。
