Skip to main content
Glama
askads

Yandex Direct MCP

Статистика

get_statistics
Read-onlyIdempotent

Retrieves Yandex Direct performance reports with configurable report type, date range, filters, fields, and goals; returns aggregated metrics by default for campaign, ad, and search-query analysis.

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. Остальные типы отчётов возвращают строки, разделённые табуляцией (без заголовка).

Input Schema

NameRequiredDescriptionDefault
topNNoМаксимум строк детализации в сводке (на сервере ограничено 100). По умолчанию 50.
goalsNoId целей Яндекс Метрики (не более 10). Без них Conversions и Revenue считаются по всем целям кампании; с ними колонки приходят как <поле>_<idЦели>_<модель> (по одной на цель × модель). Для SEARCH_QUERY_PERFORMANCE_REPORT — только одна цель и одна модель.
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).
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. Changed1 schema field changedv1.11.0
    • changedInput schema / properties / attributionModels / description
      Previous value: -"Модели атрибуции для конверсий. По умолчанию LC (последний переход)."New value: +"Модели атрибуции для конверсий по целям из goals; без goals не применяются (API их тогда не принимает). По умолчанию LC (последний переход)."
  2. 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"
      +]
  3. 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"
      +}
  4. 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)."
  5. 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"
  6. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already mark the tool read-only and idempotent, but the description adds substantial unreachable-from-schema behavior: default aggregation to one row per object, tab-separated row output without header for most report types, a computed summary (totals + top-N + tail rollup + zero-click/zero-conversion counts) for SEARCH_QUERY_PERFORMANCE_REPORT, and the precondition that Revenue/Profit/GoalsRoi are only populated for Metrica goals with a value. It also discloses a hard validation rule that rejects certain ALL_TIME calls.

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?

Front-loaded with the aggregation default and the Date advice first, then the return-format distinction, so the most decision-relevant facts come early. It is dense and long, but for an 18-parameter tool nearly every clause carries an operational constraint rather than filler.

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

Completeness5/5

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

For an 18-param tool with no output schema, the description covers default behavior, hard validation rejections, per-report-type return formats, and metric computation semantics (ROAS vs GoalsRoi). Combined with the complete schema, an agent has what it needs to call this correctly.

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?

Schema coverage is 100%, so 3 would be the baseline, but the description goes further: it explains that sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly jointly determine the shape of the SEARCH_QUERY summary, and that Conversions must be added to fieldNames for conversion counts to be usable. Minor gap: it doesn't tie the goals/attributionModels interaction to the description text beyond the schema's own note.

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

Purpose5/5

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

Opens with a specific verb and resource ("Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа") and immediately scopes what is and isn't in the data. No sibling tool covers reporting, and the description makes the tool's domain unambiguous.

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 rules are given for when to add "Date" to fieldNames (only for daily dynamics/trend questions), that hourly stats do not exist (minimum is daily; use repeated TODAY snapshots), that ALL_TIME without campaignIds is rejected for SEARCH_QUERY/CRITERIA, and that ROAS must be computed as Revenue/Cost rather than GoalsRoi. These are the exact decisions an agent would otherwise get wrong.

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