Skip to main content
Glama
Yandex Direct MCP

Yandex Direct MCP

Список кампаний

list_campaigns
Read-onlyIdempotent

Retrieves Yandex Direct campaigns with optional filters for IDs, types, states, and moderation statuses, and can include bidding strategies and key goals for campaign analysis.

Instructions

Возвращает список кампаний с необязательными фильтрами по id, типу, состоянию и статусу. Запрос идёт в API v501 (в песочнице — в v5): только он отдаёт Единую перформанс-кампанию с типом UNIFIED_CAMPAIGN (v5 называет её TEXT_CAMPAIGN; ответ v5 доступен через raw_request с apiVersion "v5"). Денежные поля (Funds общего счёта — Sum, Balance, SumAvailableForTransfer, Spend) отдаются в валюте аккаунта. Бюджет кампании — недельный (WeeklySpendLimit) и у ручных ставок, и у автостратегий; он лежит внутри BiddingStrategy и виден только при strategy: true (дневного бюджета DailyBudget у API больше нет). strategy: true добавляет блок TextCampaign/UnifiedCampaign со стратегией (BiddingStrategy), ключевыми целями (PriorityGoals), счётчиками Метрики, моделью атрибуции, пакетной стратегией и переносом бюджета (WeeklyBudgetRollover — сколько добавлено к недельному бюджету за счёт неиспользованного на прошлой неделе, до 30%; null — перенос не применяется или данных нет) — деньги в нём тоже в валюте аккаунта, а сам объект BiddingStrategy в этом виде принимает set_campaign_strategy.

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

Input Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.13.1
    • changedInput schema / properties / fieldNames / items / enum
      Previous value: -[
      -  "BlockedIps",
      -  "ExcludedSites",
      -  "Currency",
      -  "DailyBudget",
      -  "Notification",
      -  "EndDate",
      -  "Funds",
      -  "ClientInfo",
      -  "Id",
      -  "Name",
      -  "NegativeKeywords",
      -  "RepresentedBy",
      -  "StartDate",
      -  "CreateTime",
      -  "Statistics",
      -  "State",
      -  "Status",
      -  "StatusPayment",
      -  "StatusClarification",
      -  "SourceId",
      -  "TimeTargeting",
      -  "TimeZone",
      -  "Type"
      -]New value: +[
      +  "BlockedIps",
      +  "ExcludedSites",
      +  "Currency",
      +  "Notification",
      +  "EndDate",
      +  "Funds",
      +  "ClientInfo",
      +  "Id",
      +  "Name",
      +  "NegativeKeywords",
      +  "RepresentedBy",
      +  "StartDate",
      +  "CreateTime",
      +  "Statistics",
      +  "State",
      +  "Status",
      +  "StatusPayment",
      +  "StatusClarification",
      +  "SourceId",
      +  "TimeTargeting",
      +  "TimeZone",
      +  "Type"
      +]
  2. Changed2 schema fields changedv1.12.1
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Какие поля кампании вернуть. Стратегии и настройки конкретного типа кампании здесь не запрашиваются."New value: +"Какие поля кампании вернуть. Стратегия здесь не запрашивается — для неё strategy: true."
    • addedInput schema / properties / strategy
      Added value: +{
      +  "description": "Вернуть стратегию показа и ключевые цели (блок TextCampaign или UnifiedCampaign).",
      +  "type": "boolean"
      +}
  3. Changed2 schema fields changedv1.11.0
    • changedInput schema / properties / fieldNames / description
      Previous value: -"Какие поля кампании вернуть."New value: +"Какие поля кампании вернуть. Стратегии и настройки конкретного типа кампании здесь не запрашиваются."
    • addedInput schema / properties / fieldNames / items / enum
      Added value: +[
      +  "BlockedIps",
      +  "ExcludedSites",
      +  "Currency",
      +  "DailyBudget",
      +  "Notification",
      +  "EndDate",
      +  "Funds",
      +  "ClientInfo",
      +  "Id",
      +  "Name",
      +  "NegativeKeywords",
      +  "RepresentedBy",
      +  "StartDate",
      +  "CreateTime",
      +  "Statistics",
      +  "State",
      +  "Status",
      +  "StatusPayment",
      +  "StatusClarification",
      +  "SourceId",
      +  "TimeTargeting",
      +  "TimeZone",
      +  "Type"
      +]
  4. 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"
      +}
  5. Changed8 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 / fieldNames / description
      Previous value: -"Campaign fields to return."New value: +"Какие поля кампании вернуть."
    • changedInput schema / properties / ids / description
      Previous value: -"Filter by campaign 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 campaign states."New value: +"Фильтр по состояниям кампаний."
    • changedInput schema / properties / statuses / description
      Previous value: -"Filter by moderation statuses."New value: +"Фильтр по статусам модерации."
    • changedInput schema / properties / types / description
      Previous value: -"Filter by campaign types."New value: +"Фильтр по типам кампаний."
  6. Changed1 schema field changedv0.1.1
    • changedInput schema / properties / types / items / enum
      Previous value: -[
      -  "TEXT_CAMPAIGN",
      -  "MOBILE_APP_CAMPAIGN",
      -  "DYNAMIC_TEXT_CAMPAIGN",
      -  "CPM_BANNER_CAMPAIGN",
      -  "SMART_CAMPAIGN",
      -  "MCBANNER_CAMPAIGN"
      -]New value: +[
      +  "TEXT_CAMPAIGN",
      +  "MOBILE_APP_CAMPAIGN",
      +  "DYNAMIC_TEXT_CAMPAIGN",
      +  "CPM_BANNER_CAMPAIGN",
      +  "SMART_CAMPAIGN",
      +  "MCBANNER_CAMPAIGN",
      +  "UNIFIED_CAMPAIGN"
      +]
  7. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior an agent could not infer: monetary fields are in account currency, the budget is weekly (WeeklySpendLimit) and lives inside BiddingStrategy, DailyBudget no longer exists in the API, and WeeklyBudgetRollover is capped at 30% with null meaning no rollover or no data. It also discloses a cross-tool contract — that the BiddingStrategy block in this shape is accepted verbatim by set_campaign_strategy.

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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries operational information rather than filler. The strategy:true sentence is long and stacks many sub-fields, so it could be split for readability, but nothing is repetitive or wasteful.

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?

For a 10-parameter, zero-required list tool with no output schema, the description supplies the missing return-value context: currency of money fields, where the budget lives, when the strategy block appears, and how pagination is bounded. An agent has everything needed to call it correctly and interpret the payload.

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 a 3 would be the baseline, but the description goes well beyond it: it explains that strategy:true materializes the TextCampaign/UnifiedCampaign block (BiddingStrategy, PriorityGoals, Metrica counters, attribution, package strategy, rollover), clarifies that fieldNames cannot request strategy, and notes that autoPaginate walks LimitedBy while limit stops bounding total volume. These are non-obvious interactions among parameters that the flat schema does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('Возвращает список кампаний') and enumerates the filter axes (id, type, state, status), so the agent knows exactly what the tool returns. It further pins the scope by stating it targets API v501 and that only that version exposes UNIFIED_CAMPAIGN, which distinguishes it from a generic raw_request call.

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 gives real selection context: v501 is the preferred path for the Unified Performance campaign, v5 must be reached via raw_request with apiVersion "v5", and v5 labels the type TEXT_CAMPAIGN. What it lacks is an explicit 'when not to use' clause or a pointer to list_ad_groups/list_ads for drilling into a campaign's children, but the version routing guidance is unusually concrete.

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