This server lets an AI assistant interact with Bitrix24 CRM and collaboration tools through 12 MCP tools.
Deals: list deals with filters by stage/responsible/sort, get deal details, create deals with title/amount/stage/contacts, and update deal fields.
Contacts: list contacts filtered by name, phone, or email, and create contacts with name, phone, email, and linked company.
Tasks: list tasks by status/responsible/group, create tasks with title/description/deadline/priority, and mark tasks as completed.
Users: list employees with optional filters by active status and department.
Files: upload base64-encoded files to a specified Bitrix24 disk folder.
Messaging: send instant messages via Bitrix24 IM to a user or chat using BB-code.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@theyahia/bitrix24-mcp List all contacts with email containing '@gmail.com'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Если вы искали, как подключить Битрикс24 к ИИ-ассистенту, спрашивать про сделки и задачи обычными словами или заводить карточки не открывая интерфейс — это оно. 12 инструментов для сделок, контактов, задач, пользователей, файлов и сообщений. Подключение — через входящий вебхук Bitrix24, без OAuth-приложения и без программирования.
Часть серии WWmcp от @theYahia.
В Битрикс24 откройте Приложения → Разработчикам → Другое → Входящий вебхук
Создайте вебхук с правами: crm, task, user, disk, im
Скопируйте полный URL вебхука
Related MCP server: Bitrix24 MCP Server
{
"mcpServers": {
"bitrix24": {
"command": "npx",
"args": ["-y", "@theyahia/bitrix24-mcp"],
"env": {
"BITRIX24_WEBHOOK_URL": "https://your-company.bitrix24.ru/rest/1/your-webhook-key/"
}
}
}
}claude mcp add bitrix24 -e BITRIX24_WEBHOOK_URL=https://your.bitrix24.ru/rest/1/key/ -- npx -y @theyahia/bitrix24-mcpИнструмент | Описание |
| Список сделок CRM с фильтрами по стадии, ответственному и сортировкой |
| Получить одну сделку по ID |
| Создать сделку с названием, суммой, стадией и контактами |
| Обновить поля сделки |
| Список контактов с фильтрами по имени, телефону и e-mail |
| Создать контакт с именем, телефоном и e-mail |
| Список задач с фильтрами по статусу, ответственному и группе |
| Создать задачу с названием, дедлайном и приоритетом |
| Отметить задачу выполненной |
| Список сотрудников с фильтрами по активности и отделу |
| Загрузить файл на Битрикс24.Диск |
| Отправить сообщение в чат сотруднику или в группу |
Покажи все открытые сделки в Битрикс24
Создай сделку «Редизайн сайта» на 500000 рублей
Выведи все контакты с почтой на «@gmail.com»
Поставь задачу «Подготовить презентацию» сотруднику 5, дедлайн завтра
Заверши задачу 123
Кто из сотрудников активен в отделе 2?
Отправь сообщение сотруднику 1: «Встреча через 15 минут»Переменная | Обяз. | Описание |
| да | Полный URL вебхука Битрикс24 вместе с ключом авторизации |
MIT
Mark a Bitrix24 task as completed by task ID.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task ID to complete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the state change ('mark as completed') but does not mention whether the action is reversible, whether permissions are required, what side effects occur, or what return value to expect. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action and the parameter with no extraneous words. Every word earns its place, and the size is appropriate for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, but the absence of behavioral transparency and usage guidance leaves some gaps for an agent. It is adequate for making the basic call, but not fully complete regarding what happens after the call or what constraints apply.
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 fully covers the only parameter with a description ('Task ID to complete'), and the description merely restates that the task is identified by ID. No additional semantic meaning is added beyond what the schema already provides, 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 uses a specific verb ('Mark... as completed') and resource ('Bitrix24 task'), and specifies the identifier method ('by task ID'). This clearly distinguishes it from sibling tools like list_tasks and create_task, leaving no ambiguity about what the tool does.
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 usage context is implied: call it when you have a task ID and want to complete the task. However, there is no explicit guidance on prerequisites, when not to use, or alternatives. While no direct completion alternative exists among siblings, the description provides no exclusionary or situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new CRM contact with name, last name, phone, and email.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | First name | |
| No | Email address | ||
| phone | No | Phone number | |
| last_name | Yes | Last name | |
| company_id | No | Company ID to link | |
| assigned_by_id | No | Responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses only that a contact is created, but omits required field behavior, any constraints, permissions, duplicate handling, or what the response contains. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no filler. It loses a point because it lists only four fields while the schema exposes six, and it front-loads a fairly obvious phrase rather than adding distinguishing constraints.
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 six parameters, no output schema, and no annotations, the description is too sparse. It fails to note that name and last_name are required, does not mention company_id or assigned_by_id, and gives no sense of the result or side effects.
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 parameters. The description only rehearses a subset of fields without adding any extra meaning, such as format, constraints, or relationships.
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 ('Create'), a resource ('CRM contact'), and lists the main fields involved. This clearly distinguishes it from sibling tools like list_contacts, create_deal, and create_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The usage context is only implied by the word 'Create' and the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new CRM deal in Bitrix24 with title, amount, stage, and linked contact/company.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Deal title | |
| comments | No | Comments | |
| stage_id | No | Stage ID (e.g. NEW, PREPARATION, PREPAYMENT_INVOICE) | NEW |
| company_id | No | Company ID to link | |
| contact_id | No | Contact ID to link | |
| currency_id | No | Currency code | RUB |
| opportunity | No | Deal amount | |
| assigned_by_id | No | Responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing side effects. It clearly states that a new deal is created and that contact/company linking is part of the operation, but it omits details such as the return format, permission requirements, validation behavior for linked entities, and what happens on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the operation, platform, resource, and key fields with no filler or redundancy. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a straightforward create operation: it names the action and the involved fields, and the schema fully documents parameters. However, because there is no output schema and no annotations, the description lacks return-value information and any mention of prerequisites or failure conditions, which are useful for robust agent follow-up.
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 every parameter with types and defaults. The description's mention of title, amount, stage, and linked contact/company restates schema content without adding new semantic nuance.
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 ('Create') and resource ('CRM deal in Bitrix24'), and enumerates the key distinguishing fields: title, amount, stage, and linked contact/company. This clearly separates it from sibling tools like create_contact, create_task, list_deals, and update_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?
The phrase 'Create a new CRM deal' implies the intended use case — creating a new deal rather than listing or updating one. However, the description does not explicitly mention when to prefer this tool over alternatives, nor does it state prerequisites such as the need for existing contacts or companies to link.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task in Bitrix24 with title, description, responsible user, and deadline.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Task title | |
| deadline | No | Deadline in ISO format (e.g. 2025-12-31T23:59:59+03:00) | |
| group_id | No | Project/group ID | |
| priority | No | Priority: 0=low, 1=normal, 2=high | 1 |
| description | No | Task description | |
| responsible_id | Yes | Responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It only states that a task is created; it does not disclose return values, permissions, side effects, or behavior for missing optional fields. This is minimal for a mutating 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?
One front-loaded sentence with no filler. The action, system, and primary fields are clear in a single line.
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 create tool, the description plus fully documented schema is minimally viable for invocation. However, with no output schema and no annotations, it leaves return behavior and prerequisites unstated, so it is not fully 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 the baseline applies. The description restates title, description, responsible user, and deadline but adds no meaning beyond the schema, and it omits group_id and priority.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Create') and resource ('new task in Bitrix24'), and lists core fields. It is clearly distinguishable from siblings like create_deal or complete_task by the resource and verb, though it does not explicitly name an 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?
There is no guidance about when to use this tool rather than list_tasks, complete_task, or create_deal, and no exclusions or prerequisites are given. The intended use is only implied by the verb and object.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single CRM deal by ID with all fields.
| Name | Required | Description | Default |
|---|---|---|---|
| deal_id | Yes | Deal ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Get' clearly implies a read operation and 'with all fields' indicates the response scope, but the description does not mention error behavior, missing-ID handling, authentication needs, or rate limits. For a simple fetch tool this is acceptable but not rich.
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 wasted words. The core action, resource type, identifier method, and field scope are all front-loaded and immediately parseable by an agent.
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 low complexity—one required parameter, no output schema, no nested objects—the description covers the essentials: what it fetches and what is returned. It could additionally mention behavior for non-existent deals, but the current description is largely complete for selecting and invoking 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 fully documents the only parameter with 'Deal ID to retrieve', and schema description coverage is 100%. The description adds no new parameter-level meaning beyond confirming that the tool operates by deal ID, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Get'), the specific resource ('a single CRM deal'), and the identifier ('by ID'). It also specifies the return scope ('all fields'), which distinguishes it from list_deals and other deal operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when you need one specific deal by its ID rather than a list or a mutation. It doesn't explicitly name alternatives or exclusions, but the single-vs-list distinction is evident from the wording and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List CRM contacts from Bitrix24 with optional filters by name, phone, or email.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Offset for pagination (multiples of 50) | |
| select | No | Fields to return | |
| filter_name | No | Filter by name (partial match) | |
| filter_email | No | Filter by email | |
| filter_phone | No | Filter by phone number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. 'List' signals a read-only operation and the mention of filters adds behavior, but the description does not disclose pagination behavior, default result size, or authentication requirements. The behavior is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveys the verb, resource, source system, and optional filters with zero fluff. The description is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list tool with a fully documented schema, the description is nearly complete. The only gaps are lack of explicit notes on pagination or return structure, which are minor because the schema defines 'start' and the tool name itself implies the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description echoes the filter parameters (name, phone, email) but adds no meaning beyond the schema; start and select are left to the schema, which fully documents 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 opens with the specific verb 'List' and names the resource 'CRM contacts from Bitrix24', clearly distinguishing it from siblings like list_deals and create_contact. It also mentions the optional filters, making the tool's scope immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear functional context—retrieve contacts, optionally filtered by name/phone/email—but does not explicitly state when to prefer this tool over alternatives such as create_contact or list_deals. The usage is implied by the resource and verb rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List CRM deals from Bitrix24 with optional filters by stage, responsible user, and sort order.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | Sort order, e.g. {DATE_CREATE: 'DESC'} | |
| start | No | Offset for pagination (multiples of 50) | |
| select | No | Fields to return | |
| filter_stage_id | No | Filter by stage ID (e.g. NEW, WON, LOSE) | |
| filter_assigned_by_id | No | Filter by responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. The verb 'List' signals a read-only operation and the description mentions optional filtering and sorting behavior, but it does not disclose pagination defaults, return shape, or whether all deals are returned when no filters are supplied. These gaps are moderate but not critical for a simple list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It states the verb, resource, and key options efficiently, making the purpose immediately graspable.
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 five optional parameters fully documented in the schema, the description is largely sufficient. The main missing element is an explicit statement about the output format or default result set, but these are reasonably inferable from the list semantics and the select/pagination parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented structurally. The description only summarizes filter_stage_id, filter_assigned_by_id, and order without adding new semantic details 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 uses a specific verb ('List') and resource ('CRM deals from Bitrix24'), and names the key dimensions of filtering and sorting. This clearly differentiates it from siblings like get_deal (single deal) and create_deal/update_deal (mutations).
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 this tool: when a list of deals is needed, as opposed to a single deal via get_deal. It does not explicitly name alternatives or exclusion conditions, but the context is clear and no misleading guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks from Bitrix24 with optional filters by status, responsible user, and group.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Offset for pagination | |
| filter_status | No | Filter by status (e.g. 2=pending, 3=in progress, 5=completed) | |
| filter_group_id | No | Filter by project/group ID | |
| filter_responsible_id | No | Filter by responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only paraphrases the schema's filter parameters and does not mention the pagination behavior implied by the 'start' parameter, default limits, error cases, or the read-only nature beyond the conventional meaning of 'List'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 13 words, front-loaded with the action and resource, with zero filler or redundancy. Every phrase 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?
There is no output schema and no annotations, yet the description does not state the return format, pagination behavior, or any caveats about limited results. An agent would not learn that only a page of tasks may be returned or what fields a task object contains.
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 adds minor human-readable categorization of filters (status, responsible user, group) but does not clarify the 'start' parameter or provide examples. This is acceptable 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 operation (List), the resource (tasks), and the source system (Bitrix24), while naming the specific optional filter dimensions. This distinguishes it from sibling tools like list_deals/list_contacts (different resources) and create_task/complete_task (different actions).
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 phrase 'with optional filters' communicates that the tool accepts conditions but no argument is required, and the resource name implies it is for retrieving tasks. However, the description never explicitly states when to prefer this tool over alternatives or when not to use it, leaving usage to be inferred from the tool's name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Bitrix24 users with optional filters by active status and department.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Offset for pagination | |
| filter_active | No | Filter by active status | |
| filter_department_id | No | Filter by department ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry behavioral disclosure. It conveys that this is a read-only list operation with optional filters, but it does not disclose pagination defaults, response shape, or the meaning of omitted filters. The lack of destructive behavior is clear, but deeper behavior details are absent.
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, focused sentence with no filler. The core capability is front-loaded and every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers all parameters, but with no output schema and no annotations, an agent gets limited context about return values or behavior. The description is enough for basic invocation but leaves gaps around pagination behavior and expected 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 the input schema already documents all three parameters. The description only lightly restates the filter params and adds no new semantic detail 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 uses a specific verb ('List'), names the exact resource ('Bitrix24 users'), and specifies the optional filtering dimensions. It clearly distinguishes this tool from siblings like list_deals, list_contacts, and list_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the resource name: use this when you need to list users rather than deals, contacts, or tasks. However, it does not explicitly state when to choose this tool over alternatives or describe any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an instant message via Bitrix24 IM to a user or chat.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Message text (supports BB-code formatting) | |
| dialog_id | Yes | Dialog ID: user ID (e.g. '1') or chat ID (e.g. 'chat123') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It indicates a send/mutation operation but does not mention permissions, side effects, delivery guarantees, or what happens on failure. The agent is left without important behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. Every phrase ('Send', 'instant message', 'via Bitix24 IM', 'to a user or chat') contributes to understanding the tool's purpose. It is appropriately front-loaded with the verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two well-documented parameters, the description covers the core operation adequately. However, there is no output schema and no mention of return values, error behavior, or whether the message is delivered to an existing dialog, leaving moderate gaps for an agent relying solely on this definition.
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 both dialog_id and message already fully documented in the input schema. The tool description adds no parameter-level detail beyond what the schema provides, 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 ('Send') and resource ('instant message via Bitrix24 IM') and clearly states the recipient scope ('to a user or chat'). It is distinct from all sibling tools, none of which handle messaging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool is appropriate: sending an instant message through Bitrix24 IM. It does not explicitly name alternatives or exclusions, but no sibling tool performs messaging, so the usage context is effectively unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing CRM deal fields: title, stage, amount, contacts, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New deal title | |
| deal_id | Yes | Deal ID to update | |
| comments | No | New comments | |
| stage_id | No | New stage ID | |
| company_id | No | New company ID | |
| contact_id | No | New contact ID | |
| opportunity | No | New deal amount | |
| assigned_by_id | No | New responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It simply says 'Update' without explaining whether this is a partial update (only provided fields change) or a full replace, whether unspecified fields are preserved or reset, if authorization is required, or what the response looks like. This leaves significant behavioral ambiguity for a mutating 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 a single front-loaded sentence that gets to the point immediately. However, the trailing 'etc.' is vague and slightly weakens the specificity of the field list. It earns its place but could have been omitted or replaced with a more precise list.
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 8 parameters, no annotations, and no output schema, the description is somewhat thin. The schema covers parameter documentation, but the description does not address update semantics, which fields are cleared versus overwritten, or any side effects. It is minimally adequate for an agent to infer the core action, but gaps remain for a robust invocation decision.
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 mentions 'title, stage, amount, contacts' which roughly maps to schema properties, but the schema already describes each parameter more precisely (e.g., 'opportunity' as 'New deal amount'). The description adds no substantive semantic meaning beyond restating or loosely paraphrasing what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update'), a clear resource ('existing CRM deal'), and enumerates key fields. The word 'existing' implicitly distinguishes it from create_deal, and the update action separates it from get_deal and list_deals. This gives an agent enough information to know exactly what the tool does.
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 for modifying deals that already exist, but it never explicitly states when to use this tool over create_deal or get_deal, nor does it mention any prerequisites such as needing a valid deal_id. There is no exclusionary guidance or naming of sibling alternatives, so usage context is only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to Bitrix24 disk folder (base64-encoded content).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Base64-encoded file content | |
| filename | Yes | Name of the file to upload | |
| folder_id | Yes | Target folder ID in Bitrix24 disk |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the base64 encoding requirement but does not disclose overwrite behavior, permission requirements, file size limits, or response shape, which are relevant for a mutating upload operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It captures the essential operation and the critical encoding detail while remaining compact.
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 request parameters are fully documented by the schema, making the invocation inputs clear. However, the absence of an output schema and the lack of behavioral context such as overwrite semantics or access requirements leave noticeable gaps for an upload 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 coverage is 100% with descriptive text for all three parameters, so the baseline is 3. The description only restates the base64 content requirement already present in the content parameter description, adding no new semantic 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 states a specific verb and resource: 'Upload a file to Bitrix24 disk folder.' This clearly differentiates the tool from all sibling tools, which deal with deals, contacts, tasks, users, and messages rather than file uploads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the operation name and resource, but the description provides no explicit when-to-use guidance or exclusions. There are no file-related sibling tools to confuse it with, so the implied context is sufficient but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.0.1complete_taskcreate_contactcreate_dealcreate_taskget_deallist_contactslist_dealslist_taskslist_userssend_messageupdate_dealupload_fileScored across 12 tools
Each tool targets a clearly distinct resource and action, such as list_deals vs get_deal or create_task vs complete_task. No two tools appear to overlap in purpose.
All tool names follow a consistent verb_noun snake_case pattern, e.g. list_deals, create_deal, update_deal, upload_file, send_message. This makes the API surface predictable.
Twelve tools is a reasonable, focused set for a Bitrix24 integration covering deals, contacts, tasks, users, files, and messaging. Each tool earns its place without bloat.
Core workflows for deals, contacts, and tasks are present, but there are notable gaps: contacts lack update/delete and get-by-id, tasks lack get/update/delete, and deals lack delete. These missing operations could force agents into workarounds.
Operate Obriym CRM from your AI assistant: leads, deals, orders, catalog, stock, marketplaces.
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
