наблюдаемость: измерять бюджет каталога MCP

docs/mcp-interface.md

@@ -228,6 +228,17 @@ MCP-клиент видит только опубликованные опера
 
 Черновики операций не попадают в MCP-каталог. Если два пользователя работают в одном workspace, один может редактировать черновик, а второй публиковать агента. В опубликованный каталог попадут только опубликованные версии операций.
 
+При каждом обновлении каталога Crank анализирует фактические определения `tools/list` и записывает в структурированный журнал:
+
+- число инструментов;
+- размер компактного JSON в байтах;
+- оценочный объём контекста в токенах;
+- размер крупнейшего инструмента;
+- рекомендуемый предел и признак его превышения;
+- число предупреждений качества каталога.
+
+Оценка токенов равна округлённому вверх отношению размера UTF-8 к трём. Она нужна для стабильного сравнения ревизий каталога и не заменяет точный токенизатор конкретной модели.
+
 ## Обновление каталога
 
 `mcp-server` периодически обновляет опубликованный каталог. Интервал задается:

docs/observability.md

@@ -15,6 +15,8 @@ Crank сохраняет данные о тестовых запусках и в
 - краткий preview запроса и ответа;
 - категория ошибки, если вызов завершился ошибкой.
 
+При обновлении опубликованного MCP-каталога отдельное событие `published agent catalog analyzed` содержит `tool_count`, `serialized_bytes`, `estimated_context_tokens`, `largest_tool_estimated_context_tokens`, `recommended_context_tokens`, `exceeds_recommended_budget` и число предупреждений качества. По этим полям можно заметить рост цены `tools/list` до того, как он ухудшит выбор инструментов моделью.
+
 ## Использование
 
 Раздел использования агрегирует:
@@ -31,4 +33,3 @@ Crank сохраняет данные о тестовых запусках и в
 - увидеть ошибки маппинга или внешнего API;
 - найти медленные endpoint-ы;
 - понять, какие инструменты реально используются.
-

docs/tool-design.md

@@ -154,6 +154,10 @@ Crank возвращает структурированные ошибки. MCP-
 
 Если у агента слишком много похожих инструментов, модель чаще ошибается при выборе.
 
+Crank измеряет опубликованный каталог по тому же компактному JSON, который возвращается в `tools/list`. В расчёт входят имя, заголовок, описание, входная JSON-схема и добавляемое Crank описание подтверждения опасной операции. Для сравнения используется независимая от конкретной модели консервативная оценка: один токен на три байта UTF-8. Это не счётчик токенов конкретного поставщика, а стабильная инженерная метрика для поиска регрессий.
+
+Рекомендуемый бюджет одного агентского каталога — не более 4096 оценочных токенов. Превышение не блокирует публикацию, потому что допустимый объём зависит от модели, но создаёт предупреждение. Сначала сокращайте лишние описания и схемы. Если инструменты решают разные задачи, разделяйте их между специализированными агентами. Выбор нужного агента и постепенное раскрытие каталогов выполняет оркестратор Drivetrain, а не Crank.
+
 ## Проверочный список
 
 - Имя инструмента конкретное и не похоже на `call_api`.
@@ -164,3 +168,4 @@ Crank возвращает структурированные ошибки. MCP-
 - Для POST/PATCH задан idempotency key, если повторный вызов может создать дубль.
 - Для DELETE пользователь видит двухшаговое подтверждение.
 - Агенту привязаны только инструменты, нужные для его задачи.
+- Опубликованный каталог укладывается в выбранный бюджет контекста модели.