Kommo Kiro MCP

Overview Schema Source Related Servers Discussions Admin

create_lead_complex

Create a lead with a new contact and/or company in one Kommo CRM request, returning IDs and merge status; use simple lead creation when no contact/company is needed.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`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"}]}].

Output Schema

TableJSON Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed24 schema fields changedv1.0.5Oct 5, 2026

changedOutput schema / description

Previous 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."

removedOutput schema / properties / _embedded

Removed 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"
-}

removedOutput schema / properties / _links

Removed value: -{
-  "additionalProperties": true,
-  "description": "HAL links as returned by Kommo (self, next, ...).",
-  "properties": {},
-  "type": "object"
-}

removedOutput schema / properties / account_id

Removed value: -{
-  "description": "Kommo account ID.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / closed_at

Removed value: -{
-  "description": "Closing time, Unix seconds, or null.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / closest_task_at

Removed value: -{
-  "description": "Next task deadline, Unix seconds, or null.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

addedOutput schema / properties / company_id

Added value: +{
+  "description": "ID of the created or linked company.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

addedOutput schema / properties / contact_id

Added value: +{
+  "description": "ID of the created or linked contact.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

removedOutput schema / properties / created_at

Removed value: -{
-  "description": "Creation time, Unix seconds.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / created_by

Removed value: -{
-  "description": "ID of the user who created it.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / custom_fields_values

Removed 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"
-  ]
-}

removedOutput schema / properties / group_id

Removed value: -{
-  "description": "ID of the responsible user's group.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / is_deleted

Removed value: -{
-  "description": "Whether the lead is deleted.",
-  "type": [
-    "boolean",
-    "null"
-  ]
-}

removedOutput schema / properties / loss_reason_id

Removed value: -{
-  "description": "Loss reason ID, or null.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

addedOutput schema / properties / merged

Added value: +{
+  "description": "True when Kommo merged the lead into an existing duplicate.",
+  "type": "boolean"
+}

removedOutput schema / properties / name

Removed value: -{
-  "description": "Lead name.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / pipeline_id

Removed value: -{
-  "description": "Pipeline ID.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / price

Removed value: -{
-  "description": "Lead budget.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

addedOutput schema / properties / request_id

Added value: +{
+  "description": "Request IDs sent for this lead.",
+  "items": {
+    "description": "Request ID.",
+    "type": "string"
+  },
+  "type": "array"
+}

removedOutput schema / properties / responsible_user_id

Removed value: -{
-  "description": "ID of the responsible Kommo user.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / status_id

Removed value: -{
-  "description": "Current stage ID.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / updated_at

Removed value: -{
-  "description": "Last update time, Unix seconds.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

removedOutput schema / properties / updated_by

Removed value: -{
-  "description": "ID of the user who last updated it.",
-  "type": [
-    "integer",
-    "null"
-  ]
-}

addedOutput schema / required
```
Added value: +[
+  "id"
+]
```

Changed2 schema fields changedv1.0.3Oct 3, 2026

addedInput schema / properties / custom_fields_values

Added 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"
+}

changedOutput 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"
+}

Changed8 schema fields changedOct 3, 2026

changedInput schema / properties / company_name / description

Previous value: -"Company name"New value: +"Name of a new company to create and attach."

changedInput schema / properties / contact_email / description

Previous value: -"Contact email"New value: +"Contact email address."

changedInput schema / properties / contact_name / description

Previous value: -"Contact full name"New value: +"Name of a new contact to create. Phone and email are ignored unless this is set."

changedInput schema / properties / contact_phone / description

Previous value: -"Contact phone number"New value: +"Contact phone number, e.g. +15551234567."

changedInput schema / properties / name / description

Previous value: -"Lead name"New value: +"Lead name (title of the deal)."

addedInput schema / properties / pipeline_id / description

Added value: +"Pipeline for the lead. Get IDs from list_pipelines."

addedInput schema / properties / stage_id / description

Added value: +"Stage for the lead. Get IDs from list_stages."

addedInput schema / properties / tags / description

Added value: +"Tag names to attach to the lead. Created if missing."

First observedv1.0.0Oct 3, 2026

TDQS

A4.7/5.0

Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.