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

Beyond the annotations, the description discloses two important behaviors: partial-update semantics ('остальные останутся как есть') and the onboarding gate where the API is fully closed until last name, first name, and birth date are present. This is rich, actionable behavioral 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?

Two sentences, front-loaded with the action, then parameter-use instruction, then the critical onboarding context. Every sentence carries operational value and there is no 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 six-parameter, zero-required mutation tool with no output schema, the description covers the essential selection and invocation context: what it changes, how to perform partial updates, and when it must be used for onboarding. It does not describe the response format or exclusions, but the schema and annotations carry enough of that load.

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 already documents all six parameters, so the baseline is 3. The description adds meaningful semantics by instructing the agent to send only the fields to change and clarifying that unspecified fields retain their current values, going beyond the schema's individual 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 names a specific verb ('меняет') and a precise resource ('данные учётной записи'), then enumerates exactly which fields are affected: ФИО, дата рождения, телефон, часовой пояс. This clearly distinguishes account_update from generic account utilities and sibling tools.

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

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

The description gives clear usage context: use it for partial profile updates and specifically for the acquaintance/onboarding step while the API is closed. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to know when this tool applies.

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

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

Beyond the annotations, the description reveals important behavior: deletion destroys saved keys, deletion is blocked while the connection is still referenced, and the agent must first detach it from bots, knowledge bases, and AI Reply nodes. This is rich, non-obvious context that annotations alone do not 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 only two sentences: the first front-loads the core destructive action, and the second compactly lists the necessary dependency-clearing steps. Every sentence earns its place, and there is no filler.

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

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

For a destructive delete tool with no output schema, the description covers the effect, the sensitive-data consequence, the blocking condition, and the exact steps to unblock it. This is sufficient for an agent to invoke the tool correctly and avoid failed calls.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add significant new direct meaning for the provider or case parameters, though it does mention provider_id in flows_save as part of the unblocking workflow. 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 starts with a specific verb and resource: 'Удаляет подключение вместе с сохранёнными ключами' — it clearly states what is deleted and that saved keys are also removed. This distinguishes it from sibling AI tools like ai_save, ai_list, and ai_test.

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 deletion is blocked ('Пока сервис используют боты, панель удалить его не даст') and provides precise removal steps using sibling tools with parameter values: bots_save ai_provider=null, knowledge_save provider=null, and flows_save. This gives the agent clear conditions 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context by disclosing that API keys are never shown—only their last characters—which is exactly the kind of safety-relevant detail that goes beyond annotations.

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

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

The description is two short, front-loaded sentences. The first sentence states purpose and scope; the second addresses key redaction. No wasted words, 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 list operation with one optional parameter and no output schema, the description provides sufficient information: what is listed, for what scope (case), and a critical privacy guarantee. It does not describe pagination or exact return format, but these are not necessary given the tool's simplicity.

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 fully documents the single 'case' parameter, including its default behavior when omitted. The description does not add further parameter-level detail, so with 100% schema coverage the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it lists AI services connected to a case, including models and bot usage counts. It distinguishes itself from sibling tools like ai_save, ai_test, and ai_delete by framing this as a read-only enumeration of existing connections.

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 context ('connected to the case') and the optional case parameter, but it does not explicitly state when to use this versus alternatives or provide exclusion criteria. Usage is implied rather than explicitly guided.

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 reveals important behavioral details beyond the annotations: passed keys are appended onto existing ones, and an empty string cannot erase a key—only overwrite it. This gives the agent a concrete understanding of side effects for a non-idempotent, non-destructive mutation tool.

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

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

The description is compact and well-structured: it opens with the core create/update rule, then moves to provider-specific key requirements, and closes with the merging caveat. Every sentence carries necessary information without redundancy.

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

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

For a complex tool with 12 parameters, a nested `credentials` object, and no output schema, the description adequately covers the trickiest aspects: the create/update distinction, per-provider credential requirements, and key-merge behavior. It does not explain return values, but this is a minor omission for a save 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 all 12 parameters (100% coverage), but the description adds essential semantics by explaining the `credentials` structure per provider, including required fields and the default `scope` for gigachat. This compensates for the schema's generic 'see description' note and adds value beyond 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 the tool's purpose: it creates a new AI service connection when `provider` is omitted and modifies an existing one when `provider` is specified. It also distinguishes itself from sibling tools like `ai_list`, `ai_test`, and `ai_delete` by focusing on save/configure operations.

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

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

It provides explicit conditions for use: without `provider` to create, with `provider` to update. It also lists required credentials per provider, giving concrete guidance on what inputs are needed for each service type. However, it does not explicitly mention alternative tools for reading/testing/deleting, so it lacks an explicit 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description discloses that this is a real request consuming limits and potentially costing money. It also mentions it shows 'reason for refusal,' indicating potential failures. These are valuable behavioral traits not captured in annotations.

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

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

The description is two sentences long, front-loaded with the action and outcome, and the cost warning is a necessary caveat. Every sentence earns its place with no fluff or repetition.

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 (3 parameters, no nested objects, no output schema) and the strong annotations, the description covers the essential aspects: what it does, what it returns (response or error reason), and the cost/limit implications. It is complete for an agent to select and 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%, and each parameter (case, prompt, provider) already has a description. The tool description adds no additional parameter-level semantics, so it reaches the baseline but does not elevate it. It does not repeat or contradict schema information.

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

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

The description states a specific verb+resource: 'Sends a test replica and shows the model's response or reason for refusal.' This clearly distinguishes it from sibling tools like ai_list or ai_save, as it is about testing an AI service rather than managing configurations or listing services.

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: it sends a real request to the service and warns that it consumes limits and may cost money. This implies caution and informs when to use (testing a service) but does not explicitly name alternatives or exclusions. The cost warning is a useful usage guideline, though it could be more explicit about comparing to ai_list/ai_save.

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

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

Beyond the read-only/idempotent annotations, the description adds valuable behavioral details: read actions are never recorded, actions performed by an access token are attributed to that specific token, and audit.view permission is required. These traits are not inferable from the annotations or schema alone.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds meaningful information: content scope, the 'who did it' angle, token attribution, read exclusion, and permission requirement. 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?

For a read-only list tool with four optional parameters and no nested objects, the description covers the essential behavioral context: what is logged, what is not logged, token attribution, and permission needs. The schema handles parameter semantics, 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 coverage for parameters is 100%, so the schema already documents case, limit, action, and offset. The description does not add any parameter-specific meaning beyond the general 'case' context, 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?

Description clearly states the tool lists an audit/action log for a case, covering edits, additions, deletions, and permission grants, and answers 'who did it.' This is specific and the scope is evident, though it does not explicitly contrast itself with sibling tools like bots_journal or dialogs_history.

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 tells the agent when to use the tool: to determine who performed changes in a case. It also provides a useful exclusion—read operations are not logged—and warns about the required audit.view permission. However, it does not name alternative tools or explicitly state when not to use this tool in favor of another.

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 richly discloses behavior beyond the sparse annotations: missing commands are added, existing ones updated, unspecified commands are preserved unless remove_missing=true, and the platform menu only updates when sync=true or the bot restarts. This gives the agent a clear model of side effects and conditional 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 two focused sentences with the core behavior front-loaded and the important edge conditions separated into a second sentence. Every clause adds information and there is no filler.

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

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

The description provides a complete operational model for an apply-style command, including default non-destructive behavior and the sync condition, while the schema covers parameter details. It does not describe return values or error cases, and there is no output schema, which is a minor gap but not a blocker 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 structured schema already documents every parameter, including remove_missing and sync. The description mentions remove_missing and sync semantics but does not add much per-parameter 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?

The description states a specific action and resource: aligns the bot's command menu to the provided list, explaining add/update/reorder behavior. It is clearly distinct from generic bot tools, though it does not explicitly name or exclude sibling tools, so it stops short of a 5.

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

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

The description clearly implies when to use the tool — when you want to force a bot command menu to match a desired list — but it never states explicit selection criteria or contrasts with alternatives. The usage context is inferable but not directly guided.

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 state readOnlyHint=false and destructiveHint=false, so the agent knows this mutates bot state. The description adds useful behavioral nuance: startup automatically syncs the menu, while a separate sync is required after editing commands on a live bot. This goes beyond what structured data 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 compact sentences: the first enumerates the actions, the second explains the only important conditional nuance. There is no filler, no restating of the schema, and the key 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 simple three-parameter tool with no output schema, this description covers the main actions and the sync nuance well. A brief note on the effect of stop/restart on a running bot would add completeness, but the current text is sufficient for correct selection and invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description reinforces the meaning of the action enum by explaining the sync_commands edge case, but it does not add extra detail about the bot or case parameters. 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 starts with a specific set of actions and resource: 'Запускает, останавливает или перезапускает бота, а также отправляет меню команд'. This clearly distinguishes bots_control from sibling tools like bots_save or bots_journal by naming the runtime-control responsibility.

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

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

The description gives explicit guidance about when the sync_commands action is needed: after editing commands on an already running bot, because startup already performs synchronization. It does not name sibling alternatives, but the provided context is unambiguous for the listed actions.

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 consequences: deletion of commands, variables, dialogues, and irreversibility. This goes beyond the annotation, giving the agent a full picture of the tool's impact.

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: the first states the core action, the second describes consequences, the third gives an alternative. Every sentence adds value and the description is front-loaded, making it 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 no output schema, the description fully explains the destructive behavior, scope, and irreversibility. It also provides a contrast with the non-destructive alternative, making the tool's usage context 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% with clear descriptions for bot, case, and confirm_name. The tool description does not add additional parameter-level details, so the baseline score 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 clearly states the tool removes the bot from the case along with commands, variables, dialogues, and correspondence, and that restoration is impossible. This distinguishes it from sibling tools like bots_save (used for temporary disablement).

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 provides an alternative for temporary disablement: 'use bots_save enabled=false.' This tells when not to use this tool and directs to the correct sibling, fulfilling the usage guideline 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: secret variable values are hidden. This is a meaningful disclosure about response content that annotations do not cover.

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 concise sentences. The first sentence front-loads the core purpose with a colon list of contents; the second adds a crucial detail about secrets. No wasted words or redundant 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?

The description covers what the tool returns, including the masking of secret variables, which is important given there is no output schema. With strong annotations and 100% parameter schema coverage, it is nearly complete, though it does not explicitly address error cases or access restrictions.

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

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

Schema description coverage is 100%: both 'bot' and 'case' parameters have descriptive text. The tool description itself adds no extra parameter semantics, so the baseline score 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 clearly states the tool returns the full bot object ('Бот целиком') and enumerates its contents: settings, command menu, content variables, and scenario list. This distinguishes it from sibling tools like bots_list (list only) and bots_save (modify). The implicit verb is evident from the tool name and title.

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 is the comprehensive single-bot retrieval tool, but it does not explicitly state when to use it versus alternatives such as bots_list or bots_control. No exclusions or alternative tool names are mentioned, so usage guidance remains implicit rather than explicit.

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 signal readOnly, idempotent, non-destructive behavior. The description adds meaningful behavioral context: entries are returned newest-first, the log is recent history rather than an archive because the panel removes old entries, and the response ends with a summary of encountered kinds and counts. This goes beyond the structured 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?

Every sentence adds distinct value: scope of entries, differentiation from audit_list, ordering and filtering, response summary, and retention behavior. The text is dense but not bloated, and the most important information is front-loaded.

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

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

There is no output schema, but the description partially compensates by explaining ordering, filtering, the kind summary at the end, and the non-archival nature of the log. A more explicit list of per-entry fields would make it fully complete, but the provided context is sufficient for an agent to call the tool and interpret the high-level result.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description mentions the kind and level filters, particularly level=error, but does not add new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description opens with a concrete statement of what the tool returns: bot actions such as starts/stops, incoming updates, model responses, script errors, and platform refusals. It also explicitly contrasts this with audit_list, making the resource and scope unmistakable and distinguishing it from a sibling tool.

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

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

The description explicitly names audit_list as the log of human actions and states that this journal answers 'why the bot is silent', giving a clear selection condition. It also explains how to narrow results by kind and level, which directly supports correct invocation.

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, so safety is covered. The description adds context about the output contents (status, operation mode, dialogue counts, unread), which is useful behavioral information beyond the annotations. No contradictions.

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 resource and purpose. It avoids unnecessary words while conveying the key output fields.

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

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

For a simple read-only list with one optional parameter, the description provides sufficient context: what is listed and what information is included. Annotations cover safety, and schema covers parameters. The lack of output schema is mitigated by the description's field enumeration.

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 single parameter 'case' is fully described in the schema (100% coverage), including default behavior when omitted. The tool description itself does not add parameter details, so it relies on the schema, appropriate for baseline 3.

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

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

The description clearly identifies the tool as listing bots for a case ('Боты дела'), with a specific verb ('список') and resource ('боты'). It also lists the returned aspects (status, mode, dialog counts, unread), distinguishing it from sibling tools like bots_get by its list-focused 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?

The description implies usage for retrieving bots of a case, but it does not explicitly state when to use this tool versus alternatives (e.g., bots_get). No exclusions or conditions are mentioned, so it falls short of clear 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?

Beyond the annotations, the description adds crucial behavioral context: the token grants full control over the bot, and the tool should be used only on explicit user request. This meaningfully expands on destructiveHint=true and explains why the operation is sensitive.

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

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

Two sentences, zero filler. The first sentence states the primary function; the second delivers essential security guidance. The most important operational caution is placed up front.

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

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

For a two-parameter tool with no output schema, the description covers the action, the sensitive nature of the result, and the required user-consent condition. It is complete enough for safe invocation, though it does not detail output formatting or explicitly rule out token rotation.

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 schema already documents both bot and case parameters. The description adds no parameter-specific meaning beyond the operation itself, 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 clearly states the operation: 'Возвращает токен бота в открытом виде' — a specific verb, resource, and even the output form. It is recognizable as distinct from siblings like bots_get, but it does not explicitly name or differentiate against any sibling, so it falls short of a 5.

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

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

The description gives an explicit usage condition: request the token only if the user directly asks, and do not repeat it unnecessarily. It provides clear context and a strong exclusion rule, though it does not mention alternatives or broader when-not-to-use scenarios.

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 non-obvious behaviors beyond annotations: live token validation, encrypted storage, automatic restart on token or mode change, and immutability of platform. This significantly helps an agent anticipate 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?

Four short sentences front-load the main behavior and then cover constraints and side effects without filler. 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 10 parameters and no output schema, the description covers the key decision points: connect vs configure, restart semantics, platform immutability, and live token validation. It does not enumerate every parameter, but the schema already documents those.

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 goes beyond by explaining the conditional role of bot, the restart effect of changing token or mode, and the platform restriction. It adds useful integration semantics rather than merely repeating the schema.

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

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

The description states a specific action on a specific resource: connecting a new bot when bot is omitted and changing settings when bot is provided. It is clear but does not explicitly name sibling tools to differentiate, so it stops short of a 5.

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

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

Clear usage context is given: omit bot to connect, include bot to reconfigure, and changing token or mode restarts a running bot. It does not explicitly state when to choose a sibling tool such as bots_control or bots_delete, so it lacks explicit exclusions.

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

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

Beyond annotations (write, non-destructive), the description discloses that existing keys are updated, new ones created, and secret-marked values are not shown back. It also specifies key character constraints, providing valuable behavioral details.

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 compact sentences, front-loaded with the main action, and every sentence adds essential information. No fluff or redundant repetition of schema fields.

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

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

Given the schema richness and annotations, the description fully complements the structured data. It covers core behavior, key format, secret handling, and update semantics, making the tool's purpose and constraints complete 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 covers all parameters (100% coverage), but the description adds key format constraints (Latin, digits, underscore, dot) not present in the schema. It also reinforces the behavior of the 'secret' field, adding meaning 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 ('Задаёт' - sets) and resource ('переменные' - variables for bot script texts), with concrete examples (prices, addresses, links). It clearly distinguishes this tool from siblings like bots_save or bots_control by focusing on content variables.

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 through examples ('цены, адреса, ссылки') and explains the update/create behavior, implying when to use it. It does not explicitly name alternatives or exclude cases, but given the unique sibling scope, the usage is evident.

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 read-only and idempotent; the description goes further by stating that no token or key is ever exposed from the address and that the output states whether the address matches the panel's expectation. This adds safety and interpretation 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?

Three sentences, each meaningful: report contents, diagnostic use-case, and privacy caveat. Key information is front-loaded in the first sentence. No filler or repetition.

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 diagnostic tool with two documented parameters and no output schema, the description covers all relevant expectations: what the report contains, what insight it provides, and the security guarantee about secrets. Nothing essential is missing.

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

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

Schema description coverage is 100%: both bot and case are described in the schema, including the default fallback for case. The description adds no parameter-level detail, so it stays at the baseline for high schema coverage.

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

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

The description names a concrete resource ('Отчёт самой платформы') and specifies the exact outputs: delivery address, count of pending updates, and last delivery error. This clearly distinguishes bots_webhook_check from action-oriented siblings like bots_webhook_rotate.

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 scenario: use when a webhook-mode bot is silent but the panel side looks healthy ('Единственный способ понять...'). It does not, however, spell out when not to use it or name alternative diagnostic 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 mark destructiveHint=true, and the description adds that the old address 'stops working forever' (перестаёт работать навсегда), reinforcing irreversibility. It also reveals a new side effect: the running bot restarts (работающий бот перезапускается), which annotations don't cover. This gives valuable operational context beyond the structured 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?

Three short sentences in Russian, each with a distinct purpose: action, condition, and side effect. No filler words, and the main verb appears in the first sentence, front-loading the 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?

For a destructive, non-idempotent tool with no output schema, the description covers the key aspects: what it does, when to use it, and permanent consequences. It lacks explicit permission requirements, but given the annotations and schema, it is thorough enough for an agent to invoke the tool correctly.

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

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

The schema already describes both parameters (bot and case) with 100% coverage, so the baseline is 3. The description doesn't add parameter-specific semantics, but the schema does the heavy lifting. No additional meaning is provided by the description.

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 'issues a new secret webhook address' (Выдаёт боту новый секретный адрес вебхука) for the bot, indicating a rotation action. It distinguishes from sibling bot tools (bots_get, bots_save, bots_delete) by focusing specifically on address rotation. The title 'Сменить адрес вебхука' aligns perfectly.

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 this is needed 'if the old address leaked' (если старый адрес утёк), giving a clear trigger for use. It warns that the previous address stops working forever, implying it is not for routine changes. It doesn't name alternatives but provides sufficient context for 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?

The description adds substantial behavioral context beyond the annotations: sent messages cannot be recalled, a canceled broadcast cannot be resumed, only a draft can be started again, and counters remain to show delivery reach. This gives the agent a clear picture of irreversibility and side effects.

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

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

Three sentences deliver the core action and all critical consequences without redundancy. The most important fact is front-loaded, and every sentence 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?

For a cancellation tool with no output schema, the description covers what happens to unsent and sent messages, whether the operation is resumable, how to repeat the broadcast, and what remains visible. Combined with the annotated safety profile and fully documented schema, this is complete enough for an agent to invoke the 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%, so the schema already fully documents the 'case' and 'broadcast' parameters. The description adds no parameter-level detail beyond the schema, 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 opens with a specific verb and resource ('Останавливает рассылку') and immediately clarifies the effect: unsent messages will not be sent. This clearly distinguishes the tool from siblings like broadcasts_start, broadcasts_list, and broadcasts_preview.

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 a broadcast needs to be stopped before it finishes sending. However, it does not explicitly name alternatives or state when not to use it, so the guidance is present but not fully explicit.

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. The description adds useful behavioral context beyond that, including the meaning of counters and a clear explanation of each broadcast status.

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 information-dense and front-loads the core content. The status list is useful, though the informal aside about users who 'closed the bot's mouth' adds little functional 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?

Without an output schema, the description does a good job of explaining what the returned records contain and what each status means. It could be more explicit about the list nature and sorting, but it is adequate for a simple read-only listing tool.

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

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

Schema description coverage is 100%, with case, limit, and offset already documented. The description does not need to explain parameters, and it adds no additional parameter-level 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 identifies the resource (case mailings) and the data they contain — selection conditions, text, and delivery counters — and explains the statuses. However, it never uses an explicit action verb like 'list' or 'get', relying on the tool name to supply the 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 no guidance about when to use this tool versus broadcasts_preview, broadcasts_save, broadcasts_start, or broadcasts_cancel. It does not state that this is the read-only viewing tool or mention any exclusions or 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, idempotentHint, destructiveHint), the description adds behavioral specifics: it shows only the first 50 conversations by freshness, flags warnings like 'пустой отбор, слишком широкий, неизвестные подстановки', and explicitly states 'Ничего не сохраняет' (persists nothing). This aligns with and enriches the annotation-provided safety profile.

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 information: the first lists the preview outputs, the second gives the rationale for using it, the third covers side effects and condition semantics. No filler or repetition of schema contents.

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

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

With no output schema, the description adequately explains the return contents: counts, the first 50 matching conversations, how many silenced the bot, and message warnings. It also covers default behavior, side-effect-freedom, and the relationship to broadcasts_save, making it sufficient for an agent to call the tool correctly.

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

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

The schema already covers all 11 parameters with descriptions (100% coverage), so the baseline is 3. The description adds a general semantic that the filter conditions are 'те же, что у списка разговоров' (same as the conversation list) and that omitting all conditions means 'всех собеседников бота'. It also flags unknown substitutions in the text parameter, which is an extra warning 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 'Прикидка до отправки', clearly identifying this as a pre-send estimation tool for broadcasts. It enumerates concrete outputs: 'сколько разговоров подходит под условия, кто именно (первые 50 по свежести), сколько из них закрыли боту рот'. This distinguishes it from sibling tools like broadcasts_start and broadcasts_save by focusing on preview before sending.

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 when to use this tool: 'Разосланное не отзывают, поэтому смотреть надо здесь' – i.e., use it before sending because sent broadcasts cannot be recalled. It also names the alternative for saving drafts: 'черновик заводит broadcasts_save'. This gives the agent clear routing between preview and save operations.

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

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

Beyond the annotations, the description discloses important behavioral traits: a draft will not send until started, edits don't work once a broadcast has begun, selection criteria replace rather than merge, omitted criteria remain unchanged, and HTML markup is validated at save time. This is substantial value beyond the readOnly/destructive 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?

The description is dense but every sentence earns its place: it distinguishes create/edit behavior, names the cancellation sibling, explains selection-criteria semantics, and notes HTML validation. The most important behavioral distinction is front-loaded in the first sentence.

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

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

For a complex tool with 15 parameters and no output schema, the description covers the critical behavioral context: when the tool creates vs edits, when editing is impossible, how to handle a started broadcast, and how selection updates behave. Combined with the 100% schema coverage, an agent has enough to call the 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%, so the schema already documents all parameters. The description adds meaningful semantics for the key `broadcast` parameter (new vs edit, draft vs scheduled vs started) and clarifies replacement behavior for selection criteria, which is not fully captured by the schema property descriptions.

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

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

The description states a specific action and resource: without `broadcast` it creates a broadcast draft; with `broadcast` it edits an existing draft or a scheduled-but-not-yet-sent broadcast. It also clearly distinguishes itself from sibling tools `broadcasts_start` and `broadcasts_cancel`, so an agent can tell when this tool applies.

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

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

The description gives explicit usage rules: omit `broadcast` to create a draft, provide it to edit a draft or scheduled broadcast, and do not attempt to edit an already-started broadcast — instead use `broadcasts_cancel`. This is direct guidance with named alternatives and clear conditions.

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 (destructiveHint=true, openWorldHint=true), the description explains the irreversible consequence: 'Отправленное не отзывается ни у одного получателя' (sent cannot be recalled), and reveals queueing, scheduling via run_at, and the all-recipients risk. This significantly exceeds 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?

Four short sentences, each with a distinct purpose: queueing, irreversibility warning and preview, scheduling, and cancellation. The action is front-loaded and there is no filler.

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

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

For a three-parameter tool with no output schema, this description is unusually complete: it covers the core action, the main risk and mitigation, scheduling semantics, and the follow-up cancel action. Nothing essential for a correct invocation is missing.

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

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

The schema already documents every parameter (100% coverage), so the baseline is 3. The description adds rationale for confirm_title as an exact-title confirmation and clarifies scheduling behavior with run_at, adding 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?

The description immediately states a specific action and scope: 'Ставит черновик в очередь' (puts a draft into the send queue), which clearly means starting a broadcast. It also distinguishes itself from adjacent siblings by referencing broadcasts_preview and broadcasts_cancel, and from broadcasts_save by emphasizing the draft is already prepared.

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

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

It gives explicit workflow guidance: first use broadcasts_preview to check recipients, and use broadcasts_cancel for anything not yet sent. The warning that an empty selection means all bot interlocutors tells the agent when to be cautious and what to check beforehand.

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 destructiveHint annotation, the description adds concrete details: which entities are destroyed, and that deletion cannot be undone ('Восстановить нельзя'). This gives the agent a clear picture of the irreversible destructive scope, which is more than the annotation alone.

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

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

The description is just two sentences, both information-dense. The first states the action and its scope, the second states irreversibility and the alternative. There is no redundant or filler content, making it optimally 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 a destructive mutation tool with no output schema, this description is fully complete: it tells what is deleted, warns about irreversibility, and gives an alternative for a milder action. Combined with the schema's 100% parameter coverage, the agent has all the information needed 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?

Both parameters (case, confirm_name) have full schema descriptions with 100% coverage. The description adds no additional parameter-level detail, so the baseline of 3 applies; there is no need for the description to repeat 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 clearly states the tool deletes an entire case ('Удаляет дело целиком') and enumerates exactly what gets deleted (bots, scenarios, correspondence, participants, roles). It also distinguishes itself from archiving via cases_save, making it 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 provides an alternative: 'Чтобы просто убрать дело из списка, используйте cases_save с archived=true' (to simply remove from list, use cases_save with archived=true). This tells the agent when not to use this tool, which is exactly the needed 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about what the returned case card contains, including current user rights in the case and the list of summary categories. 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 a single dense sentence with no filler words. It lists multiple summary categories, which is informative, but the long list makes it slightly heavy—still reasonably concise for the richness it conveys.

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 two optional parameters, no output schema, and strong annotations, the description is sufficient for an agent to know what the tool returns: user permissions and a composite case summary. It also clarifies the date-bound correspondence aspect referenced by the 'days' parameter.

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

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

Schema description coverage is 100%, and both parameters are already documented in the input schema: 'case' explains the matching and fallback behavior, and 'days' says 7/14/30 with a default of 7. The description does not need to add further parameter-level 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 defines the tool as a case card ('Карточка дела') that returns the current user's rights and a summary of bots, dialogs, correspondence, deferred actions, knowledge bases, and participants. This distinguishes it from cases_list, cases_save, and cases_delete.

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 the tool is used for viewing/opening a single case with details and rights, but it does not explicitly state when to use it instead of sibling tools like cases_list or bots_get. No when-not-to-use or alternative tool mention is present.

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 destructiveHint=true and readOnlyHint=false. The description adds a valuable behavioral constraint: the owner cannot leave and must transfer the case first. This goes beyond the annotation flags and provides real context about preconditions and limitations.

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

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

Two concise sentences, front-loaded with the primary action followed by the exception and alternative. Every word earns its place; there is no redundancy or unnecessary elaboration.

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 action with one parameter and no output schema, the description covers the core action, the key restriction, and the alternative. It does not mention edge cases like non-participant behavior, but given the annotations and simplicity, it is nearly 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 100% coverage for the single parameter 'case' with a clear description ('Дело: название или идентификатор'). The tool description does not add further detail about the parameter, 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 clearly states the tool's function: 'Убирает вас из числа участников дела' (removes you from case participants). It specifies the action (remove) and the resource (your membership in the case), distinguishing it from sibling tools like case_transfer, which transfers ownership, and members_remove, which likely removes other members.

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 the tool cannot be used ('Владелец выйти не может') and provides a clear alternative: 'сначала нужно передать дело другому участнику (case_transfer)'. This gives the agent actionable guidance on when to use this tool versus the case_transfer sibling.

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 read-only, open-world, idempotent, and non-destructive. The description adds value by specifying the access scope and response contents (role, rights, bot/unread counters), enriching behavioral understanding without contradicting the annotations.

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

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

The description is a single, front-loaded sentence that immediately conveys the tool's purpose and scope. It contains no filler or redundant information relative to the 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?

For a straightforward list tool with one optional parameter and rich annotations, the description is sufficient: it names the resource, access scope, and returned data fields. It does not describe pagination or the exact array format, but the absence of an output schema and the tool's simplicity make this 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 only parameter (include_archived) is fully described in the schema with a default value, and the schema coverage is 100%. The description does not add parameter details, but the baseline of 3 is appropriate because the schema carries the semantic 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 states the tool lists all accessible cases ('Все дела, к которым есть доступ') and specifies the included data: role, rights, bot and unread counters. This clearly identifies it as the list operation for cases, distinguishing it from sibling tools like cases_get or cases_delete.

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 context that the tool returns only cases the user has access to and includes an optional archived filter, but it does not explicitly state when to prefer this over cases_get or other list tools. Usage is implied rather than directly contrasted with 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 show readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable context: becoming the owner, the five roles expanded, and the archive action. This goes beyond the structured data without contradicting it.

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 primary create behavior, and every clause earns its place. It's concise yet covers both modes and the side effects (ownership, roles, archive) without waste.

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

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

The tool has two modes and non-trivial side effects, but the description covers them adequately. There is no output schema, and the description doesn't mention return values, which would be helpful. However, the action is clear and the schema fills in parameter details, so it's nearly complete.

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

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

Schema coverage is 100% with each parameter documented. The description doesn't add parameter-level detail beyond the schema, which is the baseline expectation. The schema already explains the 'case' parameter's omission behavior, so the description adds no extra 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 tool creates or modifies a case, with an explicit verb for each mode ('создаёт новое' and 'меняет'). It distinguishes from sibling tools like cases_list, cases_get, and cases_delete by describing its dual create/update behavior.

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 conditional usage: omit 'case' to create, specify it to update. It doesn't explicitly name alternatives, but the conditions are explicit and easy to follow. No exclusions are mentioned, but none are needed.

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 beyond the destructiveHint annotation by explaining exactly what happens to the previous owner (demoted to admin, loses re-transfer rights) and that only the new owner can transfer back. This provides critical behavioral detail not available elsewhere.

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 long, front-loaded with the core action, and every clause adds value. 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?

For a destructive, non-idempotent tool with no output schema, the description explains the transfer, the consequences for both parties, and the irreversible nature. It lacks explicit prerequisites (e.g., current owner must invoke) but is otherwise complete for safe operation.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The tool description does not add additional parameter meanings beyond the schema, leaving confirm_name and member semantics to the schema.

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

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

The description clearly states the action: making another participant the owner of a case. It distinguishes from related tools like cases_leave or cases_delete by specifying the transfer of ownership and its consequences, 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?

The description implies usage scenarios (when you need to change case ownership) but does not explicitly contrast with alternatives or state when not to use it. The context is clear enough for an agent to infer, but explicit guidance 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?

Beyond the destructiveHint annotation, the description discloses that the entire correspondence is deleted and that restoration is impossible. It also clarifies the behavior of the alternative path (correspondence remains), which helps the agent understand the irreversible side effect.

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 deliver the core action, the irreversible consequence, and the recommended alternative. There is no filler or repetition; the most important behavioral warning 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 destructive operation with a required confirmation parameter, the description sufficiently explains what is deleted, that deletion cannot be undone, and what to do instead when permanent deletion is not desired. The schema covers parameter semantics and confirmation, so no critical context is missing.

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

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

Schema description coverage is 100%, so the parameters 'case', 'dialog', and 'confirm_contact' are already documented in the schema. The tool description adds no additional parameter-level meaning, matching the baseline for high schema coverage.

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

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

The description opens with a clear verb and resource ('Удаляет диалог') and specifies the destructive scope ('вместе со всей перепиской'). It also distinguishes itself from dialogs_update by explicitly contrasting permanent deletion with a non-destructive manual-mode 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 gives concrete guidance on when not to use this tool: if the bot should merely stop replying, the agent should call dialogs_update with mode=operator and ai_enabled=false instead. This explicitly routes to the alternative and explains the trade-off regarding preservation of the conversation.

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 destructiveHint=true, but the description adds meaningful context beyond that: the recipient's copy is removed while the panel record stays crossed out, deletion is irreversible, and too-old messages are rejected. This gives the agent a solid understanding of consequences. 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?

Three terse sentences with the core action front-loaded. Every sentence adds a distinct constraint (scope, irreversible, age limit) with no filler or repetition.

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 two required parameters and annotations already carrying the safety profile, the description covers the main side effects, scope restriction, irreversibility, and a failure condition. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, and each parameter (case, dialog, message) is already documented with meaningful descriptions in the schema. The tool description itself adds no additional parameter-level detail, 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 opens with a specific verb and resource ('Убирает своё сообщение из чата собеседника') and clarifies that only the caller's own messages can be removed. This clearly distinguishes it from siblings like dialogs_edit_message or dialogs_delete without needing to open their schemas.

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

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

The description provides clear invocation conditions: only own messages, irreversible deletion, and platform restrictions on old messages. However, it never names sibling tools or explicitly states when to prefer dialogs_delete_message over dialogs_delete or dialogs_edit_message, so routing guidance remains 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?

With annotations marking this as a mutating, non-read-only operation, the description goes further and discloses valuable behavioral details: the change appears both to the interlocutor and in the panel, buttons stay unchanged, the bot must be running, and very old messages may not be editable. 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 compact and front-loaded with the core purpose, followed by concise, high-value constraints and limitations. Every sentence carries useful information: scope, exclusions, alternatives, and runtime prerequisites.

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 edit operation with no output schema, the description covers the essential context: what gets changed, where the change appears, what cannot be changed, when the operation may fail, and what preconditions apply. An agent has enough information to select and invoke the tool correctly.

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

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

The input schema already documents all four parameters with 100% coverage, including descriptions for text, dialog, message, and case. The description adds only a little extra meaning, such as the fact that attachment captions are not edited, which clarifies the scope of the text parameter but does not substantially go 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: it changes the text of an already-sent message, affecting both the recipient and the panel conversation. It clearly distinguishes this from sibling tools like dialogs_delete_message or dialogs_reply by focusing on editing an existing sent message.

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 strong usage context: it only edits the bot's or operator's own messages, cannot edit undelivered messages (says to resend instead), and cannot edit attachment captions. It does not name sibling tools explicitly, but the conditions and exclusions are clear enough for an agent to decide when this tool is appropriate.

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, and destructiveHint. The description adds valuable behavioral context beyond those hints: the dialog is not marked as read ('Прочитанной переписка от этого не становится') and the export is recorded in the case journal ('сама выгрузка отмечается в журнале дела'). This is useful and does not contradict 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: three sentences, each carrying distinct information about output format, use cases, and side effects plus the alternative tool. It is slightly embellished with the phrase 'ровно то, что панель отдаёт файлом', but overall it is well-structured and 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 simple two-parameter tool with no output schema, the description sufficiently explains the return format, the purpose, the side effects, and the sibling alternative. The input schema covers parameter details, so nothing critical is missing for an agent to select and invoke the 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 description coverage is 100%, and both parameters (dialog and case) are already documented with clear descriptions and default behavior for case. The description does not add parameter-specific semantics, so the baseline 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 exports the whole conversation as one ready-made text with a header and messages in order, which is a specific verb+resource. It also distinguishes itself from dialogs_history, which is the sibling most likely to be confused with it.

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

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

It explicitly says the export is suitable for attaching to dispute analysis or sharing with someone without panel access. It also names dialogs_history as the better tool for per-message analysis and deep history, giving a concrete when-to-use vs alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds meaningful context about the informational content returned (scenario position, expected answer, variables), going beyond what annotations alone provide. There is 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 a single, well-structured sentence with a colon-led list. It is front-loaded with the core subject and each listed item adds useful detail. 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?

For a simple read-only getter with full schema coverage and no output schema, the description adequately explains what the agent will learn from the call. It outlines the key aspects of the dialog card without needing to specify return format. Minor lack of error/edge-case handling is acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, and both parameters ('case' and 'dialog') have clear descriptions in the schema. The tool description adds no extra parameter-level semantics, so it cannot exceed the baseline of 3.

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

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

The description clearly conveys the tool's focus: it provides the dialog and its position in the scenario, including current step, expected response, path, planned steps, and variables. This distinguishes it from sibling tools like dialogs_list or dialogs_history. However, it lacks an explicit verb like 'get' or 'retrieve', relying on the tool name for the 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 no guidance on when to use this tool relative to alternatives (e.g., dialogs_list, dialogs_history, dialogs_reply). It does not mention exclusions, prerequisites, or scenarios where other tools would be more appropriate.

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 read-only and non-destructive behavior. The description adds a valuable behavioral nuance: by default, it does not mark messages as read, leaving counters unchanged. This goes beyond the annotations and 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 two sentences, front-loaded with the main purpose, and contains no redundant information. Every sentence adds meaningful guidance.

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 (5 parameters, no output schema), the description covers ordering, pagination, and read behavior, which are the critical aspects. It does not describe return fields, but that is not strictly necessary for this list-like tool. Slightly more detail on response structure could make it a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by explaining how to use the 'before' parameter for deep history pagination and reiterating the default for mark_read. This adds practical value beyond the raw schema.

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

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

The description clearly states that this tool returns dialog messages in chronological order from old to new, which is a specific action. It also mentions the default behavior of not marking messages as read, distinguishing it from other dialog-related tools like dialogs_reply or dialogs_update.

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, including how to paginate deeper into history using the 'before' parameter. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls 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 declare readOnly, idempotent, and non-destructive behavior. The description adds that it indicates unread messages and operator status, but does not disclose pagination behavior or return format, so it provides only limited extra 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, two-sentence statement focused on the action and key capabilities. It is appropriately sized and front-loaded, with no unnecessary 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?

The combination of a clear description, thorough schema, and safety annotations provides sufficient context for a list operation. It could mention pagination defaults or return format, but these are not required given the schema details and read-only annotations.

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

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

Schema covers all 7 parameters with descriptions (100% coverage). The description's mention of filtering by bot, mode, and substring repeats the schema without adding additional semantic nuance, so the baseline 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 it lists bot conversations filtered by bot, mode, and substring, and mentions it shows unread and operator-led dialogs. This distinguishes it from sibling dialog tools like dialogs_get or dialogs_history.

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 as a listing tool but does not explicitly state when to use it vs alternatives or mention exclusions. It relies on the tool name and purpose to convey the use case, but lacks explicit 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?

Beyond annotations, which only mark the operation as read-write and non-idempotent, the description discloses that the dialog default switches to manual mode and gets assigned to the user, that the bot must be running, and that a delivery-error field may appear in the response because the message is saved even if the platform rejects it. This is valuable behavioral 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 compact and front-loaded: the core action appears in the first clause, followed by options, side-effect, prerequisites, and response caveat. Every sentence adds information, 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 six parameters, no output schema, and only basic annotations, the description covers the critical aspects: the bot must be running, the dialog's mode change, how to revert it, and how to interpret delivery errors. The response format is partially explained via the delivery-error field, which is necessary since no output schema exists.

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 six parameters are fully described in the schema (100% coverage), so the baseline applies. The description repeats the distinction that reply replaces text and mentions reply_to as an optional quote, but adds no new meaning 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 opens with a specific action—sends a message to a person on behalf of the bot—and enumerates the supported variants (free text, saved template, quote). This clearly distinguishes it from siblings like dialogs_edit_message, dialogs_delete_message, and dialogs_update, which modify or manage dialogs rather than send new messages.

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 (reply when you want to send a message on behalf of the bot) and adds prerequisites (bot must be running) and a side-effect warning (conversation switches to manual mode). However, it does not explicitly name alternatives or state when not to use it, relying on inference rather than explicit routing.

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, adding rich behavioral context: the symptom the user sees (a silent bot), the side-effect of canceling deferred continuations with the rationale ('would fire into the void'), and the post-condition (next message restarts the scenario). This adds genuine value beyond the generic readOnlyHint/idempotentHint flags. No contradiction found — canceling scheduled continuations is inherent reset semantics, not destruction.

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

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

Two sentences, zero waste. The first sentence leads with the action and purpose, the second covers side effects and post-conditions. The vivid 'mute bot' and 'fire into the void' metaphors pack meaning into few words.

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 mutation tool with only two string parameters, no output schema, and no nested objects, the description is complete: it covers the trigger condition, the side effect, and the resulting behavior. 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 both parameters (case, dialog) are already well-documented in the schema with their formats and defaults. The description adds nothing about parameters, which is acceptable per the baseline of 3 given full schema coverage, but there is no extra value either.

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 ('Освобождает' - frees/releases) and a specific resource (a conversation stuck at a wait node), clearly distinguishing it from sibling dialog tools like dialogs_list, dialogs_reply, or dialogs_delete. The real-world framing ('looks like a silently mute bot') makes the exact scenario 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?

The description provides clear, specific context for when to use the tool: when a conversation is stuck at a wait node awaiting an answer that will never come. However, it does not name explicit alternatives or exclusions (e.g., 'use dialogs_delete if...'), so it falls just short of the top tier.

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 a non-obvious side effect: switching to bot mode returns the conversation to the scenario and removes the operator. It also clarifies a boundary—blocking is handled by the platform and only displayed here. This adds behavioral context the annotations do not 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?

Two sentences with no filler. The main action is front-loaded in the first sentence, and the second sentence earns its place by clarifying a common misconception about blocking. Every word contributes.

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 settings-mutation tool with six parameters, the description covers purpose, the key mode side effect, and an explicit limitation, while annotations cover read-only/destructive/idempotent traits. It omits only minor details like response shape, acceptable because there is no output schema and the tool is straightforward.

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 parameters are already well documented. The description mostly restates the schema's parameter purposes (mode, AI, tags, pinning) and adds only a small extra nuance about the bot-mode side effect. That does not elevate it above the baseline 3 for fully covered schemas.

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 opens with a specific verb 'Меняет' and enumerates exactly which dialog settings are affected: mode (bot/operator), AI answering, tags, pinning. This clearly separates it from sibling dialog tools like dialogs_delete or dialogs_reply, which operate on the dialog itself or its messages.

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 concrete effect ('Перевод в режим bot возвращает разговор сценарию и снимает оператора') that helps an agent understand when to set mode=bot, and it explicitly states a non-goal: 'Заблокировать собеседника отсюда нельзя'. It names no alternative tools for the same configuration, but the usage context is clear.

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

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

The annotations already mark this as destructive, but the description adds key behavioral detail beyond that: deletion removes the entire edit history, is irreversible, affects running bots, and does not unpublish from the marketplace. This is exactly the kind of consequence disclosure an agent needs before invoking a destructive tool.

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

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

Three short sentences deliver the core action, the irreversible consequence, the operational warning, and the alternative tool. No filler or repetition of schema details.

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

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

For a destructive 4-parameter tool with no output schema, the description covers the important consequences: history loss, irreversibility, effect on live bots, and marketplace publication behavior. The confirm_name safety mechanism is already documented in the schema, 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 parameters are already well documented. The description does not add extra parameter-level meaning, but the baseline of 3 applies because the schema handles the load.

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

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

The description names a specific verb and resource: deletes a flow along with its entire revision history. It also distinguishes the scope from siblings by noting irreversibility and that marketplace publication is not removed, which separates it from flows_save and market_unpublish.

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 behavioral guidance: deleting is permanent, deleting an active flow leaves the bot without a canvas, and if the flow is published, the publication remains and must be removed separately via market_unpublish. This explicitly points to the relevant 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 establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond annotations by specifying that the response is ready-to-use JSON in the operbots.flow format and identical to the panel's download output.

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

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

Two sentences with no redundancy: the first front-loads the core contract, the second explains how the result should be consumed. 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 export with three well-documented parameters and no output schema, the description fully compensates by describing the response format and its intended downstream usage. 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?

The input schema covers all parameters with descriptions, so the baseline is 3. The tool description does not add parameter-level detail, but none is needed given 100% 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 tool returns a flow as a single operbots.flow object, matching the panel's Download button. It names the specific resource and output format, though it does not explicitly contrast itself with flows_get or other 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 explains the intended downstream use: pass the JSON to flows_import via the document field or save it as a copy near code. This gives practical context for when to use the tool, but it does not explicitly state when not to use it or name alternative 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 this as read-only, open-world, idempotent, and non-destructive. The description adds valuable context by specifying that the tool returns the entire graph along with diagnostics like 'connections to nowhere, missing trigger, unreachable nodes'. This goes beyond the safety profile provided by annotations and describes the tool's analytical 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, concise phrase that immediately states the tool's scope and content. It contains no unnecessary words or repetition, making it 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?

For a relatively simple getter with no output schema, the description gives a solid overview of the returned data and even highlights diagnostic features. It does not cover error behavior or the optional 'case' parameter, but the schema and annotations cover most context, making it substantial 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?

The input schema covers 100% of parameters with descriptions for bot, case, and flow. The tool description itself does not add any parameter-specific semantics, so a baseline score of 3 is appropriate for high schema coverage.

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

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

The title 'Открыть сценарий' (Open scenario) combined with the description 'Сценарий целиком...' clearly identifies this as a getter for a complete flow graph. It explicitly lists what is returned (all nodes, parameters, connections, graph remarks) and thereby distinguishes it from sibling tools like flows_list, which likely provides a list of flows.

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 use for retrieving full scenario details but does not explicitly state when to use it versus alternatives such as flows_list or flows_versions. The phrase 'Сценарий целиком' suggests detailed inspection, but no exclusions or alternative tools are mentioned.

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

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

Beyond the annotations (openWorldHint true, destructiveHint false), the description reveals that existing flows are left untouched, unresolved AI service and knowledge base links are removed, and each removal is reported in the response. This adds substantial behavioral detail not present in 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?

Three concise sentences, front-loaded with the main action, no redundant wording. Every sentence adds value and structure is clear.

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 creation tool with a complex nested document parameter and no output schema, the description explains conflict resolution behavior and response content for link removals. It hints at the response but could be more explicit about the success return value, yet given the available annotations it is reasonably complete.

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

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

All 4 parameters have schema descriptions (100% coverage), and the description only adds context (e.g., the document is the whole export from flows_export) without giving deeper parameter-specific meaning. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states it creates a scenario from an export object obtained via flows_export ('Заводит сценарий из объекта, полученного через flows_export'). This distinguishes it from related tools like flows_save or flows_delete by focusing on the import-from-export use case.

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

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

It implies usage after flows_export and clarifies that existing flows are not overwritten and name conflicts get numbering, providing useful context. However, it does not explicitly contrast with flows_save for editing or specify when not to use this tool, so it falls 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details beyond annotations: it returns a list of flows with their operational status and node counts, plus the default fallback to all bots in the case when 'bot' is omitted. No contradictions; annotations and description align well.

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. The first states what the tool returns, the second clarifies the default scoping. Every word adds value, and it's immediately 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?

For a simple list tool with rich annotations and full schema descriptions, the description covers the essential usage context. It communicates return highlights and default behavior without over-explaining, which is complete for this tool's simplicity.

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 the 'bot' parameter's default behavior ('Без него — все боты дела'). The tool description reiterates this but adds no meaningful new parameter semantics. 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 tool lists flows with specific contextual details ('какой из них в работе' for status, 'сколько в них узлов' for node counts). It also explains the default scoping behavior without the 'bot' parameter, effectively distinguishing it from single-flow retrieval tools like flows_get. This is a specific verb+resource+scope definition.

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 it by explaining the behavior with and without the 'bot' parameter. It implicitly differentiates from flows_get/flows_export and others, though it doesn't explicitly name alternatives or exclusions. This meets the 'clear context, no exclusions' bar.

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?

Despite annotations indicating non-readonly, open world, non-idempotent, and non-destructive, the description adds crucial behavioral context: publishing disables all other flows, validation prevents publishing if there are links to non-existent nodes, and disabling leaves the bot without a canvas and unresponsive. These are significant consequences not disclosed in annotations alone.

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

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

The description is two sentences, front-loaded with the main verb and resource, and every sentence carries important information: enable/disable action, exclusivity, validation check, and disabling consequence. No wasted words.

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

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

The tool has no output schema, but the description sufficiently covers the main behavior and side effects. It lacks details like return values (success/failure messages) or whether active defaults to true, but the schema already indicates 'active' default. Given the tool's moderate complexity, the description is complete enough, though a note about success/failure output would make it fully 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 description coverage is 100% (all four parameters have descriptions). The description adds context about validation and exclusive activation but doesn't add parameter-specific meaning beyond the schema. Baseline 3 is appropriate given 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 tool's function: enabling/disabling a flow script, with the specific constraint that only one flow can be active at a time and turning off leaves the bot non-responsive. This distinguishes it from sibling flow tools (e.g., flows_save, flows_delete) and other bot controls.

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 when this tool is used (publishing/enabling a flow) and a critical consequence of disabling (bot stops responding). It doesn't explicitly name alternatives, but the title and context make it clear this is for activation/deactivation, not editing or deleting. The 'only one active' rule is a strong usage condition.

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 behavioral context beyond the annotations: history is not rewritten and a new revision is layered on top, and the bot immediately behaves per the restored version if the scenario is live. Since annotations already cover safety, this extra context justifies a high score.

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 concise sentences with no filler. The first sentence states the primary action, and the second adds key behavioral nuance, making it 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?

With 100% schema coverage and annotations providing safety context, the description adequately rounds out the tool by explaining side effects. It lacks only an explicit return-value description, but this is minor for a mutation tool.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description does not add any additional meaning to the parameters, aligning with the baseline of 3.

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

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

The description clearly states the tool restores a scenario graph to a selected revision, using a specific verb and resource. It distinguishes itself from sibling tools like flows_save, flows_publish, and flows_versions by conveying the restore 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 behavior is described (new revision, immediate effect), but there is no explicit guidance on when to use this tool versus alternatives. Usage is implied by the purpose rather than explicitly stated.

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

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

Annotations only show readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds critical behavior: full-graph overwrite semantics, revision creation only on actual graph change, no activation on save, and exclusion of ready-made market templates. This goes well beyond annotation signals.

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 earns its place: mode selection, overwrite behavior, full-graph requirement, revision condition, market exclusion, and publish alternative. It is front-loaded with the core create/overwrite distinction and avoids repetition of schema details.

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

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

For a complex 9-parameter tool with no output schema, the description covers all essential operational aspects: how to create, how to overwrite, how to edit existing flows safely, what not to use it for, and what related tool to use for activation. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantic context beyond the schema: the graph must be sent whole, new revisions are created only if the graph changed, and the flow parameter controls create-vs-overwrite mode. This is genuinely useful parameter-level guidance.

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 creates a flow when `flow` is omitted and overwrites when supplied, with distinct creation modes (empty, from graph, copy_of). It is easily distinguished from sibling tools like flows_publish and flows_get, which are explicitly named.

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

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

Explicitly explains when to use the tool, how to pass the graph whole, and points to alternatives: flows_get for reading before editing, market_install for ready-made flows, and flows_publish for activating a flow. No ambiguity about selection or workflow.

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 substantially enriches the annotations: it specifies that the dialog is not saved anywhere, delays are skipped, external requests and service-chat notifications are not executed, and — critically — that AI nodes call the real model and consume its limits. This last point explains why readOnlyHint=false despite the tool being a simulation, giving the agent an accurate cost/side-effect model that annotations alone could 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 efficiently organized: purpose is front-loaded in the first sentence, followed by a compact list of what is suppressed (saving, delays, external requests, notifications), then the variables usage tip, and finally the cost warning delivered with an explicit 'Внимание' marker. Every sentence carries distinct information, and the AI-limit caution is placed at the end where it reads as an important caveat rather than burying the main 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?

Given 7 parameters, a nested variables object, no output schema, and no annotation detail, the description is remarkably complete: it states the return-relevant results (trigger, steps, bot reply), enumerates exclusions, explains parameter usage for the trickiest param (variables), and discloses the real-world cost. It could go slightly further on what the simulated run returns structurally, but it compensates for the missing output schema better than most tool definitions 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 coverage is 100%, so the baseline is 3 with the schema carrying the load. The description adds genuine value beyond the schema by explaining the purpose of the variables parameter — substituting conversation-accumulated state to exercise conditional branches and substitutions — which the schema's bare example ('{"город": "Москва"}') does not convey. Other parameters receive no description-level additions, but the schema already documents them 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 opens with a specific verb+resource combination — 'Проверяет сценарий, не выходя к платформе' — and concretely states what the agent gets out of it: which trigger fired, which steps executed, and what the bot would reply. It clearly distinguishes flows_simulate from sibling flow-management tools (flows_save, flows_publish, flows_delete) by framing it as a sandboxed test run rather than a platform operation.

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 when to use the tool: to verify conditional branches and substitutions by injecting accumulated conversation state via variables ('так проверяются ветки условий и подстановки'). It also communicates the safety profile so an agent knows it is the non-destructive option. It does not explicitly name alternatives or state when-not-to-use in favor of another tool, but the behavioral boundaries are clear enough to guide selection.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results include comments and dates, giving some return-content context, but no details on pagination or ordering.

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

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

One short sentence, front-loaded with the main content, no redundant words. It could benefit from a verb, but structure is 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 simple read-only list tool with no output schema, the description provides the essential return content (all revisions with comments and dates) and annotations cover safety. However, it doesn't explain ordering, pagination, or the exact structure of each revision, leaving some gaps.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description adds no parameter-specific context beyond what the schema provides; 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 identifies the resource (saved revisions of a script) and implies a listing operation, but lacks an explicit verb. It doesn't distinguish from sibling tools like flows_list or flows_get, though 'редакции' clarifies it's about version history.

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 on when to use this tool versus alternatives such as flows_get or flows_restore. The description only states what is returned, not when it should be selected.

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 indicate readOnlyHint=false and idempotentHint=false, and the description adds meaningful context: the server does not send the link, and anyone with the link can join with the specified role. This goes beyond the annotations and helps the agent understand the tool's side effects and security implications.

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 long, front-loaded with the primary action, and every clause adds value. It avoids redundancy and is well-structured for quick comprehension.

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 5 optional parameters and no output schema, the description should clarify the result. It implies the tool returns a link (since the server does not send it) but does not explicitly state the return format. It also omits any permission prerequisites, but overall it covers the essential behavior well 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value to parameter understanding—it mentions 'specified role' but does not elaborate on the case default, email restriction, max_uses, or TTL. The schema already provides clear per-parameter descriptions, so the description is not required to repeat them.

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: 'Делает ссылку для вступления в дело' (makes a link to join a case). It uses a specific verb and resource, and distinguishes from sibling tools like invites_revoke by focusing on creation. It also adds the important detail that it works for unregistered users.

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 the tool (to generate an invitation link) and clarifies that the server does not send the link, so the user must distribute it. However, it does not explicitly mention when not to use it or name alternative tools, though this is a straightforward create operation.

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. The description adds useful context by specifying that the invitation link becomes unusable, which clarifies the exact impact of the operation beyond the generic destructive hint.

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, directly stating the purpose and effect. It is well-structured 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?

For a simple destructive tool, the combination of annotations (destructiveHint) and fully described parameters makes the description sufficient. It clearly communicates the core action and outcome without requiring additional detail.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The tool description adds no extra parameter semantics, so the baseline score 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 clearly states the action with a specific verb 'Гасит' (revokes) and specifies the exact consequence: the invitation link will no longer work. This distinguishes it from related tools like invites_create and members_remove.

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 or when to prefer alternatives. It simply describes the action without contextual cues about suitable scenarios or exclusions.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that processing is asynchronous (material starts in pending), and that repeated calls create duplicates. This adds meaningful behavioral context useful 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?

Three concise sentences, front-loaded with the primary action, followed by two important behavioral notes. No wasted words.

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

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

For a tool with no output schema, the description covers the key operational aspects: purpose, asynchronous behavior, duplicate prevention, and how to verify the result. It could mention edge cases like providing both text and URL, but overall it's 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?

Schema description coverage is 100%, so all parameters are already documented. The description's general statement about text or URL adds minimal new meaning; the per-parameter details are 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 it adds text or a URL page to the knowledge base ("Кладёт в базу текст или страницу по ссылке"), using a specific verb and resource. It also implicitly distinguishes from update tools by emphasizing that repeated calls create duplicates, not updates.

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 practical usage context: background parsing, pending state, and a suggestion to check via knowledge_list. It warns against using repeated calls for updating, though it doesn't explicitly name an alternative for updates (e.g., knowledge_save).

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 destructiveHint annotation, the description adds concrete behavioral details: deleting a base removes all its materials and vectors, and restoration is impossible. This gives the agent a clear and complete picture of the destructive consequences before invocation.

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: the first front-loads the core operation and conditional behavior, and the second delivers the critical irreversibility warning. There is no filler or repetition.

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 fully documented schema and the absence of an output schema, the description supplies the essential behavioral context: destructive scope, conditional operation, and irreversibility. No critical gaps remain for an agent to invoke this tool safely.

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

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

The input schema already documents all four parameters with descriptions, including the fact that omitting 'document' deletes the whole base. The description essentially restates this conditional behavior rather than adding new parameter-level meaning. Therefore, the high schema coverage keeps this at the baseline of 3.

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

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

The description uses a specific verb ('удаляет') and clearly distinguishes the two deletion modes: one material when 'document' is provided, or the entire knowledge base with all materials and vectors when it is not. This makes the tool's purpose and scope immediately understandable and distinct from sibling knowledge 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 explicit conditional usage guidance: include 'document' to delete a single material, omit it to delete the whole base. It also warns that deletion is irreversible, helping the agent weigh caution. It does not explicitly name alternatives, but no direct deletion alternative exists among the siblings, so this is adequate.

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 safety expectations. The description adds useful behavioral context: the material can be referenced by name ('Материал можно назвать по имени — идентификатор не обязателен') and that chunks=true reveals the chunking used for model ingestion. These insights go beyond the structured 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?

The description is three sentences, each delivering a distinct piece of information: the tool's purpose, a comparison to the list, and the optional chunks behavior. It is front-loaded with the core purpose and contains 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?

For a read-only retrieval tool with full parameter descriptions and safety annotations, the description is complete enough. It explains what the tool returns (the material's text), highlights the key usage context (list doesn't include text), and covers the optional chunks flag. It doesn't detail the return format or error handling, but given the simplicity and existing schema, this is acceptable.

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

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

Schema coverage is 100%, with clear descriptions for all four parameters. The description reinforces the name-or-ID flexibility for the document parameter and explains the chunks option, but these details are already present in the schema. Thus, the description adds minimal new semantic value beyond the schema, 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 immediately states the tool's core function: retrieving the full text of a material ('Материал с его текстом: что в нём написано на самом деле'). It also distinguishes itself from the material list, which does not include text, and mentions the optional chunks output. This is a specific verb+resource definition with clear differentiation from sibling tools like knowledge_list.

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 contrasts this tool with the material list: 'Список материалов текста не отдаёт' (the list does not give the text), implying this tool should be used when the actual text is needed. It also explains when not to use chunks by default because they 'повторяют текст и удваивают ответ'. While it doesn't name all alternatives, it provides clear guidance for the primary alternative.

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 reveals important non-obvious behavior beyond annotations: changed text triggers reassembly to prevent stale bot answers, and link materials live as snapshots unless refetch=true is used. This adds meaningful operational context and does not contradict 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 four dense sentences, front-loaded with the primary action, and contains no filler. Every sentence earns its place by adding a distinct and useful piece of context.

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

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

Given six parameters, no output schema, and moderate annotation richness, the description covers the operation scope, key constraints, reassembly behavior, and the refetch snapshot lifecycle. It is sufficiently complete for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics for refetch (page fetched once at addition, then lives as snapshot) and for text (triggers re-slicing), which goes beyond the schema's parameter 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 uses a specific verb and resource: 'Правит название и текст материала' (edits the title and text of a material). This clearly distinguishes it from sibling tools like knowledge_add_document or knowledge_delete.

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 edit an existing material's title/text, with automatic reassembly. It also explicitly states an exclusion — source type and link cannot be changed — and explains the refetch behavior for link materials, though it does not explicitly name alternative tools for those 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 declare this a read-only, open-world, idempotent operation. The description adds meaningful behavioral context beyond that: it specifies that without 'base' it returns all knowledge bases with settings, and with 'base' it also returns a material list with parsing status. This gives the agent insight into output richness and conditional behavior, though it does not cover edge cases like empty results or pagination.

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

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

The description is a single, compact sentence that front-loads the core behavior and then expands on the conditional variant. Every word contributes to understanding the tool's output and parameter effect, with no fluff 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?

Given the simple optional-parameter structure, no output schema, and strong annotations, the description adequately explains what the tool returns under both invocation modes. It would benefit from mentioning return format details or pagination, but the provided information is sufficient for an agent to know what to expect in typical use.

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 both parameters ('base' and 'case'), so the schema already documents their meaning. The description adds conditional behavior tied to 'base', but this is more about output shape than parameter semantics. The 'case' fallback behavior is already documented in the schema, so the description does not significantly elevate 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 clearly indicates the tool lists knowledge bases ('все базы знаний дела с их настройками') and optionally their materials when 'base' is provided. It distinguishes itself from sibling tools by detailing the conditional output scope, making the purpose specific and non-tautological.

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 by explaining the behavior with and without the 'base' parameter, effectively telling the agent when to expect different result sets. It does not explicitly name alternative tools or exclusions, but the context is sufficient for choosing this tool over knowledge_search or knowledge_save.

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