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

Annotations already convey mutating, idempotent, non-destructive behavior. The description adds useful context beyond that: it returns API confirmation plus apiPointBalance, and it cannot create or invite users. It doesn't detail duplicate-access error behavior, but with idempotentHint=true the retry story is already covered.

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 the action and scope first, followed by a parameter/limitation note, then alternative and return value. The parameter restatement is slightly redundant with the schema but not wasteful enough to lower further.

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 mutation with rich schema coverage and annotations, the description covers purpose, limitation, alternative, and return value. It could note error behavior on duplicate access, but idempotentHint already addresses retry safety. Overall sufficient for correct invocation.

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

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

Schema coverage is 100% and the schema descriptions are already detailed (userId format, role enum with admin/viewer semantics). The description restates that userId is numeric but does not add significant meaning beyond the schema, so the baseline 3 applies.

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

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

Description uses a specific verb and resource: 'Выдаёт существующему пользователю Авито доступ к рекламному аккаунту с указанной ролью.' It clearly differentiates from sibling set_user_role by saying role changes for existing access go through that tool, and it disclaims invitation/account-creation capabilities.

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

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

Explicitly states the precondition (user must already exist with Avito userId), names the alternative for existing access (set_user_role), and states what the tool cannot do (invite by email/phone or create an account). This gives an agent clear when-to-use and when-not-to-use 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?

While annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: the response shape (data[] and totalData), exact metric set, currency (rubles), date semantics (inclusive, max 100 days), the inability to merge campaigns, per-day granularity, the API credit cost and apiPointBalance field, and a recommendation to prefer wide periods. This goes well 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 dense but efficient — every sentence adds information (metrics, units, period limits, limitations, quota behavior). It is slightly longer than strictly necessary and could be split into bullets, but no sentence is filler, so it remains well-structured and front-loaded with the core purpose.

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?

Combined with the schema (all 3 parameters documented) and annotations (readOnly, idempotent), the description fully covers the tool: response shape (data[] and totalData), metrics and units, date handling, limitations, campaignId source, and API quota implications. There is no ambiguity left for an agent.

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 all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful context: the inclusive period semantics, max 100 days, the source of campaignId (list_campaigns), and the trade-off between wide vs. narrow periods due to API quota. This extra context justifies 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 states a specific verb (returns statistics) and resource (a single campaign), enumerates the metrics returned (views, clicks, ctr, spend, cpm, cpc, video metrics), and explicitly differentiates itself from sibling tools by noting it cannot aggregate multiple campaigns or go below daily granularity.

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 usage context: it handles one campaign over a date range, the period is inclusive up to 100 days, campaignId comes from list_campaigns, and it advises using one wide period over many narrow calls due to weekly API quota. It does not explicitly say 'use group_stats instead for per-group granularity,' but the limitation 'cannot merge multiple campaigns' and 'no finer-than-day granularity' make the boundaries clear. The quota hint effectively guides call batching.

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 that the budget replaces the current value (not adds to it), making repeated calls safe, which aligns with the idempotentHint annotation. It also mentions the API's refusal for non-manual groups and that it returns confirmation plus apiPointBalance. While annotations already indicate idempotency and non-destructiveness, the description adds specific behavioral details about replacement semantics and API restrictions, which is valuable. No contradiction with annotations.

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

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

The description is concise and front-loaded with the core action and key constraint (minimum 1). It then provides important behavioral details and usage guidance without unnecessary fluff. It's slightly longer than necessary but each sentence adds value, covering replacement semantics, manual management requirement, return value, and exclusions. Well-structured.

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

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

Given the tool's complexity (2 params, no output schema, no nested objects), the description covers the essential aspects: what it does, constraints, prerequisites, and what it doesn't do. It also suggests a related tool for checking current budget. The only minor gap is not describing the exact format of the confirmation response, but that's not critical for invocation. Overall, it's complete enough for an agent to use correctly.

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

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

The schema already provides descriptions for both parameters (budget and groupId) with constraints and source hints. The description adds minimal extra meaning beyond the schema, such as clarifying that budget replaces the current value and that groupId comes from list_groups. Since schema coverage is 100%, the baseline is 3, and the description doesn't significantly enhance parameter understanding beyond what's already in the schema.

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

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

The description clearly states the tool's purpose: setting a budget for one ad group in rubles, with a minimum of 1. It specifies the resource (ad group) and the action (change budget), and distinguishes it from related tools like change_group_price and list_groups. The description is specific 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 explicitly states when to use this tool: for groups with manual bid management, and notes that the API rejects others. It also mentions that to change campaign budget, bid, or group status, other tools are needed, and suggests checking the current budget via list_groups first. This provides clear usage context and 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?

Goes well beyond the readOnlyHint=false/idempotentHint=true annotations by explaining the value is a replacement, not an increment ('replaces the current bid, not adds to it, so calling again is safe'). It discloses the paymentModel-dependent unit semantics, the manual-bid prerequisite, and the return payload (API confirmation plus apiPointBalance), deepening the agent's understanding of side effects and dependencies.

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?

Dense but efficient — every sentence earns its place, covering idempotency, prerequisites, returns, and cross-references to sibling tools without fluff. The Russian original is long and slightly run-on, reading as one wall of text rather than structured points, but it remains well under a reasonable length for the depth of context delivered.

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 2-param tool with no enums or nested objects, the description is thorough: constraints, idempotency, side effects, return value, and negative capabilities are all covered. Minor gaps remain — no explicit mention of auth requirements, concurrency, or rate limits — though the openWorldHint and lack of an output schema mean the description covers the critical call/decision logic fully.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds notable meaning beyond the schema: it explains the price unit depends on the group's paymentModel (rubles per 1000 impressions for CPM vs. per click for CPC), and points to list_groups as the source for groupId. This is genuinely useful enrichment, though the schema already carries most of the burden.

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: 'Sets a bid for one ad group (called price in the API) in rubles,' which states exact action, target, and unit. It distinguishes itself from the sibling change_group_budget by name, and clarifies the scope ('one ad group') so the agent cannot confuse it with campaign-level 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?

Provides explicit when-to-use conditions ('only groups with manual bid management accept it') and names the exact alternative for budget changes ('for that there is change_group_budget'). It also enumerates what the API cannot do (pause, resume, delete, change budget), both excluding irrelevant cases and routing the agent to the correct 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?

The description discloses that there are no update/delete endpoints, that mistakes must be replaced with new records, that legal details must match the state registry, and that creation consumes API points (apiPointBalance). It does not mention any side effects on other resources or auth requirements, but given the annotations already indicate non-read-only and non-idempotent, the additional info is useful.

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 informative but somewhat lengthy, packing multiple important details into one block. It is not repetitive or tautological, and the key facts (return value, no-update caveat, legal checks) are clearly stated without redundancy. Slightly overexplained but justifiable given the domain 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?

The description provides a complete operational picture: creation under the account, return value with id and balance, the id's role in other entities, legal validation rules, and guidance to check existing records first. This is sufficient for an agent to decide when to call this tool and what to expect.

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 all parameters with required flags and reasonable descriptionscars. The description clarifies legalRole enums, kpp conditionality for ul vs ip, and the inn digit count. Addresses are minimally described but acceptable as generic strings. Could be more explicit about actualAddress matching legalAddress if identical, which is partially implied.

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 resource (рекламодателя/контрагента ОРД), specifies it returns id and apiPointBalance, and explains the significance of the id for campaigns and contracts. It distinguishes from list_advertisers, which is a search tool, so the 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?

Explicit guidance is given: because there are no update/delete endpoints, the agent is advised to first search via list_advertisers to avoid creating duplicates. This directly steers tool selection and sequencing among 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?

The description discloses critical behavioral traits: credentials are shown only once (must be saved), two calls create two accounts (non-idempotent), the account cannot self-fund (money from parent), and renaming/deleting is not allowed. These go beyond the annotations and provide essential operational knowledge.

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 well-structured, front-loading the main action and then explaining implications. It is slightly verbose but every sentence carries relevant information about constraints, credentials, and behavior, so it remains focused and readable.

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 explains the return values (accountID, clientKey, clientSecret) and their one-time nature, which is crucial since no output schema is provided. It also covers operational constraints, but does not mention error handling or failure scenarios, which is a minor omission for a creation 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?

The schema already provides full descriptions for both parameters (shortName and isSelfAdvertisingEnabled), and the description does not add further clarity. With schema coverage at 100%, the baseline score of 3 is appropriate since the description offers no additional semantic 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 clearly states the action (creates a child account), the specific resource (child account without payment permission), and the key output (credentials). It differentiates from siblings by specifying 'without payment permission' and the constraint that renaming/deleting is not allowed, which sets it apart from other account-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 implies when to use the tool (when creating a child account that cannot pay) and mentions related tools like transfer_funds for adding money. However, it does not explicitly compare with create_sandbox_account or other potential alternatives, leaving some ambiguity about when to choose this over similar creation 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 behaviors beyond what annotations provide: it returns {id} and apiPointBalance, and it explicitly states that erroneous contracts remain forever because there are no update/delete endpoints. Annotations only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, which don't cover irreversibility or the return payload. This added context helps the agent understand 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 dense but every sentence carries necessary information: the core purpose and return value, type-specific field requirements, the parentId exception, and the irreversibility warning. It's front-loaded with the main verb and resource, then elaborates logically. No irrelevant details or fluff.

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

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

For a complex 12-parameter tool with a nested object and conditional logic, the description covers all critical aspects: return format, type-specific required fields, the special case of additional agreements, and the lack of edit/delete. It doesn't elaborate on the meaning of apiPointBalance beyond 'remainder of weekly API points', but that suffices given the absence of an output schema. Overall, an agent has enough to call it correctly.

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

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

Although the schema describes every parameter (100% coverage), the description adds crucial semantic logic: it explains which fields are required for each type, when cid or parentId is rejected, and how intermediary fields interact with parentId. This is not fully captured in the schema's static descriptions and is essential for correct invocation, especially for nested objects and conditional requirements.

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 the exact purpose: 'Регистрирует договор ОРД между аккаунтом и рекламодателем' (registers an ORD contract between an account and an advertiser). It also specifies the return value ({id} and apiPointBalance) and clearly differentiates the three contract types. As the only contract creation tool among siblings, the purpose is unmistakable.

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?

While it doesn't explicitly name alternative tools, it is the sole creation tool and the description clarifies when each contract type should be used (service, intermediary, external) and the special case of parentId for additional agreements. It also warns that there are no edit/delete endpoints, implicitly guiding the agent to be careful. The guidance is clear, though a direct 'use this when creating a contract' statement is missing.

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

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

Annotations already mark readOnly=false, idempotent=false, and destructive=false. The description adds substantial behavioral detail: environment-gated rejection, empty-contact pre-validation, non-idempotency, account immutability, and the fact that the new accountID is not automatically picked up by AVITO_ADS_ACCOUNT_ID and must be configured manually.

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 and front-loaded with the most important constraint (sandbox-only) and the core purpose. Every sentence adds a distinct behavioral fact, and the length is justified by the number of non-obvious side effects.

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 mutating tool with 9 parameters and no output schema, the description covers the return value, environment prerequisite, validation behavior, idempotency, immutability, and configuration follow-up. The schema covers parameter details, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the contact object requirement with an example and adds that an empty contact is rejected before the request, but it does not add meaning for the other eight parameters 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 opens with 'ТОЛЬКО ПЕСОЧНИЦА' and clearly states that the tool creates a test advertiser account and returns its accountID. This is a specific verb+resource with an explicit environment scope, distinguishing it from sibling tools like create_advertiser or create_child_account.

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 says the server rejects the call unless AVITO_ADS_ENVIRONMENT=sandbox and that such a refusal does not count against the API quota. This provides clear when-to-use context, though it does not name a non-sandbox alternative tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds critical behavioral context: it spends weekly API points, includes apiPointBalance in the response, enforces a 100-day period limit with inclusive boundaries, and clarifies that it narrows selection via creativeIds. No contradiction with annotations.

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

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

The description is dense but every sentence adds value: purpose, output structure, metrics, constraints, and quota advice. It is front-loaded with the core function and logically organized, with no 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?

Given no output schema, the description sufficiently details the return format (fields per creative, data per day, totalData), mentions metric names, currency, period rules, and the response quota field. It provides enough to call the tool correctly without ambiguity.

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 schema covers all 4 parameters (100% coverage), the description adds non-obvious semantics: creativeIds narrows the selection rather than enumerates, and the period includes both boundaries with a max duration. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it provides statistics for the listed creatives of one campaign, returns a flat array with per-creative fields, and lists the metrics. It distinguishes itself from campaign_stats by explicitly noting it does not return campaign totals and that campaign_stats covers all creatives.

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 alternative: 'to cover all creatives of a campaign, there is campaign_stats'. It also advises one broad period over many narrow calls due to API point spending, providing clear decision guidance.

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

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

Annotations already declare destructiveHint=true, so the destruction is covered. The description adds valuable context: reversibility requires add_user with an explicit role, and it clarifies that the user's Avito account, campaigns, and spending history are not deleted, plus it mentions the return value (confirmation and apiPointBalance). This goes 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 three concise sentences, front-loaded with the primary purpose, then the destructive consequence and restoration path, and finally the return value. No fluff.

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

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

With one simple parameter and annotations covering safety, the description provides everything an agent needs: what it does, what it doesn't do, how to undo it, and what it returns. No output schema exists, so mentioning the return payload is helpful. Complete.

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

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

Schema description coverage is 100% and the schema already explains userId as the Avito user id as returned by list_users. The description itself adds no further parameter detail, so baseline 3 applies.

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

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

The description states a specific verb ('revokes') and resource ('user access to advertising account'). It clearly distinguishes from siblings by noting that restoration is only via add_user and that it doesn't delete the account or campaigns, so an agent can tell it apart from deletion 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 implies when to use the tool (to revoke access) and mentions add_user as the restoration alternative, but does not explicitly state exclusions or contrast with set_user_role. The context is sufficient for an agent to infer the use case.

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

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

The annotations already establish that this is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: the account is server-bound, the call accepts no arguments, the response includes apiPointBalance with a weekly quota reset, and the response excludes monetary and campaign data.

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

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

Three dense sentences with no filler: the first states purpose and fields, the second covers argument policy, and the third handles exclusions and quota behavior. The most important information is front-loaded.

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

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

For a parameterless read-only tool with no output schema, the description is complete. It enumerates the returned fields, notes the universal apiPointBalance field, and explicitly states what the response does not contain, so an agent can invoke it and interpret the result 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?

With zero parameters, the baseline is 4, but the description goes further by explaining why no arguments exist: the account is set in AVITO_ADS_ACCOUNT_ID and cannot be selected per call. This prevents an agent from inventing parameters and clarifies the environment-based configuration.

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

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

The description starts with a specific verb and object: it returns the legal requisites of the server-bound advertising account, and it enumerates the exact fields (inn, kpp, ogrn, shortName, etc.). It also distinguishes itself from get_balance by explicitly stating it contains no money amounts, separating it from its closest sibling.

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

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

The description clearly tells the agent not to pass arguments because the account is fixed by AVITO_ADS_ACCOUNT_ID, and it explicitly routes money-sum requests to get_balance. It also excludes campaign data, but it does not name a specific sibling tool for campaign data, leaving that alternative slightly to inference.

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 description doesn't need to restate safety. It adds contextual behavior: it distinguishes real money from bonus money (bonus spendable only on ads), clarifies it's a snapshot not a history stream, and explicitly states it does not top up the account. These details go beyond the annotations and give the agent useful behavioral nuance. Lacks info about rate limits or caching but that's minor for a read-only balance call.

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

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

The description is compact and front-loaded: it states the purpose (returns balance), specifies both fields, explains the limitation (snapshot not history), and clarifies it does not top up. Every sentence adds value, and it doesn't repeat annotation info. No fluff.

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

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

For a no-argument read tool, the description covers purpose, return values, temporal scope, and non-actions (no top-up). It also gestures to alternative tools (statistics) without needing to name them. The lack of an output schema is mitigated by the description explicitly stating the two fields and their meaning. 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?

There are zero parameters and the schema is empty. The description confirms 'Аргументов не принимает' (takes no arguments), which is helpful confirmation given the empty schema. The baseline for a zero-parameter tool is 4, and the description meets it; there is nothing else to explain.

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 current balance of a configured advertising account, distinguishes between real money (balance) and bonus money (bonusBalance), and explicitly notes it takes no arguments. It names specific fields returned with their semantics, making the purpose unambiguous. It stands apart from sibling tools like get_account (which likely returns account details) and the stats tools by stating this is a balance snapshot.

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 tells the agent when to use it (current balance snapshot) and when not to: 'это срез на текущий момент, не история — расход за период дают инструменты статистики' (this is a snapshot, not history — spending over a period is provided by statistics tools). It also clarifies it does not top up the account, steering agents away from it for funding operations. This is explicit when/when-not guidance, rivaling the calibrations example.

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 explains that the tool spends weekly API points, that apiPointBalance is the balance before the quota refill on Monday 00:00 UTC, and recommends one wide period over many narrow calls. This adds meaningful operational context far beyond the annotations' readOnlyHint/openWorldHint, and it tells the agent how to handle the response's apiPointBalance field and why an open-world strategy is preferred.

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?

Though compact, the description packs an exceptional amount of useful context: return format, metrics list, inclusive period, persistence hint, rate limits, and a usage recommendation. It is dense but every clause earns its place; the only minor note is it's a single long paragraph that could be slightly better structured, yet it remains highly scannable.

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

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

Given the tool has no output schema and 4 parameters, the description covers all the essential ground: return type, metric names, period semantics, required groupIds, cross-tool references to campaign_stats/list_groups, and API quota cost. Nothing needed to call this report 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?

Since schema coverage is 100%, the baseline is 3; the description earns extra credit by clarifying that groupIds 'сужает выборку' (narrows the selection), that the period is inclusive of both boundaries, and by explaining the quota economics of wide calls, which reinforces the parameter semantics beyond what the schema already documents.

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

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

The description uses a specific verb ('возвращает статистику по группам'), names the resource (ad groups of one campaign), and specifies the exact return shape (flat array, one entry per group with {id, name, paymentModel, campaignType, data[], totalData}). It explicitly distinguishes itself from campaign_stats, and the title/sibling list confirm this is a clear read/reporting tool.

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

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

It explicitly states when to use this tool vs. campaign_stats ('Итогов по кампании не возвращает; чтобы охватить все группы кампании, есть campaign_stats'), explains that groupIds narrows rather than enumerates, and notes the maximum period length (100 days). The schema even cross-references list_groups and campaign_stats as data sources/alternatives, giving an agent full routing 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?

It discloses the exact response envelope '{total, items, page, limit, hasNextPage}' plus apiPointBalance, and enumerates per-item fields including legalType and legalRole enums. This goes well beyond the readOnly/idempotent annotations by explaining pagination behavior, filtering limitations, and returned data shape, with no contradiction.

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

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

The description front-loads the core behavior and then packs response fields, filters, defaults, and item structure into one dense paragraph. Every sentence carries information, and the detailed field list is justified because no output schema is provided.

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 paged list tool with 3 optional parameters, nested filters, and no output schema, the description covers response envelope, item fields, filter semantics, value ranges, defaults, and search limitations. An agent has enough information to call the tool and interpret the result without additional assumptions.

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 description mostly restates the schema: limit 1..100 default 20, page numbering from 1, and the same filter keys. The only added semantic is the absence of full-text search, which is useful but does not substantially deepen parameter understanding beyond the schema.

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

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

The description opens with 'Возвращает одну страницу рекламодателей, зарегистрированных под аккаунтом', giving a specific verb, resource, and pagination scope. It also details response fields, filters, and limitations, making it unambiguous which entity is returned and how this differs from contract/campaign/creative listers.

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 states the supported narrowing filters (filter.ids / filter.inns / filter.roles) and explicitly warns 'полнотекстового поиска нет, совпадения по названиям придётся искать самостоятельно', which is a clear when-not for name searches. It does not explicitly name an alternative tool, so it stops short of 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 carry readOnlyHint, idempotentHint, and destructiveHint=false, and the description consistently reinforces this by stating that no modifications are possible through this API. It adds extra transparency by disclosing the API point balance mechanism, the AND-combination of filters, and the precise boundaries of allowable actions (only via change_group_budget and change_group_price). 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?

The description is informative but not bloated. It front-loads the core purpose and pagination, then lists the returned fields, then explains filtering semantics, and finally clarifies limitations. Each sentence carries useful information. The length is justified given the number of parameters and the need to explain the generic filter's behavior. No redundancy or filler.

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

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

For a complex tool with 13 parameters and no output schema, the description is remarkably complete. It details the return structure (total, items, page, limit, hasNextPage, apiPointBalance), enumerates the campaign fields, explains filter combination rules, and sets clear boundaries on what cannot be done. The presence of the openWorldHint annotation is supported by the description of pagination but not fully explored; still, the core information an agent needs to select and call this tool correctly is all present.

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

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

Schema description coverage is 100%, so each parameter is individually documented. The description adds meaning beyond the schema by explaining the universal 'filter' parameter's pass-through behavior (additional keys are mixed in as-is) and the precedence rule between named fields and the generic filter. It also clarifies the AND logic across filter lists, which is not in the schema. This is valuable semantic context that goes beyond field descriptions.

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

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

The description opens with a clear verb ('Перечисляет') and object ('рекламные кампании аккаунта') and specifies pagination. It distinguishes this tool from siblings like campaign_stats and list_groups by focusing on campaign listing and explicitly stating what it cannot do. The return structure and key fields are enumerated, making the tool's role unambiguous.

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

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

The description clearly defines the tool's scope (read-only listing) and explicitly lists what cannot be done (create/update/pause/resume/archive/delete campaigns, modify targeting). It does not compare against sibling read tools such as campaign_stats, but the purpose is evident from the name and first sentence. The mention of alternative modification tools (change_group_budget, change_group_price) helps set expectations but does not directly guide when to use this list tool versus others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it states that the tool returns all child accounts in a single call (no pagination) and explains the apiPointBalance field's meaning (weekly quote reset Monday at 00:00 UTC). This enriches the agent's understanding of the tool's behavior without contradicting 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 brief but packs essential details: purpose, differentiation from sibling, scope (no pagination/filters/search), and the apiPointBalance interpretation. It front-loads the core function and then adds clarifying constraints. Every sentence earns its place with no 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?

Given the tool has no output schema, the description compensates by explicitly describing the return format: 'Каждая запись — {account:{id,shortName}, contract}.' It also notes the absence of balances, the lack of pagination, and explains the apiPointBalance field, covering operational details an agent would need. For a zero-parameter, read-only tool, this is 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?

The tool has zero parameters, so the schema trivially covers 100% of them. The description doesn't add parameter-specific detail because there are none. Per rubric, with 0 parameters the baseline is 4. The description compensates by describing the return structure (each record as {account:{id,shortName}, contract}), though it doesn't provide additional param semantics since there are none.

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: 'Перечисляет дочерние (суб-)аккаунты настроенного агентского аккаунта' (lists child accounts of the configured agent account). It explicitly differentiates from the sibling list_child_accounts_with_balances by stating 'Балансов здесь НЕТ, для них есть list_child_accounts_with_balances.' This makes the purpose unambiguous and distinct.

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 explicit guidance on when to use this tool versus the sibling: it notes the absence of balances and directs users to list_child_accounts_with_balances for that. It also states the lack of pagination, filters, and search, clarifying the scope. Additionally, it explains the apiPointBalance field as a weekly quota, offering operational usage advice for rate-limiting.

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 destructiveHint=false. The description adds valuable behavioral context: it returns {balance, bonusBalance} in rubles and bonus rubles, and scopes to child accounts only. This goes beyond 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 concise sentences in Russian, front-loaded with the core purpose, then usage guidance, and a clarifying note. No redundant words or repetition of schema/annotations.

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

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

With no parameters and no output schema, the description fully covers what is returned (balance fields), when to use it, and what it does not include (parent balance). An agent has all necessary information to call it correctly.

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

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

The tool has zero parameters, so schema description coverage is 100% (vacuous). Baseline for 0 params is 4; the description adds no parameter details because none are needed. Nothing is missing.

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 it is the same list as list_child_accounts plus balances for each child account, and clarifies it shows only child balances, differentiating it from get_balance. The verb 'list' and resource are clearly defined.

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 provides explicit context for when to use this tool: before transfer_funds/transfer_bonus to check balances and verify transfers. It also tells the agent that parent balance should be fetched with get_balance, giving an exclusion.

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, and the description aligns with these—no writes or deletes are implied, consistent with destructiveHint: false. The description adds value beyond the annotations by clarifying the semantic meaning of API points ('остаток недельных баллов API'—week reset) and explaining what some response fields mean (e.g., 'description (тип контрагента)', 'parentId (заполнен у дополнительных соглашений)').

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, information-dense paragraph that front-lodes the tool's purpose and response shape before covering parameters. While efficient, the long sentence is slightly run-on, and the semi-colon usage could be clearer, costing a point.

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

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

Given the tool's simple nature (a filtered list with pagination) and the rich schema, annotations, and clear description of the response structure, the description is complete. It explicitly does not detail network error handling or rate-limit behavior, but since no output schema is provided, the description's explanation of the response shape (total, items, page, limit, hasNextPage) is adequate for an agent to understand the return value.

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

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

Schema description coverage is 100%, documenting all three parameters (page, limit, filter) with defaults and ranges, so the baseline is 3. The description provides marginal extra context by specifying the default page size of 20 and the fact that 'filter' without parameters returns all contracts ('Без него возвращаются все договоры'), which complements rather than repeats the schema.

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

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

The description clearly states the tool returns a paginated list of contracts under the account, using the specific verb 'Возвращает' (returns) combined with the resource. It distinguishes itself from a potential sibling confusion by detailing its response, including a notable field 'apiPointBalance (остаток недельных баллов API)'. While it doesn't name sibling tools like list_groups or list_campaigns as alternatives, the list semantics are explicit and specific enough to be distinct.

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 how to use the tool including the pagination range (limit 1..100, default 20, page starting from 1) and filter options ('Сузить выдачу можно через filter.ids / filter.numbers / filter.clients...'). While it doesn't explicitly state 'use this instead of X', the context of listing contracts vs. other list tools is implicit in the resource type, and the detailed filtering and pagination guidance is sufficient for an agent to know when to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds: pagination behavior (returns page/limit/hasNextPage), apiPointBalance disclosure, and explicit list of what actions are NOT possible (modify/pause/delete). This exceeds annotation coverage meaningfully, though could mention rate limits (weekly API points).

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?

Description is a single dense paragraph, front-loaded with purpose and return structure, then filters, then constraints. Efficient but slightly long due to exhaustive field listing; no waste though.

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

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

For a read-only listing tool with 12 parameters and no output schema, description covers return fields, pagination, and constraints. Missing output schema is compensated by describing items. Could mention default pagination values, but schema already covers defaults. Overall complete enough.

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 detailed descriptions for every parameter, including enums inline. Description reinforces filter behavior (e.g., conflict precedence for 'filter' field) but adds only marginal value beyond schema. Baseline 3 is correct.

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

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

Description states 'Перечисляет креативы аккаунта' (lists account creatives) with explicit pagination and return structure. Differentiates from siblings by naming what it returns (creatives/ads) vs campaigns/groups/stats tools. Clear verb+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?

Lists all filter parameters and their semantics, implying use for filtering. Explicitly states it's read-only and what can't be done via this API. However, doesn't explicitly name sibling alternatives (like list_campaigns or creative_stats) for when to use them instead.

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

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

Annotations already indicate readOnlyHint=true Fox, destructiveHint=false, etc., but the description adds valuable context: it specifies the return shape ({total, items, page, limit, hasNextPage}) and extra apiPointBalance, and clarifies that groups carry budget/price in rubles. It also warns about the arbitrary paces filter values, which is useful non-obvious 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 a single paragraph but dense with information. It front-loads the core function and return shape, then details the response structure and constraints. It is concise enough for the information volume, though it runs sentences together; and could benefit from breaking into bullet points for readability.

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 is thorough for a read-only list tool with a rich schema. With schema covering all parameters and annotations providing safety profile, the description adequately fills gaps like response structure, apiPointBalance, and the money-centric nature of groups. No critical missing information for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining that groups are tied to money and that 'paces' values are arbitrary (no fixed dictionary), which helps agents understand the filter. It also explains the naming convention for 'advertisers', 'managers', etc., which is not fully clear from schema alone.

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 lists ad groups of the account with pagination, and it explicitly distinguishes itself from siblings like list_campaigns and list_creatives by focusing on the 'group' level. It also mentions that groups are the level with budget and price, which sets it apart from higher-level listing tools.

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

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

The description explicitly states what the tool cannot do (create, rename, pause, resume, delete groups) and that targeting is not output. It also mentions that the only mutable fields are 'budget' and 'price', which implies when to use change_group_budget/change_group_price instead. This provides clear exclusions and 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 cover read-only, idempotent, and non-destructive behavior, so the description's contribution is the additional return detail: apiPointBalance is returned with the user data, and each user record carries role and hasLoggedIn. This adds non-obvious output behavior beyond the annotation hints.

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?

Each sentence delivers a distinct piece of information: purpose, output shape, downstream compatibility, account scope, and the extra apiPointBalance field. There is no filler, repetition, or irrelevant detail.

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

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

Even with no output schema, the description fully documents what the tool returns: per-user id, role, and hasLoggedIn, plus apiPointBalance. It also states the scope limitation and points to downstream user-management tools, making it self-sufficient for a zero-parameter 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 tool has zero parameters and the input schema confirms that at 100% coverage. Since there is nothing to describe, the description appropriately does not spend text on parameters; this is the baseline for zero-parameter tools.

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

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

The description starts with a specific verb and resource: 'Перечисляет пользователей с доступом к рекламному аккаунту' and specifies the exact output shape, roles, and returned fields. It also disambiguates itself from child-account tools by explicitly stating that users of child accounts are not shown.

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 usage: list users of the configured account and use the ids for set_user_role or delete_user. It does not explicitly name an alternative sibling for child-account user listing, but the scope limitation 'users of a child account will not show' provides enough guidance for most agent decisions.

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

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

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=true). It explains that this tool bypasses client-side validation, that write operations are irreversible, that path binding to account is enforced, and that GET is unrestricted. It also details confirmWrite semantics for POST/DELETE. No contradictions with annotations; it adds critical safety context that the annotations alone do not convey.

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

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

The description is a long, dense paragraph with many clauses, making it verbose and somewhat difficult to parse. It front-loads the purpose but then packs multiple safety caveats and examples into one block. While every sentence has content, the lack of structure (e.g., bullet points or separate sections) hurts readability. It's adequate but not concise.

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

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

For such a powerful and dangerous raw-access tool with no output schema, the description covers all necessary aspects: purpose, usage, safety (irreversibility and confirmWrite), path constraints, and return value (raw response plus apiPointBalance). It could mention error handling or rate limits, but given the breadth already covered, it's quite complete. A 4 is fair since some edge-case behaviors are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters substantially: it explains the {accountID} substitution in path, the meaning and requirement of confirmWrite, and that body is sent as JSON. This adds value beyond the schema's terse descriptions, earning above 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 specific purpose: a universal raw HTTP requester for any Avito Ads API path, and explicitly distinguishes it from specialized tools by saying 'for endpoints that don't have a separate tool' and naming alternatives like transfer_funds, delete_user, and create_*. This makes its role unmistakable.

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

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

It gives clear when-to-use guidance: use this when no dedicated tool exists, and prefer the dedicated tools when they are available ('better to take it: transfer_funds / delete_user / create_*'). It also advises caution with confirmWrite because POST can be used for harmless reads, giving concrete decision rules. This is explicit and unambiguous.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false foot, so the description's mention that assigning the same role changes nothing is redundant. However, it adds valuable clarification that access is neither granted nor revokedanders, and that the tool returns API confirmation and balance info. This goes beyond the structured hints without contradicting them, though it omits auth/permission requirements.

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 compact three-sentence block that is front-loaded with the core action, then clarifies edge cases (no-op on same role) and exclusions (does not grant/revoke). Every sentence adds value with no fluff, making it an excellent model of concise, informative description.

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 mutation with no output schema, the description covers the essential context: what it does, its limitations, alternatives, and return value. It could mention authentication/permission requirements, but the explicit scope and no-op behaviorobis make it nearly complete. The lack of output schema is compensated by the mention of API confirmation.

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 descriptions cover 100% of the two parameters, so the description does not add parameter-specific detail. That is baseline adequate: the schema already explains each parameter, and the description does not conflict or need to compensate further. A score of 3 reflects this sufficient but non-enhanced 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 tool changes the role of an existing user who already has access to the advertising account. It explicitly contrasts with add_user (granting access) and delete_user (revoking access), and notes that re-assigning the current role is a no-op. This unambiguously differentiates it from sibling tools and defines its precise scope.

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 names the alternatives for granting (add_user) and revoking (delete_user) access, telling an agent when NOT to use this tool. It also establishes the precondition that the user must already have account access Mendapatkan. This is strong usage guidance, though it could add when to use as the primary choice, which is clearly implied.

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

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

The description adds substantial behavioral context beyond the annotations. It discloses the irreversibility of the transfer, the meaning of an empty success response, and the correct error-handling procedure (check balances instead of retrying). Since annotations already indicate destructiveHint=true and idempotentHint=false, the description enriches that with concrete operational behavior, which is exactly what this dimension rewards.

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, coherent paragraph that front-loads the tool's purpose and then adds behavioral and error-handling notes. It is appropriately sized for the tool's complexity—not excessively long, and every sentence contributes useful information. It could arguably be split into bullet points for clarity, but as written it is efficient and well-structured.

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

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

The description covers the core purpose, parameter semantics, behavioral constraints (irreversibility), success/failure indicators, and the correct fallback action after errors. It also clearly routes to the right sibling tool for real-money transfers. Given the schema fully documents the parameters and there is no output schema to explain return values, the description is complete for safe and correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail. However, the description adds meaningful context: it clarifies that amount is in bonus rubles (with a minimum of 1) and that accountIdTo is the recipient, with the sender always being the configured account. This adds semantic nuance beyond the raw schema definitions, improving the agent's understanding of the parameters.

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

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

The tool name and title clearly state the action: transferring bonus rubles to another account. The description goes further, defining what bonus rubles are (promo funds for advertising, not withdrawable) and explicitly differentiates from transfer_funds by stating that real money goes through that sibling tool. This makes the purpose unambiguous and distinguishes it from the closest alternative.

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 states when to use this tool (for bonus transfers only) and when not to (real money via transfer_funds). It also provides critical operational guidance: the transfer is irreversible, an empty data object confirms success, and after network/server errors the agent should check list_child_accounts_with_balances rather than retrying. This provides clear, actionable context an agent needs to make correct call decisions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description goes beyond annotations by explicitly stating the transfer is irreversible, unreversible, has no journal, and that retrying after errors can double-spend money. It also explains the response semantics: an empty data object on success. This is excellent transparency, especially given the high stakes.

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 paragraph but packs essential information efficiently. It front-loads the most critical fact (real money, irreversible) and then explains the response semantics and error handling. Every sentence earns its place; there is no redundancy or filler.

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

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

Given the tool's high stakes (real money, irreversible), the description is fully complete. It covers the action, parameters, response format, error handling, and troubleshooting. The schema covers parameter details, and annotations cover safety hints. No additional information is needed for an agent to use this tool correctly.

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

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

Schema coverage is 100% and the parameters are simple, but the description adds critical semantics: it clarifies that the sender is always the configured account (cannot be overridden) and that accountIdTo is the RECEIVER. It also specifies the minimum amount and reinforces the irreversibility. This adds value beyond the schema descriptions.

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

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

The description clearly states this tool transfers REAL MONEY from the configured account to another account (usually a child account). It specifies the exact resource (transfer_funds), the action (transfer), and the amount parameter. This distinguishes it from transfer_bonus, which likely transfers bonus funds, and from other siblings. The description is explicit that this is irreversible, which is a critical distinguishing feature.

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 when to use this tool (to transfer real money, typically to child accounts) and when not to (when you need bonus transfer, use transfer_bonus). It also warns against repeating calls after errors and advises checking list_child_accounts_with_balances instead. This is clear guidance for an agent to avoid duplicate transfers.

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