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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond repeating the action enum: it does not say whether delete is irreversible, whether suspend loses settings, or what preconditions (campaign state, moderation) apply.

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 with no filler; the enumeration is dense but necessary. Slightly long action list aside, nothing is wasted.

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 destructive, non-idempotent multi-action tool with no output schema, the description leaves key questions unanswered: which operations are reversible, what state transitions are invalid, and what the call returns. The action semantics are the main 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 67% and both ids and client_login carry descriptions (including the login fallback logic). The action enum itself has no description in the schema, and the tool description only echoes the values without explaining what moderate or archive vs delete actually do.

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 (объявления) and enumerates the allowed operations, so an agent understands it is a state-change tool over ad IDs. It implicitly separates itself from list_ads/update_text_ad by listing lifecycle actions only, though it never states the contrast explicitly.

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 guidance on when to choose this tool over update_text_ad (content edits) or delete_ad_groups (group-level deletion). The presence of both archive/unarchive/delete in one tool makes routing decisions non-obvious, yet nothing addresses them.

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=false, idempotentHint=false, and destructiveHint=false, so the mutation/non-idempotent profile is covered structurally. The description adds the useful behavioral constraint that values are percentages per API rules (0–1300) rather than currency, but says nothing about permissions, whether existing modifiers are merged or replaced, or what happens on repeat 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?

Two tight sentences with the operation stated first and the unit clarification front-loaded behind it. Nothing is wasted, though it is arguably too terse given the tool's 8-parameter nested 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 mutation tool with 8 optional parameters, nested objects, and no output schema, the description covers the unit semantics well but omits the add-vs-set distinction, the campaignId/adGroupId exclusivity rule, and any note on what the call returns. Adequate but with clear gaps.

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 would be 3, but the description adds real meaning the schema lacks: the schema only sets minimum: 0 on percent fields, while the description supplies the 0–1300 domain and clarifies these are percentages, not money. That is a genuinely valuable addition for interpreting all the nested percent fields.

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 names the two scopes it can target (campaign or ad group). It does not, however, differentiate itself from the very similarly named sibling set_bid_modifiers, leaving the add-vs-set distinction to inference.

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 guidance on when to use this tool rather than set_bid_modifiers or get_bid_modifiers, and no mention of prerequisites such as needing exactly one of campaignId/adGroupId. The agent must infer usage purely from the name and schema.

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 a non-read-only, non-idempotent write, but the description adds genuinely new behavioral facts: callouts cannot be modified once created, and this call does not bind them to ads. Missing are the practical limits (max callouts per ad/set) and any auth or error behavior, but it goes meaningfully 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?

Three short sentences with no filler, and the most decision-relevant fact — immutability — is placed early. Every sentence carries information an agent needs.

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 create tool with no output schema, the description covers the essentials: what is created, its size constraint, that it is immutable, and that ad binding is a separate step. It could still say what the call is returning (created IDs) and whether there is a per-ad cap on how many callouts may exist.

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%, with both `texts` and `client_login` fully documented in the schema, so baseline is 3. The description's 25-character note duplicates the schema's maxLength/minLength rather than adding 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 and resource ("Создаёт уточнения") and immediately bounds the unit of work ("до 25 символов каждое"). It does not name the sibling tools it complements, but the create/get/delete callout trio in the sibling list makes its role unambiguous.

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 immutability sentence effectively routes the agent: to change an existing callout you must delete it and create it anew, which points at delete_callouts. It also clarifies a boundary of use — attaching to ads happens elsewhere ("через сервис Ads"), so this tool is library-only. No explicit exclusion of get_callouts, but the 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 this is a mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the safety profile is covered. The description adds only that bids are optional per channel; it does not explain behavior on duplicate/existing keywords or what happens if a bid is supplied for an existing phrase, which is the non-obvious part of a non-idempotent add.

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 names the action and its optional refinement with no waste. It is efficient, though extremely terse for a mutation 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?

With no output schema but a fully described input schema and annotation coverage of the safety profile, the description is minimally adequate. For a non-idempotent mutation it should say more about how duplicates or bid conflicts are handled, and it gives no indication of the return value.

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 three parameters and nested bid/contextBid/keyword fields are already documented. The description's mention of optional search and network bids merely restates schema content without adding format, constraints, or currency nuances beyond it — baseline 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?

States a specific verb and resource (adds keywords to an ad group) with the additional scope that bids for search and networks are optional. An agent can tell this is an add operation, distinct from list_keywords or set_keyword_bids, though the description never names those siblings.

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 when the tool applies (adding new keywords to a group) but gives no explicit when-to-use versus alternatives, no note on whether to use keyword_action or set_keyword_bids for other keyword operations, and no prerequisites such as needing an existing ad group id.

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 this as read-only and idempotent, and the description adds important behavioral context: it makes no network calls and never displays the token itself. It also explains where the token comes from and where saved data resides, which is valuable 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?

The description is compact, front-loaded with the core status information, and then adds the safety guarantee and usage trigger. Every sentence earns its place 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 zero-parameter, read-only diagnostic tool, the description covers what the tool checks, what it will not do, and when to invoke it. The exact output format is not described, but the tool's purpose is simple enough that this is a minor 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?

The tool has zero parameters and the input schema is complete, so there is nothing for the description to compensate for. The description correctly implies no external input 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 identifies a specific verb and resource: it shows whether Yandex Direct is connected, with concrete details like token presence, source, expiry, and file location. This clearly distinguishes it from sibling tools like start_login, finish_login, and direct API 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 gives an explicit trigger condition: call this when Direct tools report that the connection is not configured. It doesn't explicitly discuss when not to use it or compare it to login/logout alternatives, but the intended diagnostic use is still 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, readOnlyHint=false and openWorldHint=true, so the safety profile is fully carried by structured fields. The description adds no behavioral context beyond them: it does not say that delete is irreversible while suspend/resume are reversible, whether partial failures are possible across the id list, or what permissions/client scope 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?

A single front-loaded sentence that states the verb, the target, and the complete action vocabulary with zero filler. Nothing is wasted and the key enumeration is not 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?

This is a destructive batch mutation with no output schema, and the description never addresses the return shape (per-id success/failure, partial completion) or irreversibility. Given the tool's blast radius across multiple campaign ids, more operational guidance is expected.

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 a moderate 67% and both the action enum and client_login fallback behavior (YANDEX_DIRECT_LOGIN / token's own account) are already documented in the schema. The description only restates that ids target campaigns, adding no format, ordering, or batching 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?

The description names a specific verb ('Выполняет действие') and resource ('над кампаниями по id') and enumerates the exact action set (suspend, resume, archive, unarchive, delete), so an agent knows precisely what this does. It stops short of differentiating from close siblings such as update_campaign or ad_action, which would be needed for a 5.

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?

Usage is implied by the enumerated action list rather than stated: there are no when-to-use, when-not-to-use, or alternative-routing sentences (e.g. use update_campaign to change settings instead of this). An agent can infer the batch-state-change role but must guess relative to siblings.

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, idempotent, non-destructive, so the safety profile is free; the description instead adds non-obvious operational traits: archival campaigns excluded from counts, per-client errors isolated into that row rather than aborting the call, a ~1 report/10s rate limit (~5 min for 30 clients), and a statsSkipped marker for stragglers. It also discloses API-point cost per client and the 50-client balance batching. Only gap: it does not describe response ordering or how the row shape looks beyond the fields mentioned.

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?

It is one long paragraph, but front-loaded with the purpose and the core semantics before cost details. Almost every sentence carries a decision-relevant fact (fast vs slow path, error isolation, point cost). It could be split into purpose / cost / output sections for faster scanning, which keeps it from a 5.

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?

No output schema exists, so the description carries the return-shape burden and does: per-client general-account balance, campaign counts split by state (on/suspended/off/ended) and moderation status, plus per-row error text and statsSkipped. Combined with disclosed latency and cost, an agent has everything needed to choose and call it 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?

Schema coverage is 100%, so the 3 baseline applies, but the description genuinely adds semantics: clients come from list_clients unless an explicit logins list is given, stats pulls impressions/clicks/spend with VAT in the client's own currency, and the 5-minute ceiling explains why statsSkipped appears. The limit parameter's interaction with traversal is left to 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 first sentence names a specific resource and scope: an aggregate summary over all agency clients and managed accounts in one call. It explicitly differentiates from siblings by naming list_clients as the source of clients and warning against looping list_campaigns per client. An agent can distinguish this from get_balance, get_statistics, and list_campaigns without opening any 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?

It gives a concrete triggering question («что у меня по аккаунтам в управлении») and an explicit conditional: request stats only when the question is about money or traffic, otherwise the fast path applies. It also names the anti-pattern alternative (looping list_campaigns) and states this summary is cheaper, so the when-not is covered.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the mutating, non-idempotent character is covered structurally. The description adds only that regions are part of creation — no mention of required permissions, whether a duplicate name errors, or what the call returns (notably absent, since there is no output 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?

A single front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification for a mutation tool rather than ideal trimming.

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?

Safety profile is covered by annotations and parameters are fully documented in the schema, so the minimum is met. However, with no output schema, an agent gets no indication of the return value (e.g., the created ad group's id) or failure modes, which the description could have supplied.

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%, including a worked example for regionIds, a pattern and fallback chain for client_login, so the schema carries the semantics. The description only restates that regions and a campaign are involved, adding no new parameter meaning — baseline 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 uses a specific verb+resource ('Создаёт группу объявлений') and adds scope ('в кампании с заданными регионами показа'). It is naturally distinguished from update_ad_group/delete_ad_groups/list_ad_groups by the verb, though it never names those siblings explicitly.

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 when-to-use or when-not guidance, no mention that a parent campaign must already exist, and no routing to alternatives like update_ad_group. Usage is only implied by the phrase 'в кампании'.

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, non-idempotent, non-destructive profile, so the description is not carrying the safety burden. It still adds a non-obvious behavioral trait the annotations omit: the created set is immutable, which shapes how an agent must plan follow-up edits.

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 with zero waste: the core action and count come first, the immutability constraint and its workaround second. No filler, no repetition of schema detail.

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 no output schema, the description explains creation and the immutability constraint, which is what an agent needs to plan the operation. The notable remaining gap is that it never says the new set's identifier is returned so it can be reassigned to an ad, nor mentions permission or ad-type restrictions.

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 (sitelinks array and client_login) are fully documented in the schema. The description's '1–8 штук' merely restates minItems/maxItems and adds no syntax or per-field meaning beyond the structured data, making baseline 3 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 states a specific verb and resource ('Создаёт набор быстрых ссылок') and fixes the cardinality (1–8). It implicitly separates creation from mutation by explaining that sets are immutable, but it does not name the sibling tools (get_sitelinks / delete_sitelinks) that cover the other operations.

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 concrete workflow guidance: to change links you must create a new set and reassign it to the ad, which pre-empts the most likely wrong usage (expecting an update path). It stops short of naming alternative tools or stating prerequisites such as a client_login requirement.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the key added value is the lifecycle fact that new ads are created as drafts ("Новые объявления создаются черновиками") — behavior an agent cannot infer from the schema. It omits the practical consequence of non-idempotency (repeated calls create duplicate drafts) and what state/review step follows.

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 tight sentences: purpose first, draft behavior second, the parameter constraint and sibling redirect last. No filler, and the most decision-relevant facts are 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 7-parameter create tool with fully documented schema and annotations, the description covers purpose, lifecycle and the alternative path. With no output schema, it never says what the call returns (e.g., the new ad's Id), which an agent needs to chain into ad_action or update_text_ad.

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% and href's "обязателен для TextAdAdd" note already appears in the schema, so most of the description's parameter content is a restatement. The only real addition is enumerating the alternative landing-page fields (TurboPageId/VCardId/BusinessId) that do not exist as parameters here, which is marginal.

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 gives a specific verb and resource ("Создаёт текстовое объявление (TextAd)") plus the parent container ("в группе объявлений"), which distinguishes it from create_ad_group, update_text_ad and ad_action among the siblings. It also names the one variant it does not cover (BusinessId ads), so the boundary with raw_request is visible 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?

It states the API-level constraint (TextAdAdd needs at least one of Href/TurboPageId/VCardId/BusinessId) and routes the BusinessId case explicitly to raw_request, which is real when-to-use guidance. It stops short of telling the agent to list_ad_groups/list_ads first or to use update_text_ad for existing ads, so the exclusion set is incomplete.

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 it is a non-read-only, non-destructive, open-world, non-idempotent write. The description goes beyond them by disclosing the hidden default applied when biddingStrategy is omitted (Search HIGHEST_POSITION, Network SERVING_OFF), which an agent could not infer from the schema. It stops short of stating permissions or the resulting object state.

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 sentences, zero padding, with the default-behavior caveat front-loaded before the override instruction. Every clause carries actionable 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?

For a 7-parameter creation tool with a nested biddingStrategy object and no output schema, it covers the highest-risk default but leaves budget semantics, the created object's initial state (e.g. whether it is created stopped/draft), and what the call returns unaddressed.

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 baseline is 3, and the schema already describes biddingStrategy as replacing the default. The description restates that and adds the concrete default values, which is a modest but genuine gain; it says nothing about dailyBudgetMode/dailyBudgetAmount interaction or endDate behavior.

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: 'Создаёт кампанию TextCampaign (текстово-графические объявления)', immediately telling the agent this creates a campaign container rather than an ad group or ad. It never names a sibling, but the campaign-vs-ad distinction is clear from the wording.

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 communicates one real usage decision: omit biddingStrategy to get manual Search bids with networks off, or pass biddingStrategy fully to enable an auto-strategy or networks. There is no guidance on when this tool is preferable to update_campaign, no prerequisites (client_login / auth), and no 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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a real behavioral fact not present in structured data — that created vcards are immutable and must be deleted and recreated to change. It does not address duplicate creation on retry despite idempotentHint=false.

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, zero padding, and the immutability constraint is front-loaded as the second sentence where an agent will read it before calling. Nothing extraneous.

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 15-parameter creation tool with a nested phone object and no output schema, the description covers the create action and the immutability constraint but says nothing about what is returned (e.g., a vcard id) or how client_login resolves when omitted — details an agent needs to chain follow-up calls.

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?

With 15 parameters and only 60% schema description coverage, the description must compensate, but it names no parameters at all. Six parameters (house, street, building, apartment, contactEmail, contactPerson) are undocumented in both the schema and the description, leaving the agent to infer their 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?

The description states a specific verb and resource ('Создаёт виртуальную визитку') and scopes it to a campaign, so the agent knows exactly what is produced. Sibling differentiation is only implicit — get_vcards and delete_vcards exist but are never named.

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 immutability note ('Визитки неизменяемы — чтобы поменять, нужно удалить и создать заново') implies the delete-then-recreate workflow instead of an update tool, which is genuine routing guidance. It never explicitly points to get_vcards for inspection or delete_vcards for the follow-up step.

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?

Although annotations already declare destructiveHint=true and idempotentHint=false, the description adds crucial behavioral detail beyond them: deleting a group cascades to its ads and keywords, and the action cannot be undone. That is exactly the kind of consequence an agent needs before invoking a destructive 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?

It is a single tightly packed sentence with the key operation and endpoint front-loaded, followed by the cascade and irreversibility warning. No wasted wording.

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 two-parameter delete tool with full schema coverage and strong destructive annotations, the description covers everything essential: what is deleted, the cascade effect, and the irreversibility. No output schema exists, so return-value detail is unnecessary.

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 the ids and client_login parameters are already documented in the schema. The description only repeats that deletion is by id and adds no further parameter semantics, making the baseline 3 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 states a specific verb and resource in Russian: deletes ad groups by id, and even names the API endpoint (adgroups/delete). It is clearly distinguishable from siblings such as update_ad_group or list_ad_groups.

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 operation's usage is implied clearly enough — use it to delete ad groups by id — but there is no explicit guidance on when to choose this versus update_ad_group or list_ad_groups, nor any stated exclusions or prerequisites.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that — it does not say deletions are permanent, whether the ids array is applied atomically or partially on failure, or what happens to running campaigns that referenced the modifiers.

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 short sentence with the resource and keying mechanism front-loaded and no filler. It is concise, though part of that brevity comes from omitting useful context rather than from tight editing.

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?

Annotations carry the destructive profile, the schema fully documents both parameters, and no output schema exists, so the description is minimally sufficient. For a destructive batch delete it should still flag irreversibility or partial-failure behavior, which 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 coverage is 100%, including a description for 'ids' and a detailed fallback chain for 'client_login', so the schema carries parameter meaning. The description only echoes that deletion is by id, adding no format or batch-size detail beyond the schema — the baseline 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 states a specific verb and resource ('Удаляет корректировки ставок по id') plus the API endpoint (bidmodifiers/delete), so the agent can tell it apart from get_bid_modifiers, add_bid_modifier and set_bid_modifiers. It does not explicitly name those siblings as alternatives, which keeps it from a 5.

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 delete versus using set_bid_modifiers to update or add_bid_modifier to re-create. The only usage signal is the preposition 'по id', leaving the agent to infer the workflow from the verb alone.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the endpoint reference: it does not say whether deletion is permanent, what happens to ads referencing the callouts, or how partial failures across multiple ids are handled — significant gaps for a destructive batch 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?

A single short sentence, front-loaded with the operation and immediately followed by the endpoint. No waste, though the extreme brevity reflects under-specification rather than disciplined concision.

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 destructive, non-idempotent batch delete with no output schema, the description should at minimum state irreversibility and error semantics. The schema and annotations cover parameters and the safety flag, but the consequences of invoking this tool are left entirely undisclosed.

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 (ids and the optional client_login fallback to YANDEX_DIRECT_LOGIN) are fully documented in the schema. The description's 'по id' merely echoes the schema, which is the expected baseline-3 outcome.

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 ('Удаляет уточнения по id') plus the underlying API endpoint (adextensions/delete), so an agent can tell it apart from get_callouts and add_callouts by the delete verb. It stops short of naming those siblings explicitly.

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 says nothing about when to use this versus add_callouts or get_callouts, and gives no preconditions — e.g. whether callouts must first be detached from ads or whether ids can refer to shared callout sets. Usage must be inferred entirely from the verb.

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, so the safety profile is known. The description adds valuable behavioral context beyond annotations by stating the unlinked-only restriction, which affects whether the call will succeed.

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 with no redundant restatement of the title. Every element, including the restriction, 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 low-complexity destructive tool with full schema coverage and annotations, the description covers the essential precondition and identifier basis. It does not describe error behavior for linked sets, but the key constraint is present.

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%, and both parameters ('ids' and 'client_login') are documented in the schema. The description adds only that deletion is by ID, which is already evident from the schema, so 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 states a specific verb and resource ('Удаляет наборы быстрых ссылок') and the identifier basis ('по id'). The parenthetical restriction further narrows the operation and distinguishes it from sibling tools like get_sitelinks and create_sitelinks_set.

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 clearly states a key precondition: only sitelink sets not linked to any ad can be deleted. This gives useful when-not guidance, though it does not explicitly point to get_sitelinks for discovering IDs or name 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint path and confirms deletion by id — it says nothing about permanence, batch behavior on partial failure, or permission requirements, which would have real value for a destructive batch 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?

A single short sentence with the action front-loaded and zero waste. It is efficiently sized, though perhaps too minimal to be maximally helpful.

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 destructive mutation tool with full schema coverage, annotations carrying the safety profile, and no output schema, the definition is minimally viable. It lacks any behavioral context a caller would want before mass-deleting records, but the structured fields cover the essentials.

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% (both ids and client_login are documented in-schema), so baseline is 3. The description's 'по id' merely restates the ids parameter and adds nothing about the optional client_login fallback semantics already covered by 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 gives a specific verb+resource ('Удаляет визитки') plus the API path (vcards/delete), which is unambiguous. It does not explicitly distinguish itself from siblings like get_vcards or create_vcard, but the name and verb make the distinction obvious.

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?

No guidance on when to use this versus alternatives, no prerequisites, no warnings about irreversibility beyond the implicit verb. The only hint is 'по id', which is a parameter constraint, not usage direction.

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 adds valuable behavior (file permission 0600, live verification, no restart needed, 10-minute TTL), but it contradicts the idempotentHint=true annotation by calling the code 'одноразовый' (one-time) and instructing a fresh code when it is not accepted. A one-time code means repeated calls with the same parameter cannot be idempotent, so the annotation conflict forces a score of 1.

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; key action, side effects, success consequence, and failure handling are each given one focused sentence. The essential 'second step' context 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 one-parameter auth-completion tool, the description covers the prerequisite, file side effect, live validation, and failure recovery. Minor gaps remain: it does not describe the exact response/error shape or whether an existing token file is overwritten, but no output schema is present so these are not blocking.

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% and already defines 'code' as the confirmation code shown by Yandex. The description adds useful lifecycle semantics beyond the schema: the code is single-use, expires in 10 minutes, and must be refreshed via start_login if rejected.

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 action and resource: it exchanges the confirmation code from start_login for an access token, saves it to an owner-only file, and verifies it with a live Direct request. It also frames itself as the 'second step of connection', which distinguishes it from start_login, logout, 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 states when to use the tool ('Второй шаг подключения', with a code from start_login) and what to do on failure: call start_login again for a fresh code. It also tells the agent that after success the rest of the tools work immediately, so sequencing 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?

Аннотации уже задают readOnlyHint=true, idempotentHint=true и openWorldHint=true, поэтому планка ниже. Описание добавляет полезный контекст: источник через сервис `clients` и состав возвращаемых полей, что важно при отсутствии output-схемы, но не раскрывает поведение при ошибках или авторизации.

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?

Одно предложение без лишних слов, ключевая информация (что возвращает и через какой сервис) вынесена вперёд. Ничего не сократить без потери смысла.

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?

Для read-only инструмента с двумя необязательными параметрами и полным покрытием схемы описание достаточно: оно указывает набор возвращаемых данных вместо отсутствующей output-схемы. Не хватает лишь явного указания, как отличить результат при передаче client_login от собственного аккаунта.

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?

Покрытие описаний схемы 100%, поэтому базовая оценка — 3. Перечисленные поля (логин, валюта, тип, страна) дают пример того, что можно запросить через fieldNames, но синтаксис и приоритет client_login описаны только в схеме.

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?

Указывает конкретный глагол и ресурс («Возвращает данные текущего аккаунта рекламодателя») и перечисляет возвращаемые поля (логин, валюта, тип, страна). «Текущего аккаунта» неявно отличает инструмент от list_clients, но сравнение с этим соседом не сформулировано явно.

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?

Формулировка «текущего аккаунта» подразумевает контекст использования, но нет явных указаний когда использовать этот инструмент вместо list_clients или clients_overview, и нет исключений. Ориентирование на соседей остаётся на вывод агента.

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 that results are keyed by image hash, which shapes how an agent consumes the output, but says nothing about pagination behavior or empty-result handling despite limit/offset parameters.

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 with no padding: the operation is stated first, then the sibling routing. Every clause carries 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?

For a zero-required-parameter, read-only listing tool with full schema documentation and no output schema, this is nearly sufficient. The only shortfall is that paging behavior and the shape of the returned hash-keyed collection are not described.

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 limit, offset, hashes and client_login are all documented in the schema itself. The description's hash-key remark gives mild context for the hashes filter but adds no format or usage 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?

States a concrete verb and resource (returns a list of images from the image library) and adds that the result is keyed by image hash, which is a useful distinguishing detail. It does not differentiate itself from other read-heavy siblings like get_creatives, which an agent might reasonably confuse with an image library.

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?

Explicitly routes image-creation to upload_ad_image ("Новые изображения загружает upload_ad_image"), giving a clear when-not signal. However, no positive guidance on when to call this instead of get_creatives or other asset readers is given.

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/openWorldHint, so the safety profile is covered. The description adds the useful fact that the tool cannot upload (redirecting to raw_request/adviews.add) and that ids are an API-level requirement, but says nothing about pagination behaviour or the shape of returned objects.

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, zero filler, with the primary read behaviour front-loaded and the upload redirect as a supporting note.

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 small read-only tool with four fully documented parameters and complete annotations, the description covers purpose, the key constraint and the alternative write path. Only pagination and return-content expectations are left to the schema, which is acceptable here.

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% and all four parameters carry their own descriptions, so the schema does the heavy lifting. The description only echoes the mandatory-id constraint that the schema's own 'ids' description already states, adding no new syntax or format 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?

States a specific verb ("Читает" / reads) and resource ("видео из библиотеки видео по id"), so the agent knows it retrieves video objects by identifier. It also draws a boundary against the upload path, but does not differentiate itself from neighbouring read tools like get_creatives or get_ad_images.

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 clear usage context: read with ids here, and uploads must go through raw_request (advideos/add), which prevents an agent from looking for a write path in this tool. No explicit exclusion criteria against other media-reading siblings are given.

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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds substantive context: the call goes through the legacy AccountManagement Live v4 surface, Amount is a string in account currency (not micro-units), and a negative Amount means debt. These are non-obvious behaviors an agent would otherwise get wrong; only rate limits/legacy-service constraints are unaddressed.

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: the return fields and purpose come first, followed by the legacy-API caveat and then parameter routing. The v4-vs-v5 parenthetical is long but genuinely load-bearing for an agent deciding whether another tool could do the job. Slightly denser than needed but 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?

There is no output schema, so the description carries the return-value burden and does so by naming all five financial fields plus the currency/debt semantics. What remains missing is the shape of the response when 'logins' is used (single object vs per-login array) and any partial-failure behavior, a minor gap for a read-only 2-param tool.

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, but the description adds meaning the schema does not: the agency 'up to 50 logins' cap and the bulk-multi-account use case for 'logins'. It also restates the client_login fallback chain, which the schema already documents.

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 enumerates the returned fields by name. It also differentiates itself structurally from every sibling by noting it is the only Yandex Direct API surface that exposes balance (v5 has no financial method), so an agent can rule out get_account_info or the campaign tools for this need.

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 routing for all three modes: default = token's own account, client_login = that client's account, logins = multiple shared accounts (agency, up to 50 logins). This is clear selection guidance for the parameters. It stops short of stating exclusions or error conditions, which keeps it from a 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, idempotent, non-destructive, and openWorld behavior, so safety is covered. The description adds the important domain fact that BidModifier is a percentage rather than money, plus scope across campaign and ad-group levels—context not present in annotations or schema. It does not describe return shape or pagination.

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 compact sentences are front-loaded with the action and resource, followed by a high-value unit clarification. There is no repetition or wasted text.

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 filter tool with fully documented parameters, the description covers the resource, scope, and key percentage semantic while annotations cover safety. It lacks return-value guidance, but given the simple read behavior and 100% schema coverage this is a minor 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 description coverage is 100%, so all six optional parameters are already documented in the schema; this establishes a baseline of 3. The description mentions campaign/ad-group scope and adjustment types, but adds no filter syntax, default behavior, or enum meaning beyond what the schema 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 ('Читает') and resource ('корректировки ставок'), and enumerates covered adjustment categories and campaign/ad-group scope. This clearly separates it from sibling mutators such as add_bid_modifier, set_bid_modifiers, and delete_bid_modifiers.

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?

Usage is implied by 'Читает' and by the surrounding read-versus-write sibling set, but no explicit when-to-use, when-not-to-use, or named-alternative guidance is provided. An agent can infer it is the read counterpart, yet no workflow context such as inspecting before updating is stated.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the library-source scope and the cross-service linking note, but says nothing about pagination behavior, result size, or auth/account scoping.

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 with no filler, and the core action is front-loaded before the cross-service note. Nothing redundant is included.

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 paginated list tool with full schema coverage and rich annotations, the description covers the essentials. It is thin on what the returned callout objects contain and on pagination semantics, but no output schema exists to relieve that burden entirely.

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 four parameters (ids, limit, offset, client_login) are already documented in the schema, including the fallback behavior of client_login. The description adds no parameter-level meaning beyond that baseline.

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: returns a list of callouts from the adextensions library. The word 'список' plus the read framing distinguishes it from the sibling mutators add_callouts and delete_callouts, though those siblings are never named.

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 second sentence clarifies scope by pointing out that linking a callout to an ad happens in the Ads service, which implicitly bounds what this tool does. However, there is no explicit 'use this when... instead of add_callouts/delete_callouts' guidance or prerequisite note.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the content type of the returned entities, not pagination behavior, result size limits, or auth/scope requirements beyond the client_login param.

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 with no filler. It is appropriately sized, though extremely terse given the tool's filtering and pagination surface.

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 annotations covering safety and full schema coverage of parameters, the essentials are present. However, for a paginated list tool without an output schema, the description says nothing about return shape, ordering, or pagination semantics, leaving a modest 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 description coverage is 100%, so all four parameters (ids, limit, offset, client_login) are already documented, including the login fallback chain. The description adds no additional parameter semantics, so 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 uses a clear verb+resource ('Возвращает список креативов') and clarifies the domain ('из библиотеки креативов') with examples of creative types (smart banners, HTML5). It is distinguishable from list_ads or get_ad_images, though it never names those siblings explicitly.

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 guidance on when to use this tool versus alternatives such as get_ad_images, get_ad_videos, or list_ads. The listing intent is implied only by the verb 'Возвращает список', leaving an agent to infer the use case.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds behavior the annotations do not: one dictionary (GeoRegions) is very large, which warns the agent about payload size and the need to avoid it. It says nothing about client_login resolution behavior or response shape, keeping it below a 5.

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 capability statement comes first and the cautionary sibling reference second. Every clause carries usable 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?

For a two-parameter read-only lookup with full schema coverage and annotations, the description supplies what an agent needs to choose and call it correctly. The only residual gap is that return structure is unaddressed and there is no output schema, though the enumerated dictionary kinds largely imply it.

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 names and client_login are documented in the schema itself, setting the baseline at 3. The description's enumeration of dictionary kinds loosely mirrors the enum values but adds no syntax, limits, or semantics beyond what the schema states.

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 and resource ('Возвращает справочники Яндекс Директа') and enumerates representative contents (валюты, часовые пояса, константы, категории объявлений), so the agent knows exactly what kind of data comes back. It also contrasts itself with a sibling, making it distinguishable without opening the 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 explicit routing for one important case: GeoRegions can be huge, so use get_regions for region lookup instead. That is real when-not guidance. It stops short of stating the general when-to-use framing (e.g. fetch currency/timezone codes before creating campaigns), so it is not fully 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 destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: it discloses the data provenance (the Units response header) and the freshness scope (today's quota), which tells the agent this is a live per-day counter rather than a stored value.

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 returned payload (spent / remaining / limit) and then the motivation. No filler, nothing repeated from the schema or annotations.

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 carries the burden of describing return values and it does so by naming the three fields returned. It stops short of stating the return type or error behavior (e.g. what happens when the Units header is absent), which is a minor remaining gap for a zero-required-parameter read tool.

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% and the client_login parameter already documents the fallback chain (explicit login → YANDEX_DIRECT_LOGIN → token's own account) in full. The description adds nothing about the parameter, so the baseline 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?

States a specific verb and resource: returns today's API point quota broken down as spent / remaining / limit. An agent can distinguish it from get_balance (money) and get_account_info by the 'баллов API' framing, though the description never names those siblings explicitly to reinforce the contrast.

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 trailing clause 'чтобы не упереться в дневной лимит' implies the tool should be consulted before heavy request bursts, which is useful implied usage. But there is no explicit when-to-use rule, no stated frequency, and no routing against the adjacent get_balance / get_account_info tools.

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 safety is covered. The description adds matching semantics (substring) and that output volume is bounded by limit, but says nothing about empty-result behavior or that client_login falls back to config — that fallback 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?

Two tight sentences, front-loaded with the purpose and then the filtering constraint; nothing is filler. The parenthetical aside is slightly dense but earns its place by linking to create_ad_group.

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 lookup with no output schema, the agent learns what comes back conceptually (region ids usable for targeting), how filtering works, and how many results to expect. Missing only whether names/other fields accompany the ids, which would help the agent format results.

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 three parameters are already documented in the schema, including the client_login fallback chain. The description merely restates substring filtering and the limit cap, adding no syntax or defaults beyond what the schema provides — baseline 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?

States a specific verb and resource ('Ищет id регионов') and goes further by naming the exact artifact it produces ('те самые regionIds') and the sibling that consumes it (create_ad_group). An agent can tell instantly that this is a lookup helper for targeting, not a campaign/dictionary dump.

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 the trigger condition well: use it to obtain regionIds before calling create_ad_group, filtered by name substring and capped by limit. No explicit 'when not to use' or pointer to an alternative (e.g. get_dictionaries), which keeps it from a 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=true, idempotent=true, openWorld=true and destructive=false, so the safety profile is covered. The description adds the API's mandatory-id constraint, but says nothing about pagination behaviour (limit/offset) or how the sets are returned, which is the remaining behavioral 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?

Two tightly packed sentences with the core action first and the prerequisite second; nothing is wasted. It is arguably too terse for a tool an agent may need to page through, 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?

For a simple read-only lookup with rich schema descriptions and full annotations, the description is adequate. The main omission is that there is no output schema and the description doesn't indicate the shape of the returned sitelink sets or how pagination results accumulate.

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 including limit, offset and client_login is already documented. The description only reinforces that ids are mandatory and hints at their source, which is marginal added value beyond the schema — baseline 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?

States a specific verb and resource ('Читает наборы быстрых ссылок по id'), and the id-based lookup distinguishes it from create_sitelinks_set and delete_sitelinks in the sibling list. It doesn't explicitly name those siblings, so differentiation is implied rather than stated.

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?

Adds one genuinely useful usage fact: the API requires ids, and they come from the SitelinkSetId field of ads. That covers the main prerequisite, but there is no explicit when-to-use/when-not statement or reference to alternatives such as raw_request for bulk retrieval.

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/idempotent/non-destructive, but the description adds substantial non-obvious behavior: default output is one aggregated row per object, SEARCH_QUERY_PERFORMANCE_REPORT returns a computed summary (totals + top-N + tail rollup + zero-click/zero-conversion counts) shaped by sortBy/topN/minCost/queryContains, and all other reports return tab-separated rows without a header. Metric semantics (no ROAS; GoalsRoi is ROI, not ROAS; Revenue/Profit/GoalsRoi only populate for value-bearing Metrica goals) are exactly the kind of trap-disclosure annotations cannot supply.

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 and nearly every sentence carries information that is not in structured fields, with no filler. The block is dense and unstructured, though—warnings, metric semantics, and output formats run together without separators, making it harder to scan than it needs to 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 an 18-parameter, zero-required, no-output-schema tool, the description covers aggregation defaults, the REJECTION rule for ALL_TIME, the two distinct output shapes, and metric computation caveats. Remaining gaps (e.g. what the summary's tail-rollup row looks like, whether result size is bounded) are minor given the breadth already delivered.

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 would be 3, but the description adds cross-parameter semantics the schema does not: campaignIds is mandatory for ALL_TIME on SEARCH_QUERY/CRITERIA, Conversions must be in fieldNames for conversion-count use and zeroConversionsOnly, and Date is only for daily breakdowns. It stops short of explaining how filters combine with campaignIds or how attributionModels interacts with goals beyond the schema text.

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 opening sentence names a specific verb and resource (requests a performance report via the Yandex Direct Reports service) and immediately scopes it with the default aggregation behavior. It is clearly distinct from sibling account-structure readers like list_campaigns or get_quota, and the reportType enum in the schema reinforces the resource 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?

Strong conditional guidance: add "Date" to fieldNames only for daily dynamics, no hourly granularity exists (minimum is a day; intraday only via repeated TODAY snapshots), and ALL_TIME without campaignIds is rejected for SEARCH_QUERY/CRITERIA. It does not, however, name an alternative tool (e.g. raw_request) for cases this tool cannot serve, so routing versus siblings is only implied.

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, openWorldHint, and non-destructive behavior. The description adds the mandatory-id prerequisite and id source, but does not describe return shape or pagination behavior; with annotations carrying the safety profile, this is adequate.

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 action and the key prerequisite. It does not waste space restating the title or schema fields.

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 low-complexity read tool with full schema coverage and rich annotations, the description covers the action, required id, and where to find ids. Missing explicit pagination or return-value notes are minor because the schema and annotations fill those gaps.

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 ids, limit, offset, and client_login are already documented in the schema. The description adds useful provenance for ids (VCardId from ads), but does not add meaning for the other parameters beyond what the schema 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?

States a specific verb ('Читает') and resource ('виртуальные визитки'), scoped by id. This clearly separates it from sibling mutation tools such as create_vcard and delete_vcards.

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 that the API requires ids and tells the agent where to obtain them: the VCardId field of ads. It gives clear invocation context, though it does not explicitly state when not to use this tool or name 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the action list: it does not say whether 'delete' is irreversible, whether 'suspend' can be undone via 'resume', what happens on a mixed batch of ids, or whether partial failures are reported. For a destructive batch operation, this is a meaningful 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?

A single short sentence with the resource and action list front-loaded and no filler. It is efficiently written, though the brevity is partly the source of the gaps noted elsewhere.

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?

This is a destructive, non-idempotent batch mutation with no output schema, yet the description says nothing about the return value (affected counts, per-id errors), batch limits, or the irreversibility of delete. Given the tool's risk profile and three parameters, the description leaves out information an agent needs to invoke it safely.

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 67% – 'ids' and 'client_login' carry their own descriptions, but 'action' has only an enum. The description restates the enum values without explaining their semantics (what suspension does to a keyword vs deletion), so it adds only marginal meaning over the schema. Baseline 3 is appropriate given the moderate 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?

States a specific verb and resource ('Выполняет действие над ключевыми фразами по id') and enumerates the three supported actions, so an agent knows exactly what the tool mutates. It does not name sibling tools (list_keywords, add_keywords, set_keyword_bids), so differentiation is implied by the resource name rather than stated.

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 guidance on when to use this tool versus alternatives such as set_keyword_bids (bids) or delete_ad_groups-style sibling mutations, and no stated prerequisites. The action enum hints at usage, but an agent must infer that this is the only path for suspend/resume/delete on keywords.

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/idempotent/non-destructive, so the safety profile is covered; the description adds the non-obvious API constraint that a filter is mandatory even though the schema lists zero required parameters. It omits pagination behavior and the cost of autoPaginate over large result sets, which keeps it from a 5.

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 sentences, zero filler, with the hard filter constraint front-loaded immediately after the purpose statement. Nothing is repeated from the schema or title.

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 paged listing tool with no output schema, the description never explains the return shape or how limit/offset/autoPaginate interact in practice, leaving the agent to infer pagination from schema field text. The mandatory-filter rule is well covered, but return-side completeness 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 every parameter is already documented in the schema. The description only reinforces the ids/campaignIds relationship (at-least-one semantics) and adds nothing about limit/offset/autoPaginate interplay beyond the schema text. 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?

States a specific verb and resource ('Возвращает список групп объявлений'), which lets an agent distinguish it from list_campaigns and list_ads by resource name alone. It does not explicitly name sibling alternatives, so it stops short of a 5.

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 a concrete precondition: campaignIds and/or ids must be supplied because the Yandex Direct API requires at least one selection criterion. That is real selection guidance, but there is no statement of when to prefer this over related listing tools or what happens with neither filter.

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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds only that filters are optional; it says nothing about result ordering, default page size, or what happens when no filters are supplied. That is acceptable but adds little 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity comes at the cost of detail for a ten-parameter 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?

With ten optional parameters and no output schema, the description does not explain the shape of a returned ad, which fields come back when fieldNames is omitted, or how limit/offset interact with autoPaginate. The schema compensates for the input side, and annotations cover safety, but the response-side expectations are left implicit.

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 ten parameters are documented in the schema, including client_login's fallback chain and autoPaginate's LimitedBy behavior. The description merely names a subset of the filter dimensions and adds no defaults, formats, or interaction rules beyond what the schema already states, so baseline 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?

States a specific verb and resource ("Возвращает список объявлений") and enumerates the filter dimensions (campaign, group, id, state, status), so an agent knows exactly what it returns. It does not differentiate itself from siblings such as list_ad_groups or list_campaigns, which matters in a family where several list_* tools sit side by side.

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 call this versus list_ad_groups, list_campaigns, or ad_action, and no guidance on when not to paginate manually versus using the autoPaginate parameter. The only implicit signal is the word "filters", which does not constitute usable routing 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 declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds useful non-annotation context: monetary fields such as DailyBudget.Amount and account funds values are returned in the 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?

The description is two sentences with no wasted text, front-loading the main purpose and following with a relevant monetary-currency note that is not obvious from 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 read-only listing tool with full schema coverage and no output schema, the description covers the core purpose and a non-obvious output detail. It lacks explicit pagination behavior and tool-alternative guidance, but those are either schema-covered or minor for this operation.

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 all nine parameters, including limit, offset, autoPaginate, fieldNames, and client_login. The description adds only a high-level mention of the filter dimensions and does not enrich parameter usage beyond what the schema 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 clear verb and resource: returns a list of campaigns, with optional filters by id, type, state, and status. It distinguishes itself from mutating siblings like update_campaign or campaign_action by being explicitly a listing operation, though it does not name alternatives directly.

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?

Usage is implied by the listing purpose and optional filters, but the description gives no explicit when-to-use guidance, no exclusions, and no direction to alternative tools for related tasks such as account or balance retrieval.

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, so the safety profile is covered; the description adds real behavioral context beyond them — archived agency clients hidden by default, and tools falling back to the agency's own account without client_login. It does not describe pagination or the response shape, which keeps it short of a 5.

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 core purpose and the key handoff, then the account-type caveats and the alternative tool. Dense but each sentence carries meaning; slightly long for a three-optional-param list 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 token-scoped client listing with a fully documented schema, the description covers the agency/advertiser split, default filtering of archived clients, the login handoff, and the alternative tool. 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?

Schema coverage is 100% and already documents limit, search, and includeArchived with defaults, so the description need not repeat them. It complements the schema by explaining the semantic meaning of the returned login (used as client_login in any data tool) rather than adding input-param detail, which is the expected baseline.

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 names the API source (AgencyClients.get, YANDEX_DIRECT_CLIENTS). It is clearly separable from clients_overview, which is explicitly described as the summary tool.

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-to-use context for both accountType=agency and accountType=advertiser, states why an advertiser may see an empty list, and routes the agent to clients_overview when a cross-client summary (balance, campaigns) is wanted instead. It also explains the downstream handoff of the returned login into client_login.

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, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds a useful output detail that Bid and ContextBid are returned in account currency, but it does not describe pagination behavior, return shape, or any other operational nuance beyond 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 compact sentences with no wasted wording. Purpose and main filtering capability are front-loaded, followed by a key output detail.

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 has 8 optional parameters, full schema description coverage, and rich safety annotations, so the core definition is complete enough for invocation. The main gap is that there is no output schema and the description only briefly comments on return values (currency of Bid/ContextBid), but this is minor given the fully documented input 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 each of the 8 parameters is already documented in the schema. The description adds only a high-level mention of filtering by campaign, group, or id and does not add syntax or semantics for limit, offset, autoPaginate, fieldNames, or client_login beyond what the schema provides. 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 states a specific verb and resource ('Возвращает список ключевых фраз') and names the filter dimensions (campaign, ad group, id). This clearly distinguishes it from mutation siblings such as add_keywords or set_keyword_bids, though it does not explicitly name an alternative listing tool.

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 explaining that results can be filtered by campaign, ad group, or id, which gives useful context. However, it provides no explicit when-to-use guidance, no exclusions, and no comparison to sibling tools like list_campaigns or list_ad_groups.

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, but the description adds specific details: it only removes the saved token, leaves the env var token untouched, and does not revoke access on Yandex side. This is valuable context beyond the generic destructive flag and fully aligns with 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 three sentences long, with the core action front-loaded in the first sentence and important caveats in the following ones. It is concise, well-structured, and avoids redundancy, making it efficient for an agent to parse.

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 zero parameters and no output schema, the description covers all relevant aspects: what is deleted, what isn't, and what remains active. It is complete for an agent to understand the tool's behavior and side effects without needing further documentation.

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 takes no parameters, so the description does not need to explain parameter semantics. The empty schema is sufficient, and the description adds behavioral context but not parameter-specific information. Baseline for 0 parameters 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 action ('deletes the saved Direct token from disk') and specifies the resource, distinguishing it from the environment-variable token. It also notes that access remains active on Yandex side, further clarifying scope. This is precise and distinguishable from other auth-related 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 does not explicitly state when to use this tool versus alternatives, but it does clarify what it does not do (env var token, revocation). It hints at an alternative (revoking via Yandex ID) but does not frame it as a tool choice or provide explicit when/when-not guidance. The purpose is clear, but usage guidance is minimal.

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 destructive=true / readOnly=false / non-idempotent / open-world, so the safety bar is set; the description still adds real context beyond them: the method-name-based classification of reads vs writes and the confirmWrite gate that must be set. It omits error behaviour, rate limits, and what a failed/denied write returns, which matters for a destructive catch-all.

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 what the tool is, then the routing rule, then the unit convention and write gate. No filler or restatement of the name.

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 five-parameter escape hatch with a free-form nested params object and no output schema, the description covers purpose, routing, units, and the destructive-write gate, which is most of what an agent needs. The remaining gap is that the response shape and per-service params contract depend on external API knowledge the description does not acknowledge.

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, but the description genuinely adds semantics: money values are in micro-units with no conversion, and confirmWrite is tied to the method classification rather than being a free flag. It does not explain that the params object shape is dictated by the target API method, which is the main usage risk.

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 (invokes any service/method directly) and resource (Yandex Direct API v5), with a worked example of service "bidmodifiers" + method "get". It also positions itself against the sibling tools by scope: it is the fallback for services that have no dedicated tool.

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 a clear routing rule (use it for services without a separate tool), which implicitly steers agents to the dedicated tools first, and it spells out the read-vs-write contract (get/has/check are free, everything else needs confirmWrite=true). What it does not do explicitly is forbid use when a dedicated sibling exists or name which services currently lack tools.

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 annotations, the description discloses a critical behavioral limitation: BidModifierSetItem accepts only Id and BidModifier, and the API cannot toggle enabled/disabled state. This is exactly the kind of constraint an agent needs before attempting a state change.

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 and front-loaded: it starts with what the tool does, then immediately states the key limitation and the alternative. Every sentence carries operational value.

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 with no output schema, the description covers purpose, key constraint, deprecation note, and the correct alternative for disabling an adjustment. The schema already documents client_login and the percent field, so no important call-time context 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 already 100%, so the baseline is 3, but the description adds meaningful constraint by clarifying that the item only accepts Id and BidModifier/percent and no toggle flag. The terminology differs slightly from the schema's 'percent' property, but the added semantic restriction is useful.

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: it changes the percentage of existing bid adjustments by adjustment id, and names the endpoint bidmodifiers/set. It also distinguishes the operation from toggling and deleting, so an agent can tell it apart from add_bid_modifier and delete_bid_modifiers.

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 explicit usage boundaries: use this to change percent, cannot enable or disable an adjustment, and to disable one must use delete_bid_modifiers. It even notes that bidmodifiers/toggle is deprecated and unsupported, which directly routes the agent to the correct sibling tool.

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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that bids are manual, apply to search and networks, and are expressed in account currency, though it does not explain overwrite behavior or error handling.

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 and front-loaded, stating the core operation and scope in the first sentence and clarifying currency in the second. There is little waste, though it could be slightly sharper about the bulk-targeting mode.

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 fully documented parameters and annotations covering mutability and idempotency, the description gives enough context to call the tool correctly. It does not describe return values or error cases, but there is no output schema and those gaps are not critical for this mutation tool.

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 input schema already documents the bids array, target IDs, bid/contextBid fields, and client_login. The description reinforces that bids are in account currency and can target keywords, ad groups, or campaigns, but adds little beyond the schema's own 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: setting manual bids for keyword phrases, with scope covering individual keywords or all phrases in ad groups/campaigns, and mentions the endpoint keywordbids/set. This is sufficiently specific to distinguish it from sibling tools like add_keywords, list_keywords, and keyword_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?

The description implies usage by explaining that bids can be applied to individual keywords or to all phrases in specified ad groups/campaigns, but it does not explicitly say when to use this tool versus alternatives such as keyword_action or set_bid_modifiers.

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 and idempotentHint, but the description adds meaningful behavioral detail: it returns a URL, the code is valid for 10 minutes, the code is useless to outsiders, and only this server can exchange it. This goes well beyond the structured 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 somewhat long but every sentence provides necessary guidance: the purpose, the returned OAuth link, user instructions, next step, expiration, and security note. It is front-loaded with the core purpose and remains efficient overall.

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 zero parameters, no output schema, and rich annotations, the description covers all needed context: what the tool returns, how to use that return value, the next tool to call, and important security/expiration details. Nothing an agent needs to invoke 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 no parameter documentation burden on the description. The baseline of 4 applies, and the description appropriately focuses on the tool's behavior and output rather than nonexistent inputs.

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: it is the first step of connecting Yandex Direct and returns a Yandex OAuth link. This clearly distinguishes it from finish_login, which is mentioned as the follow-up step, and from auth_status/logout.

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 explains when to use it: as the first step of the Direct connection flow, and explicitly directs the agent to pass the received code to finish_login. It does not explicitly discuss exclusions or alternative tools, but the step-by-step context is strong.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the useful partial-update signal 'и/или', but omits behaviours the annotations don't cover: that regionIds replaces the existing set and that an empty negativeKeywords array clears them.

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?

One short sentence, front-loaded with the verb and resource, with the endpoint appended for traceability. Nothing is wasted.

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?

A mutation tool with no output schema needs a bit more: the description does not say what happens to fields left unspecified, nor note that at least one of name/regionIds/negativeKeywords should be supplied. Annotations and the complete schema carry most of the load, so this is adequate but not 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 coverage is 100%, so the baseline is 3, but the description actively narrows the operation to two fields when the schema documents five, including negativeKeywords whose replace/clear semantics are important. An agent skimming the description could conclude negative keywords cannot be changed here.

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 (Обновляет) plus the resource (группа объявлений) and even the API endpoint (adgroups/update), which clearly separates it from update_campaign or update_text_ad. However, it narrows the scope to 'название и/или регионы', omitting that the tool can also replace negative keywords.

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 this versus update_campaign, campaign_action or update_text_ad, and no mention of prerequisites such as needing an existing group id from list_ad_groups. Usage is only implied by the tool name.

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 idempotent, non-destructive, non-read-only behavior, yet the description adds a non-obvious hidden side effect: an implicit campaigns/get to fetch the current budget mode before writing, plus the guarantee that changing the amount does not alter delivery pacing. Money-affecting semantics and a hidden read call are exactly the kind of context annotations cannot convey.

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 sentences, both load-bearing: the first identifies the operation, the second covers the tricky parameter interaction and its user-visible consequence. No filler, no restatement of the title, useful detail 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?

With 7 parameters fully documented in the schema, annotations covering the safety profile, and no output schema to explain, the description fills the only real gap — the budget-mode read-and-preserve behavior. An agent can invoke this correctly without further 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 100%, so baseline would be 3; the description earns above that by explaining the coupling between dailyBudgetAmount and dailyBudgetMode (Mode must accompany the sum, otherwise the current one is re-read) — an interaction the per-field schema text does not make explicit. It says nothing about negativeKeywords being a full replacement, leaving that entirely to 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?

States a specific verb and resource (updates campaign name, end date and/or daily budget) and even pins the underlying API method (campaigns/update), so the agent knows exactly what entity is being mutated. The enumeration reads as near-exhaustive yet omits negativeKeywords and client_login, which are real capabilities in the schema, so the scope is slightly under-stated.

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 one conditional usage rule (if dailyBudgetMode is absent, the current mode is read and preserved), which is genuinely useful. It never says when to pick this tool over sibling mutators like campaign_action or update_ad_group, nor does it state prerequisites such as needing id or an accessible client_login.

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 (readOnly=false, destructive=false, idempotent=true), so the bar is lower; the description still adds the non-obvious side effect that editing an active ad sends it back to moderation. It does not clarify whether omitted fields are preserved (partial vs full update), which is the remaining behavioral ambiguity.

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, both load-bearing: the first identifies action and fields, the second delivers the moderation consequence. Nothing redundant and no buried 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?

Full schema plus annotations covering safety and idempotency mean the description only needed to add the moderation re-submission risk, which it does. The one gap is update semantics (whether unspecified fields are cleared or kept), which matters for an idempotent partial-update tool.

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 title2 limits and client_login fallback. The description adds no syntax, format, or fallback detail beyond what the schema provides, so the baseline 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?

States a specific verb ('Обновляет') and resource ('текстового объявления'), and enumerates the editable fields (заголовок, текст, посадочная страница), so it's clearly distinguishable from create_text_ad. It doesn't mention ad_action or otherwise position itself against siblings, which keeps it below a 5.

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 says what is updated but never states when to use this versus ad_action or update_ad_group, nor any prerequisites (e.g. ad must belong to the token's client). The only contextual hint is the moderation note, which is behavioral rather than 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 cover non-read-only, open-world, non-idempotent, and non-destructive behavior. The description adds useful operational details: the server downloads and encodes the URL, accepted formats and size limit, and the horizontal image requirement for text-graphic ads.

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 and front-loaded: it first states the upload action and returned hash, then gives the supported input methods and image constraints. Every sentence contributes necessary context.

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 an upload tool with annotations and a fully described schema, the description is nearly complete: it explains the return value, input alternatives, and image requirements. Minor gaps remain around overwrite behavior and error handling, but these are not critical 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 description coverage is 100%, so the parameters are already documented. The description reinforces the URL-vs-imageData choice and adds relevant image constraints, but does not significantly elaborate 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?

States the specific action (uploading an image to the ad image library via adimages/add), the result (AdImageHash), and how that result is used in a text-graphic ad. This clearly distinguishes it from sibling read tools such as get_ad_images.

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 the primary use case: obtaining an AdImageHash for a text-graphic ad, with the image supplied either by public URL or base64. It gives clear context and constraints, though it does not explicitly mention alternatives such as listing existing images with get_ad_images.

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