# Почему Tools перечислены первыми?

В панели Context в cc-viewer **Tools отображаются раньше System Prompt и Messages**. Этот порядок точно отражает **последовательность префикса KV-Cache API Anthropic**.

## Последовательность префикса KV-Cache

Когда API Anthropic формирует 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 за token с начала. Как только обнаруживается несоответствие, весь последующий контент становится недействительным.

2. **Изменение Tools = весь кэш недействителен**: Поскольку Tools стоят первыми, любое изменение определений tool (даже добавление или удаление одного MCP tool) **нарушает префикс с самого начала**, делая недействительными все кэшированные System Prompt и Messages.

3. **Изменение System = кэш Messages недействителен**: System Prompt находится посередине, поэтому его изменения делают недействительной только следующую за ним часть Messages.

4. **Изменение Messages = затронут только хвост**: Messages находятся в конце, поэтому добавление новых messages делает недействительным лишь небольшой хвостовой сегмент — кэши Tools и System остаются нетронутыми.

## Практическое влияние

| Тип изменения | Влияние на кэш | Типичный сценарий |
|-------------|-------------|-----------------|
| Tool добавлен/удалён | **Полная инвалидация** | Подключение/отключение сервера MCP, включение/выключение плагина IDE |
| Изменение System Prompt | Кэш Messages утерян | Редактирование CLAUDE.md, внедрение system reminder |
| Добавлено новое message | Только хвостовой инкремент | Обычный ход разговора (самый частый, самый дешёвый) |

Вот почему `tools_change` в [CacheRebuild](CacheRebuild.md) как правило является наиболее дорогостоящей причиной перестройки — она нарушает цепочку префикса с самого начала.

## Почему определения инструментов размещаются перед «мозгом»?

С точки зрения кэширования, размещение 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

- **Убийца кэша**: JSON Schema каждого MCP-инструмента конкатенируется в самое начало префикса KV-Cache. Добавление или удаление одного MCP-инструмента = **весь кэш инвалидируется с самого начала**. Частое подключение/отключение MCP-серверов резко снижает процент попаданий в кэш
- **Раздувание префикса**: Schemas MCP-инструментов обычно больше встроенных (подробные описания параметров, перечисления и т.д.). Большое количество MCP-инструментов значительно увеличивает количество токенов в области Tools, сокращая пространство контекста для Messages
- **Накладные расходы на задержку**: Вызовы MCP-инструментов требуют межпроцессного взаимодействия (JSON-RPC через stdio/SSE), на порядок медленнее вызовов встроенных функций
- **Риск стабильности**: MCP-серверы — это внешние процессы, которые могут аварийно завершиться, вызвать таймаут или вернуть неожиданный формат, требуя дополнительной обработки ошибок

### Практические рекомендации

| Сценарий | Рекомендация |
|----------|-------------|
| Длинные разговоры, частое взаимодействие | Минимизировать количество MCP-инструментов для защиты стабильности префикса кэша |
| Короткие задачи, разовые операции | Свободно использовать MCP-инструменты; влияние на кэш ограничено |
| Частое добавление/удаление MCP-серверов | Каждое изменение вызывает полную перестройку кэша; рассмотреть фиксацию набора инструментов |
| Слишком большие Tool Schemas | Сократить описания и enum для уменьшения расхода токенов префикса |

В панели Context cc-viewer инструменты MCP отображаются рядом со встроенными инструментами в области Tools, давая наглядное представление о размере Schema каждого инструмента и его вкладе в префикс кэша.
