Статистика

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

Beyond the readOnly/idempotent annotations, the description discloses failure behavior ('VK их молча игнорирует, поэтому инструмент вернёт ошибку'), clarifies that autoPaginate is harmless in every mode, and explains the exact meaning of 'total' (sum over THIS page's objects, or over ids when filtered, not the whole account). It also states where metrics live (base) and that spent is in account currency.

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?

Purpose is front-loaded in sentence one and nearly every following clause carries a real constraint (mode limits, error behavior, total semantics). It is dense and wordy in places — the autoPaginate aside and the repeated date/period restatements could be trimmed — but there is no filler.

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?

With 11 parameters, three interacting modes and no output schema, the description still tells the agent what the response looks like (items[].total, per-day rows in day mode), where metric values sit, and which parameter combinations fail. That is everything needed to call it correctly without guessing.

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 coverage is 100%, so the baseline is 3; the description still adds real value by binding parameters together — limit/offset and sortBy/order are only honored in summary-with-dates, and ids changes the semantics of the returned total. Some of it duplicates the schema (dateFrom/dateTo notes, entity list), and the 'metrics' groups are only touched via 'Метрики лежат в base', so it is additive but not exhaustive.

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 first sentence gives a specific verb and resource ('Возвращает статистику по кампаниям (ad_plans), группам объявлений (ad_groups) или объявлениям (banners)') and enumerates the exact entity values. That makes it trivially distinguishable from the sibling list_*/update_* CRUD tools, which manage objects rather than report metrics.

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?

It gives strong mode-selection guidance: 'day' is declared for trend/dynamics questions only, dates are mandatory there, and weeks/months must be derived from 'day'. It also warns that sortBy/order/limit/offset only work in summary with dates and that the tool will error otherwise. It never routes to an alternative sibling (e.g. raw_request for unsupported groupings) or explains when to prefer list_banners for object metadata, so it stops short of a full routing statement.

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