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?

Annotations already indicate readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate safety. It adds value by mapping each action to its exact status outcome, which is beyond the annotations. However, it does not mention irreversibility of delete or any side effects beyond status change, though destructiveHint covers general caution.

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 sentence that front-loads the verb and resource, then lists the three possible actions with their corresponding status changes. Zero waste, perfectly concise.

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 simple with two parameters and no output schema. The description fully explains the actions and their effects. The only missing element is explicit mention of whether delete is permanent, but given destructiveHint=true, this is adequately covered. Overall, an agent can call this tool correctly with the provided information.

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 only 50% (ids has a description, action does not). The tool description compensates by explaining the meaning of each action enum value and clarifying that ids refer to campaign IDs. This adds meaningful semantics beyond the schema, effectively covering the gap.

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's purpose: changing campaign status by id, with specific actions and resulting statuses (activate→active, stop→blocked, delete→deleted). The resource (campaigns) is explicit, and the name ad_plan_action alongside siblings like ad_group_action and banner_action distinguishes it without ambiguity.

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 does not explicitly state when to use this tool versus alternatives, but the resource type (campaigns) is clear and distinct from ad groups and banners. Usage context is implied rather than stated, and there are no exclusions or prerequisites mentioned.

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 indicate this is a mutating, non-idempotent operation, so the description does not need to restate that. It adds useful behavioral context: targetings is passed through as-is, monetary fields are in account currency, and extra fields go through `extra`. However, it does not disclose return values, error behavior, or side effects beyond creation.

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 the purpose front-loaded and no filler. The example and currency/extra clarifications each earn their place and do not repeat schema descriptions.

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 create tool with 12 parameters and no output schema, the description covers the most important operational nuances: how targeting is structured, how currency is interpreted, and how to pass additional fields. It lacks an explicit statement about return values, but the schema and annotations cover parameter requirements and mutation semantics well enough for correct invocation.

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 adds meaningful cross-cutting semantics beyond the schema: a concrete targetings example, the account-currency rule for money fields, and the role of `extra` as a passthrough for unspecified fields. This helps an agent understand how to combine parameters correctly.

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: 'Создаёт группу объявлений внутри кампании' (creates an ad group inside a campaign). This clearly distinguishes it from sibling tools like create_ad_plan (creates a campaign) and update_ad_group (updates an existing group). The scope is explicit and immediately understandable.

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 this tool should be used when creating an ad group within a campaign, but it does not explicitly state when not to use it or name alternatives such as update_ad_group or ad_group_action. Usage context is present but left to inference rather than stated directly.

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 this is a non-read-only, non-idempotent operation. The description adds useful behavioral context beyond the schema: money fields use account currency, and `extra` is injected into the request body verbatim. It does not contradict any annotation.

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 three short sentences with no redundancy. The core purpose comes first, followed by two high-value usage notes. 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 rich input schema, annotations, and the extra-field mechanism, the description is largely complete for correct invocation. It could additionally mention what the tool returns or that existing campaigns should be modified via update_ad_plan, but these are minor gaps given the strength of the structured context.

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 adds a cross-cutting semantic rule: all monetary parameters are in account currency, and complex/rare fields should be routed through `extra`. This helps the agent choose the right place for uncommon parameters even when they are not explicitly listed in 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 states a specific action and resource: 'Создаёт кампанию (ad_plan)' — creates a campaign/ad_plan. This clearly differentiates the tool from sibling tools like update_ad_plan or list_ad_plans.

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 practical context: money fields are in account currency, and complex/rare fields should be passed via `extra`, which is mixed into the request body as-is. It does not explicitly name alternatives like update_ad_plan, but the creation intent is unambiguous and the guidance is directly actionable.

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 key behavioral disclosure is that content, textblocks, and urls 'отправляются как есть' (are sent as-is) with no transformation, and that the exact structure depends on the ad format per VK Ads documentation. This adds meaningful insight beyond the annotations, telling the agent the tool is a thin pass-through and that format-specific correctness lives in external docs.

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 sentences with no filler: the first states the core action, the second maps the key structures to their roles, and the third sets expectations about pass-through and external documentation. Every sentence earns its place and the most important 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 tool with 6 parameters, nested objects, an open-world hint, and no output schema, the description is reasonably complete: it covers the action, the parameter roles, the pass-through behavior, and where to find exact shapes. It does not mention the response format or error behavior, but the explicit pointer to the VK Ads documentation compensates for the open-ended structures.

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, and the schema already provides concrete examples for content, urls, and textblocks. The description adds value on top by mapping each structure to its semantic role (creative media, ad texts, links) and by stating all of them are forwarded verbatim, which helps an agent fill them correctly.

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-resource pair ('Создаёт объявление' – creates an ad) and scopes it precisely to 'внутри группы объявлений' (inside an ad group). This clearly distinguishes it from siblings like list_banners, update_banner, and banner_action without needing to open their 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 signals the placement context: a banner is created within an ad group, which aligns with the required adGroupId parameter. However, it does not explicitly name alternatives or state when not to use it (e.g., 'to modify an existing banner, use update_banner'), so it stops 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?

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context: row-count semantics per grouping period, presence of a 'total' summary, metric group locations (base), and currency note for spent. However, it omits pagination behavior (offset/limit/autoPaginate) which remains only in schema, leaving a minor gap.

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 compact yet information-dense, with no filler. It front-loads the core purpose, then layers grouping, sorting, total, and metrics in logical sequence. Every sentence contributes actionable guidance, achieving high efficiency in three sentences.

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's complexity (11 parameters, no output schema), the description covers the most critical pitfalls: grouping semantics, total field, server-side sorting, and metric locations. It does not explicitly mention that dateFrom/dateTo are required for day/week/month (though schema does), nor pagination mechanics. Still, for an agent to call correctly, the description provides sufficient orientation, meriting a 4 rather than 5.

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 parameters are already documented. The description adds semantic depth beyond schema: it explains the meaning of 'summary' vs period modes, gives a concrete sortBy example ('base.spent'), and clarifies that metrics groups like 'base' contain shows/clicks/spent. This extends the schema's basic field descriptions.

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 ('по кампаниям (ad_plans), группам объявлений (ad_groups) или объявлениям (banners)'), naming all three entity types. It clearly distinguishes this stats tool from sibling listing tools like list_ad_plans by focusing on statistical metrics rather than entity enumeration.

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 explicit when-to-use guidance for grouping modes: 'По умолчанию группировка summary — одна сводная строка на объект за весь период; day/week/month нужны ТОЛЬКО для динамики по дням и вопросов про тренд'. It also clarifies that the total field covers all objects so manual summation is unnecessary, and explains server-side ranking via sortBy/order.

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 establish a non-read-only, idempotent, non-destructive operation; the description adds that monetary fields are in account currency and that status is out of scope for this tool. No contradictions with annotations were found. It does not discuss side effects or response behavior, but the annotations lower the burden.

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, each earning its place: the core purpose, the currency clarification, and the status-change alternative. The most important information is front-loaded and there is no redundant or promotional language.

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 and no output schema, the combination of a focused description and fully documented schema is enough to invoke correctly. It lacks any statement about return/confirmation behavior, and the nested targetings/extra objects are only explained in the schema, but those are minor gaps given the rich 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?

Input schema coverage is 100%, so the schema carries the parameter meaning; the description only summarizes fields already documented and repeats the account-currency fact. This meets the baseline but adds little semantic detail 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?

Description starts with a concrete verb ('Меняет') tied to the resource ('группы объявлений') and enumerates the exact mutable attributes: name, budgets, max price, dates, targeting. It also routes status changes to sibling ad_group_action, which prevents confusion with the closest sibling.

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 use case is clear: change attributes of an existing ad group using optional fields. The explicit sentence 'Для смены статуса — ad_group_action' provides a concrete when-not and names the alternative tool, so an agent can decide between update_ad_group and ad_group_action immediately.

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 provide the key safety profile: readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds a small note that money fields are in account currency and routes status changes away, but it does not describe patch semantics, error behavior, or response shape. No contradiction with 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 only two sentences: the first lists the mutable fields, the second covers currency and points to ad_plan_action for status changes. It is front-loaded, minimal, and contains 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 seven-parameter update tool with a fully documented schema and safety annotations, the description covers the remaining needed context: the editable scope, currency units, and the sibling for status changes. It does not spell out response or error semantics, but there is no output schema to match and that gap is minor.

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 already carries a description, type, and constraints such as pattern and exclusiveMinimum. The tool description only groups fields into categories and repeats the currency rule, adding no real parameter-level meaning. The baseline of 3 applies.

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 the exact resource and verb ('Меняет у кампании') and enumerates exactly what can be changed: name, budgets, max bid, and dates. It also explicitly distinguishes the tool from ad_plan_action by reserving status changes for that sibling. There is no ambiguity about what this tool does.

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 an explicit routing rule: 'Для смены статуса — ad_plan_action' tells the agent when not to use this tool and which sibling to use instead. The listed editable fields make it clear when this tool is appropriate. This is direct, actionable usage guidance.

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.