This server connects AI agents to Kommo CRM (amoCRM) v4, letting you manage leads, contacts, pipelines, stages, tasks, notes, tags, companies, custom fields, and chat messages from natural language.
Leads: list (filter by pipeline/stage), get, create, update, soft-delete, move stage, bulk update, and create a lead with contact + company in one call
Contacts: list/search by name, phone, or email; get, create, update
Pipelines & stages: list, create, rename pipelines; list, create, and update stages (name, sort, color)
Tags: list account tags, add to or remove from a lead (auto-creates missing tags)
Tasks: create follow-up tasks on leads, list tasks by lead or only overdue ones
Notes & chat: add internal notes to a lead's timeline; list chat templates; send outgoing chat messages to a lead's customer conversation
Companies: create and list companies
Custom fields: list field definitions for leads/contacts/companies; create fields (text, numeric, select, multiselect, date, url, checkbox) with enum options
Read-only tools are marked non-destructive; creates are non-idempotent; updates and tag/stage moves are repeatable; delete is soft and flagged destructive
Connect AI agents to your Kommo CRM (formerly amoCRM) using the Model Context Protocol. Manage leads, contacts, pipelines, tasks, notes, tags, and companies — all from natural language in Kiro or any MCP-compatible client.
Category | Tools |
Leads | list, get, create, update, delete, move stage, bulk update |
Contacts | list, get, create, update |
Pipelines | list, create, update |
Stages | list, create, update |
Tags | list, add, remove (auto-creates if needed) |
Tasks | create, list (with overdue filter) |
Notes | add note to lead |
Chat | list templates, send message |
Companies | create, list |
Custom Fields | list, create (text, select, multiselect, date, etc.) |
Advanced | create lead + contact + company in one call |
Related MCP server: Kommo MCP Server
Open Kiro → Powers panel → Add Custom Power
Select Import power from GitHub
Paste: https://github.com/depper-IA/kommo-kiro-power
Follow the onboarding steps when activated
Published on PyPI and the official MCP Registry. With uv installed, no clone is needed:
uvx --from kommo-kiro-power kommo-mcpOr install the one-click MCPB bundle (kommo-crm.mcpb) in Claude Desktop or any MCPB-compatible client. Bundle sources live in mcpb/. After changing tools, run python scripts/build_mcpb.py to sync the manifest, then pnpm dlx @anthropic-ai/mcpb pack mcpb kommo-crm.mcpb. For Smithery, python scripts/build_mcpb.py --smithery kommo-crm-smithery.mcpb builds a variant that also carries each tool's inputSchema.
Or from source:
git clone https://github.com/depper-IA/kommo-kiro-power.git
cd kommo-kiro-power
pip install -e .Go to Kommo → Settings → Integrations → Create integration
Copy the Client ID and Client Secret
Set http://localhost:8080/callback as the Redirect URI
cp .env.example .env
# Edit .env with your Kommo integration detailspython scripts/oauth_setup.pyA browser opens → sign in to Kommo → authorize → tokens saved automatically.
python -m kommo_mcp
# or
kommo-mcpOnce installed as a Power, the server activates automatically when you mention keywords like "kommo", "leads", "pipeline", "crm", or "contacts" in your conversation.
"Show me all leads in the Sales pipeline"
"Create a lead for Maria from TechCorp with phone +57 310 543 6281"
"Move lead 12345 to the Negotiation stage"
"List all overdue tasks"Add to your claude_desktop_config.json, opencode.json, or equivalent:
{
"mcpServers": {
"kommo": {
"command": "uvx",
"args": ["--from", "kommo-kiro-power", "kommo-mcp"],
"env": {
"KOMMO_SUBDOMAIN": "your_subdomain",
"KOMMO_ACCESS_TOKEN": "your_access_token"
}
}
}
}kommo-kiro-power/
├── plugin.json # Kiro Power manifest (Agent Plugins format)
├── POWER.md # Legacy Kiro Power metadata + onboarding
├── mcp.json # MCP server config for Kiro
├── server.json # Official MCP Registry metadata
├── skills/ # Workflow guides loaded on-demand
│ ├── leads-workflow/SKILL.md
│ ├── pipeline-management/SKILL.md
│ └── automation-patterns/SKILL.md
├── kommo_mcp/ # Python MCP server
│ ├── __main__.py # Entry point (stdio transport)
│ ├── mcp_server.py # Server + tool registration
│ ├── kommo_client.py # HTTP client (OAuth, retry, cache)
│ └── tools/ # Tool definitions + handlers
│ ├── leads.py
│ ├── contacts.py
│ └── pipelines.py
├── scripts/
│ └── oauth_setup.py # One-time OAuth authentication
├── pyproject.toml # Package config
└── requirements.txtCredentials read from .env — never hardcoded
.env is in .gitignore — never committed
OAuth v4 with automatic token refresh
Rate limiting: max 5 requests/second
Exponential backoff with jitter on failures
Response caching for pipelines/stages/fields (10 min TTL)
Python: 3.10, 3.11, 3.12, 3.13
MCP Clients: Kiro, Claude Desktop, OpenCode, Cursor, Codex
Kommo API: v4
The server runs locally on your machine and talks only to your own Kommo account API. It has no telemetry and sends no data to the author or any third party. See PRIVACY.md.
Bugs and feature requests: GitHub Issues
Email: sam@wilkiedevs.com
MIT
Add a plain text (common) note to a lead's timeline. Not idempotent: repeated calls add duplicate notes. Notes are internal and are not sent to the customer; use send_chat_message for that. Returns the created note.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Note content (plain text). | |
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. |
| Name | Required | Description |
|---|---|---|
| id | No | Note ID. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| params | No | Note parameters, e.g. {text}. |
| group_id | No | ID of the responsible user's group. |
| entity_id | No | ID of the entity the note is attached to. |
| note_type | No | Note type, e.g. common. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| responsible_user_id | No | ID of the responsible Kommo user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=false, so the description's best contribution is explaining the consequence: repeated calls add duplicate notes, which is actionable context the annotation alone doesn't convey. It also clarifies visibility (internal to the team, not sent to the customer). It doesn't mention auth/permission requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, all front-loaded: action first, then the idempotency caveat, then the visibility/alternative, then the return. Every sentence earns its place 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?
For a simple two-parameter create tool with 100% schema coverage, an output schema, and annotations covering safety/idempotency, the description supplies everything else an agent needs: artifact scope, routing to the sibling tool, and the duplicate-call caveat. Return values are covered by the output schema.
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 (lead_id, text) are already fully documented in the schema, including where to obtain lead_id. The description adds only 'plain text' for the text field, which is marginal. Baseline 3 is correct when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Add a plain text (common) note to a lead's timeline') and immediately distinguishes the artifact's nature (internal note vs customer-facing message). An agent can distinguish it from send_chat_message and create_task 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 the agent away from this tool when the intent is customer-facing: 'Notes are internal and are not sent to the customer; use send_chat_message for that.' That is a clear alternative with its selecting condition. It stops short of a 5 because it doesn't cover adjacent alternatives such as tasks or tags for other kinds of follow-up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a tag to a lead by name. Creates the tag if it does not exist. Reads the lead's current tags and writes back the full list plus the new one, so existing tags are kept. Safe to repeat. Returns the updated lead. See list_tags for existing tag names.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. | |
| tag_name | Yes | Exact tag name (case-sensitive), e.g. "vip". |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readOnly, idempotent and non-destructive, yet the description adds real behavioral detail beyond them: it upserts the tag if missing, and it performs a read-modify-write that preserves existing tags. It stops short of covering permissions, failure behavior or concurrency concerns.
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?
Six short sentences, front-loaded with the action and its upsert/preservation semantics, and every sentence carries distinct information (what it does, side effects, idempotency, return, sibling pointer).
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 an output schema present, return values need no elaboration, and the annotations cover the safety profile; the description supplies the remaining non-obvious semantics (upsert, full-list rewrite, idempotency). Nothing needed to invoke 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 both parameters are already documented in the schema (including case-sensitivity and how to obtain lead_id). The description only reinforces that the tag is addressed by name; 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 (attach) and resource (tag to a lead) plus the qualifying 'by name'. It is clearly distinguishable from remove_tag, list_tags and get_lead 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 a concrete routing hint ('See list_tags for existing tag names') and states that the operation is safe to repeat, which tells the agent it need not check for duplicates first. It does not explicitly contrast with remove_tag or state when not to use it, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update many leads in a single PATCH /leads request. Each item merges its fields with the lead id and uses the same field keys as update_lead. Returns the Kommo response for the batch. Use update_lead for a single lead.
| Name | Required | Description | Default |
|---|---|---|---|
| leads_updates | Yes | Updates to apply, one per lead. Example: [{"id": 123, "fields": {"status_id": 456}}]. |
| Name | Required | Description |
|---|---|---|
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| _embedded | No | Updated leads. |
| _total_items | No | Number of leads updated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, idempotent, non-destructive, open-world. The description adds genuinely useful mechanics beyond that: each item merges `fields` with its `id`, and the return is the batch Kommo response. It omits batch-size limits and per-item partial-failure behavior, which matter most for a bulk mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler; the request shape and merge semantics come first, and the sibling routing hint is last. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the description covers request construction and sibling routing adequately. The remaining gap is operational context for a bulk write (batch limits, error handling), which is minor given annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents `id` sourcing and that `fields` mirrors update_lead. The description restates that field keys match update_lead but adds no format, constraint, or limit detail beyond the structured data, 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 (update), resource (leads), and scope (many, via a single PATCH /leads request). It explicitly contrasts itself with update_lead for single-lead updates, so an agent can route correctly 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?
Names the alternative (update_lead) and the condition that selects it (a single lead). However, it gives no guidance on when bulk is inappropriate, e.g. batch size limits or whether mixing creates/updates in one call is allowed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a company record with a name only. Not idempotent: duplicates are not checked, so look with list_companies first. Returns the created company. To create a company alongside a new lead, use create_lead_complex.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Company name, e.g. "Acme Inc". |
| Name | Required | Description |
|---|---|---|
| id | No | Company ID. |
| name | No | Company name. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags and leads. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true; the description reinforces non-idempotency and adds the concrete consequence (duplicates are not checked) plus the dedup workaround. It does not mention permissions or any failure modes, so it stops just short of full behavioral coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each load-bearing: purpose, non-idempotency caveat with remedy, return value, and the alternative tool. The scope constraint is front-loaded and nothing is padded.
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?
An output schema exists, so return values need not be detailed, yet the description still notes the created company is returned. For a one-parameter creation tool with full annotation coverage, the 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?
There is a single parameter with 100% schema description coverage, so the schema already carries the semantics (including the "Acme Inc" example). The description's "with a name only" merely restates that the call is minimal and adds no format or constraint 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?
States a specific verb+resource (create a company record) and immediately scopes it ("with a name only"). It also names the sibling create_lead_complex for the adjacent use case, so the agent can distinguish this from other creation tools 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 when-to-use guidance (check list_companies first because duplicates are unchecked) and names the alternative path (create_lead_complex when creating alongside a lead). Both the pre-condition and the routing decision are stated outright rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create one contact. Not idempotent: it does not check for duplicates, so search with list_contacts first. Phone and email are sent as Kommo's built-in PHONE and EMAIL fields (WORK values). Returns the created contact. To create a lead and contact together, use create_lead_complex.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Contact full name. | |
| No | Email address, e.g. jane@example.com. | ||
| phone | No | Phone number, ideally international, e.g. +15551234567. |
| Name | Required | Description |
|---|---|---|
| id | No | Contact ID. |
| name | No | Full name. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags and companies. |
| last_name | No | Last name. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| first_name | No | First name. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=false and openWorldHint=true, but the description goes further by explaining the consequence ('does not check for duplicates') and by disclosing how phone/email are stored (built-in PHONE/EMAIL fields with WORK values), a behavioral detail not present in annotations or 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?
The core action is front-loaded in the first sentence, followed by the caveat, the field-mapping note, and the alternative route. Every sentence carries distinct information with no padding or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be described beyond the brief 'Returns the created contact.' For a 3-parameter creation tool, the description supplies preconditions, idempotency caveat, field semantics, and alternative routing, which is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by specifying that phone and email are mapped to Kommo's built-in PHONE and EMAIL fields as WORK values. That interpretation detail is not derivable from the schema, pushing it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Create one contact') and clearly separates itself from the two most plausible alternatives (list_contacts for dedup lookup, create_lead_complex for combined creation). An agent can distinguish it from siblings 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?
It gives an explicit precondition ('search with list_contacts first') and an explicit routing rule ('To create a lead and contact together, use create_lead_complex'). Both when-to-use and the alternative are named outright, 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.
Create a custom field on leads, contacts, or companies. Not idempotent: each call creates another field, so check list_custom_fields first. Returns the created field. Clears the custom-field cache for that entity. Provide enum_values for select-type fields.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Field display name. | |
| field_type | Yes | Kommo field type sent as-is, e.g. text, numeric, select, multiselect, date, url, checkbox. | |
| entity_type | Yes | Entity to add the field to: leads, contacts, or companies. | |
| enum_values | No | Option labels for select or multiselect fields, in display order, e.g. ["Low", "High"]. Ignored by other types. |
| Name | Required | Description |
|---|---|---|
| id | No | Field ID. |
| code | No | System field code, or null. |
| name | No | Field name. |
| sort | No | Sort order. |
| type | No | Field type, e.g. text, select. |
| enums | No | Options for select-like fields. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| account_id | No | Kommo account ID. |
| entity_type | No | Entity the field belongs to. |
| is_api_only | No | Whether the field is API only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: the tool returns the created field and clears the custom-field cache for that entity, which is a side effect an agent cannot infer from 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?
Four short sentences, each carrying a distinct fact (action, non-idempotency plus remedy, return value, cache side effect, parameter hint), with the core action front-loaded. No filler or restatement of the title.
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 an output schema present, the description covers the essentials an agent needs: the write nature, the non-idempotency, the duplicate-check prerequisite, the cache invalidation, and the enum_values hint. Nothing critical is missing, though it does not mention auth or rate-limit considerations.
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 explains name, field_type, entity_type and enum_values in detail, including that enum_values is ignored by non-select types. The description's only added parameter guidance ('Provide enum_values for select-type fields') largely restates 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?
States a specific verb and resource (create a custom field) and scopes it to the three supported entities (leads, contacts, companies). It is immediately distinguishable from read-only siblings like get_lead or list_custom_fields because it declares itself a creator and names list_custom_fields as the inspection counterpart.
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 precondition: check list_custom_fields first because each call creates another field. That is real when-to-use guidance tied to an alternative. It stops short of a full when-not case (e.g. how to modify an existing field), but the routing intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create one lead in Kommo. Not idempotent: each call creates a new lead. Tag names that do not exist yet are created automatically. Returns the created lead object. To create the contact and company in the same call, use create_lead_complex.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Lead name (title of the deal). | |
| tags | No | Tag names to attach, e.g. ["vip", "web"]. Created if missing. | |
| price | No | Deal value in the account currency, e.g. 1500. | |
| stage_id | No | Stage (status) to place the lead in. Get IDs from list_stages. Omit for the first stage of the pipeline. | |
| pipeline_id | No | Pipeline to create the lead in. Get IDs from list_pipelines. Omit to use the account default. | |
| responsible_user_id | No | Kommo user ID to assign as owner. Omit for the default user. | |
| custom_fields_values | No | Lead custom field values in Kommo API v4 format: a list of objects, each addressing a field by `field_id` (from list_custom_fields) or by system `field_code`, plus `values`: [{value}] (select-type fields also take enum_id or enum_code). Example: [{"field_id": 123456, "values": [{"value": "Website"}]}]. |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=false, readOnlyHint=false, and destructiveHint=false, so the write-safety profile is covered. The description adds genuine behavioral context beyond them: tag names that don't exist are created automatically (a side effect not visible in annotations) and the explicit 'each call creates a new lead' non-idempotency warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action and followed by the most decision-relevant caveats (idempotency, tag creation, alternative tool). 'Returns the created lead object' is mildly redundant given an output schema exists, but nothing else is wasted.
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-parameter create tool with full schema coverage, annotations, and an output schema, the description covers the essential behavioral facts (non-idempotent, tag auto-creation, alternative tool) and need not explain return values. It omits permission/account requirements, but the coverage is otherwise solid.
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 in the schema, including the auto-creation of tags and the custom_fields_values format. The description adds no format, syntax, or constraint detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Create one lead in Kommo') and immediately scopes it as singular, distinguishing it from bulk creation. It also names the sibling that handles the broader case (create_lead_complex), so an agent can choose correctly 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?
It gives an explicit routing rule: use create_lead_complex when you also need to create the contact and company in the same call. That is clear context for the primary alternative, but there are no stated exclusions or guidance for other related siblings (update_lead, bulk_update_leads, move_lead_stage).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a lead together with a new contact and/or company in one request (POST /leads/complex). Not idempotent; Kommo may merge a duplicate (merged=true). Returns {id, contact_id, company_id, merged}. Contact phone and email are sent as Kommo's built-in PHONE and EMAIL fields. Use create_lead if no contact or company is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Lead name (title of the deal). | |
| tags | No | Tag names to attach to the lead. Created if missing. | |
| stage_id | No | Stage for the lead. Get IDs from list_stages. | |
| pipeline_id | No | Pipeline for the lead. Get IDs from list_pipelines. | |
| company_name | No | Name of a new company to create and attach. | |
| contact_name | No | Name of a new contact to create. Phone and email are ignored unless this is set. | |
| contact_email | No | Contact email address. | |
| contact_phone | No | Contact phone number, e.g. +15551234567. | |
| custom_fields_values | No | Lead custom field values in Kommo API v4 format: a list of objects, each addressing a field by `field_id` (from list_custom_fields) or by system `field_code`, plus `values`: [{value}] (select-type fields also take enum_id or enum_code). Example: [{"field_id": 123456, "values": [{"value": "Website"}]}]. |
| Name | Required | Description |
|---|---|---|
| id | Yes | Lead ID. |
| merged | No | True when Kommo merged the lead into an existing duplicate. |
| company_id | No | ID of the created or linked company. |
| contact_id | No | ID of the created or linked contact. |
| request_id | No | Request IDs sent for this lead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the write/safety profile is covered. The description adds real value beyond them by disclosing the dedupe consequence ('Kommo may merge a duplicate (merged=true)') and the field-mapping behavior (contact phone/email go to built-in PHONE/EMAIL fields), plus the contact_name gating. It does not cover permissions or error behavior, 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?
Four short sentences, front-loaded with the core action and endpoint, then the idempotency caveat, the return shape, and the routing rule. Every clause carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter creation tool with an output schema and full annotation coverage, the description supplies what the structured fields cannot: the sibling routing rule, the merge hazard, and the cross-field dependency (phone/email ignored without contact_name). 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: phone and email are stored in Kommo's built-in PHONE and EMAIL fields rather than arbitrary fields. It does not explain the custom_fields_values shape further, which the schema already covers.
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 ('Create a lead together with a new contact and/or company') plus the underlying endpoint, and explicitly differentiates from the sibling create_lead ('Use create_lead if no contact or company is needed'). An agent can pick between 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 alternative with the selecting condition ('Use create_lead if no contact or company is needed'), and flags the non-idempotent nature so the agent knows retries are unsafe. 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.
Create a new sales pipeline with the given name (sort order 99). Not idempotent: each call creates another pipeline. Returns the created pipeline. Add stages afterwards with create_stage. Clears the pipelines cache.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pipeline name, e.g. "Enterprise". |
| Name | Required | Description |
|---|---|---|
| id | No | Pipeline ID. |
| name | No | Pipeline name. |
| sort | No | Sort order. |
| is_main | No | Whether this is the main pipeline. |
| _embedded | No | Embedded resources. |
| account_id | No | Kommo account ID. |
| is_archive | No | Whether the pipeline is archived. |
| is_unsorted_on | No | Whether the Incoming leads stage is enabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond them: the concrete consequence of non-idempotency ('each call creates another pipeline'), the default sort order of 99, and the side effect 'Clears the pipelines cache.' It omits permission/auth requirements and duplicate-name behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying distinct information (creation, non-idempotency, return value, follow-up tool, cache side effect). The core action is front-loaded with zero 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 an output schema present, return values need no elaboration, yet the description still notes it returns the created pipeline. Non-idempotency, cache invalidation, and the create_stage follow-up are all covered, leaving only minor gaps such as duplicate-name handling and required permissions.
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 single parameter already has a documented example ('Enterprise'), so the schema carries the parameter semantics. The description mentions the name and the implicit sort order, but adds no syntax or constraint details 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 ('Create a new sales pipeline') plus the scope of the operation (name, default sort order 99). It is clearly distinguishable from sibling tools like update_pipeline, list_pipelines, and create_stage.
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 concrete workflow cue ('Add stages afterwards with create_stage') and warns that repeated calls are not idempotent, which helps an agent decide whether to retry. It does not explicitly state when to prefer update_pipeline over this tool, but the create-vs-update split is implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a stage to a pipeline. It is placed after the pipeline's existing editable stages (sort is computed automatically). Not idempotent: each call creates another stage. Returns the created stage. Clears the stage and pipeline caches.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stage name, e.g. "Negotiation". | |
| color | No | Hex color sent to Kommo as-is, e.g. #4CAF50. Optional; Kommo may restrict it to its own palette. | |
| pipeline_id | Yes | Kommo pipeline ID (integer). Obtain it from list_pipelines. |
| Name | Required | Description |
|---|---|---|
| id | No | Stage ID. |
| name | No | Stage name. |
| sort | No | Sort order. |
| type | No | 0 for regular stages, 1 for unsorted. |
| color | No | Hex color. |
| account_id | No | Kommo account ID. |
| is_editable | No | Whether the stage can be edited. |
| pipeline_id | No | Parent pipeline ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the mutation profile is covered. The description still adds real value beyond that: automatic sort placement after existing editable stages, and cache invalidation of stage and pipeline caches, which annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action and zero filler. The final "Returns the created stage" is slightly redundant given an output schema exists, but the sentences otherwise all earn their 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 create tool with a full input schema, an output schema and annotations covering safety and idempotency, the description supplies the missing operational context (placement, cache side effects). Only the lack of guidance relative to sibling tools keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents name, color and pipeline_id (including the list_pipelines pointer). The description adds nothing about parameters, 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 opening sentence gives a specific verb+resource ("Add a stage to a pipeline") and the follow-up clarifies placement semantics. It does not explicitly name a sibling to distinguish from (e.g. update_stage, create_pipeline), so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named (update_stage and create_pipeline are the obvious near neighbours). The non-idempotency note is behavioral, not routing guidance, so the agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a follow-up task (type 1) attached to a lead. Not idempotent: each call creates a new task. Returns the created task. Use list_tasks to review existing tasks and add_note for non-actionable remarks.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Task description shown in Kommo. | |
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. | |
| due_date | Yes | Deadline as a Unix timestamp in seconds, e.g. 1767225600. | |
| responsible_user_id | No | Kommo user ID responsible for the task. Omit for the default. |
| Name | Required | Description |
|---|---|---|
| id | No | Task ID. |
| text | No | Task description. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| result | No | Completion result (object or array), may be empty. |
| duration | No | Duration in seconds. |
| group_id | No | ID of the responsible user's group. |
| entity_id | No | ID of the entity the task is attached to. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| entity_type | No | Entity type, e.g. leads. |
| is_completed | No | Whether the task is completed. |
| task_type_id | No | Task type ID (1 is follow-up). |
| complete_till | No | Deadline, Unix seconds. |
| responsible_user_id | No | ID of the responsible Kommo user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds the concrete consequence of non-idempotency ('each call creates a new task'), which is useful elaboration rather than mere repetition, though it omits permission/auth needs and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place, with the core action and non-idempotency caveat front-loaded before the alternative-tool routing. 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?
An output schema exists, so return values need not be described. Purpose, side-effect behavior, and sibling routing are all present, leaving nothing an agent needs to call this 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 all four parameters are already documented in the schema, making 3 the baseline. The description adds only the 'type 1' constant, which is not mapped to any schema field and is left unexplained, so it adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (create) and resource (task), plus scope constraints: it is a follow-up task of type 1 attached to a lead. This distinguishes it from siblings like list_tasks and add_note 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?
Explicitly routes the agent: use list_tasks to review existing tasks and add_note for non-actionable remarks. This gives both the alternative tools and the conditions that select them, so when-not-to-use is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a lead. Sends PATCH /leads/{id} with is_deleted=true, so the lead is soft-deleted rather than removed through a hard-delete call. Destructive: the lead disappears from normal lists. Confirm the lead_id with get_lead first.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm destructiveHint=true and idempotentHint=true. The description adds substantial context beyond that: it discloses the soft-delete mechanism, the exact API endpoint and payload, and the observable consequence ('disappears from normal lists'), which is critical for an agent deciding whether to use this or a hard-delete alternative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, tightly front-loaded: purpose, mechanism/consequence, and precondition. Every sentence contributes necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a destructive single-resource tool. Output schema exists so return values need not be described; annotations cover safety; description covers mechanism, effect, and prerequisite. Nothing an agent needs to call this 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% and correctly documents lead_id including where to obtain it. The description reinforces the parameter's importance but adds little syntax beyond the schema; baseline for full coverage is 3, but the explicit 'confirm lead_id with get_lead first' gives it a slight bump to 4 by tying the parameter to a verification workflow.
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 ('Delete a lead') and immediately distinguishes itself from siblings by explaining the soft-delete mechanism via PATCH /leads/{id} with is_deleted=true. An agent can tell this apart from update_lead 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?
Provides a clear precondition: 'Confirm the lead_id with get_lead first', naming the sibling to use for verification. It doesn't explicitly say when not to use this (e.g., bulk deletion), but the context is clear enough for the single-lead case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one contact by ID. Read-only. Returns the contact with embedded tags and custom_fields_values (phone, email, and others). Use list_contacts to find the ID.
| Name | Required | Description | Default |
|---|---|---|---|
| contact_id | Yes | Kommo contact ID (integer). Obtain it from list_contacts or from the create_contact result. |
| Name | Required | Description |
|---|---|---|
| id | No | Contact ID. |
| name | No | Full name. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags and companies. |
| last_name | No | Last name. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| first_name | No | First name. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is largely redundant. The one additive note is the return composition (embedded tags and custom_fields_values), which is partly covered by the existing output schema. Adequate, but it adds little behavioral context beyond 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?
Three short, front-loaded sentences with no waste; the core action leads and supporting routing information follows.
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 single-parameter read tool with an output schema and rich annotations, the description covers action, safety, return shape, and how to obtain the ID. 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% and the single contact_id parameter is fully documented in the schema, including where to obtain it. The description adds no syntax or format detail beyond 'by ID', 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 and resource with explicit scope: 'Fetch one contact by ID.' The singular 'one contact' clearly distinguishes it from list_contacts and the other contact 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?
Names the sibling to use for locating the ID ('Use list_contacts to find the ID'), which gives clear operational context. It stops short of explicitly stating when to prefer this over list_contacts for a single lookup, but the guidance provided is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one lead by ID. Read-only. Returns the full lead object including embedded contacts, tags, and custom_fields_values. Use list_leads instead to browse or find lead IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the 'Read-only' sentence is largely redundant. However, the description adds real value by disclosing the response payload composition (embedded contacts, tags, custom_fields_values), which is behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose, then safety/payload, then the alternative. Every sentence earns its place with zero padding.
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 single-parameter lookup with a full output schema, the description covers purpose, routing to the sibling, and the shape of the returned object. 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% and the single lead_id parameter is fully documented in the schema, including its integer type and origin. The description's 'by ID' adds nothing beyond that, 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 and resource ('Fetch one lead by ID') and distinguishes itself from the browse sibling by explicitly naming list_leads. An agent can tell this apart from get_contact or list_leads 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?
Names the alternative (list_leads) and the condition that selects it ('to browse or find lead IDs'), and the schema further tells the agent where the ID comes from. No inference required for routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's chat message templates. Read-only. Returns template objects as provided by Kommo. This server cannot send a template; it only lists them (send_chat_message sends plain text).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuine value beyond them: it states templates are returned 'as provided by Kommo' and that the server is list-only with no send capability, which 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?
Three short sentences, each front-loaded and purposeful: purpose, safety/return, and the send limitation. Nothing is redundant and the most important information (what it does) leads.
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 an output schema present, return shape need not be explained, and rich annotations cover the safety profile. The description supplies the one thing structure cannot: the inability to send templates, making the definition complete for a zero-param list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and no parameter semantics to add. Baseline 4 for a param-less tool 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 (List) and resource (the account's chat message templates), so the agent knows exactly what the tool returns. It also distinguishes itself from the sibling send_chat_message by clarifying it only lists and cannot send, removing ambiguity with the closest related tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear scope: use this to list templates, and it explicitly notes the server cannot send a template while pointing at send_chat_message (clarifying that tool sends plain text only). This is strong routing context, though it stops short of explicit when/when-not triggers since there is no sibling template tool to disambiguate against.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List companies. Read-only. Returns an array of up to limit companies (max 250); pass page for paginated output with a has_next flag. No name search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true. | |
| limit | No | Companies per page. Default 50, capped at 250. |
| Name | Required | Description |
|---|---|---|
| page | No | Page number returned (only when `page` was requested). |
| items | Yes | Returned entities. |
| limit | No | Page size used (only when `page` was requested). |
| has_next | No | True when another page exists (only when paginated). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the description's 'Read-only' largely repeats structured data. It does add genuine behavioral value beyond annotations by documenting the pagination contract (array vs. paginated object with has_next) and the 250 cap, but return shape is also covered by the output 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?
Three short sentences, front-loaded with the operation, then behavior, then the caveat. Tight overall, though 'Read-only' is redundant with the readOnlyHint annotation.
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 2-param read tool with an output schema, the description covers scope, the pagination flow, and the no-search limitation. Only the lack of a named alternative for name search 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 description coverage is 100%, and both params are fully documented there (page semantics, limit default/cap). The description's mentions of limit/page add little beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List companies') with a clear scope and an explicit exclusion ('No name search'). It doesn't name or differentiate against a sibling search/list tool, but there is no competing companies-list sibling, so an agent can select it confidently.
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 negative constraint 'No name search' implicitly tells the agent when this tool is unsuitable, but no alternative tool is named for that case and there is no explicit when-to-use framing. Usage is implied rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search or list contacts. Read-only. Returns an array of up to limit contacts (max 250); pass page for paginated output with a has_next flag. Pass query to match by name, phone, or email; omit it to list recent contacts. Use get_contact for one contact's full details.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true. | |
| limit | No | Contacts per page. Default 50, capped at 250. | |
| query | No | Free-text search matched by Kommo against name, phone, and email, e.g. "Jane" or "+15551234567". Omit to list without filtering. |
| Name | Required | Description |
|---|---|---|
| page | No | Page number returned (only when `page` was requested). |
| items | Yes | Returned entities. |
| limit | No | Page size used (only when `page` was requested). |
| has_next | No | True when another page exists (only when paginated). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context: the two distinct return shapes (plain array vs {items, page, limit, has_next}), the 250 cap, and the page+1-while-has_next iteration contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the verb and read-only status before the branching rules. Minor redundancy: the 250 cap and 'max 250' appear in both description and schema description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and rich annotations, the description need not explain return fields; it still supplies the pagination loop contract and mode distinction that matter for correct invocation. Nothing needed to call this 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 the baseline would be 3, but the description adds cross-parameter semantics the schema cannot: the query/omit duality and the mode switch triggered by supplying page. It stops short of adding anything the schema lacks about limit's default or range.
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 both verbs and the resource ('Search or list contacts') and explicitly contrasts itself with the sibling get_contact for single-record retrieval. An agent can pick between list_contacts and get_contact 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 explicit branch conditions: pass `query` to match by name/phone/email, omit it to list recent contacts, pass `page` for paginated output. It also names the alternative tool for the single-contact case, covering both when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom field definitions for leads, contacts, or companies. Read-only. Returns field objects with id, name, code, type, and enum options. Cached for 1 hour. Use the field IDs in custom_fields_values when calling update_lead or update_contact.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | Entity whose fields to list: leads, contacts, or companies. Default "leads". | leads |
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior the annotations cannot convey: results are cached for 1 hour, which affects freshness expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place: what it lists, safety, return shape, caching constraint, and the cross-tool usage tip. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not detail return values, and the annotations cover the safety profile. Combined with the caching note and the ID-reuse guidance, an agent has everything needed to call and consume this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the entity_type parameter and its enum-ish values are already documented in the schema. The description's mention of leads/contacts/companies is essentially a restatement, 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 (List) and resource (custom field definitions) scoped to three entity types, and clearly distinguishes itself from get/list siblings that operate on records rather than field metadata.
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 tells the agent how to use the result: feed the field IDs into custom_fields_values when calling update_lead or update_contact. This is strong downstream routing, though it stops short of stating when NOT to use this tool (e.g., use create_custom_field to add one).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List leads, optionally filtered by pipeline and stage. Read-only. Returns an array of lead objects with embedded contacts and tags, up to limit items (follows Kommo pagination when limit exceeds 50). To fetch custom fields for one lead, use get_lead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of leads to return. Default 50. | |
| stage_id | No | Only leads in this stage. Ignored unless pipeline_id is also set. Get IDs from list_stages. | |
| pipeline_id | No | Only leads in this pipeline. Get IDs from list_pipelines. |
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is partly redundant. The description does add genuinely non-annotated behavior: pagination kicks in when limit exceeds 50 (Kommo pagination), and results embed contacts and tags. It does not mention rate limits or ordering guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the verb/resource and scope, then safety, then return/pagination behavior, then the alternative. No sentence is padding.
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 an output schema covering the return shape and annotations covering the safety profile, the description only needs to add scope, pagination nuance, and sibling routing — all of which it does. Nothing an agent needs to invoke this 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 the baseline is 3. The description adds meaning beyond the schema by explaining that pagination behavior changes above limit=50, which the schema's bare 'Maximum number of leads to return. Default 50.' does not convey. The stage/pipeline relationship itself is already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List leads') plus the scope of optional filtering by pipeline and stage, and explicitly names the sibling to use for a single lead's custom fields (get_lead). An agent can distinguish this from get_lead, list_contacts, or list_companies 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?
Clearly frames usage as a filtered list operation and routes the single-lead custom-field case to get_lead. It does not state when-not to use it (e.g., bulk retrieval limits or when to prefer bulk_update_leads for reads), so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sales pipelines in the account. Read-only. Returns pipeline objects (id, name, sort, embedded stages as provided by Kommo). Results are cached for 10 minutes, so very recent changes may not show. Start here to obtain the pipeline_id and stage IDs used by most lead tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context the agent cannot get elsewhere: a 10-minute result cache with a stated staleness consequence, plus the shape of returned pipeline objects including embedded stages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the purpose, then safety, then return/behavioral caveats, then usage. Every sentence carries information an agent needs; nothing is redundant with the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema, the description supplies exactly the missing pieces: caching/staleness, the ID values downstream tools consume, and its role as the entry point. Nothing an agent needs 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 zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies a no-argument full listing.
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 ("List all sales pipelines in the account") and immediately scopes it as read-only, clearly separating it from sibling mutators like create_pipeline/update_pipeline and from the adjacent list_stages.
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?
"Start here to obtain the pipeline_id and stage IDs used by most lead tools" gives explicit entry-point guidance and ties the output to downstream lead tools. It stops short of naming an alternative or stating a when-not condition, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the stages (statuses) of one pipeline. Read-only. Returns stage objects with id, name, sort, color, and is_editable. Results are cached for 10 minutes. Use the stage IDs with list_leads, create_lead, and move_lead_stage.
| Name | Required | Description | Default |
|---|---|---|---|
| pipeline_id | Yes | Kommo pipeline ID (integer). Obtain it from list_pipelines. |
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, so 'Read-only' is partly redundant, but the description adds genuinely new behavior: results are cached for 10 minutes, which matters for freshness-sensitive workflows. It also names the return fields rather than leaving the agent to open the output 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?
Four short sentences, front-loaded with the purpose and then the return shape, cache caveat, and ID handoff. Dense and readable, though 'Read-only' duplicates the annotation and costs a little space.
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 annotations carrying the safety profile and an output schema covering the return shape, the description needs only the caching caveat and the ID-usage handoff, both of which are present. Missing only failure modes for an invalid pipeline_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains that pipeline_id is a Kommo integer obtainable from list_pipelines. The description only implies the single-pipeline scoping and adds no format or validation 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 (List) plus resource (stages/statuses) scoped to exactly one pipeline, which cleanly separates it from list_pipelines. It also enumerates the returned fields, so an agent knows precisely 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?
Gives explicit downstream usage: feed the stage IDs into list_leads, create_lead, and move_lead_stage. It never states when not to use it or names a competing sibling, but the context is clear enough to select it confidently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags defined in the account for one entity type (up to 250). Read-only. Returns tag objects with id and name. Use it to check exact tag names before add_tag or remove_tag.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | No | Which tag set to list: leads, contacts or companies (singular forms accepted). Default "lead". | lead |
| Name | Required | Description |
|---|---|---|
| items | Yes | Returned entities. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'Read-only' text is partly redundant. However, the description adds the 250-item cap, which is genuine behavioral context not present in structured fields. The return-shape sentence is partially redundant given an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste, front-loaded with the operation and cap before the routing guidance to sibling tools.
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 single optional-enum read tool with full schema coverage, annotations, and an output schema, the description supplies purpose, cap, and when-to-use guidance. Nothing an agent needs to invoke 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% with a fully documented enum and default, so the schema already carries parameter meaning. The description's 'for one entity type' framing adds only marginal value beyond that. 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 ('List tags defined in the account'), scopes it to one entity type, and distinguishes itself from the mutating siblings add_tag/remove_tag. An agent can identify the operation 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?
Explicitly says when to use it ('to check exact tag names before add_tag or remove_tag') and names the two alternative tools it complements. 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.
List tasks, optionally for one lead or only overdue ones. Read-only. Returns an array (Kommo default page size unless limit is set, max 250); pass page for paginated output with a has_next flag. Overdue means deadline at or before now and not completed.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true. | |
| limit | No | Tasks per page, max 250. Omit for Kommo's default (50). | |
| lead_id | No | Only tasks attached to this lead. Omit for all tasks. | |
| filter_overdue | No | If true, only uncompleted tasks whose deadline has passed. |
| Name | Required | Description |
|---|---|---|
| page | No | Page number returned (only when `page` was requested). |
| items | Yes | Returned entities. |
| limit | No | Page size used (only when `page` was requested). |
| has_next | No | True when another page exists (only when paginated). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuine value by explaining the two return shapes (plain array vs paginated object with has_next) and defining 'overdue' precisely—details not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences front-loaded with purpose, then read-only, then return shape and the overdue definition. 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?
An output schema exists, so return values needn't be explained, yet the description still helpfully clarifies the array-vs-paginated duality that a caller must handle. The only gap is the absence of usage routing against alternatives, which is minor here.
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 every parameter is already documented in the schema with equal or greater detail (e.g., default 50, max 250, 1-based page). The description restates pagination behavior but adds nothing beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (tasks), plus the two filtering dimensions (lead, overdue). It is clearly distinguishable from siblings like create_task or list_leads.
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 covers the main filter modes (one lead, overdue) which implies when to use them, but it never names an alternative tool or states when NOT to use this one. For a list operation with no near-duplicate siblings this is acceptable but not exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a lead to another stage by setting its status_id (and optionally pipeline_id). Returns the updated lead. Use this instead of update_lead for pipeline moves. Pass pipeline_id when moving to a stage in a different pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. | |
| stage_id | Yes | Target stage ID. Get IDs from list_stages. | |
| pipeline_id | No | Target pipeline ID. Only needed when the stage belongs to a different pipeline than the lead's current one. |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety and repeatability are covered structurally. The description adds only that it returns the updated lead and that it is the pipeline-move path; it says nothing extra about side effects like stage-history entries or notifications. Adequate 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?
Three tight sentences, front-loaded with the action, then the return, then the routing rule. No filler and every sentence carries distinct 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?
With an output schema, full annotations, and 100% schema description coverage, the description only needs to cover routing and scope, which it does. Nothing an agent needs to call this 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 lead_id, stage_id, and pipeline_id are already documented in the schema; baseline is 3. The description lightly reinforces pipeline_id's conditional nature, but it also refers to 'status_id' while the actual parameter is named 'stage_id', which adds a small naming ambiguity rather than clarity.
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 ('Move a lead to another stage') plus the mechanism ('by setting its status_id'), and explicitly distinguishes itself from the sibling update_lead. An agent can tell what this does 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?
Names the alternative it replaces ('Use this instead of update_lead for pipeline moves') and gives the precise condition for the optional parameter ('Pass pipeline_id when moving to a stage in a different pipeline'). Routing and conditional usage are both explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach a tag from a lead by name. Reads the lead's tags and writes back the list without that tag; other tags are kept. The tag itself is not deleted from the account. If no tag with that name exists, nothing changes and the lead is returned as is. Safe to repeat. Returns the updated lead.
| Name | Required | Description | Default |
|---|---|---|---|
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. | |
| tag_name | Yes | Exact tag name (case-sensitive) to detach, e.g. "vip". |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains the read-modify-write mechanism, that other tags are preserved, that the tag is not deleted from the account, and that missing tags yield an unchanged lead. This adds substantial context beyond the annotations (idempotentHint, destructiveHint:false), which only flag the safety profile without explaining why.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action, then mechanism and edge cases. No filler and every sentence carries distinct 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?
Covers the action, the mutation semantics, the no-op case, and repeat safety; an output schema exists so return values need not be detailed. Nothing needed to invoke 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% and both parameters are already documented with examples (Kommo lead ID, case-sensitive tag name). The description's 'by name' adds only marginal meaning, 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+key: 'Detach a tag from a lead by name.' An agent can immediately tell this apart from sibling add_tag and from delete_lead (tag is not deleted).
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: no-op when the tag name doesn't exist, and safe to repeat. It does not explicitly name an alternative tool (e.g., list_tags to verify a tag exists first, or add_tag for the inverse), so the sibling routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an outgoing chat message to the customer in a lead's conversation. Finds a conversation (talk) whose entity is this lead and posts to it; fails with an error if the lead has none. The message is delivered externally and cannot be recalled by this server, and repeated calls send duplicates. Use add_note for internal notes.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Message text sent to the customer. | |
| lead_id | Yes | ID of a lead that already has an active conversation. Get it from list_leads. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so duplication and external reach are partly structured data. The description still adds genuine value with 'cannot be recalled by this server' and the hard precondition that the lead has a conversation, but the duplicate/external claims restate the annotations rather than extend them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, then the lookup behavior, then the delivery warning and the alternative. Nothing is redundant or padding.
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?
An output schema exists so return values need no explanation. Failure conditions, irreversibility, duplicate risk, and the sibling alternative are all present, leaving nothing an agent needs in order to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are self-documented (text and lead_id with sourcing guidance from list_leads). The description adds no format, length or escaping detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (send), resource (chat message) and target (the customer in a lead's conversation), and explicitly distinguishes itself from add_note for internal notes. An agent can separate this from the other lead tools 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?
It names the alternative tool (add_note) and the condition that selects it, plus the precondition that the lead must already have an active conversation and the failure mode if it doesn't. Both when-to-use and when-not-to-use are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing contact by sending fields as the body of a Kommo API v4 PATCH /contacts/{id}. Returns the updated contact. Provided values overwrite existing ones; omitted fields are untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Raw Kommo v4 contact fields to change, passed through unchanged. Common keys: name, first_name, last_name, responsible_user_id, custom_fields_values (array of {field_id, values: [{value, enum_code}]}; field IDs from list_custom_fields). Example: {"name": "Jane Roe"}. | |
| contact_id | Yes | Kommo contact ID (integer). Obtain it from list_contacts or from the create_contact result. |
| Name | Required | Description |
|---|---|---|
| id | No | Contact ID. |
| name | No | Full name. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags and companies. |
| last_name | No | Last name. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| first_name | No | First name. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=true. The description adds meaningful context beyond them: it is a merge-style PATCH where provided values overwrite and omitted fields are untouched, which tells the agent it will not clobber unspecified fields. It does not cover auth requirements or error behavior, keeping it short of 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?
Three compact sentences, front-loaded with the action and endpoint, followed by return value and mutation semantics. Every sentence carries 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?
An output schema exists so return values need not be detailed, and the description still notes the updated contact is returned. With full schema coverage, annotations covering the safety profile, and overwrite/merge semantics stated, nothing needed to invoke 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 both parameters are already well documented in the schema, including the fields object shape and example. The description adds only that `fields` is sent as the PATCH body unchanged, which is marginal 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?
The description states a specific verb and resource ("Update fields on an existing contact") and pins the exact API surface (PATCH /contacts/{id}), so the agent knows precisely what it does. It does not explicitly contrast itself with create_contact or get_contact, so it falls short of full sibling differentiation.
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?
Usage is implied by "existing contact" (not a create) and the overwrite/omit semantics, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative such as create_contact for new records. Adequate but with clear gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing lead by sending fields as the body of a Kommo API v4 PATCH /leads/{id}. Returns the updated lead. Overwrites the given values; omitted fields are untouched. For a stage change prefer move_lead_stage; for several leads use bulk_update_leads.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Raw Kommo v4 lead fields to change, passed through unchanged. Common keys: name (string), price (integer), status_id (stage ID), pipeline_id, responsible_user_id, custom_fields_values (array of {field_id, values: [{value}]}), _embedded.tags (full replacement list of {id}). Example: {"name": "Acme renewal", "price": 2000}. | |
| lead_id | Yes | Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result. |
| Name | Required | Description |
|---|---|---|
| id | No | Lead ID. |
| name | No | Lead name. |
| price | No | Lead budget. |
| _links | No | HAL links as returned by Kommo (self, next, ...). |
| group_id | No | ID of the responsible user's group. |
| _embedded | No | Embedded tags, contacts and companies. |
| closed_at | No | Closing time, Unix seconds, or null. |
| status_id | No | Current stage ID. |
| account_id | No | Kommo account ID. |
| created_at | No | Creation time, Unix seconds. |
| created_by | No | ID of the user who created it. |
| is_deleted | No | Whether the lead is deleted. |
| updated_at | No | Last update time, Unix seconds. |
| updated_by | No | ID of the user who last updated it. |
| pipeline_id | No | Pipeline ID. |
| loss_reason_id | No | Loss reason ID, or null. |
| closest_task_at | No | Next task deadline, Unix seconds, or null. |
| responsible_user_id | No | ID of the responsible Kommo user. |
| custom_fields_values | No | Custom field values in Kommo format: objects with field_id, field_code and values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds genuinely useful semantics beyond them: partial-update behavior ('Overwrites the given values; omitted fields are untouched') and that `fields` is passed through raw to the Kommo v4 PATCH endpoint. It does not cover auth requirements or failure behavior, which keeps it short of 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?
Three short sentences, zero filler, with the core action and mutation semantics front-loaded before the sibling routing hints. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is unnecessary, and the description correctly notes the updated lead is returned. Required parameters, mutation semantics, and sibling routing are all covered for a two-parameter tool with a nested passthrough object; only edge cases like invalid field names or partial failure are 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 100% and the `fields` parameter already documents common keys, custom_fields_values shape, tag replacement semantics, and an example. The description only adds that `fields` is sent as the request body unchanged, which is marginal beyond the schema. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Update fields on an existing lead') and names the exact underlying operation (PATCH /leads/{id}), so the agent knows precisely what is being mutated. It also explicitly distinguishes itself from the two closest siblings, move_lead_stage and bulk_update_leads.
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 routing rules: use move_lead_stage for a stage change and bulk_update_leads for several leads. This is a when-to-use-this-vs-alternatives statement with the selecting condition attached, 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.
Rename an existing pipeline. Only the name can be changed with this tool. Returns the updated pipeline. Safe to repeat. Clears the pipelines cache. To change a stage use update_stage.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New pipeline name. | |
| pipeline_id | Yes | Kommo pipeline ID (integer). Obtain it from list_pipelines. |
| Name | Required | Description |
|---|---|---|
| id | No | Pipeline ID. |
| name | No | Pipeline name. |
| sort | No | Sort order. |
| is_main | No | Whether this is the main pipeline. |
| _embedded | No | Embedded resources. |
| account_id | No | Kommo account ID. |
| is_archive | No | Whether the pipeline is archived. |
| is_unsorted_on | No | Whether the Incoming leads stage is enabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (idempotentHint, destructiveHint=false, readOnlyHint=false), and 'Safe to repeat' largely restates idempotency. However, 'Clears the pipelines cache' is a genuine side-effect disclosure not present in annotations, and 'Returns the updated pipeline' confirms the mutation result. Solid added value, minor redundancy.
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?
Five short, front-loaded sentences with zero filler. The scope restriction and alternative routing appear before less critical details like cache behavior.
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?
An output schema exists, yet the description still notes what is returned, and it covers the mutation's side effect, idempotency, and the sibling alternative. Nothing needed to invoke this two-parameter rename tool 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 both parameters are self-documented (baseline 3). The description adds a constraint beyond the schema: only 'name' is mutable, which is not derivable from a schema that marks both fields as required. That extra semantic boundary earns a bump.
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 ('Rename an existing pipeline') and immediately bounds the scope with 'Only the name can be changed with this tool.' It also names the sibling update_stage for stage changes, so the agent can distinguish it 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?
Explicitly states the when-not condition ('Only the name can be changed') and routes the alternative case ('To change a stage use update_stage'). Combined with the schema note that pipeline_id comes from list_pipelines, the selection path is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a stage's name, sort order, or color. Only the provided fields are sent; supply at least one of name, sort, or color. Returns the updated stage. Safe to repeat. Clears the stage and pipeline caches. Get IDs from list_stages.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New stage name. | |
| sort | No | New sort position; lower values appear first (e.g. 10, 20). | |
| color | No | New hex color, e.g. #4CAF50, sent to Kommo as-is. | |
| stage_id | Yes | Stage ID within that pipeline. Obtain it from list_stages. | |
| pipeline_id | Yes | Kommo pipeline ID (integer). Obtain it from list_pipelines. |
| Name | Required | Description |
|---|---|---|
| id | No | Stage ID. |
| name | No | Stage name. |
| sort | No | Sort order. |
| type | No | 0 for regular stages, 1 for unsorted. |
| color | No | Hex color. |
| account_id | No | Kommo account ID. |
| is_editable | No | Whether the stage can be edited. |
| pipeline_id | No | Parent pipeline ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the description's 'Safe to repeat' is largely redundant. It does add genuine behavior beyond the structured fields: the partial-update semantics ('only the provided fields are sent') and the side effect 'Clears the stage and pipeline caches'. It omits permission/auth requirements and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six short sentences, front-loaded with the core action and constraint, with the ID-source hint last - no wasted padding overall. 'Safe to repeat' mildly duplicates the idempotentHint annotation, which is the only slack in an otherwise tight 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?
With a full output schema, the return value needs no explanation, and the annotations carry the safety profile; the description covers the remaining essentials (partial update, cache invalidation, ID provenance). Only edge behavior - validation errors, whether additional stage fields exist, required permissions - is 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 100%, so the baseline is 3, but the description adds a real constraint the schema does not express: at least one of name, sort, or color must be supplied (only pipeline_id/stage_id are marked required). It also names the exact fields it operates on, reinforcing the schema. It adds no syntax beyond the schema's own param text.
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 ('Change a stage's name, sort order, or color'), so the agent immediately knows this is an in-place mutation of an existing stage. It routes to list_stages for IDs, which implicitly separates it from create_stage. It stops short of explicitly contrasting itself with the create/delete siblings, so it is clear but not maximally differentiating.
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 concrete invocation constraint ('Only the provided fields are sent; supply at least one of name, sort, or color') and the prerequisite source for IDs (list_stages). That is clear when-to-use context. It offers no when-not-to-use guidance or comparison against alternatives such as create_stage or update_pipeline, so it lands at 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.5create_lead_complex24 fields changedOutput schema / descriptionPrevious value: -"The created lead; may also carry contact_id and company_id."New value: +"Result of POST /leads/complex for the created (or merged) lead."Output schema / properties / _embeddedRemoved value: -{
- "additionalProperties": true,
- "description": "Embedded tags, contacts and companies.",
- "properties": {
- "tags": {
- "description": "Embedded tags.",
- "items": {
- "additionalProperties": true,
- "description": "A Kommo tag.",
- "properties": {
- "color": {
- "description": "Tag color, or null.",
- "type": [
- "string",
- "null"
- ]
- },
- "id": {
- "description": "Tag ID.",
- "type": "integer"
- },
- "name": {
- "description": "Tag name.",
- "type": [
- "string",
- "null"
- ]
- }
- },
- "type": "object"
- },
- "type": "array"
- }
- },
- "type": "object"
-}Output schema / properties / _linksRemoved value: -{
- "additionalProperties": true,
- "description": "HAL links as returned by Kommo (self, next, ...).",
- "properties": {},
- "type": "object"
-}Output schema / properties / account_idRemoved value: -{
- "description": "Kommo account ID.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / closed_atRemoved value: -{
- "description": "Closing time, Unix seconds, or null.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / closest_task_atRemoved value: -{
- "description": "Next task deadline, Unix seconds, or null.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / company_idAdded value: +{
+ "description": "ID of the created or linked company.",
+ "type": [
+ "integer",
+ "null"
+ ]
+}Output schema / properties / contact_idAdded value: +{
+ "description": "ID of the created or linked contact.",
+ "type": [
+ "integer",
+ "null"
+ ]
+}Output schema / properties / created_atRemoved value: -{
- "description": "Creation time, Unix seconds.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / created_byRemoved value: -{
- "description": "ID of the user who created it.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / custom_fields_valuesRemoved value: -{
- "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
- "items": {
- "additionalProperties": true,
- "description": "One custom field with its values.",
- "properties": {},
- "type": "object"
- },
- "type": [
- "array",
- "null"
- ]
-}Output schema / properties / group_idRemoved value: -{
- "description": "ID of the responsible user's group.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / is_deletedRemoved value: -{
- "description": "Whether the lead is deleted.",
- "type": [
- "boolean",
- "null"
- ]
-}Output schema / properties / loss_reason_idRemoved value: -{
- "description": "Loss reason ID, or null.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / mergedAdded value: +{
+ "description": "True when Kommo merged the lead into an existing duplicate.",
+ "type": "boolean"
+}Output schema / properties / nameRemoved value: -{
- "description": "Lead name.",
- "type": [
- "string",
- "null"
- ]
-}Output schema / properties / pipeline_idRemoved value: -{
- "description": "Pipeline ID.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / priceRemoved value: -{
- "description": "Lead budget.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / request_idAdded value: +{
+ "description": "Request IDs sent for this lead.",
+ "items": {
+ "description": "Request ID.",
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / responsible_user_idRemoved value: -{
- "description": "ID of the responsible Kommo user.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / status_idRemoved value: -{
- "description": "Current stage ID.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / updated_atRemoved value: -{
- "description": "Last update time, Unix seconds.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / properties / updated_byRemoved value: -{
- "description": "ID of the user who last updated it.",
- "type": [
- "integer",
- "null"
- ]
-}Output schema / requiredAdded value: +[
+ "id"
+]send_chat_message3 fields changedOutput schema / descriptionPrevious value: -"Kommo response for the posted chat message, passed through unchanged."New value: +"Kommo response to POST /talks/{talk_id}/send_message, passed through unchanged."Output schema / properties / _embeddedRemoved value: -{
- "additionalProperties": true,
- "description": "Embedded messages.",
- "properties": {},
- "type": "object"
-}Output schema / properties / _total_itemsRemoved value: -{
- "description": "Number of messages created.",
- "type": "integer"
-}v1.0.3add_note1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created note.",
+ "properties": {
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "entity_id": {
+ "description": "ID of the entity the note is attached to.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Note ID.",
+ "type": "integer"
+ },
+ "note_type": {
+ "description": "Note type, e.g. common.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "params": {
+ "additionalProperties": true,
+ "description": "Note parameters, e.g. {text}.",
+ "properties": {},
+ "type": "object"
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}add_tag1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The lead after the tag was added.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}bulk_update_leads1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Kommo bulk update response: the updated leads (usually id, name, updated_at) under _embedded.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Updated leads.",
+ "properties": {
+ "leads": {
+ "description": "Embedded leads.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo lead. Fields beyond those listed (embedded contacts, companies, etc.) may appear. Write operations may return only id, name, updated_at and request_id.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "_total_items": {
+ "description": "Number of leads updated.",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+}create_company1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created company.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and leads.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Company ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Company name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_contact1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created contact (id, name and request_id at minimum).",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "first_name": {
+ "description": "First name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Contact ID.",
+ "type": "integer"
+ },
+ "last_name": {
+ "description": "Last name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Full name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_custom_field1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created custom field.",
+ "properties": {
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "code": {
+ "description": "System field code, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "entity_type": {
+ "description": "Entity the field belongs to.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enums": {
+ "description": "Options for select-like fields.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One option.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Field ID.",
+ "type": "integer"
+ },
+ "is_api_only": {
+ "description": "Whether the field is API only.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Field name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "Field type, e.g. text, select.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_lead2 fields changedInput schema / properties / custom_fields_valuesAdded value: +{
+ "description": "Lead custom field values in Kommo API v4 format: a list of objects, each addressing a field by `field_id` (from list_custom_fields) or by system `field_code`, plus `values`: [{value}] (select-type fields also take enum_id or enum_code). Example: [{\"field_id\": 123456, \"values\": [{\"value\": \"Website\"}]}].",
+ "items": {
+ "properties": {
+ "field_code": {
+ "description": "Field system code, e.g. UTM_SOURCE. Use this or field_id.",
+ "type": "string"
+ },
+ "field_id": {
+ "description": "Custom field ID from list_custom_fields. Use this or field_code.",
+ "type": "integer"
+ },
+ "values": {
+ "description": "One or more values to store, each as {value} (plus enum_id/enum_code).",
+ "items": {
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "values"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created lead (id, name and request_id at minimum).",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_lead_complex2 fields changedInput schema / properties / custom_fields_valuesAdded value: +{
+ "description": "Lead custom field values in Kommo API v4 format: a list of objects, each addressing a field by `field_id` (from list_custom_fields) or by system `field_code`, plus `values`: [{value}] (select-type fields also take enum_id or enum_code). Example: [{\"field_id\": 123456, \"values\": [{\"value\": \"Website\"}]}].",
+ "items": {
+ "properties": {
+ "field_code": {
+ "description": "Field system code, e.g. UTM_SOURCE. Use this or field_id.",
+ "type": "string"
+ },
+ "field_id": {
+ "description": "Custom field ID from list_custom_fields. Use this or field_code.",
+ "type": "integer"
+ },
+ "values": {
+ "description": "One or more values to store, each as {value} (plus enum_id/enum_code).",
+ "items": {
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "values"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created lead; may also carry contact_id and company_id.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_pipeline1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created pipeline.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded resources.",
+ "properties": {
+ "statuses": {
+ "description": "Embedded statuses.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A pipeline stage (status).",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Pipeline ID.",
+ "type": "integer"
+ },
+ "is_archive": {
+ "description": "Whether the pipeline is archived.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_main": {
+ "description": "Whether this is the main pipeline.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_unsorted_on": {
+ "description": "Whether the Incoming leads stage is enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Pipeline name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_stage1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created stage.",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}create_task1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The created task.",
+ "properties": {
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "complete_till": {
+ "description": "Deadline, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "duration": {
+ "description": "Duration in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "entity_id": {
+ "description": "ID of the entity the task is attached to.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "entity_type": {
+ "description": "Entity type, e.g. leads.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Task ID.",
+ "type": "integer"
+ },
+ "is_completed": {
+ "description": "Whether the task is completed.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "result": {
+ "description": "Completion result (object or array), may be empty."
+ },
+ "task_type_id": {
+ "description": "Task type ID (1 is follow-up).",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "text": {
+ "description": "Task description.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}delete_lead1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The lead marked as deleted, as returned by Kommo.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}get_contact1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The contact with tags and custom fields.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "first_name": {
+ "description": "First name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Contact ID.",
+ "type": "integer"
+ },
+ "last_name": {
+ "description": "Last name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Full name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}get_lead1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The lead with contacts, tags and custom fields.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}list_chat_templates1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Chat templates, as {items: [...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A chat message template.",
+ "properties": {
+ "content": {
+ "description": "Template text.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Template ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Template name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "status": {
+ "description": "Approval status.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "Channel type.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_companies5 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum companies to return. Default 50, capped at 100."New value: +"Companies per page. Default 50, capped at 250."Input schema / properties / limit / maximumAdded value: +250Input schema / properties / limit / minimumAdded value: +1Input schema / properties / pageAdded value: +{
+ "description": "1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true.",
+ "minimum": 1,
+ "type": "integer"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Companies, as {items: [company, ...]}. With `page` set, also page, limit and has_next.",
+ "properties": {
+ "has_next": {
+ "description": "True when another page exists (only when paginated).",
+ "type": "boolean"
+ },
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo company.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and leads.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Company ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Company name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "limit": {
+ "description": "Page size used (only when `page` was requested).",
+ "type": "integer"
+ },
+ "page": {
+ "description": "Page number returned (only when `page` was requested).",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_contacts5 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum contacts to return. Default 50, capped at 100."New value: +"Contacts per page. Default 50, capped at 250."Input schema / properties / limit / maximumAdded value: +250Input schema / properties / limit / minimumAdded value: +1Input schema / properties / pageAdded value: +{
+ "description": "1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true.",
+ "minimum": 1,
+ "type": "integer"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Contacts, as {items: [contact, ...]}. With `page` set, also page, limit and has_next.",
+ "properties": {
+ "has_next": {
+ "description": "True when another page exists (only when paginated).",
+ "type": "boolean"
+ },
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo contact. Phone and email live in custom_fields_values.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "first_name": {
+ "description": "First name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Contact ID.",
+ "type": "integer"
+ },
+ "last_name": {
+ "description": "Last name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Full name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "limit": {
+ "description": "Page size used (only when `page` was requested).",
+ "type": "integer"
+ },
+ "page": {
+ "description": "Page number returned (only when `page` was requested).",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_custom_fields1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Custom fields, as {items: [field, ...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A custom field definition.",
+ "properties": {
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "code": {
+ "description": "System field code, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "entity_type": {
+ "description": "Entity the field belongs to.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "enums": {
+ "description": "Options for select-like fields.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One option.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Field ID.",
+ "type": "integer"
+ },
+ "is_api_only": {
+ "description": "Whether the field is API only.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Field name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "Field type, e.g. text, select.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_leads1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Leads, as {items: [lead, ...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo lead. Fields beyond those listed (embedded contacts, companies, etc.) may appear. Write operations may return only id, name, updated_at and request_id.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_pipelines1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Pipelines, as {items: [pipeline, ...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A sales pipeline.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded resources.",
+ "properties": {
+ "statuses": {
+ "description": "Embedded statuses.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A pipeline stage (status).",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Pipeline ID.",
+ "type": "integer"
+ },
+ "is_archive": {
+ "description": "Whether the pipeline is archived.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_main": {
+ "description": "Whether this is the main pipeline.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_unsorted_on": {
+ "description": "Whether the Incoming leads stage is enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Pipeline name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_stages1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Stages of the pipeline, as {items: [stage, ...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A pipeline stage (status).",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_tags3 fields changedInput schema / properties / entity_type / descriptionPrevious value: -"Entity type, inserted as-is into the Kommo path /{entity_type}/tags. Default \"lead\"."New value: +"Which tag set to list: leads, contacts or companies (singular forms accepted). Default \"lead\"."Input schema / properties / entity_type / enumAdded value: +[
+ "lead",
+ "leads",
+ "contact",
+ "contacts",
+ "company",
+ "companies"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Tags, as {items: [tag, ...]}.",
+ "properties": {
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}list_tasks3 fields changedInput schema / properties / limitAdded value: +{
+ "description": "Tasks per page, max 250. Omit for Kommo's default (50).",
+ "maximum": 250,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / pageAdded value: +{
+ "description": "1-based page number. Omit for a plain array (first page). When set, returns {items, page, limit, has_next}; request page+1 while has_next is true.",
+ "minimum": 1,
+ "type": "integer"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Tasks, as {items: [task, ...]}. With `page` set, also page, limit and has_next.",
+ "properties": {
+ "has_next": {
+ "description": "True when another page exists (only when paginated).",
+ "type": "boolean"
+ },
+ "items": {
+ "description": "Returned entities.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo task.",
+ "properties": {
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "complete_till": {
+ "description": "Deadline, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "duration": {
+ "description": "Duration in seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "entity_id": {
+ "description": "ID of the entity the task is attached to.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "entity_type": {
+ "description": "Entity type, e.g. leads.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Task ID.",
+ "type": "integer"
+ },
+ "is_completed": {
+ "description": "Whether the task is completed.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "result": {
+ "description": "Completion result (object or array), may be empty."
+ },
+ "task_type_id": {
+ "description": "Task type ID (1 is follow-up).",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "text": {
+ "description": "Task description.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "limit": {
+ "description": "Page size used (only when `page` was requested).",
+ "type": "integer"
+ },
+ "page": {
+ "description": "Page number returned (only when `page` was requested).",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+}move_lead_stage1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The lead after the stage change.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}remove_tag1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The lead after the tag was removed (unchanged if absent).",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}send_chat_message1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "Kommo response for the posted chat message, passed through unchanged.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded messages.",
+ "properties": {},
+ "type": "object"
+ },
+ "_total_items": {
+ "description": "Number of messages created.",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+}update_contact1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The updated contact as returned by Kommo.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "first_name": {
+ "description": "First name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Contact ID.",
+ "type": "integer"
+ },
+ "last_name": {
+ "description": "Last name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Full name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}update_lead1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The updated lead as returned by Kommo.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded tags, contacts and companies.",
+ "properties": {
+ "tags": {
+ "description": "Embedded tags.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A Kommo tag.",
+ "properties": {
+ "color": {
+ "description": "Tag color, or null.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Tag ID.",
+ "type": "integer"
+ },
+ "name": {
+ "description": "Tag name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "_links": {
+ "additionalProperties": true,
+ "description": "HAL links as returned by Kommo (self, next, ...).",
+ "properties": {},
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closed_at": {
+ "description": "Closing time, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "closest_task_at": {
+ "description": "Next task deadline, Unix seconds, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_at": {
+ "description": "Creation time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "created_by": {
+ "description": "ID of the user who created it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "custom_fields_values": {
+ "description": "Custom field values in Kommo format: objects with field_id, field_code and values.",
+ "items": {
+ "additionalProperties": true,
+ "description": "One custom field with its values.",
+ "properties": {},
+ "type": "object"
+ },
+ "type": [
+ "array",
+ "null"
+ ]
+ },
+ "group_id": {
+ "description": "ID of the responsible user's group.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Lead ID.",
+ "type": "integer"
+ },
+ "is_deleted": {
+ "description": "Whether the lead is deleted.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "loss_reason_id": {
+ "description": "Loss reason ID, or null.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Lead name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "price": {
+ "description": "Lead budget.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "responsible_user_id": {
+ "description": "ID of the responsible Kommo user.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "status_id": {
+ "description": "Current stage ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_at": {
+ "description": "Last update time, Unix seconds.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "updated_by": {
+ "description": "ID of the user who last updated it.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}update_pipeline1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The updated pipeline.",
+ "properties": {
+ "_embedded": {
+ "additionalProperties": true,
+ "description": "Embedded resources.",
+ "properties": {
+ "statuses": {
+ "description": "Embedded statuses.",
+ "items": {
+ "additionalProperties": true,
+ "description": "A pipeline stage (status).",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Pipeline ID.",
+ "type": "integer"
+ },
+ "is_archive": {
+ "description": "Whether the pipeline is archived.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_main": {
+ "description": "Whether this is the main pipeline.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "is_unsorted_on": {
+ "description": "Whether the Incoming leads stage is enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Pipeline name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}update_stage1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": true,
+ "description": "The updated stage.",
+ "properties": {
+ "account_id": {
+ "description": "Kommo account ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "color": {
+ "description": "Hex color.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Stage ID.",
+ "type": "integer"
+ },
+ "is_editable": {
+ "description": "Whether the stage can be edited.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "name": {
+ "description": "Stage name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "pipeline_id": {
+ "description": "Parent pipeline ID.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "sort": {
+ "description": "Sort order.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "0 for regular stages, 1 for unsorted.",
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+}add_note2 fields changedInput schema / properties / lead_id / descriptionAdded value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."Input schema / properties / text / descriptionPrevious value: -"Note content"New value: +"Note content (plain text)."add_tag2 fields changedInput schema / properties / lead_id / descriptionAdded value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."Input schema / properties / tag_name / descriptionAdded value: +"Exact tag name (case-sensitive), e.g. \"vip\"."bulk_update_leads3 fields changedInput schema / properties / leads_updates / descriptionPrevious value: -"Array of {id, fields} objects"New value: +"Updates to apply, one per lead. Example: [{\"id\": 123, \"fields\": {\"status_id\": 456}}]."Input schema / properties / leads_updates / items / properties / fields / descriptionAdded value: +"Raw Kommo v4 lead fields to change for this lead (see update_lead)."Input schema / properties / leads_updates / items / properties / id / descriptionAdded value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."create_company1 field changedInput schema / properties / name / descriptionPrevious value: -"Company name"New value: +"Company name, e.g. \"Acme Inc\"."create_contact3 fields changedInput schema / properties / email / descriptionPrevious value: -"Email address"New value: +"Email address, e.g. jane@example.com."Input schema / properties / name / descriptionPrevious value: -"Contact full name"New value: +"Contact full name."Input schema / properties / phone / descriptionPrevious value: -"Phone number"New value: +"Phone number, ideally international, e.g. +15551234567."create_custom_field4 fields changedInput schema / properties / entity_type / descriptionPrevious value: -"leads, contacts, or companies"New value: +"Entity to add the field to: leads, contacts, or companies."Input schema / properties / enum_values / descriptionPrevious value: -"Values for select/multiselect fields"New value: +"Option labels for select or multiselect fields, in display order, e.g. [\"Low\", \"High\"]. Ignored by other types."Input schema / properties / field_type / descriptionPrevious value: -"text, numeric, select, multiselect, date, url, checkbox"New value: +"Kommo field type sent as-is, e.g. text, numeric, select, multiselect, date, url, checkbox."Input schema / properties / name / descriptionPrevious value: -"Field name"New value: +"Field display name."create_lead6 fields changedInput schema / properties / name / descriptionPrevious value: -"Lead name"New value: +"Lead name (title of the deal)."Input schema / properties / pipeline_id / descriptionPrevious value: -"Target pipeline ID"New value: +"Pipeline to create the lead in. Get IDs from list_pipelines. Omit to use the account default."Input schema / properties / price / descriptionPrevious value: -"Deal value"New value: +"Deal value in the account currency, e.g. 1500."Input schema / properties / responsible_user_id / descriptionPrevious value: -"Assigned user ID"New value: +"Kommo user ID to assign as owner. Omit for the default user."Input schema / properties / stage_id / descriptionPrevious value: -"Target stage ID"New value: +"Stage (status) to place the lead in. Get IDs from list_stages. Omit for the first stage of the pipeline."Input schema / properties / tags / descriptionPrevious value: -"Tag names"New value: +"Tag names to attach, e.g. [\"vip\", \"web\"]. Created if missing."create_lead_complex8 fields changedInput schema / properties / company_name / descriptionPrevious value: -"Company name"New value: +"Name of a new company to create and attach."Input schema / properties / contact_email / descriptionPrevious value: -"Contact email"New value: +"Contact email address."Input schema / properties / contact_name / descriptionPrevious value: -"Contact full name"New value: +"Name of a new contact to create. Phone and email are ignored unless this is set."Input schema / properties / contact_phone / descriptionPrevious value: -"Contact phone number"New value: +"Contact phone number, e.g. +15551234567."Input schema / properties / name / descriptionPrevious value: -"Lead name"New value: +"Lead name (title of the deal)."Input schema / properties / pipeline_id / descriptionAdded value: +"Pipeline for the lead. Get IDs from list_pipelines."Input schema / properties / stage_id / descriptionAdded value: +"Stage for the lead. Get IDs from list_stages."Input schema / properties / tags / descriptionAdded value: +"Tag names to attach to the lead. Created if missing."create_pipeline1 field changedInput schema / properties / name / descriptionPrevious value: -"Pipeline name"New value: +"Pipeline name, e.g. \"Enterprise\"."create_stage3 fields changedInput schema / properties / color / descriptionPrevious value: -"Hex color (e.g. #4CAF50)"New value: +"Hex color sent to Kommo as-is, e.g. #4CAF50. Optional; Kommo may restrict it to its own palette."Input schema / properties / name / descriptionPrevious value: -"Stage name"New value: +"Stage name, e.g. \"Negotiation\"."Input schema / properties / pipeline_id / descriptionAdded value: +"Kommo pipeline ID (integer). Obtain it from list_pipelines."create_task4 fields changedInput schema / properties / due_date / descriptionPrevious value: -"Due date as Unix timestamp"New value: +"Deadline as a Unix timestamp in seconds, e.g. 1767225600."Input schema / properties / lead_id / descriptionAdded value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."Input schema / properties / responsible_user_id / descriptionAdded value: +"Kommo user ID responsible for the task. Omit for the default."Input schema / properties / text / descriptionPrevious value: -"Task description"New value: +"Task description shown in Kommo."delete_lead1 field changedInput schema / properties / lead_id / descriptionPrevious value: -"The lead ID"New value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."get_contact1 field changedInput schema / properties / contact_id / descriptionAdded value: +"Kommo contact ID (integer). Obtain it from list_contacts or from the create_contact result."get_lead1 field changedInput schema / properties / lead_id / descriptionPrevious value: -"The lead ID"New value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."list_companies1 field changedInput schema / properties / limit / descriptionAdded value: +"Maximum companies to return. Default 50, capped at 100."list_contacts2 fields changedInput schema / properties / limit / descriptionAdded value: +"Maximum contacts to return. Default 50, capped at 100."Input schema / properties / query / descriptionPrevious value: -"Search query (name, phone, or email)"New value: +"Free-text search matched by Kommo against name, phone, and email, e.g. \"Jane\" or \"+15551234567\". Omit to list without filtering."list_custom_fields1 field changedInput schema / properties / entity_type / descriptionPrevious value: -"Entity type: leads, contacts, companies"New value: +"Entity whose fields to list: leads, contacts, or companies. Default \"leads\"."list_leads3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Max leads to return"New value: +"Maximum number of leads to return. Default 50."Input schema / properties / pipeline_id / descriptionPrevious value: -"Filter by pipeline ID"New value: +"Only leads in this pipeline. Get IDs from list_pipelines."Input schema / properties / stage_id / descriptionPrevious value: -"Filter by stage ID"New value: +"Only leads in this stage. Ignored unless pipeline_id is also set. Get IDs from list_stages."list_stages1 field changedInput schema / properties / pipeline_id / descriptionAdded value: +"Kommo pipeline ID (integer). Obtain it from list_pipelines."list_tags1 field changedInput schema / properties / entity_type / descriptionPrevious value: -"Entity type (lead, contact, company)"New value: +"Entity type, inserted as-is into the Kommo path /{entity_type}/tags. Default \"lead\"."list_tasks2 fields changedInput schema / properties / filter_overdue / descriptionAdded value: +"If true, only uncompleted tasks whose deadline has passed."Input schema / properties / lead_id / descriptionAdded value: +"Only tasks attached to this lead. Omit for all tasks."move_lead_stage3 fields changedInput schema / properties / lead_id / descriptionPrevious value: -"The lead ID"New value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."Input schema / properties / pipeline_id / descriptionPrevious value: -"Target pipeline ID (optional if same pipeline)"New value: +"Target pipeline ID. Only needed when the stage belongs to a different pipeline than the lead's current one."Input schema / properties / stage_id / descriptionPrevious value: -"Target stage ID"New value: +"Target stage ID. Get IDs from list_stages."remove_tag2 fields changedInput schema / properties / lead_id / descriptionAdded value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."Input schema / properties / tag_name / descriptionAdded value: +"Exact tag name (case-sensitive) to detach, e.g. \"vip\"."send_chat_message2 fields changedInput schema / properties / lead_id / descriptionAdded value: +"ID of a lead that already has an active conversation. Get it from list_leads."Input schema / properties / text / descriptionAdded value: +"Message text sent to the customer."update_contact2 fields changedInput schema / properties / contact_id / descriptionAdded value: +"Kommo contact ID (integer). Obtain it from list_contacts or from the create_contact result."Input schema / properties / fields / descriptionPrevious value: -"Fields to update"New value: +"Raw Kommo v4 contact fields to change, passed through unchanged. Common keys: name, first_name, last_name, responsible_user_id, custom_fields_values (array of {field_id, values: [{value, enum_code}]}; field IDs from list_custom_fields). Example: {\"name\": \"Jane Roe\"}."update_lead2 fields changedInput schema / properties / fields / descriptionPrevious value: -"Fields to update"New value: +"Raw Kommo v4 lead fields to change, passed through unchanged. Common keys: name (string), price (integer), status_id (stage ID), pipeline_id, responsible_user_id, custom_fields_values (array of {field_id, values: [{value}]}), _embedded.tags (full replacement list of {id}). Example: {\"name\": \"Acme renewal\", \"price\": 2000}."Input schema / properties / lead_id / descriptionPrevious value: -"The lead ID"New value: +"Kommo lead ID (integer). Obtain it from list_leads or from the create_lead result."update_pipeline2 fields changedInput schema / properties / name / descriptionAdded value: +"New pipeline name."Input schema / properties / pipeline_id / descriptionAdded value: +"Kommo pipeline ID (integer). Obtain it from list_pipelines."update_stage5 fields changedInput schema / properties / color / descriptionAdded value: +"New hex color, e.g. #4CAF50, sent to Kommo as-is."Input schema / properties / name / descriptionAdded value: +"New stage name."Input schema / properties / pipeline_id / descriptionAdded value: +"Kommo pipeline ID (integer). Obtain it from list_pipelines."Input schema / properties / sort / descriptionAdded value: +"New sort position; lower values appear first (e.g. 10, 20)."Input schema / properties / stage_id / descriptionAdded value: +"Stage ID within that pipeline. Obtain it from list_stages."v1.0.0add_noteadd_tagbulk_update_leadscreate_companycreate_contactcreate_custom_fieldcreate_leadcreate_lead_complexcreate_pipelinecreate_stagecreate_taskdelete_leadget_contactget_leadlist_chat_templateslist_companieslist_contactslist_custom_fieldslist_leadslist_pipelineslist_stageslist_tagslist_tasksmove_lead_stageremove_tagsend_chat_messageupdate_contactupdate_leadupdate_pipelineupdate_stageScored across 30 tools
Every tool targets a distinct entity+action, and the descriptions proactively resolve the few natural overlaps (update_lead vs move_lead_stage vs bulk_update_leads, create_lead vs create_lead_complex, add_note vs send_chat_message). Cross-references like 'use X instead of Y' make selection unambiguous. No two tools appear to do the same thing.
Consistent verb_noun snake_case throughout (create_lead, update_lead, delete_lead, list_leads, create_stage, update_pipeline, add_tag, remove_tag, send_chat_message). Pluralization is applied sensibly for list operations. No mixed conventions or vague verbs.
30 tools is on the heavy side, but the domain genuinely spans leads, contacts, companies, pipelines, stages, tasks, tags, notes, chat, and custom fields, so most tools earn their place. It is comprehensive rather than padded, though a few operations could be consolidated.
Leads have full lifecycle coverage (create/get/list/update/delete/move/bulk), but other entities are partial: contacts lack delete, companies have only create/list (no get/update/delete), tasks lack get/update/delete, and pipelines/stages/custom fields lack delete/update in places. These gaps will force workarounds for maintenance workflows.
Connect AI to your Attio CRM. Manage contacts, companies, deals, and sales pipelines. Create tasks…
Your own CRM, fully customizable and agent-driven. Start with contacts, companies and a sales pipeli
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
Operate Obriym CRM from your AI assistant: leads, deals, orders, catalog, stock, marketplaces.
