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

yandex-direct-mcp-plus

by Pavelsiba

Поисковые запросы

get_search_queries
Read-only

Retrieve actual Yandex.Direct search query reports by campaign and date to identify irrelevant terms and add negative keywords. Supports filters, goals, and pagination for conversion analysis.

Instructions

Отчёт по фактическим поисковым запросам для анализа и добавления минус-фраз.

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": {
      "campaign_ids": "<campaign_ids>",
      "date_from": "<date_from>",
      "date_to": "<date_to>"
    },
    "name": "get_search_queries"
  }
}

Input Schema

NameRequiredDescriptionDefault
goalsNoЦели Метрики (до 10): без них отчёт не отдаёт конверсии по конкретной цели. Столбцы Conversions, CostPerConversion, ConversionRate и другие считаются по этим целям
limitNoСколько строк отчёта вернуть. Без лимита отчёт по площадкам или запросам целиком попадает в контекст: ставьте 1000–5000. Если строк ровно столько, остальные — на следующей странице (offset)
fieldsNoПоля отчёта; по умолчанию Query, CampaignId, CampaignName, AdGroupId, AdGroupName, Criterion, Impressions, Clicks, Cost
offsetNoСколько строк пропустить; для следующей страницы — предыдущий offset плюс limit
date_toYesПоследний день периода включительно, YYYY-MM-DD
filtersNoОтбор строк отчёта, условия через И. Например, Impressions GREATER_THAN 0 или AdNetworkType EQUALS AD_NETWORK. Фильтр по кампаниям ставится из campaign_ids сам
date_fromYesПервый день периода, YYYY-MM-DD
campaign_idsYesКампании, по которым нужен отчёт о поисковых запросах
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. Changed10 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"
      +}
    • 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"
      +}
  2. First observedv1.6.1

TDQS

B3.1/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that the description adds no behavioural context at all: nothing about the mandatory campaign scoping, paging through large query sets, the default field set, or the cost of an unbounded pull — all of which lives only in the schema.

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 well-formed sentence with no filler and the purpose front-loaded. It is efficient, though for a nine-parameter reporting tool the terse framing leaves the agent to discover operational constraints elsewhere.

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?

For a complex nine-parameter report tool with no output schema, the description does not say what the rows contain beyond the word "queries", how far back data goes, or how it differs from the general statistics tool. The rich schema compensates on parameters, but the definition as a whole is thin for this level of complexity.

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%, and the property descriptions are genuinely informative (goals drive conversion columns, limit/offset paging, filters AND together, attribution model naming quirks). The description itself contributes nothing parameter-specific, so the baseline of 3 applies.

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 and verb: a report of actual search queries, framed for minus-keyword analysis. That is clear enough that an agent understands what comes back, but it never distinguishes this from the sibling get_statistics, which plausibly returns overlapping data.

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?

"Для анализа и добавления минус-фраз" implies the workflow (find irrelevant queries, then move them to negative keywords), which is useful implied usage. It stops short of stating when to prefer this over get_statistics or when not to use it, so the agent must infer the routing.

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