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

Annotations already signal mutating and destructive behavior (readOnlyHint=false, destructiveHint=true). The description adds specific behavioral detail beyond those flags by mapping each action value to the resulting status: activate=active, stop=blocked, delete=deleted. This clarifies what the operation actually does to the resource.

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?

A single, compact sentence that front-loads the core behavior ('changes status of ad groups by id') and then lists the action-to-status mappings. Every piece of information is useful, and there is no redundancy with the schema.

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?

For a two-parameter tool with an enum and no output schema, the description plus schema provide enough information to select and invoke it correctly. It omits details about response values or error behavior, but these are not essential for a straightforward status-change action.

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 50%: 'ids' has a description but 'action' does not. The description compensates by explaining the three action enum values and their status mappings. This adds real meaning beyond the raw enum list, though it adds little about 'ids' beyond what the schema already provides.

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 states a specific action ('Меняет статус'), a specific resource ('групп объявлений'), and the exact domain of operations (activate/stop/delete with resulting statuses). It clearly distinguishes this from sibling tools like ad_plan_action or banner_action by naming ad groups and the status-change semantics.

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 gives clear context for when to use the tool: when the caller needs to change the status of ad groups by id, with the exact allowed actions enumerated. It does not explicitly name alternatives or state when-not-to-use cases, so it misses the top tier, but the intended usage is unambiguous.

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

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

Goes beyond the annotations by disclosing the key non-obvious behavior: delete is non-cascading and leaves groups/ads in their prior status. The annotations already flag destructiveHint=true and idempotentHint=false, so the remaining gap is minor — no mention of whether deletion is reversible or what permissions are needed.

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?

Two tight sentences with zero filler: the operations and their state mappings come first, then the important caveat about delete scope. Nothing is left dangling or repeated.

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?

For a two-parameter mutation tool with no output schema and destructive annotations already present, the description covers operations, state results, and cascade behavior. It could still say whether errors on one id abort the whole batch, but that is a small residual gap.

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 50% — only `ids` is documented in the schema, while the `action` enum has no description. The description compensates by defining every enum value's meaning and side effect, though it does not clarify whether `ids` accepts mixed campaigns or what happens on partial failure.

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?

States a specific verb+resource (меняет статус кампаний по id) and enumerates the three concrete operations with their resulting states. It also names ad_group_action and banner_action, making the boundary with siblings explicit.

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?

Each action is spelled out with its effect (activate→active, stop→blocked, delete→deleted), which is effectively the when-to-use guidance an agent needs. It further clarifies that deleting child objects is a separate task routed to ad_group_action and banner_action.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: it makes no network requests and does not reveal the token or client_secret. It also discloses the exact diagnostic details returned, which is valuable context for an agent choosing this tool.

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 front-loaded with the action, then gives the concrete data points, then safety/security constraints, and ends with a one-sentence usage condition. Every sentence contributes information and 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?

For a parameterless diagnostic tool, the description covers what the tool reports, its security behavior (no network, no secret exposure), and the exact trigger for invoking it. Even without an output schema, an agent has enough to call it correctly and interpret its purpose.

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?

The tool has zero parameters and the schema already covers 100% of that, so there is nothing for the description to add about arguments. Per the zero-parameter baseline, this is a strong fit; the description instead clarifies the output dimensions, which is appropriate.

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 starts with a specific verb ('Показывает') and precisely enumerates the resource scope: whether VK Ads is connected, token presence and source, expiry, client_id, account, and saved-data file location. This makes it immediately distinguishable from auth-mutating siblings like start_login, finish_login, logout, and from other diagnostic tools.

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 explicitly gives a usage trigger: call this when VK Ads tools report that the connection is not configured. It does not spell out when-not-to-use or name an alternative such as start_login, so it lacks the full when/when-not/exclusion structure, but the intended selection context is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, indicating a mutation that can be destructive. The description adds specific behavioral context by mapping each action to a resulting status (activate→active, stop→blocked, delete→deleted), clarifying that 'delete' is a status transition rather than a physical deletion. It does not contradict annotations and provides useful detail about the side effects.

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 a single, front-loaded sentence that states the core purpose first ('Меняет статус объявлений по id') and then lists the actions with their effects. No wasted words; it is compact and immediately understandable.

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?

The tool is a simple mutation with two parameters, but there is no output schema and the description does not mention what the response looks like, or any limitations (e.g., maximum number of ids, reversibility of delete). While the core behavior is clear, an agent might need to know the return format or potential errors. Given the simplicity, it is adequate but not exhaustive.

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 50% – only 'ids' has a description. The description compensates for the undocumented 'action' parameter by explaining what each enum value does (status mapping). It also clarifies that the operation is performed on multiple ids (array). This adds meaning beyond the raw schema.

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 states a specific verb ('Меняет статус' – changes status), a resource (объявлений – ads/banners), and distinguishes three actions with explicit target statuses (activate→active, stop→blocked, delete→deleted). It clearly differentiates from sibling tools like update_banner (which would handle field edits) and ad_plan_action/ad_group_action (different resources).

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 implies usage by defining the tool as a status-change operation, but it does not explicitly say when to use this tool versus alternatives like update_banner (which might also allow status changes) or when not to use it. No exclusions or comparative guidance is provided, so the agent must infer the appropriate context.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds genuinely useful behavioral context that annotations do not: monetary fields are in the account currency and arbitrary fields are passed through via `extra`. It does not mention auth requirements, rate limits, or what happens if a duplicate name exists.

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?

Three short sentences with no filler. The purpose is front-loaded, followed immediately by the two highest-risk semantic points (targetings shape and currency), then the catch-all rule for `extra`.

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?

For a 12-parameter, nested-object creation tool with no output schema, the description covers the two trickiest inputs (targetings and extra) but omits any indication of what is returned (e.g. the created group's id) and does not flag that only adPlanId and name are required. Adequate but leaves gaps an agent would need to discover by trial.

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 the baseline is 3, but the description goes beyond the schema by supplying a concrete targeting example ({"geo":{"regions":[188]},"age":{"age_list":[25,26]}}) for a parameter the schema only calls 'sent as-is'. It also clarifies that all money fields (price, maxPrice, budgetLimit, budgetLimitDay) share the account-currency unit, which ties several parameters together.

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 opens with a precise verb and resource in Russian: 'Создаёт группу объявлений внутри кампании', which is unambiguous. The resource (ad group) is distinct from siblings like create_ad_plan and create_banner, though the description never explicitly names those alternatives.

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 sentence 'Остальные поля — через `extra`' gives a usage rule for the catch-all parameter, which is helpful. However, there is no guidance on when to use this tool versus update_ad_group or the ad_group_action sibling, and no stated prerequisites (e.g. the parent campaign must already exist, which adPlanId implies but does not explain).

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

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

Annotations already establish this is a non-read-only, non-idempotent, open-world write with no destructive semantics; the description adds substantial constraints beyond that — budgetLimit vs budgetLimitDay mutual exclusivity, the extra.ad_object_type/ad_object_id requirement for site campaigns, and the status="blocked" recipe for creating without launching. It adds real value over the annotations, but it does not cover throttling or what a successful call returns (the campaign id), which an agent would need for follow-up calls.

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?

Every sentence carries operational content, and the core constraint (VK won't create an empty campaign) is front-loaded. However, it is one dense paragraph with several distinct rules (extra passthrough, adGroups shape, URL binding, budget exclusivity, status blocked) run together, making it harder to scan than a lightly structured version would be.

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?

For a complex create operation with nested objects, no output schema, and high schema coverage, the description covers almost all invocation-time rules (required group structure, URL binding, budget exclusivity, blocked status). The main gaps are the return value/id of the created campaign and any rate-limit expectations, which matter for chaining into create_ad_group.

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 descriptions already document each parameter, which sets the baseline at 3 even though the description adds genuinely useful cross-parameter meaning: required adGroups structure (name, package_id, targetings, priced_goal for max_goals), the

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?

States a concrete verb+resource ('Создаёт кампанию (ad_plan)') and immediately clarifies the non-obvious scope: the campaign is created together with its first ad groups, not standalone. It explicitly hands off to the sibling 'create_ad_group' for groups added later, so an agent can separate this from update_ad_plan and create_ad_group without reading schemas.

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?

Gives explicit when-and-how guidance: VK rejects an empty campaign, so adGroups must carry new groups; subsequent groups go through create_ad_group. It also prescribes the practical path of copying ad_object_id/package_id/priced_goal from existing entities via list_ad_plans/list_ad_groups, and names the concrete failure mode (invalid_package) if the URL binding is missing.

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

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

Annotations already declare the write/one-shot/open-world profile, so the bar is lower and the description earns credit for adding real context: the structures are passed through as-is with no server-side reshaping, and the format-specific shape is delegated to VK Ads documentation. It stops short of saying what is returned (banner id) or whether validation errors are surfaced per field.

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?

Front-loaded with the action and endpoint, then the payload semantics, then the documentation pointer — a logical order with no filler. The parenthetical endpoint note costs some density but pays for itself by preventing a wrong-endpoint call.

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?

For a 6-parameter tool with nested free-form objects and no output schema, the description covers the destination, the meaning of each payload shape, and where to find the per-format contract. The remaining gap is the response shape and the upload_image dependency, which are only implied.

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 3 is the baseline; the description earns a bump by explaining the relationship between the three passthrough objects (content → uploaded media, textblocks → ad copy, urls → links) and by flagging that the exact shape varies per banner format and lives in external docs — something the schema explicitly cannot express.

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?

States a specific verb and resource ('Создаёт объявление') and pins down the exact endpoint (POST v2/ad_groups/{adGroupId}/banners.json), which immediately distinguishes it from list_banners and the other create_* siblings. It also pre-empts a likely confusion by noting that the top-level v2/banners.json is list-only.

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?

Clearly establishes the required context — a banner can only be created inside an existing ad group — and rules out the top-level path. It implies the upload_image prerequisite by saying the creative references already-uploaded media, but does not state prerequisites or failure modes explicitly (e.g. what happens with a wrong adGroupId or a slot-mismatched image).

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

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

The description is rich in behavioral detail (file permissions 0600, live validation request, token lifetime, auto-renewal, new token per call, 5-token limit, invalid_client meaning). However, it directly contradicts the annotation idempotentHint=true by stating 'каждый вызов создаёт НОВЫЙ токен' and warning about a maximum of 5 active tokens, meaning repeated calls have distinct external effects.

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 front-loaded with the core action and every subsequent sentence carries distinct operational value: file permissions, immediate live check, no restart, token lifecycle, repeat policy, token limit, and a common error. 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?

For a tool with no output schema, the description covers prerequisite sequence, side effects, security posture, success condition, and a common failure mode. It does not explicitly describe the return value, but the success state ('остальные инструменты работают немедленно') is sufficiently clear for an agent to act.

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 of parameters is 100%, so the baseline is 3. The description adds meaningful context by indicating the parameters come from start_login, tying them to a sibling tool, and explaining that invalid_client means the pair is incomplete or from different apps. It also reinforces the sensitivity of clientSecret.

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 uses a specific verb ('обменивает' / exchanges) and a clear resource ('client_id и client_secret ... на токен доступа'), and identifies itself as the 'Второй шаг подключения' (second connection step). This clearly distinguishes it from sibling tools like start_login and auth_status.

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 explicitly says this is the second step after start_login, states that after success other tools work immediately, and advises that repeat calls are unnecessary. It does not explicitly name alternatives like auth_status for checking status, but the sequencing and repeat guidance are clear.

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

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

Beyond the read-only/idempotent annotations, it discloses that this is a passthrough call to user.json, that the response is returned raw and unmodified, that the exact balance field name is unverified on the live platform, and that read_payments access may be needed. This is exemplary transparency about uncertainty and side-effect-free behavior.

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 the first sentence, and the following caveats are all substantive rather than filler. The description is longer than strictly necessary, but each sentence communicates a distinct, useful fact about invocation or response handling.

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 no output schema, the description compensates by explaining the raw response shape, the relevant account.balance field, the permission requirement, and the unresolved schema risk. Nothing needed to call this tool safely or interpret its result is missing.

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?

The input schema is empty, and the description nonetheless explains that there are no parameters and that the target account is determined by the token. This adds the only meaningful implicit-parameter context needed for correct invocation.

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 opens with a concrete verb and resource: it returns the current VK Ads account balance, including available funds and currency. It also names the underlying user.json account field and clarifies that the balance is tied to the token's account, which separates it from sibling tools like get_user_info or raw_request.

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 conveys that this tool is for reading the balance of the token's account and that it takes no parameters, so an agent can infer when to use it. However, it never explicitly says when to choose get_balance over alternatives such as raw_request or get_user_info, nor does it give exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: it specifies the return fields (id, name, type) and the filtering behavior (by case-insensitive substring). This gives the agent clear behavioral expectations without contradicting the annotations.

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 zero fluff. The core purpose is front-loaded, and the usage purpose is stated concisely. Every word contributes to understanding the tool.

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?

For a simple read-only list tool with only two optional parameters and no output schema, the description is complete. It covers the return structure, filtering capability, and the practical use case (geo-targeting). Annotations cover safety, and the schema covers parameters. Nothing essential is missing.

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 both parameters (limit and query) are already fully documented in the input schema. The description adds no extra meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 verb (returns), the resource (geo-regions of VK Ads), and the output structure (id, name, type). It also mentions the optional filtering by name substring. This distinguishes it from all sibling tools, none of which deal with region data.

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 gives clear context for when to use the tool: 'Id регионов нужны для гео-таргетинга группы объявлений' (region ids are needed for geo-targeting an ad group). However, it does not explicitly mention alternatives or exclusions. Since no sibling tool provides similar functionality, this is sufficient.

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

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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds value by specifying the exact data returned (limits and remainder) and referencing the endpoint, providing context beyond annotations without contradiction.

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?

A single, front-loaded sentence that states the action, the resource, and the rationale. No filler words; every part 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?

For a parameterless read-only tool with rich annotations, the description fully covers what the tool does and why. No output schema exists, so the description need not explain return format. Nothing an agent needs to call it correctly is missing.

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?

The tool has zero parameters, so there is nothing to explain. With 100% schema coverage (empty schema), the description need not add parameter details, and it doesn't. Baseline for 0 params is 4.

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 tool returns current request limits and remaining quota for VK Ads, referencing the throttling.json endpoint. This specific verb+resource distinguishes it from all sibling tools, which deal with auth, regions, user info, or ad management.

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 rationale 'to avoid hitting the limit' gives clear context for when to call it. It doesn't explicitly mention alternatives, but no sibling tool serves this purpose, so the guidance is adequate though not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds modest context: the underlying user.json endpoint and the presence of additional_info.client_name in the response, but it does not explain default fields, response shape beyond client_name, or auth nuances.

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?

Two dense sentences with no filler. The core function and the most relevant returned field are front-loaded, and the verification use case is stated in the second sentence.

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?

For a read-only, single-optional-parameter info tool, the description is nearly complete: it identifies the endpoint, the account scope, a key return field, and the practical use case. It stops short of enumerating all possible user fields, but the fields parameter and open-world annotation make that reasonably acceptable.

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% for the single optional 'fields' parameter, so the schema carries the parameter meaning. The description adds no parameter-specific guidance beyond the implied default/basic set, which matches the baseline of 3.

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 names a specific verb+resource: returns information about the current VK Ads account (user.json) and specifically calls out additional_info.client_name. This clearly distinguishes it from siblings like auth_status (auth state) and get_balance (financial state) by focusing on full advertiser-account identity.

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 clear context: use this to verify which advertiser account the token points to. It does not explicitly list alternatives or when-not scenarios, but the single intended use is obvious from the token-account tie.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful semantic behavior beyond that: monetary fields are in account currency, and targetings contains geo/demographic/interest targeting structure. There is no contradiction.

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?

Two concise sentences front-load the core action and filters, then add high-value field semantics about currency and targeting structure. There is no filler or redundant repetition of schema details.

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?

For a read-only list tool with all parameters optional and fully explained by the schema, the description covers the key facts an agent needs: what is returned, available filters, currency behavior, and targetings structure. Pagination details are already in the schema, so their absence from the description is not a gap.

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 all 7 parameters are already documented in the input schema. The description adds context by linking filters to ids, adPlanIds, and statuses and by clarifying the targetings field, but it does not provide syntax or constraints beyond the schema.

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 opens with 'Возвращает список групп объявлений' – a specific verb and resource. It clearly distinguishes this read-only listing tool from mutating siblings like create_ad_group, update_ad_group, and ad_group_action, and states the optional filter dimensions.

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 names the supported filter dimensions (id, parent campaign, status), making the intended use clear. It does not explicitly name alternatives or give when-not-to-use guidance, but the listing context and annotations make the read-only role unambiguous.

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

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. The description adds a useful note that monetary fields are in account currency, and clarifies the entity is the top-level campaign object. This adds beyond annotations but does not deep dive into pagination or default behavior, which are partially addressed by the schema.

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 sentences with no redundancy. The main purpose is front-loaded, and the currency note adds value without bloat. Every word contributes to clarity.

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 tool has no required parameters, annotations covering safety, and a schema that documents all parameters, the description covers the core purpose and an important data format detail (currency). It does not explicitly state the response is an array, but that is implied by 'list'. The lack of an output schema makes this acceptable, and no critical missing context stands out.

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 all six parameters are already documented. The description only reiterates filtering by id and status, matching the ids and statuses parameters. It does not add meaningful new parameter context beyond the schema, such as explaining autoPaginate or offset semantics; hence baseline 3 is appropriate.

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 tool returns a list of ad_plan objects (the top-level campaign object in VK Ads) with optional filtering by id and status. This is a specific verb+resource, and it distinguishes from siblings like create_ad_plan, update_ad_plan, and list_ad_groups by explicitly naming the entity and its role.

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 makes clear the tool is for listing ad_plans, but it does not explicitly contrast with alternative tools or state when not to use it. The purpose implies usage for read-only listing, and sibling naming reinforces it, but explicit guidance is absent.

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

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

The annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description does not need to restate that. It adds value by explaining that moderation_status and delivery indicate why an ad is or is not shown, which helps interpret the returned data. However, it does not disclose additional behavioral details such as pagination behavior or response structure, so a mid-range score is appropriate.

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 sentences with no wasted words. The first sentence front-loads the core functionality and filter options, while the second adds interpretive value about the response fields. It is compact, clear, and well structured.

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?

For a read-only listing tool with fully documented parameters, the description provides the essential purpose and clarifies two important response fields. There is no output schema, so the description carries some burden for explaining returned objects, which it partially does via moderation_status and delivery. It could be more explicit about pagination or the general response shape, but the schema's autoPaginate, limit, and offset parameters already signal pagination, making the description reasonably complete.

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%, meaning all 7 parameters are already documented in the input schema with descriptions and constraints (e.g., limit maximum 250, offset minimum 0, statuses enum). The description adds no new parameter-level meaning beyond what the schema provides; it merely restates the filter categories. Baseline 3 is appropriate given the high schema coverage.

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 states a specific verb and resource: 'Возвращает список banner' (returns a list of banners) and clarifies that a banner is an ad/creative object in VK Ads. It names the main filter dimensions (id, parent ad group, status), which helps distinguish it from sibling list tools for ad plans or ad groups. It does not explicitly name sibling alternatives, so it falls just short of a perfect score.

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?

There is no explicit guidance on when to use list_banners versus list_ad_groups, list_ad_plans, or other alternatives. The description implies its use by naming the resource and filtering options, but it does not state when-not-to-use, prerequisites, or context that would route an agent to this tool over siblings. This is a clear gap.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral detail: it specifies exactly what gets deleted (saved token and app data), what is excluded (env var token), and why remote revocation is not performed (because it would delete all tokens for the client_id). This goes beyond the annotations to fully disclose the tool's effects and side effects.

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 a single, dense paragraph that front-loads the core action (delete from disk) and then adds necessary clarifications about the env token and remote revocation. It is slightly longer than minimal but every sentence carries useful information without redundancy.

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?

For a tool with no parameters and no output schema, the description is complete. It explains the exact effect, what is not affected, the manual workaround for the env token, and the rationale for not revoking remotely. An agent has everything needed to decide and invoke this tool correctly.

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?

The tool has 0 parameters and the schema is empty, so schema coverage is 100% trivially. Per the baseline for 0 parameters, a score of 4 is appropriate. The description adds no parameter-level information, but none is needed.

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 it 'Deletes the saved token and VK Advertising application data from disk', naming the specific verb (deletes) and resource. It also explicitly clarifies what it does NOT do (touch the env token, revoke the remote token), which distinguishes it from related auth tools like start_login and finish_login.

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 on when to use this tool (to clear local state) and explains the limitation that the remote token remains active, with a note on how to revoke it manually if needed. However, it does not explicitly contrast with sibling auth tools like auth_status or start_login, though the purpose is implicit.

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

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

Annotations already mark it as non-read-only and destructive; the description adds the specific rule that GET is executed freely while POST and DELETE are writes requiring confirmWrite=true, giving context beyond the annotations.

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?

Four concise sentences, front-loaded with the core purpose, and each sentence adds a distinct piece of information without redundancy or fluff.

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?

The description covers purpose, usage condition, parameter handling, and safety requirements. It does not describe the response format, but for a generic raw request without an output schema this is acceptable and not a critical gap.

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 covers all parameters (100%), and the description adds how `query` maps to the query string and `body` is sent as JSON for POST, enriching the semantics of parameter usage beyond the schema.

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 it performs a universal request to any endpoint of the VK Ads API and explicitly says it is for endpoints without a dedicated tool, distinguishing it from sibling tools that cover specific resources.

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 an explicit condition: use when no separate tool exists, and clarifies that GET is free while POST/DELETE require confirmWrite=true. This is clear guidance on when and how to use it versus the specialized alternatives.

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

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

The description goes well beyond the readOnly/idempotent annotations by explicitly stating that the tool sends nothing to the network and merely returns instructions. It also discloses an important security detail: client_secret is a password that will be stored on disk and is needed for token renewal.

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?

Three dense sentences with no filler: the first states purpose and constraints, the second describes the return value and next action, and the third conveys necessary security guidance. The most important scoping information is front-loaded.

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?

For a zero-parameter tool whose safety profile is already covered by annotations, the description is complete. It tells the agent what the tool returns, how to use the result, what to warn the user about, and which sibling tool to call next.

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?

The input schema is empty, so the baseline is 4. The description adds relevant context about the client_id/client_secret pair even though they are not parameters of this tool, clarifying what the returned instructions will cover.

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 that start_login is the first step of connecting VK Ads and that it returns instructions rather than performing a network action. It names the exact next step (passing the credentials to finish_login), which distinguishes it from the sibling tools.

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 explicitly frames itself as the first step and instructs the agent to pass the obtained client_id/client_secret pair to finish_login. It does not exhaustively state when not to use it, but the positioning relative to finish_login gives clear usage context.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description's remaining job is narrower. It adds that monetary values use account currency, but omits the key behavioral question for an update tool: whether omitted fields are left untouched, and whether replacing targetings discards the previous structure (that detail lives only in the schema).

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?

Three short sentences, front-loaded with the scope, then the currency constraint, then the sibling redirect. No filler and nothing buried.

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?

For a mutation tool with 8 parameters, a nested object, no output schema and full schema coverage plus annotations, the description covers most of what an agent needs. The gap is partial-update semantics and the `extra` escape hatch, which an agent could misuse without further explanation.

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 of the 8 parameters is already documented, including currency and the YYYY-MM-DD pattern; baseline is therefore 3. The description only restates the field groups and repeats the account-currency rule, without explaining the `extra` passthrough or partial-update semantics.

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?

Names a specific verb (Меняет) plus the exact resource and enumerates the mutable field groups (название, бюджеты, предельную ставку, даты, таргетинг), so an agent knows precisely what this tool writes. It also disambiguates from the closest sibling by routing status changes to ad_group_action.

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?

Gives an explicit alternative ('Для смены статуса — ad_group_action'), which is the most likely confusion given that sibling exists. It lacks any positive when-to-use context or prerequisites (e.g. that the ad group must exist / be editable), so it falls short of a full 5.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds that monetary fields use account currency, which is genuinely useful for correct invocation. It does not disclose the partial-update behavior (are omitted fields left untouched?) or failure modes, which is the main remaining behavioral gap for a mutation tool.

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?

Two short sentences, front-loaded with the mutation scope and immediately followed by the sibling routing rule. Every clause earns its place with 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?

For a 7-parameter mutation tool with full schema coverage, annotations and no output schema, the description covers field scope, units and the key sibling alternative. The one substantive omission is whether the operation is a partial patch (only provided fields change), which an agent needs to avoid unintended overwrites.

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 the schema already documents every parameter including id, extra, dateEnd format and currency. The description's currency note largely restates the schema's own wording and adds nothing about the 'extra' passthrough object or partial-update semantics. Baseline 3 applies when the schema carries the detail.

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?

Names a specific verb (меняет) and resource (кампания), then enumerates the exact mutable fields: name, budgets, max bid, dates. It also explicitly distinguishes itself from ad_plan_action, so an agent can tell the two apart without opening either schema.

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?

Gives one explicit routing rule — use ad_plan_action for status changes — which is the most likely confusion with this tool. It does not spell out other conditions (e.g. that only supplied fields are modified, or when to prefer create_ad_plan vs this tool), so guidance is clear but not exhaustive.

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

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

Annotations already carry the mutation profile (readOnlyHint=false), idempotency, and non-destructive hints, so the description's incremental behavioral contribution is limited to stating that structures are sent as-is. This is useful for nested objects but is also already reflected in the schema property descriptions. It does not discuss response format, error behavior, or replacement semantics beyond what the schema states.

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: the action is front-loaded, the sibling alternative is given immediately, and only one additional behavioral caveat ('Структуры отправляются как есть') is included. 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?

For a mutation tool with solid annotations and a fully described schema, this definition supplies the missing selection context: what can be updated and which sibling handles status changes. No output schema exists, but the update semantics and nested-object behavior are adequately covered by the description plus the parameter schema.

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 every parameter is already documented. The description adds a light semantic grouping (name, text blocks, links), but no new details for id, extra, or the raw-pass-through behavior beyond what the schema already provides.

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 uses a specific verb ('Меняет' – changes) and identifies the resource (banner/объявление) plus the affected fields: name, text blocks, and links. It also explicitly distinguishes itself from banner_action, which handles status changes, so an agent can select this tool without opening schemas.

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 clearly states the main use case and explicitly routes status changes to the sibling tool banner_action ('Для смены статуса — banner_action'). This is an explicit when-to-use versus alternative instruction, leaving no ambiguity about which tool handles status updates.

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

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

Annotations only declare non-readonly, open-world, non-idempotent, non-destructive. The description adds real behavioral context beyond that: the multipart POST transport, the returned id/variants, the failure mode bad_width produced by oversized images, and the critical warning that a network error or 5xx may still mean the upload succeeded, so blind retries are unsafe.

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?

Front-loads what the tool does and what it returns, then chains the downstream usage, then the sizing constraint, then the retry hazard. Five dense sentences with no filler; every clause carries operational information.

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?

There is no output schema, and the description compensates by naming the return fields (id, variants). For a 3-parameter upload tool with annotations covering safety, the description supplies the remaining essentials: transport, output, downstream wiring, size constraint, and retry 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 coverage is 100%, so the baseline is 3; the description still adds value by tying width/height to slot constraints (e.g., the 600 px limit for image_600x600) and reinforcing that base64 must omit the data: prefix. It does not add much beyond the schema for individual fields, but the slot-dimension relationship is genuinely new meaning.

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?

States a specific verb (uploads) and resource (JPEG/PNG image into VK Ads media library), names the underlying endpoint (multipart POST v2/content/static.json), and describes the return value (id and variants). It is clearly distinguishable from siblings like create_banner, which it explicitly feeds into.

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?

Explains exactly how to consume the result: pass the id into create_banner as content.<slot>={'id': <id>}, and notes the required slots depend on the group's package format. It also gives concrete sizing guidance (image_600x600 rejects wider than 600 px → bad_width) and an explicit when-not-to-act rule: do not retry blindly after a network error or 5xx.

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