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?

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=false) by disclosing the percentage domain (0–1300, not money), the one-type-per-element API constraint and the deterministic emission order, the Type field stamping each AddResults entry, and precise partial-failure semantics (retry only the types with Errors) versus all-or-nothing within a single type.

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

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

Four dense sentences, all front-loaded and all load-bearing: purpose, value semantics, request shaping, response/error handling. Slightly compression-heavy, but nothing is redundant.

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 8 optional params, nested objects and no output schema, the description covers what a caller most needs: value units, how the payload is split, and how to interpret and retry from AddResults. The only remaining gap is that return-shape detail is described only enough to explain retry, and the campaignId/adGroupId either-or is left to the 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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning on top: percent values follow API percentage rules (0–1300) rather than currency, and it enumerates the five type keys (mobile, desktop, demographics, retargeting, regional) mapped to their adjustment types. It doesn't clarify the campaignId/adGroupId mutual exclusion that the schema hints at.

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?

Opens with a precise verb+resource in the imperative ('Добавляет корректировку ставок на кампанию или группу объявлений') and names the underlying API method (bidmodifiers/add), so an agent knows exactly what is created. However, it never contrasts itself with the sibling set_bid_modifiers or delete_bid_modifiers, leaving the add-vs-overwrite distinction implicit.

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 only implied through the mechanics described (one modifier type per element sent as separate items in a single call, in that order). There is no explicit statement of when to call this versus set_bid_modifiers, which in the sibling list is the obvious alternative for the same resource.

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, destructiveHint=false. The description adds substantive behavioral context: the 25/1000 limits, the immutability constraint forcing delete+recreate, and that ads binding happens in a separate Ads service. This is real value beyond the annotations, though it omits what the response contains for the newly created items.

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, zero waste, and the core creation action plus limits are front-loaded before the immutability caveat. Every sentence earns its place.

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

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

For a mutation tool with full annotation coverage and no output schema, the description covers creation semantics, limits, immutability, and cross-service binding. It is nearly complete; the main gap is that it doesn't indicate whether the response returns created callout IDs needed for the Ads-side binding.

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 both parameters (texts, client_login) are already documented in the schema, including the client_login fallback logic. The description repeats the 25/1000 constraint that the schema already encodes, adding no new parameter semantics. 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+resource ("Создаёт уточнения" = creates callouts) with scope limits (25 chars, 1000/call). It is clear what the tool does, though it doesn't explicitly name the sibling it differs from (get_callouts/delete_callouts are only implied by the immutability note).

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 implies usage via the immutability note ("to change, delete and recreate") and the cross-service binding note ("binding to ads — via Ads service"), which is helpful routing context. However, it never explicitly says when to use this vs get_callouts/delete_callouts or what preconditions (a client_login) select a different path.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing the actual API limits (30/60/1024 chars), the exact error returned when exceeded ('Превышена допустимая длина'), the advice to truncate beforehand, and the immutability of created sets. That is precisely the behavioral context an agent needs before a write call.

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, front-loaded with the operation, then constraints, then the immutability consequence. Dense and purposeful, with only minor redundancy against the schema's maxLength 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 mutation tool with no output schema, annotations covering safety, and fully documented parameters, the description is nearly complete — limits, error behavior, and immutability are all covered. The gap is the return value: since the new set must be 'переназначен объявлению', the agent needs to know an identifier comes back, which is neither in the description nor in an output 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 coverage is 100% and the schema already documents each field's maxLength, so the baseline is 3. The description adds value by explaining the consequence of exceeding those lengths (API error) and by reinforcing the 1–8 item range, though it repeats the character limits already in the schema.

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

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

States a specific verb and resource with scope: 'Создаёт набор быстрых ссылок (1–8 штук)'. It is clearly distinguishable from the sibling read/delete tools (get_sitelinks, delete_sitelinks) by the create verb, but 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?

Gives clear usage context for the key decision: sets are immutable, so changing links requires creating a new set and reassigning it to an ad — which effectively routes the agent here for updates. It does not explicitly name alternatives (delete_sitelinks, get_sitelinks) or state when not to use it.

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, it discloses that ads are created as drafts, that the API emits warnings about automatic field changes, and that Title2 may be merged with Title or dropped depending on the 56-character limit. It also explains the RESPONSIVE_AD combinatorial behavior and the VCard deprecation — behavior an agent cannot infer from annotations alone.

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 dense paragraph that front-loads the creation action and draft status before the alternates and edge-case behaviors. Slightly long, but nearly every clause carries actionable information such as the href requirement and the Title2 merge behavior.

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?

Complete for a mutation tool with no output schema: it covers what gets created (a draft), required linkage (href), the raw_request escape hatch, and the API's warning-based field mutations. Nothing material is left for the agent to guess.

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 real meaning: why href is required (TextAdAdd needs one of Href/TurboPageId/BusinessId), what VCardId no longer does, and how title2 interacts with title. This goes beyond the schema's simple length constraints.

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 (creates) and resource (TextAd in an ad group) and clarifies scope against siblings by naming raw_request as the route for BusinessId-based ads and noting VCard is no longer supported. An agent can distinguish this from update_text_ad 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?

Explicitly routes the agent to raw_request when the ad should use BusinessId instead of a landing page, and states href is mandatory here. It does not explicitly mention update_text_ad for modifications, so it stops short of full when/when-not coverage.

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?

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?

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?

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds that the call is served by the `clients` service and that a default field set applies when none is given, but it says nothing about permissions, token scope, or how restricted/agency logins affect the result.

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

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

A single front-loaded sentence that states the action, the resource, the returned fields, and the backing service with no filler.

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

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

For a non-destructive two-parameter read with 100% schema coverage and no output schema, the description plus schema is nearly sufficient; only the sibling-selection guidance and the account-resolution fallback story are left implicit in the schema text.

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 both parameters carry full descriptions (field enum, login pattern, fallback to YANDEX_DIRECT_LOGIN then the token's own account). The description adds nothing beyond the schema, 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?

Specific verb+resource: returns data of the current advertiser account and names the backend service (`clients`) plus example fields (login, currency, type, country). It does not differentiate itself from neighbors like list_clients or clients_overview, which also return client data, so an agent must infer the boundary.

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 statement of when to use this rather than list_clients, clients_overview, or get_balance, and no mention of the agency/managed-login scenario implied by the client_login parameter. Usage is only implied by the phrase 'current account'.

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 mark the tool read-only and idempotent, but the description adds substantial unreachable-from-schema behavior: default aggregation to one row per object, tab-separated row output without header for most report types, a computed summary (totals + top-N + tail rollup + zero-click/zero-conversion counts) for SEARCH_QUERY_PERFORMANCE_REPORT, and the precondition that Revenue/Profit/GoalsRoi are only populated for Metrica goals with a value. It also discloses a hard validation rule that rejects certain ALL_TIME 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?

Front-loaded with the aggregation default and the Date advice first, then the return-format distinction, so the most decision-relevant facts come early. It is dense and long, but for an 18-parameter tool nearly every clause carries an operational constraint rather than 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 an 18-param tool with no output schema, the description covers default behavior, hard validation rejections, per-report-type return formats, and metric computation semantics (ROAS vs GoalsRoi). Combined with the complete schema, an agent has what it needs to call this 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 3 would be the baseline, but the description goes further: it explains that sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly jointly determine the shape of the SEARCH_QUERY summary, and that Conversions must be added to fieldNames for conversion counts to be usable. Minor gap: it doesn't tie the goals/attributionModels interaction to the description text beyond the schema's own note.

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?

Opens with a specific verb and resource ("Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа") and immediately scopes what is and isn't in the data. No sibling tool covers reporting, and the description makes the tool's domain 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?

Explicit rules are given for when to add "Date" to fieldNames (only for daily dynamics/trend questions), that hourly stats do not exist (minimum is daily; use repeated TODAY snapshots), that ALL_TIME without campaignIds is rejected for SEARCH_QUERY/CRITERIA, and that ROAS must be computed as Revenue/Cost rather than GoalsRoi. These are the exact decisions an agent would otherwise get wrong.

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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description usefully discloses the API-level filter requirement, which is genuine behavioral context. However it says nothing about pagination behavior or how autoPaginate interacts with limit, which materially affects how results are returned.

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, front-loaded with purpose before the requirement, and nothing is padded. However the second sentence only covers one parameter pair while six other parameters go unmentioned, so brevity comes partly at the cost of coverage.

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 read-only list tool with a fully documented schema and no output schema, the description supplies the one non-obvious calling rule. Details like the default page size or what autoPaginate returns per page 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 description coverage is 100%, so every parameter including limit, offset, fieldNames, autoPaginate and client_login is already documented, establishing the baseline of 3. The description only reinforces the ids/campaignIds constraint and adds no semantics for the remaining five parameters.

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 cleanly separates it from write siblings like create_ad_group and delete_ad_groups. It does not explicitly name a read alternative such as list_campaigns, so it stops short of the top mark.

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 a real precondition absent from the schema: at least one of campaignIds or ids must be supplied because the Yandex Direct API demands a selection criterion, with all parameters technically optional this would otherwise be a silent failure. It does not discuss when to prefer listing by campaign vs. by id, or how it relates to sibling list_* 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's added value is the API-level rule that a filter id is mandatory despite the schema marking zero required params. That is a meaningful behavioral constraint an agent cannot infer from structured fields. It does not describe result shape or pagination behavior, keeping it at 4.

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 core requirement and the narrowing behavior front-loaded. Every clause 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 10-parameter read tool with full schema coverage and annotations, the description supplies the one thing the schema omits (the mandatory filter). Minor gaps around autoPaginate/limit interaction and client_login precedence are already covered by the schema text.

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 baseline is 3, but the description adds semantics beyond the schema by grouping campaignIds/adGroupIds/ids as the required selector set and framing states/statuses as narrowing filters. This helps the agent understand parameter relationships rather than read each field in isolation.

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 states a specific verb and resource ('Возвращает список объявлений'), which is unambiguous and distinguishes it from sibling listers such as list_campaigns and list_ad_groups. It does not explicitly name alternatives to route against, so it falls 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?

The description gives an explicit precondition — at least one of campaignIds, adGroupIds or ids must be supplied because the Yandex Direct API demands it — and clarifies that states/statuses only narrow the result. That is real when-to-use guidance, though it does not discuss alternatives like raw_request or get_creatives.

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 a non-obvious behavioral fact beyond them: monetary fields (DailyBudget.Amount, Funds Sum/Balance/SumAvailableForTransfer/Spend) are returned in the account currency, which prevents misreading values. It does not mention pagination shape or volume limits.

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

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

Two dense sentences with no filler: capability and filters first, then the currency caveat that materially affects interpretation of results. Nothing is repeated 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 nine-parameter read tool with no output schema, the description covers purpose, filters and a key return-value semantic (account currency). The remaining gap is the pagination contract (offset/limit vs autoPaginate walking LimitedBy), which is only documented in the schema, not in the description.

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 enums and the fieldNames restriction. The description only echoes four filter names and adds no syntax or format detail beyond the schema, 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?

The description names a specific verb and resource ("Возвращает список кампаний") and enumerates the filter dimensions (id, тип, состояние, статус), so the agent can tell this is a filtered read of campaigns. It does not explicitly distinguish itself from siblings like get_statistics or campaign_action, leaving that inference to the agent.

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 only implied: the word "необязательными" signals that all filters are optional and that omitting them lists everything. There is no explicit statement of when to prefer this tool over list_ad_groups/get_statistics, nor any prerequisite or exclusion 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 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new behavioral facts: the mandatory-filter requirement enforced by the Yandex Direct API and the fact that Bid/ContextBid come back in account currency, which affects how results must be interpreted.

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

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

Three short sentences, each doing distinct work: what it returns, the validity constraint, and a return-value caveat. The most action-critical fact (the mandatory filter) is placed early with no filler.

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

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

With 8 optional parameters, no output schema and 100% schema coverage, the description supplies the missing pieces an agent needs before calling: a required filter and bid currency. It could still say more about pagination behavior (limit/offset vs autoPaginate), which is the one notable gap for a list 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 every parameter carries its own Russian description, so the baseline is 3. The description adds one valuable cross-parameter rule (at least one filter id array is mandatory) that the schema does not express via 'required', plus currency semantics for bid fields, but nothing on fieldNames, limit/offset or autoPaginate interplay.

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 cleanly separates it from list_campaigns, list_ad_groups and list_ads among the siblings. It does not, however, explicitly contrast itself with keyword_action or add_keywords, so the read-vs-write distinction is left to the reader.

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 discloses a hard API constraint — at least one of campaignIds, adGroupIds or ids must be supplied — which tells the agent how to make a valid call. It gives no guidance on when to prefer this listing over keyword_action or how to combine filters, so usage context 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 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 declare destructiveHint=true, readOnlyHint=false and non-idempotent, so the description doesn't need to restate danger; instead it contributes real behavioral detail: the read-vs-write classification (get/has/check vs everything else), the confirmWrite gate, and that monetary values are in micro-units with no conversion. It doesn't cover error behavior, rate limits, or payload limits of the raw endpoint, which for an open-world passthrough would be valuable.

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

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

Four short sentences, front-loaded with the verb and scope, then the carve-out for dedicated tools, then the two facts (micro-units, write gating) that most affect correctness. Nothing redundant with the title or 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 generic, open-world passthrough with no output schema, the description supplies the three things the schema cannot: which services it exists for, how write gating works, and the micro-unit convention. Return-value shape and failure modes are unaddressed, which is the main remaining gap for a raw API escape hatch.

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; the description goes beyond by defining which method values count as reads and by flagging that all monetary fields in params are micro-units without conversion — a semantic trap the schema never mentions. It adds no detail on the params object shape, but the schema already says params are passed as-is.

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: a universal passthrough that calls any Yandex Direct v5 service or method, with a concrete example ("bidmodifiers"/"get"). It also explicitly scopes itself to services that lack a dedicated sibling tool, so an agent can tell it apart from the ~40 named 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?

Gives clear when-to-use ("для сервисов, у которых нет отдельного инструмента"), which implicitly routes the agent to dedicated siblings first, and adds the gating rule that read methods run freely while any other method needs confirmWrite=true. No explicit prohibition or listing of the dedicated alternatives, but the selection condition is unambiguous.

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

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

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?

Annotations already declare this is a non-read-only but idempotent, non-destructive, open-world mutation. The description adds genuinely useful behavior: bids are in account currency, the operation sets manual bids, and the target-type homogeneity rule means a call cannot partially apply across id types. It still omits whether existing/automatic bids are overwritten and what happens on partial failure.

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

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

Two dense sentences, front-loaded with the verb and resource, then the call-structure constraint. Nothing is redundant given what the schema covers, and no sentence is 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 mutation tool with full annotation coverage, a fully documented schema, and no output schema, the description supplies the essential operational facts (currency, one target type per call, separate calls). It could still state whether manual bids replace automated strategies or what the response contains, but nothing critical to correct invocation 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%, and the nested bids schema already documents bid/contextBid currency semantics, the exactly-one-target-id rule, and the homogeneous-id-type rule. The description restates these rather than adding new meaning, so the baseline 3 is correct.

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 (sets manual search and network bids for keywords) and scopes it to individual keywords, all keywords of ad groups, or all keywords of campaigns, plus the API path keywordbids/set. This clearly separates it from bid-modifier and keyword-action siblings without requiring the schema to be opened.

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

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

The description clearly states a hard usage constraint: one target type per call, and separate calls for mixed target types. However, it never says when to prefer this over related tools such as set_bid_modifiers or keyword_action, nor does it mention prerequisites like a manual bidding strategy. Usage is implied rather than routed.

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.