Skip to main content
Glama
Yandex Direct MCP

Yandex Direct MCP

Статистика

get_statistics
Read-onlyIdempotent

Retrieves Yandex Direct performance reports with configurable metrics, date ranges, filters, and campaign breakdowns; supports period comparisons for analyzing ad efficiency.

Instructions

Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа. По умолчанию отчёт АГРЕГИРОВАН за весь период (одна строка на объект) — добавлять "Date" в fieldNames только для динамики по дням или вопросов о трендах. Почасовой статистики в Reports нет: минимум — сутки, внутридневную динамику дают только повторные снимки TODAY. Готового ROAS нет — считать Revenue / Cost; GoalsRoi — это ROI ((Revenue − Cost) / Cost), не ROAS. Revenue, Profit, GoalsRoi и конверсии заполняются только по целям Метрики с ценностью. ALL_TIME без фильтра по кампаниям отклоняется для отчётов SEARCH_QUERY/CRITERIA: нужно передать campaignIds или ограниченный период. SEARCH_QUERY_PERFORMANCE_REPORT возвращает не сырые строки, а ВЫЧИСЛЕННУЮ СВОДКУ (итоги по ВСЕМ строкам + детализация top-N + свёртка хвоста + количество строк без кликов и без конверсий); её форму задают sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly, а для подсчётов по конверсиям нужно добавить Conversions в fieldNames. Остальные типы отчётов возвращают строки, разделённые табуляцией (без заголовка). compareTo — сравнение двух периодов: инструмент запускает ДВЕ задачи Reports (текущий период dateFrom/dateTo и compareTo) и возвращает JSON, где строки сопоставлены по разрезам отчёта (matchKey; название кампании или группы не учитывается, если запрошен её id — переименование не ломает сопоставление), с current, previous, delta и deltaPct по каждой метрике. Это только значения Яндекса и их разность: вклад факторов (расход = показы × CTR × CPC) инструмент не считает — при объяснении изменений считать по колонкам ответа и называть порядок факторов. Последние ~3 дня статистики Яндекс может пересчитать.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_statistics"
  }
}

Input Schema

NameRequiredDescriptionDefault
topNNoМаксимум строк детализации в сводке (на сервере ограничено 100). По умолчанию 50.
goalsNoId целей Яндекс Метрики (не более 10). Без них Conversions и Revenue считаются по всем целям кампании; с ними колонки приходят как <поле>_<idЦели>_<модель> (по одной на цель × модель). Для SEARCH_QUERY_PERFORMANCE_REPORT и compareTo сводка разбирает только одну цель и одну модель (ограничение инструмента, не API).
orderNoПорядок сортировки строк детализации. По умолчанию desc.
dateToNoДата окончания YYYY-MM-DD (обязательна для CUSTOM_DATE).
sortByNoМетрика для ранжирования строк детализации. По умолчанию Cost.
filtersNoПроизвольные условия SelectionCriteria.Filter, складываются с campaignIds по И. Например Clicks GREATER_THAN 0 или Device EQUALS MOBILE.
minCostNoВключать в детализацию только строки с Cost >= этого значения.
dateFromNoДата начала YYYY-MM-DD (обязательна для CUSTOM_DATE).
compareToNoПериод, с которым сравнить текущий (dateFrom/dateTo, обязательны). Лучше той же длины. Не для SEARCH_QUERY_PERFORMANCE_REPORT и не с Date/Week/Month/Quarter/Year в fieldNames. sortBy задаёт сортировку по |delta|, topN — сколько строк показать.
fieldNamesNoКолонки отчёта (должны быть допустимы для его типа). Сверх базовых метрик: Conversions, ConversionRate, CostPerConversion, Revenue, Profit, GoalsRoi. Разрезы CUSTOM_REPORT: Date, Device, Age, Gender, LocationOfPresenceName, Placement, AdNetworkType, Slot и др.
includeVatNoВключать ли НДС в расход. По умолчанию true.
reportTypeNoТип отчёта. По умолчанию CAMPAIGN_PERFORMANCE_REPORT.
campaignIdsNoОграничить отчёт этими id кампаний.
client_loginNoЛогин клиента агентства или кабинета в управлении (из list_clients). Если не указан — YANDEX_DIRECT_LOGIN из конфигурации, а без него собственный аккаунт токена.
dateRangeTypeNoПредустановленный период. Если заданы dateFrom/dateTo, подставляется CUSTOM_DATE.
queryContainsNoВключать только строки, где запрос или условие содержит эту подстроку (без учёта регистра).
zeroClicksOnlyNoВключать в детализацию только строки с 0 кликов.
attributionModelsNoМодели атрибуции для конверсий по целям из goals; без goals не применяются (API их тогда не принимает). По умолчанию LC (последний переход).
zeroConversionsOnlyNoТолько строки с clicks>0 и 0 конверсий (нужно Conversions в fieldNames).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.12.1
    • addedInput schema / properties / compareTo
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Период, с которым сравнить текущий (dateFrom/dateTo, обязательны). Лучше той же длины. Не для SEARCH_QUERY_PERFORMANCE_REPORT и не с Date/Week/Month/Quarter/Year в fieldNames. sortBy задаёт сортировку по |delta|, topN — сколько строк показать.",
      +  "properties": {
      +    "dateFrom": {
      +      "description": "Начало периода для сравнения, YYYY-MM-DD.",
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +      "type": "string"
      +    },
      +    "dateTo": {
      +      "description": "Конец периода для сравнения, YYYY-MM-DD.",
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "dateFrom",
      +    "dateTo"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / fieldNames / items / enum
      Added value: +[
      +  "AdFormat",
      +  "AdGroupId",
      +  "AdGroupName",
      +  "AdId",
      +  "AdNetworkType",
      +  "Age",
      +  "AvgClickPosition",
      +  "AvgCpc",
      +  "AvgCpm",
      +  "AvgEffectiveBid",
      +  "AvgImpressionFrequency",
      +  "AvgImpressionPosition",
      +  "AvgPageviews",
      +  "AvgTrafficVolume",
      +  "AvgVideoCompleteCost",
      +  "BounceRate",
      +  "Bounces",
      +  "CampaignId",
      +  "CampaignName",
      +  "CampaignUrlPath",
      +  "CampaignType",
      +  "CarrierType",
      +  "Clicks",
      +  "ClickType",
      +  "ClientLogin",
      +  "ConversionRate",
      +  "Conversions",
      +  "Cost",
      +  "CostPerConversion",
      +  "CPV",
      +  "Criteria",
      +  "CriteriaId",
      +  "CriteriaType",
      +  "Criterion",
      +  "CriterionId",
      +  "CriterionType",
      +  "Ctr",
      +  "Date",
      +  "Device",
      +  "ExternalNetworkName",
      +  "Gender",
      +  "GoalsRoi",
      +  "ImpressionReach",
      +  "Impressions",
      +  "IncomeGrade",
      +  "LocationOfPresenceId",
      +  "LocationOfPresenceName",
      +  "MatchedKeyword",
      +  "MatchType",
      +  "MobilePlatform",
      +  "Month",
      +  "Placement",
      +  "Profit",
      +  "PurchaseRevenue",
      +  "PurchaseProfit",
      +  "PurchaseGoalsRoi",
      +  "Quarter",
      +  "Query",
      +  "Revenue",
      +  "RlAdjustmentId",
      +  "Sessions",
      +  "Slot",
      +  "TargetingCategory",
      +  "TargetingLocationId",
      +  "TargetingLocationName",
      +  "VideoComplete",
      +  "VideoCompleteRate",
      +  "VideoFirstQuartile",
      +  "VideoFirstQuartileRate",
      +  "VideoMidpoint",
      +  "VideoMidpointRate",
      +  "VideoThirdQuartile",
      +  "VideoThirdQuartileRate",
      +  "VideoViews",
      +  "VideoViewsRate",
      +  "Week",
      +  "WeightedCtr",
      +  "WeightedImpressions",
      +  "Year"
      +]
    • changedInput schema / properties / goals / description
      Previous value: -"Id целей Яндекс Метрики (не более 10). Без них Conversions и Revenue считаются по всем целям кампании; с ними колонки приходят как <поле>_<idЦели>_<модель> (по одной на цель × модель). Для SEARCH_QUERY_PERFORMANCE_REPORT — только одна цель и одна модель."New value: +"Id целей Яндекс Метрики (не более 10). Без них Conversions и Revenue считаются по всем целям кампании; с ними колонки приходят как <поле>_<idЦели>_<модель> (по одной на цель × модель). Для SEARCH_QUERY_PERFORMANCE_REPORT и compareTo сводка разбирает только одну цель и одну модель (ограничение инструмента, не API)."
  2. Changed1 schema field changedv1.11.0
    • changedInput schema / properties / attributionModels / description
      Previous value: -"Модели атрибуции для конверсий. По умолчанию LC (последний переход)."New value: +"Модели атрибуции для конверсий по целям из goals; без goals не применяются (API их тогда не принимает). По умолчанию LC (последний переход)."
  3. Changed6 schema fields changedv1.5.2
    • addedInput schema / properties / attributionModels
      Added value: +{
      +  "description": "Модели атрибуции для конверсий. По умолчанию LC (последний переход).",
      +  "items": {
      +    "enum": [
      +      "FCCD",
      +      "LC",
      +      "LSCCD",
      +      "AUTO"
      +    ],
      +    "type": "string"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / dateRangeType / enum
      Previous value: -[
      -  "TODAY",
      -  "YESTERDAY",
      -  "LAST_7_DAYS",
      -  "LAST_30_DAYS",
      -  "THIS_MONTH",
      -  "LAST_MONTH",
      -  "ALL_TIME",
      -  "CUSTOM_DATE"
      -]New value: +[
      +  "TODAY",
      +  "YESTERDAY",
      +  "LAST_3_DAYS",
      +  "LAST_5_DAYS",
      +  "LAST_7_DAYS",
      +  "LAST_14_DAYS",
      +  "LAST_30_DAYS",
      +  "LAST_90_DAYS",
      +  "LAST_365_DAYS",
      +  "THIS_WEEK_MON_TODAY",
      +  "THIS_WEEK_SUN_TODAY",
      +  "LAST_WEEK",
      +  "LAST_BUSINESS_WEEK",
      +  "LAST_WEEK_SUN_SAT",
      +  "THIS_MONTH",
      +  "LAST_MONTH",
      +  "ALL_TIME",
      +  "CUSTOM_DATE",
      +  "AUTO"
      +]
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Колонки отчёта (должны быть допустимы для его типа)."New value: +"Колонки отчёта (должны быть допустимы для его типа). Сверх базовых метрик: Conversions, ConversionRate, CostPerConversion, Revenue, Profit, GoalsRoi. Разрезы CUSTOM_REPORT: Date, Device, Age, Gender, LocationOfPresenceName, Placement, AdNetworkType, Slot и др."
    • addedInput schema / properties / filters
      Added value: +{
      +  "description": "Произвольные условия SelectionCriteria.Filter, складываются с campaignIds по И. Например Clicks GREATER_THAN 0 или Device EQUALS MOBILE.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "field": {
      +        "description": "Поле для фильтрации (должно быть допустимо для типа отчёта).",
      +        "type": "string"
      +      },
      +      "operator": {
      +        "description": "Оператор сравнения.",
      +        "enum": [
      +          "EQUALS",
      +          "NOT_EQUALS",
      +          "IN",
      +          "NOT_IN",
      +          "LESS_THAN",
      +          "GREATER_THAN",
      +          "STARTS_WITH_IGNORE_CASE",
      +          "DOES_NOT_START_WITH_IGNORE_CASE",
      +          "STARTS_WITH_ANY_IGNORE_CASE",
      +          "DOES_NOT_START_WITH_ALL_IGNORE_CASE"
      +        ],
      +        "type": "string"
      +      },
      +      "values": {
      +        "description": "Значения; числа передавать строками, деньги — в валюте аккаунта.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "field",
      +      "operator",
      +      "values"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / goals
      Added value: +{
      +  "description": "Id целей Яндекс Метрики (не более 10). Без них Conversions и Revenue считаются по всем целям кампании; с ними колонки приходят как <поле>_<idЦели>_<модель> (по одной на цель × модель). Для SEARCH_QUERY_PERFORMANCE_REPORT — только одна цель и одна модель.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / reportType / enum
      Previous value: -[
      -  "ACCOUNT_PERFORMANCE_REPORT",
      -  "CAMPAIGN_PERFORMANCE_REPORT",
      -  "ADGROUP_PERFORMANCE_REPORT",
      -  "AD_PERFORMANCE_REPORT",
      -  "CRITERIA_PERFORMANCE_REPORT",
      -  "SEARCH_QUERY_PERFORMANCE_REPORT"
      -]New value: +[
      +  "ACCOUNT_PERFORMANCE_REPORT",
      +  "CAMPAIGN_PERFORMANCE_REPORT",
      +  "ADGROUP_PERFORMANCE_REPORT",
      +  "AD_PERFORMANCE_REPORT",
      +  "CRITERIA_PERFORMANCE_REPORT",
      +  "SEARCH_QUERY_PERFORMANCE_REPORT",
      +  "CUSTOM_REPORT"
      +]
  4. Changed1 schema field changedv1.6.0
    • addedInput schema / properties / client_login
      Added value: +{
      +  "description": "Логин клиента агентства или кабинета в управлении (из list_clients). Если не указан — YANDEX_DIRECT_LOGIN из конфигурации, а без него собственный аккаунт токена.",
      +  "pattern": "^[A-Za-z0-9][A-Za-z0-9._@-]{0,99}$",
      +  "type": "string"
      +}
  5. Changed14 schema fields changedv1.5.1
    • changedInput schema / properties / campaignIds / description
      Previous value: -"Limit the report to these campaign ids."New value: +"Ограничить отчёт этими id кампаний."
    • changedInput schema / properties / dateFrom / description
      Previous value: -"Start date YYYY-MM-DD (required for CUSTOM_DATE)."New value: +"Дата начала YYYY-MM-DD (обязательна для CUSTOM_DATE)."
    • changedInput schema / properties / dateRangeType / description
      Previous value: -"Predefined date range. Inferred as CUSTOM_DATE when dateFrom/dateTo are given."New value: +"Предустановленный период. Если заданы dateFrom/dateTo, подставляется CUSTOM_DATE."
    • changedInput schema / properties / dateTo / description
      Previous value: -"End date YYYY-MM-DD (required for CUSTOM_DATE)."New value: +"Дата окончания YYYY-MM-DD (обязательна для CUSTOM_DATE)."
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Report columns (must be valid for the report type)."New value: +"Колонки отчёта (должны быть допустимы для его типа)."
    • changedInput schema / properties / includeVat / description
      Previous value: -"Whether costs include VAT. Default true."New value: +"Включать ли НДС в расход. По умолчанию true."
    • changedInput schema / properties / minCost / description
      Previous value: -"Only include rows with Cost >= this in the detail list."New value: +"Включать в детализацию только строки с Cost >= этого значения."
    • changedInput schema / properties / order / description
      Previous value: -"Sort order for detail rows. Default desc."New value: +"Порядок сортировки строк детализации. По умолчанию desc."
    • changedInput schema / properties / queryContains / description
      Previous value: -"Only include rows whose query/criterion contains this substring (case-insensitive)."New value: +"Включать только строки, где запрос или условие содержит эту подстроку (без учёта регистра)."
    • changedInput schema / properties / reportType / description
      Previous value: -"Report type. Default CAMPAIGN_PERFORMANCE_REPORT."New value: +"Тип отчёта. По умолчанию CAMPAIGN_PERFORMANCE_REPORT."
    • changedInput schema / properties / sortBy / description
      Previous value: -"Metric to rank the detail rows by. Default Cost."New value: +"Метрика для ранжирования строк детализации. По умолчанию Cost."
    • changedInput schema / properties / topN / description
      Previous value: -"Max detail rows in the summary (server-capped at 100). Default 50."New value: +"Максимум строк детализации в сводке (на сервере ограничено 100). По умолчанию 50."
    • changedInput schema / properties / zeroClicksOnly / description
      Previous value: -"Only include rows with 0 clicks in the detail list."New value: +"Включать в детализацию только строки с 0 кликов."
    • changedInput schema / properties / zeroConversionsOnly / description
      Previous value: -"Only rows with clicks>0 and 0 conversions (needs Conversions in fieldNames)."New value: +"Только строки с clicks>0 и 0 конверсий (нужно Conversions в fieldNames)."
  6. Changed3 schema fields changedv0.1.1
    • removedInput schema / properties / dateTo / $ref
      Removed value: -"#/properties/dateFrom"
    • addedInput schema / properties / dateTo / pattern
      Added value: +"^\\d{4}-\\d{2}-\\d{2}$"
    • addedInput schema / properties / dateTo / type
      Added value: +"string"
  7. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real behavioral context well beyond them: tab-separated rows without a header for standard reports, a computed summary object for SEARCH_QUERY_PERFORMANCE_REPORT, compareTo spawning two Report jobs and returning matched current/previous/delta/deltaPct JSON, empty Revenue/Profit/GoalsRoi unless Metrica goals with value exist, and ~3-day retroactive restatement.

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?

Purpose is front-loaded and virtually every clause carries operational content — no filler or restatement of the title. It is, however, one very dense paragraph of dash-joined clauses; splitting the report-type, compareTo and caveat material into distinct blocks would make it scannable rather than a wall of text.

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

Completeness4/5

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

For a 19-parameter tool with no output schema, the description covers return shapes, defaults, rejection rules and data caveats unusually well. Residual gaps are minor: server-side row/size limits and quota/rate behavior are not mentioned (a get_quota sibling exists), nor what happens on invalid field/report-type combinations.

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

Parameters5/5

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

Schema coverage is 100%, so a 3 would be the floor, but the description adds meaning the schema cannot: default aggregation semantics, the matchKey-based row matching that survives renames when ids are requested, the constraint that only one goal and one attribution model are parsed for SEARCH_QUERY/compareTo, and the fact that factor decomposition (cost = impressions × CTR × CPC) is not computed.

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?

States a specific verb and resource ("Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа") and immediately characterizes the default output shape (aggregated, one row per object). An agent knows exactly what it gets. It does not name a sibling tool it is not (e.g. raw_request, which could also hit Reports), so it stops short of 5.

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

Usage Guidelines5/5

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

Explicit when/when-not rules throughout: add "Date" only for daily dynamics, no hourly granularity (minimum day, TODAY snapshots), ALL_TIME without campaignIds is rejected for SEARCH_QUERY/CRITERIA, compareTo is unavailable for SEARCH_QUERY_PERFORMANCE_REPORT or date-part fields. It also pre-empts a wrong interpretation (GoalsRoi is ROI, not ROAS) and tells the agent to compute ROAS itself.

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