# Чому Tools відображаються першими?

На панелі Context у cc-viewer **Tools з'являються перед System Prompt та Messages**. Такий порядок точно відображає **послідовність префікса KV-Cache в Anthropic API**.

## Послідовність префікса 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 за token від початку. Щойно виявляється розбіжність, весь наступний контент стає недійсним.

2. **Зміна Tools = весь кеш скасовано**: Оскільки Tools стоять першими, будь-яка зміна у визначеннях інструментів (навіть додавання або видалення одного MCP tool) **ламає префікс з самого початку**, роблячи недійсними весь кешований System Prompt та Messages.

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

4. **Зміна Messages = впливає тільки на хвіст**: Messages знаходяться в кінці, тому додавання нових повідомлень скасовує лише невеликий кінцевий сегмент — кеш Tools та System залишається незайманим.

## Практичний вплив

| Тип зміни | Вплив на кеш | Типовий сценарій |
|-----------|-------------|-----------------|
| Tool додано/видалено | **Повне скасування** | Підключення/відключення MCP server, увімкнення/вимкнення плагіна IDE |
| Зміна System Prompt | Втрата кешу Messages | Редагування CLAUDE.md, ін'єкція system reminder |
| Додано нове повідомлення | Лише хвостове збільшення | Звичайний хід розмови (найпоширеніший, найдешевший) |

Саме тому `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 кожного інструменту та його внесок у префікс кешу.
