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

Goes well beyond the annotations: discloses the return value (comment_id), that every call appends a new comment, that it mutates Bitrix24 data and requires showing the user the text and getting consent, the required BITRIX24_WEBHOOK_URL with crm/task/user scopes, and the auto-enforced 2 req/s rate limit. Annotations (readOnly=false, idempotent=false, destructive=false) are consistent with this text.

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

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

Front-loads purpose and scope, then behavior, then auth/limit requirements — a logical order with little waste. Some content (the consent reminder, the repeat of the append behavior) is boilerplate-adjacent, which keeps it from a 5.

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

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

For a mutating tool with no output schema, the description supplies everything an agent needs: what it does, which entities it targets, the return value, the consent requirement, and the auth/rate-limit constraints. 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 67%: text and entity_id carry inline descriptions and entity_type carries an enum, so the schema does most of the work. The description restates the entity types but adds no format, length, or ID-resolution guidance beyond what the schema already provides.

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

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

States a specific verb and resource (adds a comment to the timeline) and enumerates the exact entity types it accepts: deal, lead, contact, company. No sibling tool covers comments, so the agent can distinguish it immediately.

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

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

Gives concrete usage context by naming typical content — call results, agreements, notes — which tells the agent when this tool is appropriate. It does not state explicit exclusions or prerequisites for choosing it over other record-mutating tools, so it stops short of a 5.

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

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

Goes well beyond the annotations: it discloses the required auth (BITRIX24_WEBHOOK_URL with crm, task, user rights), the 2 req/s rate limit that is handled automatically, and the consent workflow for a write operation. It also confirms the idempotent no-op behavior, adding operational context the agent needs.

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

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

Front-loads the purpose, then layers idempotency, consent, auth and rate-limit notes in a tight set of sentences with little waste. Slightly dense, but every clause carries useful operational information.

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

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

For a two-param mutation tool with full schema coverage, annotations, and no output schema, the description covers purpose, idempotency, auth prerequisites, rate limiting, and consent. It is essentially complete for correct invocation, missing only an explicit note on what the completion returns.

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

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

Schema coverage is 100%, so both parameters (id, result) are already documented. The description mentions the result comment ('комментарием-результатом'), adding marginal reinforcement but no format or syntax detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Отмечает задачу выполненной') and clarifies the optional result comment. The agent can distinguish this completion action from siblings like b24_create_task and b24_tasks without opening any schema.

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

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

Explains the usage context (marking a task done, optionally with a result comment) and notes the idempotent behavior for already-closed tasks. However, it does not name any alternative tool or state explicit when-not conditions, leaving routing to inference.

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

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

Goes well beyond annotations (readOnly=false, destructive=false, idempotent=false): it discloses the return values (deal_id, contact_id), that data is modified and user consent must be obtained, the required BITRIX24_WEBHOOK_URL with crm/task/user rights, and that the 2 req/s limit is handled automatically. 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?

Front-loads what the tool does and the return shape, then stacks prerequisites, consent, and config requirements. Every sentence carries distinct information with no filler, appropriate for an 11-parameter mutation tool.

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

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

With no output schema, the description compensates by naming the returned IDs. Safety/consent, auth config, rate limits, and the funnel/stage dependency are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious relational semantics: contact_name + phone/email creates a new contact while contact_id links an existing one, and funnel/stage come from b24_portal. It does not spell out every field (amount, currency, responsible_id), but the cross-parameter logic is the valuable part.

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

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

States a specific verb+resource ('Создаёт сделку в Битрикс24') plus the secondary capability of optionally creating or linking a contact. This clearly distinguishes it from b24_create_lead and b24_update_deal, which are the nearest 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?

Explicitly prescribes prerequisites and alternatives: pull funnel/stage from b24_portal (with the consequence of omitting them — first stage of the general funnel), and check b24_find_contact first to avoid duplicate contacts. This is real when-to-use/when-not guidance, not implied.

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

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

Annotations already declare a non-idempotent, non-destructive, open-world write. The description goes beyond them by disclosing the required credential (BITRIX24_WEBHOOK_URL with crm/task/user rights), that the 2 req/s limit is auto-handled, the consent obligation, and the return value (lead_id). It stops short of warning that repeat calls create duplicate leads, which is the main residual risk.

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

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

Front-loaded with verb and resource, then routing, then operational caveats. Every clause carries information, though the credential and consent sentences make it denser than strictly necessary for a create tool.

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

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

No output schema exists, so the description correctly supplies the return value (lead_id). For an 8-parameter mutation tool it covers routing, auth, consent, and rate limiting; only the semantics of the undocumented responsible_id parameter remain unaddressed.

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

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

Schema description coverage is only 50%, but the description names seven of the eight parameters (title, name, phone, e-mail, amount, source, comment) — including several the schema leaves undocumented, such as phone, email, and comment. It adds no format or constraint detail (e.g. source_id vocabulary, responsible_id semantics), so it compensates only partially.

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

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

States a specific verb and resource ('Создаёт лид (входящую заявку) в Битрикс24') and enumerates the fields it writes, so the resource is unambiguous. It also names the sibling it is not ('для подтверждённой продажи — b24_create_deal'), letting an agent separate it from the deal tools without opening a schema.

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

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

Explicit routing rule: use for requests that are not yet qualified, use b24_create_deal for a confirmed sale. It also gives a procedural precondition (show the user what will be written and obtain consent), so both the when and the how are covered.

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

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

Adds substantial behavior beyond annotations: returns task_id, defaults the responsible to the webhook owner when unset, requires BITRIX24_WEBHOOK_URL with specific scopes (crm, task, user), and states the 2 req/s rate limit is handled automatically. These are meaningful operational facts the agent cannot infer from the write/non-idempotent hints 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?

Front-loaded with the core action and lead sentence follows logically through behavior, consent, and auth. Dense but each sentence earns its place; the consent instruction is slightly emphatic but operationally relevant.

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

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

For a 7-param create tool with no output schema, the description covers return value (task_id), defaults, auth, rate limits, and the mutation-safety requirement. Nothing essential 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?

With schema coverage at 86%, the baseline is 3, but the description adds real value: the default responsible_id behavior (webhook owner) is not documented in the schema, and the CRM-linking semantics of deal_id/lead_id/contact_id are explained.

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

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

States a specific verb and resource ('Ставит задачу сотруднику') and clarifies the optional CRM linking (deal/lead/contact). This clearly distinguishes it from siblings like b24_tasks (listing) and b24_complete_task (closing).

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

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

Gives clear context: which entity types it can attach to, the default assignee behavior, and a consent requirement before mutating data. It does not explicitly name when to prefer it over alternatives, but the use case is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful operational context beyond that: required BITRIX24_WEBHOOK_URL with specific crm/task/user rights, an auto-enforced 2 req/s rate limit, and the return shape. 'Только чтение' is slightly redundant with readOnlyHint but harmless.

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

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

Front-loaded with the core purpose, followed by matching behavior, return values, usage context, and auth/rate-limit notes — each sentence carries distinct information. It is dense but slightly verbose in bundling return fields inline.

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 correctly enumerates the returned contacts fields and the included open deals. Auth requirements and rate limiting are covered. An agent has what it needs to call and interpret results, though the undocumented 'limit' parameter leaves a small gap.

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

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

Schema coverage is only 50% (only 'query' has a schema description; 'limit' does not). The description compensates by clarifying query semantics — phone format is irrelevant, e-mail uses duplicate search, name matching is substring-based — well beyond what the schema states. It does not mention the 'limit' parameter, keeping it from a 5.

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

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

States a specific verb+resource (finds contacts) and goes further by describing exactly how each input type is matched: phone/e-mail via Bitrix24 duplicate search, name by substring. This distinguishes it from siblings like b24_search_deals and gives an agent enough to know it is a contact-lookup 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?

Explicitly says to use it 'перед звонком и перед созданием сделки' (before calling and before creating a deal), which gives clear invocation context. It does not name alternative tools or state when NOT to use it, 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?

The annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context on top: missing ids return a specific 'не найдена' error, the call fans out to 4–6 upstream requests, BITRIX24_WEBHOOK_URL with crm/task/user rights is required, and a 2 req/s limit is handled automatically. These are exactly the operational traits an agent cannot infer from structured fields.

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

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

Front-loaded with the return contents, then usage, error behavior, cost, prerequisites, and the read-only note. Dense but well ordered with no filler sentences; only slightly list-heavy.

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 compensates by enumerating the return payload field by field, plus error behavior and auth requirements. An agent has everything needed to invoke it correctly and anticipate the response shape.

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 'id' and 'comments_limit' are already documented in the schema, including the default of 10 and range 0–50. The description's mention of 'последние комментарии таймлайна' restates the schema text rather than adding format or behavior beyond it, so the baseline 3 applies.

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

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

States a specific verb+resource ('Полная карточка одной сделки по id') and enumerates exactly what the card contains beyond the sibling: comments, contacts, company, open_tasks with due date/overdue flag, and recent timeline comments. It explicitly positions itself relative to b24_search_deals, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit usage moment ('Используйте перед звонком или письмом клиенту') and names the two sources for the id (b24_search_deals, b24_find_contact). No when-not guidance (e.g., batch lookups, large lists), so it falls just short of the full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further: it names the required credential (BITRIX24_WEBHOOK_URL with crm, task, user scopes), states the rate limit (2 req/s) is handled automatically, and documents the 2000-deal ceiling. That is meaningful operational context beyond the annotation block.

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

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

A single dense paragraph, front-loaded with what the report returns, followed by scope, use cases, and operational constraints. Every clause carries information; it is slightly clause-heavy but with no filler.

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

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

There is no output schema, so the description carries the full burden of describing the return shape — and it does, field by field. Combined with auth, rate-limit, and volume-limit details, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantics by clarifying that dates filter on deal creation date and that omitting them returns all deals up to 2000 — behavior the schema alone does not convey. It does not explain category_id, though the schema field is self-describing.

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

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

States a specific resource (sales pipeline/summary report) and enumerates the exact output fields (deals, amount, open/won/lost, win_rate_pct, avg_cycle_days, stages, managers) plus the scoping rule (deals created in the period). An agent can distinguish it from b24_search_deals, b24_get_deal, and b24_stale_deals without opening any schema.

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

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

Gives explicit trigger questions ("как идут продажи в этом месяце", "кто из менеджеров лучше закрывает") and states the no-date fallback behavior (all deals, up to 2000). It lacks explicit when-not-to-use guidance or references to sibling tools, so it is clear on context but not on alternatives.

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

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

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing a 10-minute result cache, the required BITRIX24_WEBHOOK_URL credential with its crm/task/user scopes, and an automatically enforced 2 requests/second rate limit. These are exactly the operational facts an agent needs before invoking.

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?

Information density is high and front-loaded: returned shape first, then call-ordering rationale, then caching, credentials, and rate limits. It is a single dense paragraph, slightly long, but nearly every clause carries distinct operational value.

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

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

With no output schema, the description usefully sketches the return shape (users id/name/email/active; categories id/name/is_default; stages C1:NEW-style ids, name, open/won/lost semantics) and covers prerequisites, caching, and rate limiting. Nothing needed to call it correctly is absent.

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

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

The tool takes no parameters, so there is nothing for the description to clarify; the schema is empty and complete. Baseline 4 applies, with no param-level detail needed or missing.

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

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

The description states a specific resource — the Bitrix24 portal reference directory — and enumerates exactly what it returns: users, deal funnel categories, and stages with their id formats. It is clearly distinguishable from siblings like b24_search_deals or b24_get_deal, which consume rather than supply these ids.

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 says to call this first in a conversation and names the specific downstream tools whose filters depend on its ids (b24_search_deals, b24_tasks, b24_pipeline_report, b24_create_deal, b24_update_deal). The when-to-use condition and the reason are both given.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive=false, so the description goes further: it discloses the BITRIX24_WEBHOOK_URL requirement with specific scopes (crm, task, user), the automatic 2 req/s rate limit, and the sort order ('свежие изменения первыми'). That is real context beyond the annotations; only return pagination/total-count semantics is left unstated.

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

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

Dense but front-loaded: capability first, then return shape, then sibling routing, then prerequisites. Every clause carries information; it is slightly long for a single paragraph but has no filler.

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

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

With no output schema, the description compensates by enumerating the return payload (count, total_amount, deals with id/title/amount/category/stage/result/responsible/contact_id/dates) and the sort order, plus auth and rate-limit constraints. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description only maps human labels to parameter names (воронка→category_id, стадия→stage_id, период создания→created_from/created_to), which is a marginal restatement rather than added syntax or format guidance. Baseline 3 applies.

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

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

States a precise verb and resource ('Ищет сделки') plus the exact match/filter dimensions (substring in title, funnel, stage, responsible, result, creation period). It also names the sibling tools it is not (b24_get_deal, b24_pipeline_report, b24_stale_deals), so an agent can distinguish it without opening a schema.

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

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

Explicitly routes: full card with contact/tasks/comments goes to b24_get_deal, aggregate analytics to b24_pipeline_report, stalled deals to b24_stale_deals. Each alternative is paired with the condition that selects it, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new operational context: the required BITRIX24_WEBHOOK_URL with crm/task/user scopes, the 2 req/s rate limit being handled automatically, the return shape (count, amount_at_risk, deals with reasons) and the largest-first 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?

Front-loaded with the definition, then return shape, use cases, and prerequisites; each sentence carries information. Slightly list-dense but no filler.

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

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

With no output schema, the description does the heavy lifting by describing the return payload and ordering, plus auth and rate-limit prerequisites. The main gap is that the filtering parameters (category_id, responsible_id, limit) are never explained, so an agent may not realize it can scope the search.

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 only 25% — just 'days' is documented — and the description adds no semantics for limit, category_id, or responsible_id, which are undocumented in both places. It only echoes the 'days' meaning already present in the schema, so it fails to compensate for the coverage gap.

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

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

States a precise verb+resource: finds open deals that have not changed in more than N days and/or lack open tasks. Scope ('открытые сделки без движения'), the returned payload, and the business question it answers are all named, distinguishing it from b24_search_deals and b24_pipeline_report.

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

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

Gives clear usage context via the questions it answers ('что у нас зависло', 'где теряем деньги'), which tells the agent when this tool is the right call. It stops short of naming alternative siblings or stating when not to use it.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint. The description adds genuine value beyond them: the required BITRIX24_WEBHOOK_URL with crm/task/user scopes, and a rate limit of 2 req/s that is self-throttled. 'Только чтение' merely restates the annotation, so not a 5.

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

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

A dense but well front-loaded paragraph: purpose and scope first, then return shape, then usage examples, then auth/rate-limit caveats. Every clause carries information, though the compact Russian phrasing packs several concerns into one block.

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 no output schema, the description covers scope semantics, the response shape (count, by_responsible, tasks fields), auth prerequisites and rate limiting. An agent has everything needed to call it and interpret the 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 coverage is 0%, so the description must compensate, and it does for scope (all three enum values explained) and responsible_id (filter by responsible). It omits the limit parameter and its 100/500 bounds, leaving one of three params unexplained.

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

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

States a specific verb+resource (list of open tasks) and enumerates the scope semantics (overdue/today/open), which cleanly separates it from write siblings like b24_create_task and b24_complete_task. The example questions ('what's overdue for managers', 'what tasks for today') further pin down the intent.

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

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

Gives clear context for when to reach for it via the two example questions and the scope parameter. It stops short of naming alternatives or when-not conditions (e.g. vs b24_pipeline_report or b24_stale_deals), so it earns a 4 rather than 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?

Adds real operational context beyond the annotations: required BITRIX24_WEBHOOK_URL with crm/task/user rights, an auto-enforced rate limit, and a consent/write-preview requirement for a mutating call. The idempotency statement largely repeats idempotentHint=true, which keeps it from a 5.

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

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

Dense and front-loaded: mutation scope first, then constraints, then auth/limits. A couple of clauses (the idempotency note, the generic 'modifies data in Bitrix24') restate structured data and could be trimmed.

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

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

For a mutation tool with annotations but no output schema, the description covers auth, consent, rate limiting, error conditions, and partial-update semantics. Return-value behavior is unspecified, which is a minor gap given 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: only changed fields should be sent, and at least one field besides id is required or the call errors. The won/lost semantics pointer for stage_id is also useful non-schema context.

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

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

States a specific verb ('Меняет сделку') plus the exact mutable fields (stage, amount, responsible, title, description), and cross-references b24_portal for stage semantics. An agent can immediately tell this is the field-update tool rather than the sibling b24_create_deal.

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

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

Gives a clear usage rule ('pass only what changes; without fields — error') and a routing hint for closing deals via stage semantics from b24_portal. It does not explicitly distinguish when to prefer update vs create or get, but the context is otherwise unambiguous.

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