Skip to main content
Glama
perejaslav

DirectAI MCP

by perejaslav

DirectAI MCP — личный сервер статистики и управления Яндекс Директом

ИИ-агент? Следуй AGENTS.md.

DirectAI MCP is a local MCP server for Yandex Direct stats and management. Runs on your Windows 11 PC for a single user. Tested on Windows 11 only; macOS/Linux not supported. Start install at §1 below.

Локальный MCP-сервер: ИИ-ассистенты (OpenCode, Codex и др.) через него читают статистику и управляют вашими аккаунтами Яндекс Директа. Только для одного пользователя, работает на вашем компьютере, в интернет ничего не выставляет.

Прежде чем устанавливать

Обязательно:

  • Windows 11 (инструкции — только для PowerShell; macOS/Linux не тестировались и не поддерживаются);

  • аккаунт Яндекс Директа с хотя бы одной кампанией (можно черновик); для агентств — главный логин агентства;

  • своё приложение на oauth.yandex.ru (анкета на 5 минут, права Директ и Метрика) — запомните ID приложения;

  • одобренный доступ к API Директа (Инструменты → API → заявка с ID приложения); одобрение занимает до нескольких дней;

  • ИИ-помощник с поддержкой MCP (OpenCode, Codex, Claude Code, Claude Desktop, Hermes); сам DirectAI бесплатный, работает локально на вашем компьютере, для одного пользователя.

По ходу установки: токен получаете по ссылке, вводите сами в своём терминале, никогда не в чат.

Желательно: доступ к счётчику Метрики (иначе CRM-выручка не отличается от условной ценности целей).

Не нужно: программировать, покупать сервер, заранее ставить git или Python.

С чего начать

  1. Создайте приложение и подайте заявку на API — это самое долгое, начните с этого (подробности — §1.1, шаг 5).

  2. Пока ждёте одобрения — установите DirectAI (§1 или §1.1).

  3. Когда заявку одобрят — получите токен и выполните проверку (set-token, затем check).

Related MCP server: MCP «Яндекс Директ»

1. Установка с нуля

Нужно: Windows 11, uv, git (оба ставятся через winget, см. §1.1), токен Яндекс Директа (как получить — см. §1.1, нужен доступ к API).

cd $env:USERPROFILE
git clone https://github.com/perejaslav/directai-mcp.git directai-mcp
cd $env:USERPROFILE\directai-mcp
uv tool install --editable .
uv tool update-shell
directai-mcp init
directai-mcp set-token --login ВАШ_ЛОГИН
directai-mcp check

Впишите свой логин в %USERPROFILE%\.directai\accounts.toml ([auth] login, замените демо-алиасы) между init и set-token; в set-token передайте тот же логин флагом --login.

Что происходит: init создаёт %USERPROFILE%\.directai\ и копирует примеры конфигов (существующие не трогает); set-token маскированно спрашивает токен и кладёт его в Credential Manager Windows (в файлах токена нет никогда); check проверяет доступ. Ожидание — строки OK по каждому аккаунту с числом кампаний и остатком баллов.

1.1. Установка через ИИ-агента — промпт для новичка

Новичок (свой аккаунт Директа, ничего общего с автором) копирует блок ниже в любого агента (OpenCode, Codex, Claude Code) — агент ставит всё с нуля.

Ты помогаешь новичку установить DirectAI MCP с нуля на Windows 11.
Человек не знает git, uv и PowerShell. Объясняй простыми словами,
одно действие за раз. Каждую команду давай отдельно, жди результата.
Правила: бюджеты и стратегию не менять; guard не выключать никогда;
запись только через план с подтверждением; токен только в Credential Manager.
0. Сначала спроси, одобрен ли уже доступ к API Директа. Нет — начни
с шага 5 (создать приложение и подать заявку: это самое долгое),
затем ставь DirectAI (шаги 1–4), а токен и check — после одобрения.
Доступ уже одобрен — иди по шагам 1–4, затем токен и проверка.
1. Спроси разрешение и поставь git и uv (флаги снимают лишние вопросы):
winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements
winget install --id astral-sh.uv -e --accept-package-agreements --accept-source-agreements
Проверь: git --version и uv --version. Нет команды — обнови PATH в этой сессии
(давай строку одним блоком, проверь, что вставилась одной строкой):
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
Нет winget — поставь App Installer из Microsoft Store.
2. Склонируй репозиторий (три команды, по одной). Папка directai-mcp уже есть —
не клонируй, а выполни git pull внутри неё:
cd $env:USERPROFILE
git clone https://github.com/perejaslav/directai-mcp.git directai-mcp
cd $env:USERPROFILE\directai-mcp
3. Установи и инициализируй (по одной команде):
uv tool install --editable .
uv tool update-shell
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
directai-mcp --version
directai-mcp init
Первая установка качает Python несколько минут — это не зависание.
4. Спроси логины кабинетов (это не секрет): главный — владелец будущего токена.
Если кабинетов несколько (агентство: главный логин видит клиентские) —
попроси все. ПОЛНОСТЬЮ замени демо-алиасы в %USERPROFILE%\.directai\accounts.toml:
[auth] login — реальный главный логин, под каждый логин свой [aliases.*].
goals.toml необязателен: названия целей Метрики, можно заполнить позже.
5. Токен. Объясни: создай приложение типа «Для доступа к API или отладки»
на https://oauth.yandex.ru/client/new с правами direct:api и metrika:read.
Redirect URI настраивать не нужно — он фиксирован. Затем открой в браузере ссылку
https://oauth.yandex.ru/authorize?response_type=token&client_id=ID_ПРИЛОЖЕНИЯ&redirect_uri=https://oauth.yandex.ru/verification_code
(подставь ID со страницы приложения) и нажми «Разрешить» — токен появится
в адресной строке. Скопируй ТОЛЬКО значение после access_token= и до &,
не весь URL (вид: access_token=y0_AgA...&token_type=...). Спроси «что видишь?»:
ошибка OAuth — проверить ID приложения и пробелы. Это штатный способ из доки:
https://yandex.ru/dev/direct/doc/ru/concepts/auth-token. Затем подай заявку
на доступ к API в интерфейсе Директа (Инструменты → API → Мои заявки),
инструкция: https://yandex.ru/dev/direct/doc/ru/concepts/register.
В описании заявки укажи «личный учёт статистики и управление своими кампаниями».
Одобрение занимает до нескольких дней — ошибка 58 до этого норма, просто ждём.
Без metrika:read типы ценностей берутся из goals.toml (по умолчанию условные).
6. Токен в чат писать ЗАПРЕЩЕНО. Пусть человек САМ выполнит в своём терминале:
directai-mcp set-token — и введёт токен в скрытое поле. Символы не отображаются —
это нормально: вставить и Enter. Если вставил в чат — останови, попроси
отозвать токен в Яндекс ID и выпустить новый.
7. Проверь: directai-mcp check. Расшифруй итог: OK — работает; 53 — неверный
токен, повторить шаг 6; 58 — нет доступа к API, вернуться к шагу 5; 513 —
у логина нет аккаунта в Директе (создай кампанию в интерфейсе); 152 —
кончились баллы API, подождать до завтра. Коды:
https://yandex.ru/dev/direct/doc/ref-v5/concepts/errors-list.html
8. Самопроверка сервера: directai-mcp probe. Ожидание — две строки OK
(версия сервера, число инструментов, stats_summary найден). Баллы API
не тратятся. Сырые stdio-пробы вручную не делать — только probe.
9. Подключи харнес: сначала спроси, какой — OpenCode, Codex или Claude Code.
Сделай копию его конфига (*.bak), потом ДОПИШИ блок directai-mcp, чужие MCP
не трогай. Готовые блоки — examples/harness-configs.md.
9. Попроси человека САМОГО перезапустить харнес (закрыть все его окна
и открыть заново). В новой сессии пусть спросит:
«Используй только directai-mcp: покажи расходы по всем аккаунтам за вчера» —
и сверит цифры с веб-интерфейсом Директа. Сошлось — готово.
10. Удали свои бэкапы (*.bak-*, *-tool-backup-*), чужие файлы не трогай.

2. Подключение к харнесам

Команда запуска везде одна — directai-mcp (без аргументов: STDIO-сервер). После настройки перезапустите харнес.

OpenCode — файл %USERPROFILE%\.config\opencode\opencode.json:

{
  "mcp": {
    "directai-mcp": {
      "type": "local",
      "command": ["directai-mcp"],
      "enabled": true
    }
  }
}

Codex — файл %USERPROFILE%\.codex\config.toml:

[mcp_servers.directai-mcp]
command = "directai-mcp"
args = []

Остальные (Claude Desktop, Claude Code) — готовые фрагменты в examples/harness-configs.md. Если харнес не видит команду, укажите полный путь к directai-mcp.exe (покажет (Get-Command directai-mcp).Source).

Проверка (задать ИИ): «Покажи расходы по всем аккаунтам за последние 7 дней» — итоги должны совпасть с веб-интерфейсом Директа.

3. Файлы в %USERPROFILE%\.directai\

Файл

Что внутри и как править

accounts.toml

Ваши кабинеты: [auth] login — владелец токена, под каждый логин свой [aliases.*] (короткое имя и роль). Плюс defaults (include_vat, max_rows, attribution) и секция [guard]. Секретов здесь нет. Править любым текстовым редактором, применяется со следующего запроса.

rules.toml

Правила: обязательный DisplayUrlPath, слова для заголовков, пороги max_budget_ratio / max_bid_ratio (предупреждения при резких изменениях).

goals.toml

id цели → Название (цели Метрики). В отчётах цель видна как «Название (id)», без названия — голый id. Названия вписываете вы.

journal.sqlite

Журнал всех записей (не удаляйте).

exports\

CSV/MD-выгрузки из отчётов.

logs\

Логи сервера.

Переопределить каталог: переменная DIRECTAI_HOME. Токен: только Credential Manager (directai-mcp) или переменная DIRECTAI_TOKEN.

4. Что умеет сервер

Порядок работы ИИ: search_actions → describe_action → run_read (чтение) или plan_write → показать вам → apply_write (запись).

Чтение (29):

Действие

Что делает

stats_summary

Итоги по аккаунтам: показы, клики, расход, конверсии

stats_campaigns

Статистика по кампаниям

stats_adgroups

Статистика по группам объявлений

stats_ads

Статистика по объявлениям

stats_keywords

Статистика по фразам и автотаргетингу

stats_search_queries

Поисковые запросы пользователей

stats_regions

Статистика по регионам местонахождения

stats_placements

Статистика по площадкам РСЯ

stats_devices

Статистика по устройствам

stats_audiences

Статистика по аудиториям и ретаргетингу

stats_compare

Сравнение двух периодов (только так, не вручную)

stats_custom

Произвольный отчёт: свои поля и фильтры

campaigns_list, campaigns_get

Список и полные настройки кампаний

adgroups_list

Группы кампании

ads_list

Объявления (ссылки, уточнения, DisplayUrlPath)

keywords_list

Фразы группы или кампании

negatives_audit

Все минус-фразы кампании одним ответом

extensions_list

Быстрые ссылки, уточнения, изображения

audiences_list

Аудиторные условия и списки ретаргетинга

bids_get

Ставки фраз (поиск и сети)

bid_modifiers_get

Корректировки ставок

dictionaries_get

Справочники (регионы по названию)

changes_check

Что менялось с даты

accounts_discover, accounts_check, accounts_balance

Кабинеты: поиск, проверка доступа, баллы

counter_check

Проверка счётчиков Метрики кампании

moderation_check

Статусы модерации объявлений

Запись (15, все — только через план, см. §5):

Действие

Что делает

campaigns_create, campaigns_update, campaigns_state

Создание, изменение, остановка/архив кампаний

adgroups_create, adgroups_update

Создание и изменение групп

ads_create, ads_update, ads_state

Создание, изменение, состояние объявлений

keywords_add, keywords_update, keywords_state

Фразы: пакетное добавление, тексты, состояние

negatives_set

Минус-фразы кампании/групп и общие наборы

extensions_create

Ссылки, уточнения, изображения

bids_set

Ставки фраз (поиск и сети)

bid_modifiers_set

Корректировки: добавить, изменить, удалить

5. Как работает запись

  1. ИИ вызывает plan_write — сервер показывает предпросмотр «было → станет» и предупреждения (например, ставка меняется больше чем в 2 раза).

  2. Вы читаете предпросмотр и явно разрешаете.

  3. ИИ вызывает apply_write (с acknowledge_warnings=true, если были предупреждения) — сервер выполняет, затем повторно читает объект (read-back) и пишет всё в журнал.

  4. Итог: applied (подтверждено), partial (часть строк отклонена API), failed, unverified (результат неясен — проверить вручную).

Журнал: инструмент get_operation_log (последние операции) и файл journal.sqlite. Прямых записей в обход плана не бывает. Что можно где: бюджеты и смена стратегии запрещены везде; в боевых кампаниях разрешены фразы (добавление, пауза/запуск), объявления (создание, тексты, ссылки), ссылки/уточнения, регионы групп, минусы и площадки (добавление), ставки и корректировки; замена целиком (replace), пауза кампаний и объявлений, удаления — только в тестовых кампаниях [TEST DirectAI]*.

6. Guard (защита)

Опасные операции — строго внутри кампаний [TEST DirectAI]*. Guard это контролирует: перед каждой записью сверяет живое имя кампании через API.

Как завести тестовую кампанию: создайте в интерфейсе Директа кампанию с именем, начинающимся на [TEST DirectAI] (можно черновик); только в ней доступны replace, пауза кампаний/объявлений, удаления.

Коротко о правилах:

  • бюджеты и смена стратегии — запрещены везде, даже в тестовых;

  • в боевых кампаниях можно: фразы, объявления, ссылки/уточнения, регионы, минусы и ставки (см. §5);

  • только в тестовых: замены целиком, пауза кампаний/объявлений, удаления.

Блокируется: запись вне разрешённого, переименование кампаний, модерация, чужие общие объекты, неизвестные действия.

Включён по умолчанию ([guard] guard=true в accounts.toml плюс дефолт в коде). Выключение — только вашим решением: поставьте guard = false (и убедитесь, что нет переменной DIRECTAI_TEST_GUARD=1), после тестов верните true.

6.1 Правило для агентов-клиентов MCP

Текст блокировки guard — это защита, а не ошибка.

При блокировке агент:

  1. останавливается и сообщает вам: какая операция, какой объект, почему заблокирована;

  2. не ищет и не меняет конфиг guard (accounts.toml, секция [guard], переменная DIRECTAI_TEST_GUARD) и вообще ничего в safety/;

  3. не предлагает обход защиты;

  4. не переносит операцию на другую кампанию (в т.ч. тестовую) без вашего явного указания.

Снятие ограничения — только ваше ручное решение (см. §6). Ни один инструмент сервера конфиг guard не пишет и не читает наружу: единственный источник — accounts.toml и переменная окружения.

6.2 Сравнение периодов и выбор инструмента

  1. Сравнение периодов агент выполняет только через stats_compare (A, B, Δ абс., Δ% одним вызовом). Два вызова stats_* с ручной арифметикой запрещены — они дают разную точность Δ%.

  2. Если вы указали конкретный MCP-сервер или инструмент — агент использует только его и не подменяет другим.

7. Обновление

Перед обновлением: закройте все окна харнесов и остановите фоновый шлюз Hermes (он держит directai-mcp.exe даже при закрытых окнах) — команды выполняет человек в обычном PowerShell:

Get-Process directai-mcp -ErrorAction SilentlyContinue | Stop-Process
Get-CimInstance Win32_Process -Filter 'Name="python.exe"' |
  Where-Object { $_.CommandLine -like '*hermes_cli.main*gateway run*' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId }

Обновление с бэкапом вне uv tool dir и откатом при ошибке (без exit — он закрывает окно PowerShell):

cd $env:USERPROFILE\directai-mcp
git pull
$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$tooldir = uv tool dir
Copy-Item "$tooldir\directai-mcp" "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" -Recurse
uv tool install --editable .
uv tool update-shell
if ($LASTEXITCODE -ne 0) {
  Remove-Item "$tooldir\directai-mcp" -Recurse -Force
  Copy-Item "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" "$tooldir\directai-mcp" -Recurse
  Write-Output "ОТКАТ: инструмент восстановлен из бэкапа"
} else {
  directai-mcp check
  directai-mcp probe
  Remove-Item "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" -Recurse -Force
}

init после обновления можно повторить: существующие конфиги не затрутся, недостающие (например, новые примеры) докопируются. После обновления откройте харнесы заново и запустите Hermes (сервер подхватывается при старте). Никогда не делайте cd внутрь каталога установки (uv tool dir): бэкап перед установкой — только вне tool dir (копии внутри tool dir uv считает инструментами и выдаёт malformed); бэкап удаляется только при успехе, при ошибке — откат из бэкапа.

8. Типичные ошибки

Симптом

Что делать

Ошибка 53 (авторизация)

Токен недействителен: directai-mcp set-token, затем check

Ошибка 58 (регистрация приложения)

Завершите заявку на доступ к API в интерфейсе Директа

Ошибка 513 (логин не подключён)

Логин не привязан к Директу — проверьте Client-Login/аккаунт

Не хватает баллов API

Подождите сброса лимита; остаток виден в check

Харнес не видит сервер

Стабильный путь к exe — (Get-Command directai-mcp).Source (обычно %USERPROFILE%\.local\bin\directai-mcp.exe); перезапуск харнеса, логи в .directai\logs

План с предупреждениями не применяется

Это защита: повторите apply_write с acknowledge_warnings=true только после вашего согласия

token missing for login 'X'

Токен сохранён под другим логином: выполните directai-mcp set-token --login <[auth] login> с логином из accounts.toml

Ignoring malformed tool

Битая копия/рецепт, не повод сносить рабочий инструмент: закройте все окна харнесов и переустановите с --force (бэкап — вне tool dir). uninstall — только для заведомо мусорных записей

os error 32 при переустановке

exe занят MCP-клиентами: покажите владельцев (Get-CimInstance Win32_Process -Filter 'Name="directai-mcp.exe"', поле ParentProcessId), чужие процессы не убивайте. Шлюз Hermes (python.exe … hermes_cli.main … gateway run) работает в фоне и держит exe даже при закрытых окнах — человек останавливает его сам (см. §7: остановка сервера и шлюза), после установки запускает Hermes заново. Висящие opencode serve — тоже владельцы: их закрывают штатно, не kill

Как быстро проверить сервер

directai-mcp --version → check → probe (две строки OK, stats_summary найден; баллы не тратятся). Сырые stdio-пробы вручную не делать

9. Что отложено

Вордстат, удалённый HTTP-режим, многопользовательский режим. Метрика частично уже внутри: типы целей — из API Метрики (metrika:read), goals.toml — названия и запасной тип; счётчики проверяет counter_check.

Available Tools

7 tools
apply_writeB

Применить план. Только после согласия пользователя.

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYes
acknowledge_warningsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. The description implies a write/mutation operation ('apply') but doesn't disclose what the plan application does, whether it's reversible, what side effects occur, or what happens with warnings. The acknowledge_warnings parameter hints at potential destructive or risky behavior, but the description doesn't explain this. This is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two short phrases. It front-loads the core action and the critical consent requirement. However, it's so brief that it sacrifices necessary behavioral detail. Still, for what it does say, it's efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema and 2 parameters, the description is incomplete. It doesn't explain the plan application process, the role of acknowledge_warnings, what the output represents, or any side effects. The consent requirement is useful but insufficient for an agent to confidently invoke this tool, especially since it appears to be a write operation with potential warnings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It doesn't explain what plan_id refers to or what acknowledge_warnings does. The parameter names are somewhat self-explanatory, but the description adds no meaning beyond the schema. The acknowledge_warnings parameter especially needs explanation (what warnings? why acknowledge?).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Применить план' (Apply the plan) clearly identifies the action: executing a previously created plan. It distinguishes itself from siblings like plan_write (which creates the plan) and run_read (which performs read operations). However, it doesn't explicitly name the sibling alternatives, so it loses a point for not fully differentiating itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states a critical usage condition: 'Только после согласия пользователя' (Only after user consent). This is explicit guidance on when to use the tool. It doesn't explicitly mention alternatives or when not to use it, but the consent requirement is a strong contextual signal that this is a confirmation step after planning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_actionC

Описание действия: параметры (JSON Schema), пример, ограничения.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full burden. It only mentions that it describes parameters, example, and restrictions, but does not disclose whether the operation is read-only, has side effects, requires authentication, or any other behavioral traits. The description is insufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (one line), but this is under-specification rather than effective conciseness. It omits critical details that an agent needs, so brevity is not a virtue here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists, the description does not explain what the tool returns beyond vague mentions of 'example' and 'restrictions'. With a single parameter and no behavioral context, the definition is far from complete for reliable tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter 'name' with type string, but the description does not explain its meaning or expected format. Schema description coverage is 0%, and the phrase 'parameters (JSON Schema)' merely repeats the schema structure without adding semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Action description: parameters (JSON Schema), example, restrictions' which is vague and does not specify a concrete verb or resource. It reads as a template rather than a specific tool purpose, and it does not differentiate from siblings like list_accounts or search_actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of contexts, exclusions, or preferred scenarios, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_operation_logC

Последние операции записи из журнала.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
accountNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the full burden. It does add useful behavioral context by stating the tool returns recent write operations from the journal, which implies a safe read operation. However, it does not disclose ordering, scoping, or account-filter behavior explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact phrase with no filler, and the core meaning is front-loaded. It is appropriately terse, though the brevity sacrifices useful usage and parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and has an output schema, but the description omits when to use it, what the parameters do, and any log-specific behavior. An agent could guess the basics, but the description alone is not complete enough for confident selection and correct parameter usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the meaning or interaction of 'limit' and 'account' beyond their names and defaults. Since the schema itself provides no descriptions, the tool description needed to compensate but did not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies a read operation returning the most recent write operations from the journal, and the tool name reinforces the resource. It is distinguishable from siblings like list_accounts and apply_write, though it does not explicitly differentiate itself from search_actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus search_actions or other siblings. There are no stated exclusions, prerequisites, or alternative conditions; the intended use is only implied by the word 'latest'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsB

Кабинеты из кеша discover, активные кампании, остаток баллов.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It mentions 'from discover cache,' indicating the data is cached, and specifies the type of data (active campaigns, balance). However, it does not explicitly state that this is a read-only operation, whether it requires authentication, or any side effects. For a listing tool, read-only is likely, but it is not stated. The description provides some behavioral context but falls short of full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the key data points. It is front-loaded with the source (cache) and the main outputs. It is efficient with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description only needs to clarify purpose and usage. It provides some context (what data is returned) but lacks any guidance on when to use it versus siblings. For a simple listing tool, the missing usage guidance is a notable gap. The description is adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially complete. The description does not need to add parameter details. A baseline of 4 is appropriate because no parameter information is missing or ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description lists what the tool returns (accounts from cache, active campaigns, balance) but does not clearly state the action (listing). It is more of a summary of output than a purpose statement. It avoids a pure tautology by adding details, but it is not a specific verb+resource description. The name 'list_accounts' hints at the action, so an agent could infer it, but the description itself is vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The sibling tools (search_actions, describe_action, run_read, plan_write, apply_write, get_operation_log) suggest different operation types, but the description does not differentiate or recommend one. An agent would have to guess based on the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plan_writeC

Подготовить запись: предпросмотр, предупреждения, plan_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It conveys that the tool produces a preview and warnings rather than directly applying a change, which is useful, but it does not explicitly state side-effect safety, authorization needs, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence front-loaded with the verb and key artifacts. There is no filler or repetition, although the brevity comes at the cost of missing input guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema likely covers return values, but the description is otherwise incomplete: it does not explain what name/params mean, how the plan connects to apply_write, or any preconditions. For a tool with a free-form params object, this is too thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description adds no meaning to 'name' or 'params'. 'params' is an open object with no documented keys, and 'name' could be an action identifier or something else; an agent cannot reliably construct valid input. The only related term, plan_id, appears as an output artifact, not an input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete operation ('prepare a write') and names the artifacts it produces (preview, warnings, plan_id). This distinguishes it at the intent level from apply_write, though it never explicitly names the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The verb 'prepare' plus preview/warnings/plan_id implies this is a pre-flight step before apply_write rather than an actual mutation. However, it never explicitly states when to use it vs. alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_readC

Выполнить действие чтения. Возвращает Markdown-текст.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
paramsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the output is Markdown, but says nothing about read-only guarantees, error behavior, permissions, rate limits, or side effects. 'Чтения' implies a read, but this is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and the second sentence about Markdown output provides useful information. However, the first sentence merely restates the tool name, so part of the text is redundant. It is concise but under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 0% schema coverage and no annotations, this description is far from complete. It does not explain how to select a value for 'name', what read actions exist, or what 'params' should contain. The output schema exists but cannot compensate for missing invocation guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not mention the parameters 'name' or 'params' at all. It fails to explain what 'name' refers to, what valid values exist, or how 'params' should be structured, adding zero semantic value beyond the bare schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase 'Выполнить действие чтения' is essentially a restatement of the tool name 'run_read', not a specific verb+resource description. It adds that output is Markdown, but does not clarify what read action, resource, or domain it operates on, leaving the purpose vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus siblings like search_actions or describe_action. The description does not mention any prerequisites, alternatives, or selection criteria, so the agent gets no help deciding when run_read is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_actionsC

Поиск действий каталога. mode: read, write или any.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoany
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full disclosure burden. It only says 'search' and lists mode values; it does not state whether the call is read-only, whether permissions are required, or what happens with no matches. The non-mutating nature of search is inferable but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded: the operation is stated first and there is no filler. It is terse to the point of being telegraphic, but that still serves conciseness well.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though the parameter count is small and an output schema exists, the description omits query semantics, mode semantics, and how this tool relates to siblings like describe_action or run_read. It is not complete enough for an agent to select and invoke reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for both parameters. It adds allowed values for mode ('read, write or any') but does not explain what mode means or what the query should contain, leaving query entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Поиск' = search) and a resource ('действий каталога' = catalog actions), and it adds the mode filter. It does not precisely define what counts as an 'action' or how it differs from siblings like describe_action, but the core purpose is identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call search_actions rather than list_accounts, describe_action, or get_operation_log. The mode values hint at filtering, but no explicit context, prerequisites, or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.2.2
    • First observedapply_write
    • First observeddescribe_action
    • First observedget_operation_log
    • First observedlist_accounts
    • First observedplan_write
    • First observedrun_read
    • First observedsearch_actions

TDQS

B3.1/5.0

Scored across 7 tools

Disambiguation5/5

Each tool maps to a distinct stage or resource: account listing, catalog search, action introspection, read execution, write planning, write application, and logging. The plan/apply pair is complementary rather than ambiguous, and read/execute vs. catalog search are clearly separated.

Naming Consistency5/5

All tool names follow a consistent lowercase snake_case verb-first pattern: list_, search_, describe_, run_, plan_, apply_, get_. The naming style is uniform and predictable across the entire set.

Tool Count5/5

Seven tools is well within the ideal range and each tool earns its place in the workflow. The count matches the server's apparent scope: account discovery, action inspection, read execution, and a two-phase write flow.

Completeness4/5

The toolset covers the main lifecycle well: discover accounts, search and describe actions, run reads, plan writes, apply them, and review the operation log. Minor gaps exist, such as no explicit cancel-plan operation or fetching a single log entry by ID, but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    A local MCP server that connects Yandex Direct advertising reports and safe campaign creation to AI agents, enabling natural-language analytics and protected campaign setup.
    8
    2
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.
    2
    1
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to work with Yandex Webmaster, Direct, and Metrika data through natural language, including managing sites, sitemaps, recrawls, ad campaigns with write-safety guards, and pulling traffic, conversion, and ad statistics.
    MIT