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

yandex-direct-mcp-plus

by Pavelsiba

Список объявлений

list_ads
Read-only

Retrieve Yandex Direct ads with titles, texts, links, statuses, types, sitelinks, images, and videos; filter results by ad, group, or campaign IDs plus state, status, and type.

Instructions

Объявления: все заголовки и тексты, ссылки, статусы, тип и подтип объявления, привязанные сайтлинки, изображения и видео. Текстовые объявления Директ отдаёт комбинаторными (RESPONSIVE_AD). Причина отказа модерации приходит в StatusClarification. Отбор по ID объявлений, группам или кампаниям — хотя бы одно из трёх; сужается состоянием, статусом и типом. Без фильтра по состоянию архивные приходят наравне с активными. Список может быть неполным: объявления, тексты которых генерирует нейросеть Яндекса, через API недоступны и в выдачу не попадают, а по ответу это никак не видно. Поэтому «в группе только эти объявления» из ответа не следует — ни из пустого, ни из непустого; для полноты картины сверяйтесь с интерфейсом Директа.

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": "list_ads"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoСколько объектов вернуть (максимум 10000)
typesNoФильтр по типу объявления
ad_idsNoКонкретные объявления по ID
offsetNoСмещение выборки: сюда передаётся LimitedBy предыдущей страницы
statesNoФильтр по состоянию: ON — показывается, SUSPENDED — остановлено, ARCHIVED — в архиве
statusesNoФильтр по статусу модерации
ad_group_idsNoГруппы, объявления которых нужно выбрать
campaign_idsNoКампании, объявления которых нужно выбрать, до 10

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 / ad_group_ids / maxItems
      Added value: +1000
    • removedInput schema / properties / ad_group_ids / minItems
      Removed value: -1
    • addedInput schema / properties / ad_ids
      Added value: +{
      +  "description": "Конкретные объявления по ID",
      +  "items": {
      +    "description": "ID объявления",
      +    "pattern": "^[1-9]\\d*$",
      +    "type": "string"
      +  },
      +  "maxItems": 10000,
      +  "type": "array"
      +}
    • addedInput schema / properties / campaign_ids
      Added value: +{
      +  "description": "Кампании, объявления которых нужно выбрать, до 10",
      +  "items": {
      +    "description": "ID кампании",
      +    "pattern": "^[1-9]\\d*$",
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
    • addedInput schema / properties / states
      Added value: +{
      +  "description": "Фильтр по состоянию: ON — показывается, SUSPENDED — остановлено, ARCHIVED — в архиве",
      +  "items": {
      +    "enum": [
      +      "ON",
      +      "OFF",
      +      "OFF_BY_MONITORING",
      +      "SUSPENDED",
      +      "ARCHIVED"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / statuses
      Added value: +{
      +  "description": "Фильтр по статусу модерации",
      +  "items": {
      +    "enum": [
      +      "ACCEPTED",
      +      "DRAFT",
      +      "MODERATION",
      +      "PREACCEPTED",
      +      "REJECTED"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / types
      Added value: +{
      +  "description": "Фильтр по типу объявления",
      +  "items": {
      +    "enum": [
      +      "TEXT_AD",
      +      "MOBILE_APP_AD",
      +      "DYNAMIC_TEXT_AD",
      +      "IMAGE_AD",
      +      "CPC_VIDEO_AD",
      +      "CPM_BANNER_AD",
      +      "CPM_VIDEO_AD",
      +      "SMART_AD",
      +      "SHOPPING_AD",
      +      "LISTING_AD",
      +      "RESPONSIVE_AD"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "ad_group_ids"
      -]
  2. First observedv1.6.1

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the readOnly/openWorld annotations: it explains that ads whose texts are AI-generated are silently excluded from results, that an empty or non-empty response therefore cannot prove a group's full ad inventory, and that the Direct UI is the cross-check. It also tells the agent where rejection reasons land (StatusClarification) and why text ads surface as RESPONSIVE_AD.

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 what is returned, then constraints, then the completeness caveat; every sentence carries information. It is dense and slightly long, but there is no filler or repetition.

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?

With no output schema, the description supplies the returned fields, the key non-obvious behavior (invisible exclusion of AI-text ads), and the filtering contract. Pagination via offset is already documented in the schema, so nothing essential is missing for correct invocation or interpretation of results.

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 the baseline would be 3. The description earns above that by stating the 'at least one of three' constraint on ad_ids/ad_group_ids/campaign_ids that the schema does NOT enforce (required: 0), and by explaining the practical consequence of omitting states, which the schema's per-parameter text does not convey.

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 opening enumerates exactly what the call returns (headlines, texts, links, states, ad type/subtype, sitelinks, images, video) and notes that Direct returns text ads as RESPONSIVE_AD combinators, which is a concrete, tool-specific detail. It stops short of explicitly distinguishing itself from siblings such as manage_ads or moderate_ads, so an agent must infer that this is the read-only listing variant.

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?

Gives real selection semantics: at least one of ad IDs, ad group IDs or campaign IDs is required, optionally narrowed by state, status and type, plus the caveat that without a state filter archived ads appear alongside active ones. It does not name alternatives (e.g. manage_ads for edits, moderate_ads for moderation), which leaves sibling routing to inference.

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