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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation/safety profile is known. However, the description adds no behavioral detail beyond the action names—no mention of irreversibility, error conditions, or permissions. With annotations covering the basic profile, the description provides minimal extra transparency.

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 concise sentence that front-loads the resource and action list. It avoids fluff and efficiently conveys the core purpose. However, the brevity comes at the cost of omitting action semantics, which is a minor structural flaw.

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 tool (as indicated by annotations), the description lacks critical context: what happens after a delete or moderate, any side effects, or error behaviors. While the schema documents parameter types, the action semantics are unexplained. Given the destructive nature and no output schema, the description is incomplete for an agent that needs to reason about consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (ids has a description, action does not). The description lists the action enum values but merely repeats them without explaining what each action does (e.g., what 'moderate' or 'suspend' entails). The ids parameter is already documented in the schema, so the description adds little semantic value beyond the schema.

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

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

Description clearly states the tool performs an action on ads (объявления) by id, listing the specific actions. This differentiates it from sibling tools like campaign_action and keyword_action which target campaigns and keywords respectively, giving the agent unambiguous resource identification.

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

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

The description implies usage for ads due to the explicit mention of 'объявления', but it does not provide any when-to-use vs. alternatives guidance, e.g., contrasting with campaign_action or keyword_action. No exclusions or conditions are stated, so the agent must infer from the resource name 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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds a useful semantic constraint: BidModifier values are percentages per API rules, e.g. 0–1300, not money. However, it does not disclose whether repeated calls merge with existing modifiers, replace them, or create duplicates, nor what a successful response looks like.

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 with the purpose stated first and the critical value-format constraint immediately after. There is no redundant wording or filler, and the most important operational caveat is front-loaded.

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

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

For a tool with 7 parameters, nested objects, zero required parameters, and no output schema, the description is too thin. It does not mention that a target such as campaignId or adGroupId is likely required, how the adjustment types relate, or how this differs from set_bid_modifiers. An agent would need extra inference or external knowledge to invoke 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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that all percent values are percentages in the API range 0–1300 and are not monetary amounts. It also reinforces the campaign/ad group targeting distinction.

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

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

The description states a specific action and resource: adding a bid adjustment to a campaign or ad group. It is clear and immediately useful, but it does not contrast with the sibling tool set_bid_modifiers, so an agent might not know the exact difference between add and 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?

No guidance is given about when to use this tool instead of set_bid_modifiers, delete_bid_modifiers, or get_bid_modifiers. There are no prerequisites, exclusions, or conditions described beyond the general target being a campaign or ad group.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds valuable behavioral detail beyond that: callouts are immutable and must be deleted/recreated, and binding to ads happens through the Ads service. No contradiction with annotations was found.

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 carry the essential information with no filler. The action is front-loaded, followed by the immutable-recreation constraint and the external binding note. 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 single-parameter tool, the description covers creation, length limits, immutability, and the Ads-service dependency. It would benefit from stating what the tool returns (notably whether created callout IDs are returned), but this is a minor gap for invocation purposes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description repeats the 25-character limit already present in the schema but adds no new semantic meaning for the 'texts' parameter. It neither compensates for gaps nor introduces confusion.

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 'Создаёт уточнения' (creates callouts), naming both the action and the resource. It also adds distinguishing constraints: up to 25 characters and immutability. This clearly separates it from siblings like delete_callouts and get_callouts.

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

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

The description gives clear context for when to use the tool: to create new callouts. It also explains the workflow for changes ('нужно удалить и создать заново'), implying that modifications require delete-then-create. It does not explicitly name the sibling delete_callouts, but the guidance is still actionable.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the description adds no extra behavioral context. It does not mention failure modes, side effects, or authentication requirements beyond what flags convey. Consistency with annotations is maintained, but no additional value is provided.

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, concise sentence that front-loads the core action and mentions optional bids without any fluff. Highly efficient and easy 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?

The tool is simple: two parameters, no output schema. The description covers the main action, but lacks any indication of what the response looks like or potential failure conditions (e.g., if a keyword already exists). Acceptable but not comprehensive.

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 are described in the schema. The description's mention of optional bids ('при необходимости') adds little because the schema already marks bid and contextBid as not required. Baseline 3 is appropriate.

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

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

The description clearly states the verb (adds) and resource (key phrases to ad group), and mentions optional bids. It distinguishes the action from set_keyword_bids (which only sets bids) but does not explicitly differentiate from sibling keyword_action, so it's clear but not fully distinguished.

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?

Provides no guidance on when to use this tool versus alternatives like keyword_action or set_keyword_bids. It simply states what it does without any context on selection criteria 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 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 readOnlyHint=false and destructiveHint=true, and the description does not contradict them. The description adds only the list of actions, which is already present in the schema enum. It provides no extra behavioral context such as irreversibility of delete or effects on related resources.

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 that front-loads the purpose and action list. No redundant content, optimal for an API that expects efficient parsing.

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 low-complexity tool with two required parameters, both covered by the schema (one with description, the other self-explanatory from the enum). The description, along with annotations, adequately conveys the destructive nature and the scope. No output schema is provided, but the description does not need to explain return values for such a simple action 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 50% (only 'ids' has a description). The description repeats the action list already defined in the enum but does not elaborate on the semantics of each action (e.g., difference between suspend and archive). It adds marginal value beyond the schema for the 'action' parameter.

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 over a specific resource (campaigns) and enumerates the exact set of actions (suspend, resume, archive, unarchive, delete). This clearly differentiates it from sibling tools like ad_action or keyword_action by naming the resource and the specific lifecycle operations.

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

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

The description implies usage for campaign lifecycle actions by listing them, but it does not explicitly contrast this tool with alternatives like update_campaign or provide conditions for when to use this tool. No explicit when-not-to-use guidance 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 provide readOnlyHint=false (writing), idempotentHint=false (each call may create a new group), and destructiveHint=false (non-destructive). The description adds minimal behavioral context beyond confirming the write operation. It doesn't mention side effects (e.g., requires existing campaign, creates a new resource each call) or what happens on success/failure. With annotations covering the major traits, a 3 is appropriate – the description adds some but not rich context.

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, direct sentence with the key action front-loaded. No redundant phrasing or filler. It could be slightly expanded to mention usage guidance, but as is, it's concise and to the point, earning a high conciseness score.

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 tool with 3 required parameters and no output schema, the description covers the core purpose and the region aspect. However, it doesn't mention potential prerequisites (e.g., campaign must exist), the return format (e.g., new ad group ID), or error outcomes. Since there are no nested objects and annotations are present, it's adequate but not fully complete – an agent might still wonder what to expect after a successful call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, meaning all three parameters (name, campaignId, regionIds) are already documented in the schema with meaningful descriptions. The description only restates the existence of the regionIds concept ('с заданными регионами показа') without adding new semantics like validation rules or relationships between parameters. Baseline 3 applies because the schema does the heavy lifting.

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 a specific verb ('Создаёт' – creates), the resource ('группу объявлений' – ad group), and the context ('в кампании' – in a campaign, 'с заданными регионами показа' – with specified display regions). It distinguishes this from sibling tools like update_ad_group or delete_ad_groups by implying it's for new ad groups, and there is no ambiguity about the target resource.

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

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

The description implies usage – you'd use this when you need to create a new ad group for a campaign. However, it provides no explicit guidance on when not to use it or alternatives (e.g., when to use update_ad_group or delete_ad_groups instead). Given the large set of sibling tools, some explicit routing would help, but the purpose is straightforward enough that an agent can infer the right context.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses the immutability behavior and the need to reassign the set, which are important side effects not captured elsewhere. This adds meaningful transparency for the agent.

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

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

The description is two sentences, front-loads the action, and states the key constraint (immutability) and follow-up action (reassign) efficiently. There is no extraneous information, and the structure is clear and easy 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 the absence of an output schema and the presence of sibling tools, the description covers the essential behavioral aspects: what it does, the item limit, and the immutability implication. It could explicitly state that the created set is not automatically assigned to an ad, but the phrase 'reassign' implies this, so it is sufficiently 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?

The schema already describes the 'sitelinks' parameter with the same range (1-8 items) and item details. The description does not add new parameter-level information beyond reiterating the range, so it meets but does not exceed the baseline for full schema coverage.

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

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

The description clearly states the action ('Creates a set of quick links') and specifies the resource and its constraints (1-8 items). This distinguishes it from sibling tools like get_sitelinks and delete_sitelinks, leaving no ambiguity about the tool's purpose.

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 explains that sets are immutable and that to change links, one must create a new set and reassign it to an ad. This provides clear guidance on when to use this tool (for initial creation or replacement), covering the primary use case without explicitly listing 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?

Beyond the annotations (readOnlyHint=false), the description discloses additional behavioral traits: it mentions that new ads are drafts and that the tool requires href, which is not evident from the schema alone. It also notes the deprecation of the mobile field indirectly via schema, but the description reinforces this. This adds transparency about the post-creation state (draft) and parameter constraints.

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 composed of two sentences and is relatively concise, front-loading the core action. It includes essential caveats (draft status, alternative for BusinessId) without excessive verbosity. The structure is clear, though it could be slightly trimmed without losing meaning.

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 that there is no output schema, the description adequately covers the operation's purpose, the draft nature of created ads, and the specific requirement for href. It does not describe return values or error scenarios, but the lack of an output schema makes this less critical. The mention of an alternative for BusinessId enhances completeness. Overall, it is sufficiently informative for a create operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage with descriptions for all six parameters, so the baseline is 3. The description adds tool-level context (e.g., href is the landing page and required) but does not provide additional per-parameter semantics beyond what the schema already states. Thus, it adds minimal extra meaning.

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

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

The description clearly states that the tool creates a text ad (TextAd) in an ad group, using a specific verb ('Создаёт') and resource ('текстовое объявление'). It distinguishes itself from related tools by explicitly mentioning that ads with BusinessId should be created via raw_request, thereby differentiating from alternatives.

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

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

The description provides usage context by stating that new ads are created as drafts and that the tool specifically passes the landing page via href (required). It also explicitly points out that for BusinessId, raw_request should be used instead, giving a clear alternative. However, it does not comprehensively cover when to use this tool over other ad creation or update 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?

The description discloses key behavioral details: if biddingStrategy is omitted, manual bids with networks off are applied; passing biddingStrategy fully enables auto strategy or networks. This goes beyond the annotations (which only indicate readOnly false) and gives the agent a clear picture of side effects.

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

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

The description is concise—two sentences—and front-loads the primary purpose. It avoids unnecessary details and clearly presents the key usage caveat, making it easy to parse and act upon.

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 return values are not required. The description suffices for a creation tool, covering defaults and how to modify behavior. It doesn't mention permissions or error handling, but these are not typically expected given the annotations and simplicity of the operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers each parameter with descriptions (100% coverage). The tool description adds valuable context about biddingStrategy's default and override behavior, which enhances understanding beyond the schema. It doesn't duplicate but complements, earning a 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 it creates a TextCampaign (text and graphic ads). It specifies the resource (campaign) and the action (create), and differentiates from siblings like create_ad_group or create_sitelinks_set by focusing on campaign creation.

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 explains when to use the tool: for creating a TextCampaign. It also provides concrete guidance on default behavior (manual bids, networks off) and how to override it via biddingStrategy, which helps the agent decide when and how to invoke 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?

The description discloses a critical behavioral trait: 'Визитки неизменяемы — чтобы поменять, нужно удалить и создать заново' (vcards are immutable — to change, you must delete and recreate). This goes beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. The description adds the immutability constraint, which is essential for the agent to understand the consequences of creation. Annotations don't contradict this; they are consistent with a create operation.

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 concise: two sentences. The first states the purpose, the second adds the critical immutability constraint. It's front-loaded with the action and resource. No wasted words. However, it could have been slightly more structured by mentioning the required campaignId, but that's in 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?

Given the tool has 14 parameters, 6 required, and no output schema, the description is relatively thin. It doesn't explain what the response looks like (though no output schema exists, so the agent might need guidance on return values). It also doesn't mention any side effects beyond immutability, such as whether creation requires specific permissions or if there are rate limits. The immutability note is valuable, but for a complex creation tool with many parameters, more context could be provided, such as typical usage patterns or validation rules.

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 57%, so the schema documents many parameters but leaves some (house, street, building, apartment, contactEmail, contactPerson, ogrn) without descriptions. The description itself doesn't add parameter-level semantics beyond what the schema provides. It mentions the workTime format example in the schema, but the description doesn't elaborate on any parameters. Since coverage is moderate, the description could have compensated but doesn't, so a baseline 3 is appropriate.

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

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

The description clearly states the verb ('Создаёт' = creates) and the resource ('виртуальную визитку в кампании' = virtual business card in a campaign). It distinguishes from siblings like get_vcards and delete_vcards by focusing on creation. However, it doesn't explicitly name the sibling alternatives, so it doesn't fully differentiate from other create tools like create_text_campaign or create_sitelinks_set, though the resource is specific enough.

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 to use it (when you need to create a vcard) but doesn't provide explicit guidance on when not to use it or mention alternatives. It doesn't state prerequisites like needing a campaignId or that the campaign must exist. The context of sibling tools suggests there are related operations (get_vcards, delete_vcards) but no explicit routing 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 flag destructiveHint=true, but the description adds specific context: it deletes ads and key phrases along with the group, and explicitly states that this cannot be undone. This goes beyond the annotation flags and fully discloses the behavior's consequences.

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, tight sentence that front-loads the action and immediately provides the cascade and irreversibility caveats. There is no filler or redundancy, making it highly efficient.

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 tool with one parameter and no output schema, the description covers the action, endpoint, destructive scope, and irreversibility completely. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully documents the single 'ids' parameter with a description ('Id групп, которые нужно удалить'), so the description adds no additional semantic depth. With 100% schema coverage, the baseline of 3 applies as the description does not compensate with extra parameter details.

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 ('Удаляет' – deletes) with a clear resource ('группы объявлений' – ad groups) by id, and references the API endpoint. It distinguishes from siblings like update_ad_group and list_ad_groups by its destructive scope, and explicitly notes it removes associated ads and key phrases.

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 implies when to use it (when permanently deleting ad groups) and warns about the cascade deletion, which helps disambiguate from tools like ad_action or keyword_action. However, it does not explicitly name alternative tools or state conditions when not to use it, so it stops short of full routing guidance.

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

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

The description does not contradict the annotations: destructiveHint=true and idempotentHint=false already signal the destructive, non-idempotent nature of the operation. The description adds only the id-based deletion detail and API endpoint, but does not surface additional consequences such as irreversibility or behavior for nonexistent ids.

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, efficient sentence with no filler. The parenthetical endpoint reference is compact and disambiguating, so every part earns its place.

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

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

For a simple one-parameter destructive tool, the description is nearly sufficient. However, there is no output schema and the description does not mention return values, error cases, or side effects of deleting bid modifiers, leaving minor but real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the 'ids' parameter already has a clear description in the schema. The tool description merely repeats that deletion happens 'по id', adding no new meaning beyond what the schema already provides.

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

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

The description uses a clear action verb ('удаляет') plus a specific resource ('корректировки ставок') and a precise deletion scope ('по id'). It distinguishes this tool from its sibling tools for adding, getting, and setting 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?

The intended use is only implied: use this tool when existing bid modifiers should be deleted by their identifiers. There is no explicit guidance about when not to use it or which alternative tool to choose, although the sibling names make the distinction fairly inferable.

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 destructive nature is conveyed. The description does not contradict this but adds no additional behavioral context such as permanence, side effects, or required permissions. Given the annotations, the minimalism is acceptable but not enhancing.

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, clear sentence with no wasted words. The action is front-loaded directly, making it easy to scan and understand.

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 delete operation with a single array parameter, the description and annotations are adequate. It does not describe the response or error handling, but given the low complexity and lack of output schema, this is a minor gap. An agent can invoke the tool correctly with the information provided.

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 schema covers 100% of the parameter with a description for 'ids' (Id уточнений, которые нужно удалить). The description does not add further meaning beyond what the schema provides. The baseline of 3 applies since the schema is sufficient.

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

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

The description clearly states the verb 'deletes' and the resource 'callouts' (уточнения), specifying deletion by id and referencing the API endpoint. This unambiguously distinguishes it from sibling tools like delete_vcards or delete_sitelinks.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or contrast with other delete operations. An agent has no information about when this is the appropriate choice among many similar 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 indicate destructive behavior and non-idempotency. The description adds a meaningful behavioral constraint: deletion only succeeds for sets not attached to any ad. It does not contradict annotations, though it could disclose behavior when some IDs are linked or invalid.

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 sentence with no filler. It front-loads the action and resource, then immediately states the critical constraint in a parenthetical. Every part contributes to correct invocation.

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 one-parameter delete operation with annotations covering destructive behavior, the description is largely complete. It does not describe the response or error handling if some ids are linked to ads, but the core constraints and action are clear. Given there is no output schema, a bit more detail could help, but the definition is adequate for safe 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?

The schema already fully describes the 'ids' parameter with 100% coverage. The description mostly restates that deletion happens by id and adds the unlinked constraint, which is behavioral rather than parameter-specific. Since the schema carries the parameter meaning, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Удаляет' — deletes) and the resource ('наборы быстрых ссылок' — sitelink sets), and specifies deletion by id. It also distinguishes itself from other deletion tools like delete_callouts or delete_ad_groups by targeting sitelink sets specifically.

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

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

The description implies this tool is for deleting sitelink sets and adds the important condition that only unlinked sets can be deleted. However, it does not explicitly state when to prefer this over create_sitelinks_set or get_sitelinks, nor does it mention alternatives or exclusions beyond the unlinked requirement.

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

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

Annotations already disclose destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds no additional behavioral context such as permanence, side effects, or permissions, but it doesn't contradict the annotations. With annotations carrying the safety profile, this is a neutral baseline.

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 concise sentence that front-loads the verb and resource, includes the endpoint in parentheses for technical reference, and contains no filler. Every word 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?

The tool is simple with one well-documented parameter and strong annotations. The description, while minimal, covers the essential purpose and resource. It omits nothing critical for an agent to call it correctly, though it could elaborate slightly on multi-id deletion semantics, which the schema already conveys.

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% for the single 'ids' parameter, which already explains it contains the ids to delete. The description echoes this without adding new meaning, such as format constraints or relationships to other resources. Baseline for high coverage 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 explicitly states the action (Удаляет – deletes), the resource (визитки – business cards), and the criterion (по id – by id). It also includes the API endpoint (vcards/delete), making the tool's purpose unambiguous and distinct from siblings like delete_callouts or delete_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 description clearly indicates the tool deletes vcards by id, and sibling tools are for other resources, so the use case is inferable. However, it doesn't explicitly state when not to use it or mention alternatives. For a simple delete operation, this is adequate but lacks explicit exclusionary 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?

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 indicate a read-only, idempotent operation, and the description does not add extra behavioral details such as potential errors or rate limits. It is consistent with the annotations, but provides no additional transparency.

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, concise sentence that includes the essential purpose and scope. It avoids unnecessary detail and is well-structured for quick understanding.

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 getter with one optional parameter and no output schema, the description sufficiently covers the tool's functionality. It could mention return format or error scenarios, but these are not critical given the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, fieldNames, is described in both the schema and the description as selecting client fields with a default set. The description adds no new meaning beyond the schema, so the baseline score 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 clearly specifies a verb ('returns data') and a resource ('current advertiser account'), listing typical fields (login, currency, type, country) and the underlying service (`clients`). This distinguishes it from sibling tools like get_balance or get_statistics.

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

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

The description implies usage for retrieving account-level information, but does not explicitly state when to use it over alternatives or any exclusions. There is no mention of when to prefer other tools, leaving the context to be inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the image-hash key and the upload path, but it does not disclose response shape or pagination behavior beyond what the schema already provides.

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 with no filler: the first states the core purpose and key concept, the second routes new-image uploads to the correct sibling tool. The structure is front-loaded and 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 simple read-only list tool with rich annotations and fully documented parameters, the description is sufficient for an agent to select and call it. It could mention what fields the returned image objects contain, but the absence of an output schema and the clear 'returns a list of images' statement keep this from being a major 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 limit, hashes, and offset are already documented in the input schema. The description reinforces that the hash is the key identifier but adds no new syntax, defaults, or parameter-specific guidance beyond the schema.

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

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

The description states a specific verb and resource: 'Возвращает список изображений из библиотеки изображений' (returns a list of images from the image library), and identifies the key as the image hash. It also distinguishes itself from the sibling upload_ad_image by explicitly assigning that tool the responsibility for uploading new 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?

The description gives a clear usage context: this tool lists existing images from the library, while new images are handled by upload_ad_image. It does not explicitly discuss exclusions or other alternatives like get_ad_videos, but the routing to upload_ad_image is a useful when-not signal.

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 operation as read-only, idempotent, and non-destructive. The description adds a small amount of context by stating that IDs are required by the API and that fetching goes through raw_request (advideos/add), but it does not cover output structure or edge-case behavior.

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

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

The description is short and front-loaded with the core purpose. The parenthetical about raw_request is slightly technical but not verbose, and no words are 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 simple get-with-IDs tool, the annotations and schema handle most context. The description is adequate, but with no output schema and no mention of return or error behavior, an agent lacks some information about what to expect after the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% parameter description coverage: ids, limit, and offset are all documented. The description only repeats that ids are required, so it adds little beyond the schema. This matches the baseline 3 for full schema coverage.

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

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

The description clearly states a specific action ('Читает') and resource ('видео из библиотеки видео по id'), making it obvious this is a read operation for video-library entries. It implicitly distinguishes itself from siblings like get_ad_images and get_creatives by focusing on videos, though it does not explicitly contrast itself with them.

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 conveys when to use the tool: when you need to read videos from the library by given IDs. However, it does not provide clear exclusions or alternatives, and the note about raw_request/advideos.add is more implementation detail 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?

The description provides concrete behavioral details: it returns the balance, Amount is a string in account currency (not micro-units), and a negative Amount indicates debt. This complements the readOnlyHint and idempotentHint annotations, giving a full picture of the tool's side-effect-free behavior.

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

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

The description is moderately detailed but well-organized. It covers purpose, uniqueness, field format, negative meaning, and parameter usage in a logical sequence. Some extra context (e.g., 'deprecated service') is included but does not detract from clarity.

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

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

The description lists the returned fields, explains the currency format, and clarifies the default account behavior. Since no output schema is provided, this textual description compensates well. It lacks error-handling details or edge cases, but for a simple read-only balance retrieval, it is sufficiently 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?

The input schema has a single parameter 'logins' with its own description explaining it defaults to the token's account. The tool description repeats this information without adding significant new semantics. Since schema coverage is 100% and the description adds no extra meaning, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns the balance and financial fields, specifying the exact fields (Amount, AmountAvailableForTransfer, Currency, Discount, AccountID). It also distinguishes this tool as the only Yandex Direct API that provides balance, highlighting its unique purpose among 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 explicitly explains the default behavior (returns the token's own account balance) and how to request specific accounts by passing the 'logins' parameter. It also notes that this is the sole API for balance, making it clear when to use this tool rather than alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe-read nature is covered. The description adds valuable behavioral context by noting 'BidModifier — это процент, а не деньги' (BidModifier is a percentage, not money), which prevents a common semantic pitfall and enriches the agent's understanding beyond structured fields.

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

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

Two concise sentences carry a complete thought: what the tool reads, for which levels, and a crucial detail about the data type. No fluff, no repetition of schema information; every word 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 read-only, filterable list operation with zero required parameters and no output schema, the description is largely sufficient. It names the filter categories, defaults via the levels parameter, and gives the percentage semantic. The only minor omission is an explicit statement about the response shape, but this is not critical given the operation's simplicity and annotation coverage.

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 five parameters are documented inline with their own descriptions. The description adds no extra detail about parameters themselves; the percentage hint concerns return-value semantics rather than parameter usage, keeping this at the 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?

The description states a clear verb 'Читает' (reads), identifies the resource as bid adjustments, and lists the supported categories (mobile, desktop, demographics, retargeting, regions, video). It also clarifies the scope to campaigns or ad groups, which together with the sibling tools (add_bid_modifier, set_bid_modifiers, delete_bid_modifiers) makes its purpose distinct and unambiguous.

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

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

The description gives clear context on what data it retrieves and for which entities (campaigns, ad groups), making it obvious when to use this read operation versus the mutation siblings. However, it does not explicitly state exclusions or alternative tools, leaving some inference to the agent.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds context about the adextensions library and the separate Ads binding flow, but discloses no further behavioral details like pagination behavior or return shape.

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

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

The description is two short sentences, front-loaded with the main purpose. The second sentence is not redundant; it sets expectations about the attachment flow, making every word useful.

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

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

Given the schema describes all inputs and annotations cover read-only/idempotent behavior, the description is nearly complete for a simple list/filter operation. However, there is no output schema, and it does not describe the structure of the callout objects returned, which would help an agent understand the response.

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?

All three parameters (ids, limit, offset) already have descriptive definitions in the schema. The tool description adds no additional semantic information about these parameters, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as returning a list ('Возвращает список') of callouts from the adextensions library, which separates it from the add/delete callout siblings. It also clarifies that attaching callouts to ads is done elsewhere. It could be stronger by explicitly naming a sibling such as add_callouts or delete_callouts, but the purpose is not ambiguous.

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 an implied usage signal: you can fetch callouts here, and attaching them to ads is possible through the Ads service. This hints at when to use the tool but does not explicitly state when not to use it or how it compares to adjacent get_sitelinks/get_vcards 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and the description agrees with them. It adds that the response contains smart banners/HTML5 from the creative library, but does not disclose return-format details, pagination behavior, or authentication expectations, so it adds only modest behavior context beyond the annotations.

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

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

The description is a single well-structured sentence with no filler. The main action and object are front-loaded, and the parenthetical adds useful type detail without bloat.

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 simple read-only list operation with zero required parameters and fully described optional parameters, so the description plus schema is sufficient for safe invocation. It is not a 5 because the absence of an output schema means the description could have added a note about what fields a creative object contains or explicitly addressed when this tool should be used instead of get_ad_images/get_ad_videos.

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 (ids, limit, offset) are already documented with meaningful descriptions. The tool description itself does not add any parameter-level meaning or constraints, which corresponds to the baseline score of 3.

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

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

The description clearly identifies a read operation ('Возвращает список') on a specific resource type ('креативов') and adds the sub-types 'смарт-баннеры, HTML5' and source 'библиотека креативов'. This makes the tool's purpose obvious, though it does not explicitly contrast it with nearby sibling tools such as get_ad_images or get_ad_videos.

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 no guidance on when to choose this tool over alternatives and names no sibling tools or exclusions. An agent can only infer that it should be used when a list of creatives is needed, but the description does not say so.

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 read-only and idempotent behavior, and the description adds a useful behavioral caveat: GeoRegions can be very large, steering agents away from unnecessary large payloads. This goes beyond the annotations without contradicting 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?

Two sentences, front-loaded with the core purpose, followed by concrete examples and a single actionable caveat. There is no filler or repetition of schema content.

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 one-parameter read-only operation with a fully documented enum and clear sibling differentiation, the description covers everything an agent needs to select and invoke the tool correctly. No output schema is present, but this is acceptable for a well-known dictionaries endpoint.

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 schema already documents the names parameter fully with an enum and a description, so the description does not need to restate parameter details. It adds a relevant example list, but that is already reflected in 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 ('справочники Яндекс Директа'), then lists concrete examples such as currencies, time zones, constants, and ad categories. It also distinguishes itself from get_regions, so an agent can tell them apart immediately.

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 identifies the alternative get_regions for the case where the agent needs to search regions, warning that GeoRegions can be very large. This gives clear when-to-use and when-not-to-use guidance for the main edge 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 readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the important detail that data comes from the Units header and lists the exact fields returned. This goes beyond the annotations by revealing the data source, which is non-obvious. No contradictions with annotations.

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

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

A single, front-loaded sentence that states the action, the resource, the source, and the purpose. No wasteful words; every part earns its place. The purpose clause is placed at the end but still concise. Excellent efficiency.

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 tool, the description is complete: it specifies the return fields (spent/remaining/limit) and the data source (Units header). No output schema exists, but the description effectively communicates the return content. Some implicit context like authentication state is not mentioned, but it is likely shared across sibling tools. Overall, nothing an agent needs for a basic call 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?

There are no parameters (0 params, schema coverage 100%), so the description does not need to explain parameters. The baseline for zero-parameter tools is 4, and the description correctly avoids irrelevant parameter details. It focuses on the return value instead.

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

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

The description clearly states it returns today's API points quota (spent/remaining/limit) from the Units header. It is specific about the verb and resource, but does not explicitly differentiate from sibling tools like get_balance, which might be confused with financial balance. Still, the core purpose is unambiguous.

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

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

The description includes a usage motivation ('to avoid hitting the daily limit') which implies when to use it, but it does not explicitly state when not to use it or name alternatives such as get_balance. The usage context is implied rather than fully articulated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the semantic context that results feed create_ad_group and that output is limited by the limit parameter, but beyond that it adds little behavioral depth. No contradiction with annotations.

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

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

Two compact sentences, front-loaded with the most important information (purpose and the downstream create_ad_group link). The second sentence partly restates schema details about the substring filter and limit, which is slightly redundant, but the overall size is well-controlled and nothing is extraneous.

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

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

For a simple read-only lookup with 2 optional parameters and no output schema, the description covers purpose, behavior, and result-limiting. The main gaps are minor: no mention of return shape (e.g., list of objects with id/name) and no pointer to get_dictionaries as a potential alternative source of region data.

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%: limit documents its range and default of 50, and query documents substring matching, case-insensitivity, and examples. The description only paraphrases these ('Фильтр — подстрока названия; количество результатов ограничено limit'), adding no meaning beyond the schema, 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 states a specific verb ('Ищет' — searches), a clear resource (regions), and a specific deliverable: the regionIds needed by create_ad_group. This makes the tool's purpose concrete and immediately ties it to a downstream consumer, distinguishing it from generic dictionary lookups.

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 identifies the exact usage context — obtaining regionIds for ad group targeting, referencing create_ad_group by name. However, it does not explicitly exclude alternatives (e.g., get_dictionaries, which may also contain region data) or state when not to use this tool, so it earns a 4 rather than 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 readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, covering the safety profile. The description adds the behavioral detail that ids are required and can be sourced from the SitelinkSetId field of ads, which is useful context. However, it does not elaborate on pagination (though the schema covers limit/offset) or what the response contains, so the added value over annotations is modest.

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 consists of two short sentences, each earning its place: the first states the primary function, the second provides essential guidance on where to obtain identifiers. It is compact and free of fluff, though the second sentence could be slightly more tied to the tool's purpose. Overall, it's appropriately sized for the tool's simplicity.

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

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

Given the simplicity of the tool (read-only, 3 documented params, no nested objects, no output schema), the description is complete for an agent to decide when to call it. Combined with the 100% schema coverage and helpful annotations, the missing details (e.g., return format) are not critical. There's minor ambiguity in whether pagination behavior is fully clear, but that's addressed by the limit/offset parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all three parameters (ids, limit, offset) described in the input schema. The description adds no parameter-specific semantics beyond what's in the schema, so it takes the baseline score of 3 without adding extra 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?

The description uses the verb 'Читает' (reads) with a clear resource, 'наборы быстрых ссылок по id' (sitelinks sets by id), which clearly differentiates it from sibling tools like create_sitelinks_set or delete_sitelinks. While it doesn't explicitly name alternatives, the read-scope is obvious and the source of IDs ('поле SitelinkSetId объявлений') adds precision. The title 'Наборы быстрых ссылок' is a natural noun phrase, but the description removes ambiguity.

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

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

The description implies when to use the tool by stating that it reads by id and that the API requires ids from SitelinkSetId, which is helpful prerequisite guidance. However, it does not explicitly distinguish from alternatives (e.g., when to use get_sitelinks vs. create/delete) or state any exclusions. The contextual hint about where to find ids is useful but not a full when-to-use explanation.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important behavioral traits: the default aggregation level, the server-side limit of 100 detail rows, the tab-separated output without header for most report types, and the rejection of ALL_TIME without campaignIds for specific reports. This transparency helps the agent anticipate response format and potential errors.

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 dense but not overly verbose. It front-loads the primary purpose, then explains special cases and constraints. The structure is logical, though it could be slightly more concise by separating the general behavior from edge cases, but the current length is justifiable given the complexity.

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

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

Given the 14 optional parameters and the absence of an output schema, the description provides sufficient context: it explains defaults, output format differences, and key constraints. It does not explicitly define the exact structure of the returned report rows, but the indication of tab-separated values and the aggregated nature is enough for an agent to handle the response.

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?

While the schema covers 100% of parameters with descriptions, the tool description adds cross-parameter semantics such as the relationship between dateRangeType and dateFrom/dateTo, the effect of zeroClicksOnly/zeroConversionsOnly on detail rows, and the requirement to include Conversions in fieldNames for conversion metrics. This enriches the understanding beyond individual parameter definitions.

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

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

The description clearly states the tool's purpose: it requests a performance report from Yandex Direct Reports service. It specifies the default report type and explains the returned data format, making the tool's function unambiguous and distinguishable from other statistics-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 provides extensive usage guidance: how to get daily dynamics (add 'Date' to fieldNames), constraints on ALL_TIME for certain report types (must specify campaignIds or a limited period), and the special aggregated behavior of SEARCH_QUERY_PERFORMANCE_REPORT. This enables the agent to correctly configure parameters for different use cases.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the disclosure burden. The description adds the data-model context that ids come from the VCardId field of ads, but discloses no further behavioral traits such as error handling for invalid ids, pagination behavior, or response semantics.

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 — the first states the core action and resource, the second adds the essential sourcing context. Every word earns its place, and there is no redundancy with the schema.

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

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

For a simple read-only tool with three fully documented parameters and annotations covering the safety profile, the definition is nearly complete. The VCardId hint connects it to the wider ad data model; the only gap is that the return shape is never mentioned, and there is no output schema to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so ids, limit, and offset are each already documented in the schema. The description adds the VCardId sourcing hint for the ids parameter, a small increment above the schema, which matches the high-coverage baseline of 3.

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

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

The description uses a specific verb 'читает' (reads) with a clear resource — virtual business cards — and a specific access method (by id). The read semantics and resource clearly distinguish it from sibling tools like create_vcard and delete_vcards, whose names alone signal different operations.

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

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

The description gives practical usage context: the API requires ids, and the agent is told they can be sourced from the VCardId field of ads, which directs the agent on where to obtain inputs. It doesn't explicitly name alternatives or exclusion conditions, but for a simple read-by-id tool the sourcing hint provides clear usage direction.

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

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

Annotations already declare the tool is not read-only (readOnlyHint: false), destructive (destructiveHint: true), and not idempotent (idempotentHint: false). The description adds the specific actions (suspend, resume, delete), which aligns with these annotations and gives clarity on the operation types. However, it does not disclose additional behavioral traits such as reversibility, permission requirements, or side effects beyond what annotations and the schema enum already imply. The bar is lower due to annotations, so this is acceptable but not exceptional.

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, compact sentence that front-loads the core concept: performing an action on keywords by ID, followed by a list of the allowed actions. There is zero redundancy, and every part contributes to understanding. It is appropriately minimal for the tool's simplicity.

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 tool with an enum and an array, the description, combined with the schema and annotations, provides enough for an agent to make a correct call. It mentions the action types and the ID nature, and the schema defines required fields. While there is no output schema, that is not required for a mutation operation. The description is adequate, though it could hint at the return value (e.g., a status) or the effect on multiple items, but these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: only the 'ids' parameter has a description, while 'action' does not. The description compensates by listing the three enum values for 'action' in its text, and mentions 'по id' to clarify that ids are the target keywords. This adds context beyond the raw schema, but it does not fully elaborate on the semantics of each action or any constraints on ids (e.g., whether the same id can be in multiple actions). Given the low-to-moderate coverage, the description adds some value but not comprehensive meaning.

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

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

The description clearly states the verb 'Выполняет действие' (performs an action) on 'ключевыми фразами' (key phrases) by ID, and explicitly lists the three possible actions: suspend, resume, or delete. This specifies the resource and operation precisely, though it does not explicitly contrast with sibling tools like ad_action or campaign_action. The resource name 'keyword' already differentiates it, so it's clear but not fully distinguishing.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, no context about required permissions, and no exclusions. It only states what the tool does, without any 'use this when...' or 'instead of...' information. This leaves the agent to infer when this tool is appropriate, which is a notable gap.

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

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

The annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat safety traits. It does add useful behavioral context by stating that the Yandex Direct API requires at least one selection criterion. It does not, however, describe return format, error conditions, or pagination behavior beyond what annotations and schema imply.

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

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

The description is two short sentences with no filler or redundant restatement. The core purpose is front-loaded, and the critical API requirement follows immediately. Every sentence earns its place.

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

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

Given the simple read-only nature, full parameter documentation in the schema, and clear annotations, this description is nearly complete. The one notable gap is the absence of return-shape information and no hint about which fields may be requested via fieldNames, though both are mitigated by schema completeness and the tool's straightforward semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter is individually explained. The description adds genuine cross-parameter meaning: campaignIds and/or ids must be passed, and the API requires at least one criterion. This compensates for the schema listing zero required parameters and clarifies an otherwise non-obvious constraint.

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 operation: it returns a list of ad groups. It unambiguously targets the resource 'ad groups', which distinguishes it from sibling tools like list_ads, list_campaigns, and list_keywords. The verb and object are both specific and accurate.

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

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

The description provides clear context for use: to list ad groups, you must supply campaignIds and/or ids. It does not explicitly name alternatives or exclusions, but the requirement is direct and practically actionable.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already carry the safety profile, and the description's 'Возвращает список' is fully consistent with these. However, the description adds little behavioral context beyond the annotations: it does not mention pagination behavior (limit, offset, autoPaginate semantics), default response size, or behavior when no filters are provided. It neither contradicts the annotations nor significantly enriches 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?

A single sentence with the action verb and resource front-loaded, immediately followed by the filter scope. Every word earns its place and the description remains appropriately brief for a simple list tool. It is a model of efficient communication given the tool's complexity.

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

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

For a read-only list tool with 9 self-describing parameters, no nested objects, and rich safety annotations, the description is close to adequate, but it omits any mention of pagination defaults or the shape of what is returned (no output schema exists to document return values). A future-oriented agent might wonder about defaults for limit/offset. The filtering dimension is well covered though, and the missing return-format guidance is only a moderate gap at this complexity level.

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 at 100%, so the baseline is 3. The description previews parameter semantics by grouping filters conceptually ('по кампании, группе, id, состоянию и статусу'), which maps onto campaignIds, adGroupIds, ids, states, and statuses, aiding overall comprehension. This is a nice touch but adds no detail beyond what the schema already documents for each parameter.

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 ('Возвращает список объявлений' - returns a list of ads) and enumerates the filter dimensions (campaign, group, id, state, status), making the purpose unambiguous. It does not explicitly distinguish this tool from its siblings (e.g., list_campaigns, list_ad_groups), though the resource name 'ads' differentiates it implicitly. A small miss against the highest bar of explicit sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_creatives, get_ad_images, or list_keywords, and does not mention exclusions or preconditions. Given the large sibling list (over 40 tools), some routing hints about when filtering at the ad level is appropriate vs. querying at the campaign or group level would be valuable. Usage is only implied by the tool's own 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds valuable behavioral context beyond them: monetary fields (DailyBudget.Amount, Funds Sum/Balance/SumAvailableForTransfer/Spend) are returned in account currency. This prevents misinterpretation of return values and does not contradict any annotation.

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

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

Two sentences with zero waste: the first front-loads the core function and filter options, the second adds the currency disclosure. 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 an 8-parameter listing tool with no output schema, the combination of a precise description, fully documented schema, and comprehensive annotations covers the agent's call-decision needs: purpose, filters, pagination (in the schema's autoPaginate/offset/limit), safety, and value semantics (currency). The only minor gap is that default return fields are not stated, though the fieldNames parameter makes this largely self-explanatory.

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% — all 8 parameters have individual descriptions in the schema, so the description's mention of filters by id/type/state/status adds no meaning beyond what the input schema already provides. The baseline of 3 applies since the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource pair ('Возвращает список кампаний' — returns a list of campaigns) and enumerates the filter dimensions (id, type, state, status), making the tool's job unambiguous. It is inherently distinguished from sibling listing tools like list_ad_groups, list_ads, and list_keywords by its resource.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named. Usage context is only implied through the resource name and the optional filters; an agent must infer that this is the campaign-listing entry point among 40+ 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds one useful behavioral detail: Bid and ContextBid are returned in account currency. However, it does not describe pagination behavior, response shape, or default returned fields, so transparency is average.

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

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

The description is two sentences, front-loads the main action and filters, and includes only the extra currency detail that matters. No filler or redundant restatement of the title or schema.

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

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

For a read-only list tool, the description plus full schema coverage is mostly sufficient: it states the resource, filters, and currency behavior, and the schema documents paging and field selection. It lacks an explicit statement of response shape or how filters combine, but nothing critical prevents an agent from invoking 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 description coverage is 100%, and all seven parameters have their own descriptions, so the schema already carries the main semantic weight. The description adds minimal param-related value by naming campaign, ad group, and id filters and clarifying currency for Bid/ContextBid, but it does not meaningfully expand parameter understanding.

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: 'Возвращает список ключевых фраз' (returns a list of key phrases), and it names the main filtering dimensions (campaign, ad group, id). This clearly distinguishes it from sibling list tools like list_campaigns, list_ad_groups, and list_ads.

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

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

The description implies usage through its filter options, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or comparison with siblings such as list_ads or add_keywords are provided, so the guidance is only implicit.

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

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

Annotations already 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?

The description adds meaningful disclosures beyond the annotations: money values are passed in micro units without conversion ('Деньги — в микроединицах'), a data-representation gotcha that could silently corrupt bids; it also explains the write-confirmation gate (confirmWrite) for anything not get/has/check. The read/write semantics align consistently with readOnlyHint=false and destructiveHint=true. A small amount of additional color about side effects or response behavior would push this to 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?

Three dense sentences with zero fluff: one for the mechanism and example, one for the use case, one for data-format and safety semantics. Every sentence earns its place, and the most important differentiator (universal fallback) is front-loaded. This is exemplary conciseness, not under-specification.

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 open-world, generic passthrough tool with no output schema, the description covers the critical ground: what it does, when to use it, how writes are gated, and the numeric-unit gotcha. Given its inherent universality (openWorldHint=true, so full behavioral documentation is impossible by design), this is appropriately complete. It could mention rate limits or the absence of an output schema, but those are minor given the passthrough nature.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3, and the description correctly avoids restating parameter definitions. It earns a 4 by enriching the meaning of what gets passed in params (unit semantics for money, the distinction between read and write call shapes) and by explaining when the confirmWrite flag is mandatory. The example format (service 'bidmodifiers', method 'get') also clarifies the expected shape of two parameters beyond their schema text.

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

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

The description states a specific verb and resource ('вызывает напрямую любой сервис или метод API Яндекс Директа v5') with a concrete example (service 'bidmodifiers', method 'get'). It explicitly frames itself as the universal fallback ('для сервисов, у которых нет отдельного инструмента'), which functionally distinguishes it from the many sibling wrappers. The role of 'generic passthrough vs. specialized siblings' is immediately clear.

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

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

The description explicitly conditions usage on the absence of a dedicated sibling tool ('Нужен для сервисов, у которых нет отдельного инструмента'), telling the agent when to select it over alternatives. It also prescribes the read vs. write usage path (get/has/check free; anything else requires confirmWrite=true). It falls just short of 5 by not enumerating concrete sibling names to prefer, and its own 'bidmodifiers' example slightly conflicts with the guidance, since bidmodifier siblings already exist.

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 as non-read-only and idempotent. The description adds meaningful behavior beyond annotations: the API cannot toggle a modifier on/off, the toggle method is deprecated, and deletion is required to disable it. No contradiction with annotations. It does not describe invalid-id or partial-failure behavior, a minor gap.

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

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

The description is compact and front-loaded: the first sentence states the primary mutation, and the second sentence explains an important API limitation and the supported deletion route. Every sentence carries necessary information without padding.

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 one-parameter, fully schema-covered mutation, the description provides enough to choose and call the tool correctly. It also warns about the deprecated toggle method and gives a safe fallback. The main missing piece is return/error behavior, but no output schema is present anyway.

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 required fields id and percent already have clear descriptions. The description says BidModifierSetItem accepts only Id and BidModifier but does not meaningfully expand on the parameter semantics beyond what the schema already 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?

Description states a specific verb and resource: 'Меняет процент существующих корректировок' by adjustment id. It also differentiates this set operation from the delete path by explaining the deprecated toggle limitation and pointing to 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?

The description clearly frames the use case as updating existing bid modifiers rather than enabling/disabling them. It gives an explicit alternative ('удалить через delete_bid_modifiers') for the case where an adjustment must be turned off, though it does not explicitly contrast with add_bid_modifier for creation.

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 mentions it sets manual bids and specifies scope, but it does not disclose side effects such as whether existing bids are overwritten or merged, or how partial failures are handled. The annotations already cover idempotency and non-destructiveness, but the description adds no further behavioral details beyond the basic modification.

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 concise sentence that effectively conveys the core functionality without unnecessary verbosity. It is well-structured and includes all essential information without redundancy.

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

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

The description covers the main use case and the schema defines the structure thoroughly. However, it does not mention potential response behavior or error scenarios, and it is unclear whether setting bids replaces or merges existing values, which would be important for a complete understanding. Given the moderate complexity, it is mostly adequate but leaves a few gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides field-level descriptions for each parameter, and the description adds context about the duality of search and network bids and the ability to target multiple keywords. It clarifies that each element requires a target ID and at least one bid field, which is not fully obvious from the schema alone, adding meaningful 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 clearly states the tool's function: setting manual bids for keyword phrases on search and networks, with the ability to target specific keywords or entire ad groups/campaigns. It includes the API method reference, which adds specificity, and the verb 'sets' is precise.

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 indicate when to use this tool versus alternatives like 'add_bid_modifier' or 'set_bid_modifiers'. Although the name and scope imply it is for keyword bids, there is no explicit comparison or condition to guide selection among sibling 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 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 disclose readOnlyHint=false (mutation), idempotentHint=true, and destructiveHint=false. The description does not introduce additional behavioral information beyond what annotations provide, and it does not contradict them. Role of description is minimal but acceptable given annotation coverage.

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, concise sentence that directly states the action and scope. The information is front-loaded and there is no filler or 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?

The schema fully documents parameters, annotations cover mutation/idempotency/destructiveness, and there is no output schema. The description, though brief, is sufficient for an agent to correctly invoke the tool. The only minor gap is not mentioning negativeKeywords in the prose, but the schema covers it, so overall completeness is strong.

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%, with all four parameters (id, name, regionIds, negativeKeywords) individually described. The description adds no new parameter-level meaning, so it relies on the schema. Baseline 3 is appropriate because the schema carries the burden and does it well.

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

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

The description clearly states the tool updates the name and/or display regions of an ad group, and includes the exact API endpoint (adgroups/update). This distinguishes it from sibling tools like create_ad_group and list_ad_groups, leaving no ambiguity about its function.

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 verb 'updates' and the described scope (name/regions) clearly indicate it modifies existing ad groups. It does not explicitly mention when to prefer it over alternatives, such as using keyword_action for keyword-level changes, or note exclusions, but the purpose itself provides contextual guidance among the sibling list.

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 exposes a genuinely important and non-obvious behavior: the API requires the budget mode to be sent with the budget amount, and if the mode is omitted, the tool reads and preserves the current mode via campaigns/get. It also clarifies that changing the amount does not change the spending pace. This is valuable context beyond what the annotations and schema provide.

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

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

The description is front-loaded with the purpose and contains only relevant information about the API's budget-mode requirement. It is somewhat long and dense as a single sentence, and splitting it into two sentences would slightly improve readability, but every clause adds 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?

The description covers the primary update capabilities and, importantly, the tricky API behavior around budget mode. It does not mention negativeKeywords in the high-level purpose list, but the schema fully documents that field, so the major gap is contextual guidance rather than parameter coverage.

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?

Since the schema description coverage is 100%, the schema already documents individual parameters well. The description adds cross-parameter semantics that are not derivable from the schema alone, particularly the coupling between dailyBudgetAmount and dailyBudgetMode and the fallback behavior when the mode is omitted.

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

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

The description states a clear verb and resource: it updates a campaign's name, end date, and/or daily budget, and it references the underlying API method. It does not explicitly differentiate itself from related siblings such as campaign_action or the update_* tools, so it slightly misses the strongest purpose clarity.

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 about when to prefer this tool over siblings or when to use an alternative instead. Usage must be inferred from the field list, so the description leaves this dimension under-specified.

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, and idempotentHint=true. The description adds the important behavioral detail that editing an active ad sends it for re-moderation, which is not in the annotations. This is valuable context beyond what annotations provide.

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

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

The description is two sentences with zero waste. The first sentence states the purpose and scope, the second adds the critical moderation behavior. It's front-loaded with the most important 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 mutation tool with 5 parameters, all documented in the schema, and no output schema, the description covers the essential context: what it does, what fields it updates, and the moderation consequence. The only minor gap is that it doesn't mention whether partial updates are allowed (e.g., can you update just the title without providing text?), but the schema's optional parameters imply this.

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 5 parameters are already documented in the schema with their constraints (maxLength, minLength, etc.). The description doesn't add much beyond what the schema provides, but it does list the three main fields (title, text, href) in the overview. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the verb (обновляет) and the resource (текстовое объявление), and lists the specific fields that can be updated (заголовок, текст, посадочная страница). It also includes the API endpoint (ads/update) for reference. This distinguishes it from sibling tools like create_text_ad and ad_action.

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

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

The description provides clear context on when to use this tool: when updating the title, text, or landing page of a text ad. It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough given the sibling tools. The note about moderation re-review is a useful usage hint.

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 a non-read-only operation; the description adds meaningful behavior: the server downloads from the URL and encodes it, accepts JPG/PNG/GIF up to 10 MB, and requires horizontal dimensions of at least 1080×607. This helps the agent predict validation and side effects beyond the annotation flags.

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

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

Three dense sentences with no filler: purpose and return value first, input options second, format and dimensional constraints last. Every sentence contributes useful 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 simple upload tool with no output schema, the description covers what the tool does, how to pass the image, what it returns, accepted formats, size limit, and the target ad use case. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes url, name, and imageData, including the exclusivity between url and imageData and the base64 prefix behavior. The description mostly restates these facts, so it adds only marginal parameter-level value.

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 ('Загружает изображение'), a specific resource ('библиотеку изображений (adimages/add)'), and the key return value (AdImageHash). It clearly distinguishes the tool from sibling tools like get_ad_images or delete_callouts.

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

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

It states the primary use case — producing an AdImageHash for a text-graphic ad — and explains the two input alternatives (public URL or base64 imageData). It does not explicitly compare against sibling tools, but no sibling offers equivalent upload functionality, so the guidance is sufficient.

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