# Справочник инструментов

🇬🇧 **English version**: [`TOOLS.md`](./TOOLS.md)

Полный справочник по 18 read-only инструментам, которые предоставляет
`@inso_web/els-mcp`. Для каждого — назначение, основные параметры и
**примеры промптов**, которые можно дать AI-агенту (Claude Code, Cursor,
Windsurf, ChatGPT и др.), чтобы он естественно вызвал нужный инструмент.

Все инструменты требуют API-ключ с правом `errors:mcp-read`. У
`list_apps` дополнительное требование — master-key (для обычных ключей
работает graceful fallback).

## Содержание

- [Поиск и детали](#поиск-и-детали)
  - [`search_logs`](#search_logs)
  - [`get_log_details`](#get_log_details)
  - [`query_logs_jql`](#query_logs_jql)
  - [`errors_in_session`](#errors_in_session)
- [Аналитика и тренды](#аналитика-и-тренды)
  - [`top_error_messages`](#top_error_messages)
  - [`error_histogram`](#error_histogram)
  - [`error_heatmap`](#error_heatmap)
  - [`traffic_stats`](#traffic_stats)
  - [`error_stats_breakdown`](#error_stats_breakdown)
- [Группировка и корреляции](#группировка-и-корреляции)
  - [`find_similar_errors`](#find_similar_errors)
  - [`find_correlated_errors`](#find_correlated_errors)
  - [`grouped_errors`](#grouped_errors)
- [Impact и регрессии](#impact-и-регрессии)
  - [`impact_analysis`](#impact_analysis)
  - [`baseline_compare`](#baseline_compare)
  - [`version_regression`](#version_regression)
- [Триаж и AI](#триаж-и-ai)
  - [`triage_recent_critical`](#triage_recent_critical)
  - [`explain_error`](#explain_error)
  - [`list_apps`](#list_apps)

---

## Поиск и детали

### `search_logs`

**Назначение**: Faceted-поиск по логам с полной поддержкой фильтров.
Возвращает hits + facets (level, browser, urlPath и т. д.) + гистограмму
одним вызовом.

**Основные параметры**: `appSlug`, `from`, `to`, `level`, `serviceName`,
`appVersion`, `urlPath`, `fingerprint`, `sessionId`, `search`,
`response_format`, `limit`, `cursor`.

**Примеры промптов**:

- «Покажи последние 20 критических ошибок в production за последний час.»
- «Найди WARNING-логи `auth-service` где URL содержит `/login`, последние 24 часа.»
- «Список ошибок с appVersion `2.4.1` и serviceName `billing`.»

---

### `get_log_details`

**Назначение**: Полные детали одной записи лога по `traceId` — stack
trace, headers, контекст запроса, AI diagnosis если доступен.

**Основные параметры**: `appSlug`, `traceId`.

**Примеры промптов**:

- «Покажи полные детали для traceId `abc-123-def-456`.»
- «Достань весь stack и контекст для trace `xyz789`.»

---

### `query_logs_jql`

**Назначение**: Поиск через JQL (JIRA-like Query Language). Поддерживает
`AND`, `OR`, `NOT`, операторы сравнения и `IN` по whitelist-полям.

**Основные параметры**: `appSlug`, `jql`, `from`, `to`, `limit`,
`cursor`, `response_format`.

**Примеры промптов**:

- «Выполни JQL `level IN (ERROR, CRITICAL) AND serviceName = \"api-gateway\" AND NOT urlPath ~ \"/health\"` за последние 6 часов.»
- «Через JQL найди ERROR-ошибки где browser = Safari и appVersion ≥ `3.0.0`.»
- «Покажи пример JQL-запроса, который фильтрует по fingerprint и выводит только сообщения.»

---

### `errors_in_session`

**Назначение**: Восстановление полной хронологии ошибок одной
пользовательской сессии — для понимания причинно-следственной цепочки в
рамках действий конкретного юзера.

**Основные параметры**: `appSlug`, `sessionId`, `response_format`.

**Примеры промптов**:

- «Какие ошибки словил сессия `sess_abc`? Покажи по порядку.»
- «Восстанови timeline сбоя для sessionId `01HX9Y…` — нужно понять что
  переживал пользователь.»

---

## Аналитика и тренды

### `top_error_messages`

**Назначение**: Топ-N сообщений об ошибках по частоте (deduped по
нормализованному message).

**Основные параметры**: `appSlug`, `from`, `to`, `limit`, `level`,
`serviceName`.

**Примеры промптов**:

- «Какие были топ-10 сообщений об ошибках на прошлой неделе?»
- «Топ-25 ошибок для `payment-service` за 24 часа, только ERROR и CRITICAL.»

---

### `error_histogram`

**Назначение**: Time-series гистограмма count'а ошибок с автоматическим
выбором бакетов (`5m` / `30m` / `1h` / `1d`) в зависимости от окна.

**Основные параметры**: `appSlug`, `from`, `to`, `level`, `serviceName`,
`bucket` (auto по умолчанию).

**Примеры промптов**:

- «Построй гистограмму error rate за последние 7 дней, часовые бакеты.»
- «Гистограмма CRITICAL ошибок для `lk` за последние 30 минут.»

---

### `error_heatmap`

**Назначение**: Heatmap «день недели × час». Показывает когда обычно
случаются ошибки.

**Основные параметры**: `appSlug`, `from`, `to`, `level`.

**Примеры промптов**:

- «Heatmap ошибок за последние 30 дней — когда мы наиболее уязвимы?»
- «Покажи heatmap по дням-часам для `payment-service`, только ERROR, последние 14 дней.»

---

### `traffic_stats`

**Назначение**: Request rate (RPM) и percentile-латентность (p50, p95,
p99) по сервису.

**Основные параметры**: `appSlug`, `from`, `to`, `serviceName`.

**Примеры промптов**:

- «Покажи RPM и латентность p95/p99 для `api-gateway` за последний час.»
- «Сравни traffic и latency `billing` и `payment` за последние 24 часа.»

---

### `error_stats_breakdown`

**Назначение**: Статистическая разбивка ошибок по произвольному полю
(browser, appVersion, deploymentEnv и т. д.). Возвращает counts и shares.

**Основные параметры**: `appSlug`, `from`, `to`, `dimension`, `level`.

**Примеры промптов**:

- «Разбей ошибки по browser за 7 дней — какая доля мобильных?»
- «Распределение ошибок по `appVersion` за 24 часа.»
- «Stats по deploymentEnv за неделю.»

---

## Группировка и корреляции

### `find_similar_errors`

**Назначение**: Агрегаты вокруг указанной ошибки (по fingerprint):
`totalOccurrences`, счётчики lastHour / 24h / 7d, топ URL и IP,
client/server split.

**Основные параметры**: `appSlug`, `traceId`.

**Примеры промптов**:

- «Насколько распространена ошибка traceId `abc-123`? Покажи hour / 24h / 7d.»
- «Найди похожие ошибки на `xyz789` — сколько юзеров словили, на каких URL?»

---

### `find_correlated_errors`

**Назначение**: Ошибки, случившиеся в ±N минут вокруг указанного
traceId — для диагностики каскадных сбоев.

**Основные параметры**: `appSlug`, `traceId`, `windowMinutes` (default 5).

**Примеры промптов**:

- «Что ещё сломалось в 5 минутах вокруг traceId `abc-123`?»
- «Покажи ошибки коррелирующие с `xyz789` в окне ±15 минут — кажется тут каскад.»

---

### `grouped_errors`

**Назначение**: Группировка ошибок по fingerprint — список уникальных
сигнатур с counts.

**Основные параметры**: `appSlug`, `from`, `to`, `limit`, `level`,
`serviceName`.

**Примеры промптов**:

- «Сгруппируй ошибки за 24 часа по fingerprint — сколько уникальных проблем?»
- «Топ-15 уникальных fingerprint за неделю.»

---

## Impact и регрессии

### `impact_analysis`

**Назначение**: Severity scoring ошибки — сколько юзеров, сессий, URL
затронуто, с учётом URL-weight.

**Основные параметры**: `appSlug`, `traceId` или `fingerprint`, `from`,
`to`.

**Примеры промптов**:

- «Насколько серьёзна ошибка traceId `abc-123`? Посчитай impact.»
- «Отранжируй impact топ-10 fingerprint за неделю — что чинить первым?»

---

### `baseline_compare`

**Назначение**: Сравнение текущего окна с baseline-периодом. Детектит
регрессии (рост error count, рост error rate, рост latency).

**Основные параметры**: `appSlug`, `from`, `to`, `baselineFrom`,
`baselineTo`.

**Примеры промптов**:

- «Сравни сегодняшние ошибки с тем же временем вчера — что регрессировало?»
- «Baseline-сравнение последнего часа против среднего за 24 часа.»

---

### `version_regression`

**Назначение**: Per-version timeline counts ошибок. Видно какой релиз
ввёл или починил какую проблему.

**Основные параметры**: `appSlug`, `from`, `to`, `serviceName`.

**Примеры промптов**:

- «Какие ошибки появились в `v2.4.1` приложения `lk` и не было в `v2.4.0`?»
- «Покажи version-by-version regression timeline для `payment-service` за 30 дней.»

---

## Триаж и AI

### `triage_recent_critical`

**Назначение**: Композитный инструмент для быстрого триажа CRITICAL
ошибок за последние N минут. Объединяет `search_logs` +
`find_similar_errors` + `impact_analysis` в одну приоритизированную
сводку.

**Основные параметры**: `appSlug`, `minutesBack` (default 30).

**Примеры промптов**:

- «Сделай триаж CRITICAL за последние 30 минут — отдай ранжированный список.»
- «Что сейчас горит в `lk`? Покажи топ критических с impact.»

---

### `explain_error`

**Назначение**: Возвращает контекст ошибки (stack, headers, similar
counts, correlated traces), чтобы LLM мог сам синтезировать объяснение
причины. Полноценный AI-summary запланирован на следующие релизы —
сейчас LLM-клиент делает синтез сам.

**Основные параметры**: `appSlug`, `traceId`.

**Примеры промптов**:

- «Объясни ошибку traceId `abc-123` — что могло быть причиной?»
- «Пройдись по сбою `xyz789` и предложи фикс.»

---

### `list_apps`

**Назначение**: Список приложений (tenants), к которым текущий API-ключ
имеет доступ. Master-keys видят все приложения; обычные ключи получают
`[{ slug: '(current-app)' }]` как graceful fallback.

**Основные параметры**: нет.

**Примеры промптов**:

- «Какие приложения я могу запрашивать?»
- «Список доступных appSlug для моего ключа.»