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

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

The annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat safety traits. It does add useful behavioral context by stating that the Yandex Direct API requires at least one selection criterion. It does not, however, describe return format, error conditions, or pagination behavior beyond what annotations and schema imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler or redundant restatement. The core purpose is front-loaded, and the critical API requirement follows immediately. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple read-only nature, full parameter documentation in the schema, and clear annotations, this description is nearly complete. The one notable gap is the absence of return-shape information and no hint about which fields may be requested via fieldNames, though both are mitigated by schema completeness and the tool's straightforward semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is individually explained. The description adds genuine cross-parameter meaning: campaignIds and/or ids must be passed, and the API requires at least one criterion. This compensates for the schema listing zero required parameters and clarifies an otherwise non-obvious constraint.

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

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

The description clearly states the operation: it returns a list of ad groups. It unambiguously targets the resource 'ad groups', which distinguishes it from sibling tools like list_ads, list_campaigns, and list_keywords. The verb and object are both specific and accurate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use: to list ad groups, you must supply campaignIds and/or ids. It does not explicitly name alternatives or exclusions, but the requirement is direct and practically actionable.

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