Skip to main content
Glama
Yandex Direct MCP

Yandex Direct MCP

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

list_ad_groups
Read-onlyIdempotent

Retrieves ad groups filtered by campaign IDs or ad group IDs, requiring at least one selection criterion. Returns configurable fields and supports pagination.

Instructions

Возвращает список групп объявлений. Нужно передать campaignIds и/или ids — API Яндекс Директа требует хотя бы один критерий отбора. Запрос идёт в API v501 (в песочнице — в v5): группы Единой перформанс-кампании приходят с Type UNIFIED_AD_GROUP (v5 называет их TEXT_AD_GROUP; ответ v5 доступен через raw_request с apiVersion "v5").

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_ad_groups"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsNoФильтр по id групп объявлений.
limitNoМаксимум объектов на страницу.
offsetNoСмещение постраничной выдачи (сколько объектов пропустить).
fieldNamesNoКакие поля группы вернуть.
campaignIdsNoФильтр по id кампаний.
autoPaginateNoЗабрать все страницы, идя по LimitedBy (limit тогда не ограничивает общий объём).
client_loginNoЛогин клиента агентства или кабинета в управлении (из list_clients). Если не указан — YANDEX_DIRECT_LOGIN из конфигурации, а без него собственный аккаунт токена.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.11.0
    • addedInput schema / properties / fieldNames / items / enum
      Added value: +[
      +  "Id",
      +  "CampaignId",
      +  "Status",
      +  "Name",
      +  "RegionIds",
      +  "RestrictedRegionIds",
      +  "NegativeKeywords",
      +  "NegativeKeywordSharedSetIds",
      +  "Type",
      +  "TrackingParams",
      +  "Subtype",
      +  "ServingStatus"
      +]
  2. 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"
      +}
  3. Changed6 schema fields changedv1.5.1
    • 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 group fields to return."New value: +"Какие поля группы вернуть."
    • changedInput schema / properties / ids / description
      Previous value: -"Filter by ad group 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: +"Смещение постраничной выдачи (сколько объектов пропустить)."
  4. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds real behavioral context beyond them: the API version used (v501 vs v5 in sandbox) and the UNIFIED_AD_GROUP / TEXT_AD_GROUP type naming difference that affects how results are interpreted. It does not discuss result volume or pagination behavior, which the schema carries instead.

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?

Three sentences, front-loaded with the purpose, then the constraint, then version caveats. The final parenthetical is dense but each clause carries actionable information; slight compression cost in readability of the version/type note.

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?

With 7 optional params, no output schema, and annotations present, the description supplies the critical missing constraint (at-least-one filter) and version/type caveats. It leaves return-shape and pagination/autoPaginate interaction to the schema, which documents those fields, so nothing essential is missing.

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 baseline would be 3, but the description adds something the schema does not: that at least one of campaignIds or ids is required despite the schema declaring zero required parameters. That is a genuine semantic addition beyond the structured fields.

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?

States a specific verb and resource ("Возвращает список групп объявлений") and implicitly distinguishes itself from raw_request by noting the v5 escape hatch. It does not explicitly contrast with list_campaigns or list_ads, so the sibling differentiation is only partial.

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?

Explicitly states the selection constraint (campaignIds and/or ids must be provided) and names raw_request with apiVersion "v5" as the alternative for the v5 response. Clear usage context, though no explicit guidance on when to prefer it over, e.g., list_campaigns for campaign data.

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