Skip to main content
Glama
yandex-direct-mcp-plus

yandex-direct-mcp-plus

by Pavelsiba

Статистика

get_statistics
Read-only

Retrieve Yandex.Direct performance statistics across campaigns, ad groups, ads, criteria, or accounts, including impressions, clicks, cost, CTR, CPC, and optional Metrica goal conversions and CPA.

Instructions

Статистика за период по кампаниям, группам, объявлениям, условиям показа или аккаунту: показы, клики, расход (руб), CTR, CPC; с goals — конверсии и CPA по целям Метрики (ReportService, TSV).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

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

Input Schema

NameRequiredDescriptionDefault
goalsNoЦели Метрики (до 10): без них отчёт не отдаёт конверсии по конкретной цели. Столбцы Conversions, CostPerConversion, ConversionRate и другие считаются по этим целям
limitNoСколько строк отчёта вернуть. Без лимита отчёт по площадкам или запросам целиком попадает в контекст: ставьте 1000–5000. Если строк ровно столько, остальные — на следующей странице (offset)
fieldsNoПоля отчёта; по умолчанию — свой набор для каждого типа отчёта. Допустимость поля зависит от типа: например, Query бывает только в поисковых запросах, а Keyword — только фильтр. Date делит строки по дням. Деньги приходят в рублях
offsetNoСколько строк пропустить; для следующей страницы — предыдущий offset плюс limit
date_toYesПоследний день периода включительно, YYYY-MM-DD
filtersNoОтбор строк отчёта, условия через И. Например, Impressions GREATER_THAN 0 или AdNetworkType EQUALS AD_NETWORK. Фильтр по кампаниям ставится из campaign_ids сам
date_fromYesПервый день периода, YYYY-MM-DD
report_typeNoУровень отчёта: CAMPAIGN_PERFORMANCE_REPORT — по кампаниям, ADGROUP_PERFORMANCE_REPORT — по группам, AD_PERFORMANCE_REPORT — по объявлениям, CRITERIA_PERFORMANCE_REPORT — по условиям показа (фразы, автотаргетинг, аудитории), ACCOUNT_PERFORMANCE_REPORT — по аккаунту целиком, CUSTOM_REPORT — без своей группировки, только по выбранным полям, REACH_AND_FREQUENCY_PERFORMANCE_REPORT — охват и частота медийных кампаний. Поисковые запросы — get_search_queriesCAMPAIGN_PERFORMANCE_REPORT
campaign_idsNoКампании, по которым строится отчёт. Обязательны для всех типов, кроме ACCOUNT_PERFORMANCE_REPORT
attribution_modelsNoМодели атрибуции конверсий: FC — первый переход, LC — последний, LSC — последний значимый, LYDC — последний переход из Яндекса; CD в конце — кросс-девайс; AUTO — автоматическая. Столбцы называются <метрика>_<ID цели>_<модель>, но модель в названии не всегда равна запрошенной: FC даёт FCCD, LSC даёт LSCCD, LYDC и LYDCCD дают AUTO; без attribution_models столбцы идут с LSCCD

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changedv2.1.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / attribution_models
      Added value: +{
      +  "description": "Модели атрибуции конверсий: FC — первый переход, LC — последний, LSC — последний значимый, LYDC — последний переход из Яндекса; CD в конце — кросс-девайс; AUTO — автоматическая. Столбцы называются <метрика>_<ID цели>_<модель>, но модель в названии не всегда равна запрошенной: FC даёт FCCD, LSC даёт LSCCD, LYDC и LYDCCD дают AUTO; без attribution_models столбцы идут с LSCCD",
      +  "items": {
      +    "enum": [
      +      "AUTO",
      +      "FC",
      +      "FCCD",
      +      "LC",
      +      "LSC",
      +      "LSCCD",
      +      "LYDC",
      +      "LYDCCD"
      +    ],
      +    "type": "string"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / campaign_ids / description
      Previous value: -"Кампании, по которым строится отчёт"New value: +"Кампании, по которым строится отчёт. Обязательны для всех типов, кроме ACCOUNT_PERFORMANCE_REPORT"
    • changedInput schema / properties / fields / description
      Previous value: -"Поля отчёта; по умолчанию Date, CampaignName, Impressions, Clicks, Cost, Ctr, AvgCpc. Деньги приходят в рублях"New value: +"Поля отчёта; по умолчанию — свой набор для каждого типа отчёта. Допустимость поля зависит от типа: например, Query бывает только в поисковых запросах, а Keyword — только фильтр. Date делит строки по дням. Деньги приходят в рублях"
    • addedInput schema / properties / fields / items / enum
      Added value: +[
      +  "AdFormat",
      +  "AdGroupId",
      +  "AdGroupName",
      +  "AdId",
      +  "AdNetworkType",
      +  "AdUrl",
      +  "Age",
      +  "AudienceTargetId",
      +  "AutotargetingBrandOption",
      +  "AvgClickPosition",
      +  "AvgCpc",
      +  "AvgCpm",
      +  "AvgEffectiveBid",
      +  "AvgImpressionFrequency",
      +  "AvgImpressionPosition",
      +  "AvgPageviews",
      +  "AvgTrafficVolume",
      +  "AvgVideoCompleteCost",
      +  "BounceRate",
      +  "Bounces",
      +  "CPV",
      +  "CampaignId",
      +  "CampaignName",
      +  "CampaignType",
      +  "CampaignUrlPath",
      +  "CarrierType",
      +  "ClickType",
      +  "Clicks",
      +  "ClientLogin",
      +  "ConversionRate",
      +  "Conversions",
      +  "Cost",
      +  "CostPerConversion",
      +  "Criteria",
      +  "CriteriaId",
      +  "CriteriaType",
      +  "Criterion",
      +  "CriterionId",
      +  "CriterionType",
      +  "Ctr",
      +  "Date",
      +  "Device",
      +  "DynamicTextAdTargetId",
      +  "ExternalNetworkName",
      +  "Gender",
      +  "GoalsRoi",
      +  "ImpressionReach",
      +  "ImpressionShare",
      +  "Impressions",
      +  "IncomeGrade",
      +  "Keyword",
      +  "LocationOfPresenceId",
      +  "LocationOfPresenceName",
      +  "MatchType",
      +  "MatchedKeyword",
      +  "MobilePlatform",
      +  "Month",
      +  "OfferUrl",
      +  "Placement",
      +  "Profit",
      +  "PurchaseGoals",
      +  "PurchaseGoalsRoi",
      +  "PurchaseProfit",
      +  "PurchaseRevenue",
      +  "Quarter",
      +  "Query",
      +  "Revenue",
      +  "RlAdjustmentId",
      +  "Sessions",
      +  "Slot",
      +  "SmartAdTargetId",
      +  "SmartBannerFilterId",
      +  "SocialMediaLink",
      +  "SocialMediaName",
      +  "TargetingCategory",
      +  "TargetingLocationId",
      +  "TargetingLocationName",
      +  "VideoComplete",
      +  "VideoCompleteRate",
      +  "VideoFirstQuartile",
      +  "VideoFirstQuartileRate",
      +  "VideoMidpoint",
      +  "VideoMidpointRate",
      +  "VideoThirdQuartile",
      +  "VideoThirdQuartileRate",
      +  "VideoViews",
      +  "VideoViewsRate",
      +  "Views",
      +  "Week",
      +  "WeightedCtr",
      +  "WeightedImpressions",
      +  "Year"
      +]
    • removedInput schema / properties / fields / items / minLength
      Removed value: -1
    • addedInput schema / properties / fields / minItems
      Added value: +1
    • addedInput schema / properties / filters
      Added value: +{
      +  "description": "Отбор строк отчёта, условия через И. Например, Impressions GREATER_THAN 0 или AdNetworkType EQUALS AD_NETWORK. Фильтр по кампаниям ставится из campaign_ids сам",
      +  "items": {
      +    "properties": {
      +      "field": {
      +        "description": "Поле отчёта, по которому отбираются строки",
      +        "enum": [
      +          "AdFormat",
      +          "AdGroupId",
      +          "AdGroupName",
      +          "AdId",
      +          "AdNetworkType",
      +          "AdUrl",
      +          "Age",
      +          "AudienceTargetId",
      +          "AutotargetingBrandOption",
      +          "AvgClickPosition",
      +          "AvgCpc",
      +          "AvgCpm",
      +          "AvgEffectiveBid",
      +          "AvgImpressionFrequency",
      +          "AvgImpressionPosition",
      +          "AvgPageviews",
      +          "AvgTrafficVolume",
      +          "AvgVideoCompleteCost",
      +          "BounceRate",
      +          "Bounces",
      +          "CPV",
      +          "CampaignId",
      +          "CampaignName",
      +          "CampaignType",
      +          "CampaignUrlPath",
      +          "CarrierType",
      +          "ClickType",
      +          "Clicks",
      +          "ClientLogin",
      +          "ConversionRate",
      +          "Conversions",
      +          "Cost",
      +          "CostPerConversion",
      +          "Criteria",
      +          "CriteriaId",
      +          "CriteriaType",
      +          "Criterion",
      +          "CriterionId",
      +          "CriterionType",
      +          "Ctr",
      +          "Date",
      +          "Device",
      +          "DynamicTextAdTargetId",
      +          "ExternalNetworkName",
      +          "Gender",
      +          "GoalsRoi",
      +          "ImpressionReach",
      +          "ImpressionShare",
      +          "Impressions",
      +          "IncomeGrade",
      +          "Keyword",
      +          "LocationOfPresenceId",
      +          "LocationOfPresenceName",
      +          "MatchType",
      +          "MatchedKeyword",
      +          "MobilePlatform",
      +          "Month",
      +          "OfferUrl",
      +          "Placement",
      +          "Profit",
      +          "PurchaseGoals",
      +          "PurchaseGoalsRoi",
      +          "PurchaseProfit",
      +          "PurchaseRevenue",
      +          "Quarter",
      +          "Query",
      +          "Revenue",
      +          "RlAdjustmentId",
      +          "Sessions",
      +          "Slot",
      +          "SmartAdTargetId",
      +          "SmartBannerFilterId",
      +          "SocialMediaLink",
      +          "SocialMediaName",
      +          "TargetingCategory",
      +          "TargetingLocationId",
      +          "TargetingLocationName",
      +          "VideoComplete",
      +          "VideoCompleteRate",
      +          "VideoFirstQuartile",
      +          "VideoFirstQuartileRate",
      +          "VideoMidpoint",
      +          "VideoMidpointRate",
      +          "VideoThirdQuartile",
      +          "VideoThirdQuartileRate",
      +          "VideoViews",
      +          "VideoViewsRate",
      +          "Views",
      +          "Week",
      +          "WeightedCtr",
      +          "WeightedImpressions",
      +          "Year"
      +        ],
      +        "type": "string"
      +      },
      +      "operator": {
      +        "description": "Оператор сравнения",
      +        "enum": [
      +          "DOES_NOT_START_WITH_ALL_IGNORE_CASE",
      +          "DOES_NOT_START_WITH_IGNORE_CASE",
      +          "EQUALS",
      +          "GREATER_THAN",
      +          "IN",
      +          "LESS_THAN",
      +          "NOT_EQUALS",
      +          "NOT_IN",
      +          "STARTS_WITH_ANY_IGNORE_CASE",
      +          "STARTS_WITH_IGNORE_CASE"
      +        ],
      +        "type": "string"
      +      },
      +      "values": {
      +        "description": "Значения строками: числа и ID тоже. Для IN и NOT_IN — список, для остальных операторов — одно",
      +        "items": {
      +          "type": "string"
      +        },
      +        "minItems": 1,
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "field",
      +      "operator",
      +      "values"
      +    ],
      +    "type": "object"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / goals
      Added value: +{
      +  "description": "Цели Метрики (до 10): без них отчёт не отдаёт конверсии по конкретной цели. Столбцы Conversions, CostPerConversion, ConversionRate и другие считаются по этим целям",
      +  "items": {
      +    "description": "ID цели Метрики",
      +    "pattern": "^[1-9]\\d*$",
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "Сколько строк отчёта вернуть. Без лимита отчёт по площадкам или запросам целиком попадает в контекст: ставьте 1000–5000. Если строк ровно столько, остальные — на следующей странице (offset)",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Сколько строк пропустить; для следующей страницы — предыдущий offset плюс limit",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / report_type
      Added value: +{
      +  "default": "CAMPAIGN_PERFORMANCE_REPORT",
      +  "description": "Уровень отчёта: CAMPAIGN_PERFORMANCE_REPORT — по кампаниям, ADGROUP_PERFORMANCE_REPORT — по группам, AD_PERFORMANCE_REPORT — по объявлениям, CRITERIA_PERFORMANCE_REPORT — по условиям показа (фразы, автотаргетинг, аудитории), ACCOUNT_PERFORMANCE_REPORT — по аккаунту целиком, CUSTOM_REPORT — без своей группировки, только по выбранным полям, REACH_AND_FREQUENCY_PERFORMANCE_REPORT — охват и частота медийных кампаний. Поисковые запросы — get_search_queries",
      +  "enum": [
      +    "CAMPAIGN_PERFORMANCE_REPORT",
      +    "ADGROUP_PERFORMANCE_REPORT",
      +    "AD_PERFORMANCE_REPORT",
      +    "CRITERIA_PERFORMANCE_REPORT",
      +    "ACCOUNT_PERFORMANCE_REPORT",
      +    "CUSTOM_REPORT",
      +    "REACH_AND_FREQUENCY_PERFORMANCE_REPORT"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "campaign_ids",
      -  "date_from",
      -  "date_to"
      -]New value: +[
      +  "date_from",
      +  "date_to"
      +]
  2. First observedv1.6.1

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds genuinely useful context beyond that – the ReportService/TSV return format and ruble-denominated monetary values – but says nothing about result volume, pagination, or the cost of unfiltered reports, all of which appear only in parameter descriptions.

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 dense sentence that front-loads the resource and period, then lists report levels and metrics in priority order. The parenthetical (ReportService, TSV) is compact and earns its place by conveying the output format; the semicolon-joined clauses are readable despite the density.

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?

For a 10-parameter analytics tool with no output schema, the description gives the essential shape (report levels, metrics, TSV format, goal-driven conversions) and the schema covers the rest thoroughly. What it omits – mandatory campaign_ids except for account reports, the 10-goal cap, paging discipline – is documented in the schema, so it is adequate rather than complete.

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

Parameters3/5

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

Schema description coverage is 100%, including detailed notes on goals, limit/offset paging, field admissibility, and attribution model quirks, so the schema carries the parameter burden. The description only echoes that goals unlock conversion and CPA metrics, adding nothing the schema does not already say.

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 names a specific resource (statistics for a period) and enumerates the five report levels it can produce (campaigns, groups, ads, criteria, account) plus the core metrics (impressions, clicks, cost in rubles, CTR, CPC), so an agent can tell exactly what this tool returns. It stops short of naming a sibling tool it is not, which leaves differentiation to the schema's report_type note pointing at get_search_queries.

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?

Usage is only implied by the enumeration of report levels – there is no explicit statement of when to pick this over alternatives or what prerequisites apply. The crucial routing rule (use get_search_queries for search queries) lives only in the report_type schema description, not in the tool description itself.

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