Skip to main content
Glama
Yandex Direct MCP

Yandex Direct MCP

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

list_ads
Read-onlyIdempotent

Retrieves Yandex Direct ads by campaign, ad group, or ad IDs, with state/status filters, pagination, and selectable fields, including responsive ad details.

Instructions

Возвращает список объявлений. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них; states и statuses только сужают выборку. Текстовые объявления Единой перформанс-кампании Директ хранит комбинаторными и отдаёт в одном из двух видов. Без responsiveAdFieldNames — в виде совместимости: Type TEXT_AD, запрошенные тексты в объекте TextAd. Если передано хотя бы одно поле в responsiveAdFieldNames — как Type RESPONSIVE_AD с объектом ResponsiveAd вместо TextAd, где заголовки и тексты — массивы Titles[] и Texts[] со статусом модерации каждого варианта.

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
idsNoФильтр по id объявлений. Длинный id (приходит в ответах строкой) передавать строкой как есть.
limitNoМаксимум объектов на страницу.
offsetNoСмещение постраничной выдачи (сколько объектов пропустить).
statesNoФильтр по состояниям объявлений.
statusesNoФильтр по статусам модерации.
adGroupIdsNoФильтр по id групп объявлений.
fieldNamesNoКакие поля объявления вернуть; без параметра — Id, AdGroupId, CampaignId, Status, State, Type. Тексты и ссылки (Title, Title2, Text, Href, …) приходят в объекте TextAd. Если переданы только они, в запрос добавляется Id: API не принимает пустой список полей объявления.
campaignIdsNoФильтр по id кампаний.
autoPaginateNoЗабрать все страницы, идя по LimitedBy (limit тогда не ограничивает общий объём).
client_loginNoЛогин клиента агентства или кабинета в управлении (из list_clients). Если не указан — YANDEX_DIRECT_LOGIN из конфигурации, а без него собственный аккаунт токена.
responsiveAdFieldNamesNoПоля комбинаторного объявления (ResponsiveAdFieldNames API, передаются как есть). Хотя бы одно поле переключает ответ для комбинаторных объявлений на Type RESPONSIVE_AD с объектом ResponsiveAd вместо TextAd. Цены в PriceExtension (Price, OldPrice) приходят как в API — в микроединицах (× 1 000 000) валюты PriceCurrency, без пересчёта.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.14.0
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Какие поля объявления вернуть. Тексты и ссылки (Title, Title2, Text, Href, …) приходят в объекте TextAd."New value: +"Какие поля объявления вернуть; без параметра — Id, AdGroupId, CampaignId, Status, State, Type. Тексты и ссылки (Title, Title2, Text, Href, …) приходят в объекте TextAd. Если переданы только они, в запрос добавляется Id: API не принимает пустой список полей объявления."
    • changedInput schema / properties / ids / description
      Previous value: -"Фильтр по id объявлений."New value: +"Фильтр по id объявлений. Длинный id (приходит в ответах строкой) передавать строкой как есть."
    • addedInput schema / properties / ids / items / anyOf
      Added value: +[
      +  {
      +    "type": "integer"
      +  },
      +  {
      +    "pattern": "^\\d+$",
      +    "type": "string"
      +  }
      +]
    • removedInput schema / properties / ids / items / type
      Removed value: -"integer"
    • addedInput schema / properties / responsiveAdFieldNames
      Added value: +{
      +  "description": "Поля комбинаторного объявления (ResponsiveAdFieldNames API, передаются как есть). Хотя бы одно поле переключает ответ для комбинаторных объявлений на Type RESPONSIVE_AD с объектом ResponsiveAd вместо TextAd. Цены в PriceExtension (Price, OldPrice) приходят как в API — в микроединицах (× 1 000 000) валюты PriceCurrency, без пересчёта.",
      +  "items": {
      +    "enum": [
      +      "Titles",
      +      "Texts",
      +      "Href",
      +      "FinalUrl",
      +      "DisplayDomain",
      +      "DisplayUrlPath",
      +      "DisplayUrlPathModeration",
      +      "DutPrefix",
      +      "DutSuffix",
      +      "SitelinkSetId",
      +      "SitelinksModeration",
      +      "AdImages",
      +      "AdExtensions",
      +      "PriceExtension",
      +      "VideoExtensions",
      +      "ButtonExtension",
      +      "ButtonExtensionModeration",
      +      "Carousel",
      +      "BusinessId",
      +      "TrackingPhoneId",
      +      "ErirAdDescription"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  2. Changed2 schema fields changedv1.11.0
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Какие поля объявления вернуть."New value: +"Какие поля объявления вернуть. Тексты и ссылки (Title, Title2, Text, Href, …) приходят в объекте TextAd."
    • addedInput schema / properties / fieldNames / items / enum
      Added value: +[
      +  "AdCategories",
      +  "AgeLabel",
      +  "AdGroupId",
      +  "CampaignId",
      +  "Id",
      +  "State",
      +  "Status",
      +  "StatusClarification",
      +  "Type",
      +  "Subtype",
      +  "Title",
      +  "Title2",
      +  "Text",
      +  "Href",
      +  "FinalUrl",
      +  "DisplayDomain",
      +  "DisplayUrlPath",
      +  "Mobile",
      +  "SitelinkSetId",
      +  "VCardId",
      +  "AdImageHash",
      +  "AdExtensions",
      +  "TurboPageId",
      +  "BusinessId",
      +  "ErirAdDescription"
      +]
  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. Changed9 schema fields changedv1.5.1
    • changedInput schema / properties / adGroupIds / description
      Previous value: -"Filter by ad group ids."New value: +"Фильтр по id групп объявлений."
    • changedInput schema / properties / autoPaginate / description
      Previous value: -"Fetch all pages by following LimitedBy (ignores limit as a total cap)."New value: +"Забрать все страницы, идя по LimitedBy (limit тогда не ограничивает общий объём)."
    • changedInput schema / properties / campaignIds / description
      Previous value: -"Filter by campaign ids."New value: +"Фильтр по id кампаний."
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Ad fields to return."New value: +"Какие поля объявления вернуть."
    • changedInput schema / properties / ids / description
      Previous value: -"Filter by ad ids."New value: +"Фильтр по id объявлений."
    • changedInput schema / properties / limit / description
      Previous value: -"Max objects per page."New value: +"Максимум объектов на страницу."
    • changedInput schema / properties / offset / description
      Previous value: -"Pagination offset (objects to skip)."New value: +"Смещение постраничной выдачи (сколько объектов пропустить)."
    • changedInput schema / properties / states / description
      Previous value: -"Filter by ad states."New value: +"Фильтр по состояниям объявлений."
    • changedInput schema / properties / statuses / description
      Previous value: -"Filter by moderation statuses."New value: +"Фильтр по статусам модерации."
  5. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses real behavioral detail the annotations cannot: the API's mandatory-filter constraint and the two distinct response shapes (TextAd vs ResponsiveAd) selected by responsiveAdFieldNames. It does not cover pagination behavior despite an autoPaginate parameter, which keeps it from a 5.

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 purpose, then the hard constraint, then the responsive-ad explanation — a logical order with no filler. The final section on Titles[]/Texts[] and moderation status is dense but each clause carries information; slightly tighter phrasing would earn a 5.

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 an 11-parameter, no-output-schema read tool, the definition supplies the essential call constraints and the non-obvious response-shape behavior. Gaps remain around pagination (limit/offset/autoPaginate interaction) and default page size, which an agent would have to infer from parameter descriptions alone.

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 the baseline would be 3, but the description adds meaning the schema cannot express: the cross-parameter requirement that at least one id filter be present (the schema marks nothing as required), the narrowing role of states/statuses, and the fact that responsiveAdFieldNames switches the response object type. That is genuine added semantics beyond the structured field descriptions.

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 opens with a specific verb and resource ('Возвращает список объявлений') and immediately narrows the semantics with the mandatory-filter rule. It does not explicitly name a sibling (e.g. list_ad_groups) to contrast against, so differentiation is left to the agent's reading of tool names, but the ad-listing purpose is unmistakable.

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?

It states a concrete precondition: at least one of campaignIds, adGroupIds or ids must be supplied, and clarifies that states/statuses only narrow the result rather than scope it. What is missing is routing guidance toward alternatives (list_ad_groups, ad_action) for related tasks, but the when/how-to-call guidance is clear.

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