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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description's job is to add context — and it does: 10-minute result caching with an instruction not to re-call, required AMOCRM_DOMAIN/AMOCRM_TOKEN credentials, and an automatic 7 req/s rate-limit compliance note. None of this is derivable from the annotations or the empty schema.

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

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

Content is front-loaded: purpose first, then the 'call this first' directive, then cache/credentials/rate-limit operational notes, ending with the read-only confirmation. Every sentence carries distinct, non-redundant information despite the density.

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 and no input parameters, the description fully carries the burden: it describes the return shape (account fields, user fields, pipeline/status fields), when to call it, the auth requirements, caching behavior, and rate-limit handling. An agent has everything needed to invoke and consume it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. The description compensates somewhat by naming the field groups returned, but there is no parameter syntax to explain.

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

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

States a concrete resource (amoCRM/Kommo account directory) and enumerates exactly what it returns: account (name, subdomain, currency), users (id, name, email, active), and pipelines with statuses (id, name, type open/won/lost). This is specific enough that an agent can distinguish it from every sibling, none of which are account-level reference lookups.

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

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

Explicitly instructs 'Вызывайте первым в разговоре' and justifies it: pipeline/stage/manager ids are required for the filters of crm_search_leads, crm_tasks, crm_pipeline_report and for writes via crm_create_lead/crm_update_lead. It names both the context in which to call it and the downstream tools it feeds, so no inference is required.

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 (which only declare the mutation/idempotency profile), the description discloses the credential requirements (AMOCRM_DOMAIN, AMOCRM_TOKEN), the auto-respected 7 req/s amoCRM rate limit, the return value (note_id), and an explicit consent workflow for a write operation. These are substantive behavioral facts the annotations do not carry.

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?

Purpose is front-loaded in the first sentence and every sentence carries information, but the description runs to five dense clauses where examples like the call-summary list are somewhat expendable. Slightly long, though no sentence is pure 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 correctly supplies the return value; for a mutation tool with auth and rate-limit constraints it covers credentials, throttling, consent, and sibling routing. An agent has everything needed 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 description coverage is 100%, and the schema itself documents text, entity_id, and the entity_type enum. The description merely echoes the entity kinds already in the enum and adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource — adds a plain text note to the feed of a deal, contact, or company — and immediately distinguishes itself from siblings by naming crm_update_lead (field changes) and crm_create_task (tasks). An agent can tell exactly what this tool is and is not.

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

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

It states what the tool is for (call summaries, agreements, comments), what it is not for, and names the two alternative tools with the condition that selects each. Nothing about when to route here versus elsewhere is left 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 only flag readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds what they don't: the result becomes visible in the deal feed, the tool returns «completed», it requires AMOCRM_DOMAIN and AMOCRM_TOKEN, and the amoCRM 7 req/s limit is handled automatically. It further instructs the agent to show the user what will be written and obtain consent before mutating CRM data.

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

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

Front-loaded with the core action, then id sourcing, the closure caveat, return value, auth/rate-limit facts, and the consent requirement — every clause carries information. It is slightly dense with several trailing operational clauses that could be tightened, keeping it just short of 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?

There is no output schema, so the description correctly supplies the return value («Возвращает completed») plus the auth prerequisites, rate-limit behavior, and the consent requirement for a mutation. Nothing an agent needs to invoke this correctly against the sibling set 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%, so the two parameters are already documented there and the baseline is 3. The description still adds value by specifying where the id must come from and by exemplifying the result text («Дозвонился, отправил КП»), which clarifies the expected content of the free-text result field.

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 immediately scopes it with an output example and the side effect («результат виден в ленте сделки»). An agent can distinguish it from siblings like crm_create_task or crm_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?

Names the sources for the required id («id берите из crm_tasks или crm_get_lead») and states an explicit exclusion («Закрытую задачу этим инструментом не открыть»), so both when-to-use and when-not-to-use are covered. It also routes the agent toward a confirmation step before writing.

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, it discloses required environment variables (AMOCRM_DOMAIN, AMOCRM_TOKEN), automatic amoCRM rate-limit compliance, contact-merging behavior with merged_with_existing=true, and the need to show the user what will be written and obtain consent. These are substantial operational details not captured by the annotations.

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

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

The description is dense and somewhat run-on, but it is front-loaded with the core create action and each sentence carries relevant information. For an 11-parameter mutation tool with no output schema, the length is largely justified.

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 complexity, high schema coverage, and absence of an output schema, the description is complete: it covers creation scope, defaults, auth requirements, rate limits, merge behavior, return identifiers, alternatives, and user-consent expectations.

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 still adds useful semantics: pipeline_id/status_id default to the first stage of the main pipeline, IDs come from crm_account, and the note parameter adds a note. It does not add much beyond schema for every parameter, so 4 is appropriate.

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

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

The description states a specific verb and resource: creates a deal together with a new contact, company, and tags, and optionally adds a note. It also names sibling tools and distinguishes this creation tool from crm_update_lead and crm_find_contact, so an agent can route correctly.

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 to use crm_update_lead for modifying an existing deal and to check crm_find_contact first to avoid duplicates. It also explains the default pipeline/status behavior when pipeline_id/status_id are omitted.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, but the description adds real behavior: date-only input resolves to 18:00 server timezone, ISO with zone for exact time, returns task_id and due, required env vars AMOCRM_DOMAIN/AMOCRM_TOKEN, the amoCRM 7 req/s limit handled automatically, and the obligation to confirm the write with the user.

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, then grouped details (date semantics, return values, sibling routing, auth/rate limits, consent). Every sentence carries information, though the definition is dense and could be slightly tighter.

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, yet the description names the returned fields (task_id, due). With 6 params fully schema-documented, annotations covering safety, and auth/rate-limit/consent behavior disclosed, an agent has everything 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the 18:00 default for a date-only due value and the ISO-with-timezone format are not documented in the schema itself. This genuinely clarifies the most error-prone parameter.

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

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

States a specific verb (Ставит) plus resource (задачу) and enumerates the full scope: task type (звонок/встреча), the three binding targets or none, and the responsible party. It is immediately distinguishable from crm_complete_task and crm_tasks, which it names.

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

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

Explicitly routes the agent to siblings: 'Закрыть задачу — crm_complete_task, посмотреть задачи — crm_tasks', and states the consent requirement before mutating CRM data. It does not state exclusions (e.g. when not to create a task), so it falls just short of 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new operational context: required credentials (AMOCRM_DOMAIN, AMOCRM_TOKEN) and that the amoCRM 7 req/s limit is handled automatically. It restates read-only, but the auth and rate-limit disclosures are real value 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?

Front-loaded with purpose, then return fields, then routing, then requirements — a logical order with no filler. It is dense but every clause (returned fields, next step, auth, rate limit) 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?

No output schema exists, and the description compensates by enumerating the returned contact fields (id, name, phones, emails, responsible, lead_ids, company_ids, custom_fields). Combined with auth and rate-limit notes, an agent has everything 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?

Schema coverage is 100%, so the schema already documents query and limit. The description adds a nuance not in the schema — that phone matching accepts any format — giving marginal meaning beyond the structured fields.

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 ('Ищет контакты') and enumerates the searchable fields (имя, телефон, e-mail), including the useful 'в любом формате' normalization detail. It also names the sibling it is not (crm_search_leads for deals), so an agent can distinguish it without opening 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?

Gives concrete when-to-use context ('при входящем звонке или письме') and explicit routing: use crm_get_lead to open the related deal, and crm_search_leads to search deals themselves. Both the trigger and the alternatives are named.

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, yet the description adds real context: it performs 3–5 API calls, requires AMOCRM_DOMAIN and AMOCRM_TOKEN, auto-handles the amoCRM 7 req/s limit, and returns an error for a non-existent id. The only weak point is the redundant 'Только чтение' repetition of readOnlyHint.

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 returned payload, then usage, then operational constraints. Dense but every sentence carries information; the only minor waste is restating read-only, which annotations already cover.

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

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

With no output schema, the description carries the return-value burden and does so fully (field-level detail for contacts, company, tasks, notes). Error behavior, auth, and rate-limit handling are all covered, so an agent has everything needed 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 50% – id is documented in the schema and notes_limit is not. The description mentions 'последние notes', implicitly signalling that the notes count is bounded, but never names or bounds notes_limit, so it only partially compensates for the schema gap. 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 ('полная карточка одной сделки по id') and explicitly enumerates the added payload (contacts, company, open_tasks, notes) over the sibling crm_search_leads. An agent can distinguish it from the search tool without opening the schema.

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

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

Gives explicit when-to-use ('перед звонком или письмом клиенту, чтобы понять историю') and tells the agent exactly where to source the id ('из crm_search_leads или crm_find_contact'). Alternatives and their selection conditions are named.

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 annotations by disclosing the truncation contract (loads up to max_leads, truncated=true when hit), latency risk on large periods ('занять десятки секунд'), required env vars AMOCRM_DOMAIN/AMOCRM_TOKEN, and that the 7 req/s amoCRM limit is handled automatically. This is exactly the operational context annotations cannot carry.

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?

Single dense paragraph but strictly front-loaded: purpose and output fields first, usage and alternatives next, operational caveats last. Every clause carries distinct information 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?

No output schema exists, yet the description enumerates the return payload fields so an agent knows what it will receive, and it covers the safety, auth, rate-limit and truncation dimensions needed to invoke and interpret a 4-param analytics tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: max_leads is tied to the truncated flag, and the period semantics (default 30 days) are framed as a window over lead creation dates, which clarifies created_from/created_to intent. Pipeline defaulting to the primary funnel is also restated usefully.

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

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

Names a specific resource (sales analytics over one pipeline for leads created in a period) and enumerates the exact result fields (stages, won/lost/open, win_rate_pct, avg_deal, avg_cycle_days, managers ranking). An agent can distinguish it from crm_search_leads and crm_stale_leads, which the description explicitly points to for other needs.

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 when-to-use triggers ('как идут продажи', 'кто лучше закрывает', comparing months) plus named alternatives with their selecting condition: crm_search_leads for concrete deals, crm_stale_leads for problematic ones. Nothing is left 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?

Beyond the annotations (readOnly/idempotent/non-destructive/openWorld), the description discloses the return shape and sort order (fresh changes first), a hard error condition (status_id only valid with pipeline_id), required credentials (AMOCRM_DOMAIN, AMOCRM_TOKEN), and that the amoCRM 7 req/s limit is handled automatically.

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 purpose and return shape, then alternatives, then constraints and auth. Dense but efficient; the one small redundancy is restating the status_id+pipeline_id rule that the schema already carries.

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, and the description fully covers the return payload (count, total_budget, leads with their fields and ordering), the prerequisites, and the failure mode. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'query' spans name/phone/e-mail/custom field values (the schema only says 'Поисковая строка'), and it restates the status_id/pipeline_id dependency that the schema also encodes. Marginal gain over the schema is modest, hence 4 rather than 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 ('Ищет сделки') and enumerates the searchable fields (name, phone, e-mail, field values) plus the filter set. It also names the sibling tools it is not, so an agent can separate it from crm_get_lead and crm_pipeline_report 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?

Explicitly routes the agent: this tool to find a deal or a list of deals, crm_get_lead for the full card with contacts and tasks, crm_pipeline_report for aggregated analytics, crm_stale_leads for stuck deals. When-to-use and alternatives are both stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: it scans up to 3000 open deals, requires AMOCRM_DOMAIN and AMOCRM_TOKEN, and self-throttles to amoCRM's 7 req/s limit. The only gap is no mention of what happens when the 3000-deal cap truncates results.

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 at-risk definition and return shape, then routing, then operational limits. Dense and information-rich, though the single block could be broken up slightly for scanability.

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 returned fields (count, at_risk_budget, leads with id, name, price, stage, pipeline, responsible, idle_days, reasons). Auth requirements, scan cap and rate-limit behavior are all covered, so an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented, including days, limit, pipeline_id, include_no_task and responsible_user_id. The description reinforces the days threshold and result ordering, but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource (returns at-risk open deals) and precisely defines the inclusion criteria: unchanged for days+, and either no scheduled task or an overdue task. It also names the fields returned and the ordering, so an agent knows exactly what it gets.

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

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

Explicitly states when to use it ('что зависло', daily funnel review, manager reminders) and routes to named alternatives: crm_pipeline_report for the overall picture and crm_tasks for tasks. No inference required.

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

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

Annotations already cover the read-only/idempotent safety profile, so the bar is lower, yet the description still adds credential prerequisites (AMOCRM_DOMAIN, AMOCRM_TOKEN), automatic rate-limit compliance (7 req/s), and result ordering ('ближайшие сроки первыми'). That is behavioral context the annotations do not convey.

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

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

One dense but well-ordered paragraph: scope semantics first, then return shape, then use cases and alternatives, then prerequisites. Every clause carries information, though the sentence count is low and the block is longer than strictly needed.

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?

Despite having no output schema, the description enumerates the returned fields (count, tasks with id, text, due, overdue, responsible, entity_type, entity_id), the ordering, auth requirements and rate limits. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit, scope, lead_id and responsible_user_id are already documented in the schema with the same wording. The description echoes the scope enum verbatim and only loosely maps 'фильтры по ответственному и по сделке' onto the two filter params, adding little beyond the structured fields.

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 (незавершённые задачи) and scope semantics, and explicitly routes sibling operations ('поставить задачу — crm_create_task, закрыть — crm_complete_task'). An agent can distinguish this from every other crm_* tool 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?

Gives concrete use cases ('что просрочено у менеджера', планирование дня) and names the alternative tools for the adjacent write operations. When-to-use and when-to-use-something-else are both 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), yet the description adds real behavioral context beyond them: tags replace the whole set, required env prerequisites (AMOCRM_DOMAIN/AMOCRM_TOKEN), automatic amoCRM rate-limiting at 7 req/s, the returned fields (updated and changed), and the instruction to obtain user consent before writing. This is exactly the extra context annotations cannot convey.

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

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

Dense but front-loaded: the partial-update rule leads, then field semantics, then return values, then dependencies and siblings, then the consent warning. Every sentence carries information, though the bulk of clauses makes it heavier than an ideal two-liner.

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

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

For a mutation tool with no output schema, the description covers what the agent needs: partial-update contract, field migration rules, the shape of the response (updated/changed), auth/rate-limit constraints, error condition, and consent obligation. No critical gap remains.

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 documents each field, but the description still adds cross-field semantics the schema does not encode: pipeline_id is required when switching pipelines, and status_id 142/143 encode won/lost. It largely restates the tags and custom_fields formats already in the schema, so it earns a 4 rather than 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?

The description opens with a specific verb+resource (частично обновляет существующую сделку) and immediately scopes the operation (только поля, которые меняются). It then explicitly routes to siblings crm_create_lead for creation and crm_add_note for notes, so an agent can separate it from adjacent tools without inspecting 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?

Explicit when-to-use is given (pass only changed fields) along with a failure condition (без изменяемых полей — ошибка) and named alternatives for the two adjacent operations. The migration semantics for status_id/pipeline_id and the consent requirement give the agent a clear decision procedure.

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