Kommo Kiro MCP

by sam-wilkie

Overview Schema Source Related Servers Discussions Admin

Python

Local

list_companies

Read-onlyIdempotent

Retrieve companies from Kommo CRM in read-only pages, using limit and page to browse up to 250 records per request.

Instructions

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.

Input Schema

TableJSON Schema

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.

Output Schema

TableJSON Schema

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).

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.0.3Oct 3, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum companies to return. Default 50, capped at 100."New value: +"Companies per page. Default 50, capped at 250."

addedInput schema / properties / limit / maximum
```
Added value: +250
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

addedInput schema / properties / page

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

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

Changed1 schema field changedOct 3, 2026
- addedInput schema / properties / limit / description
```
Added value: +"Maximum companies to return. Default 50, capped at 100."
```
First observedv1.0.0Oct 3, 2026

TDQS

A3.5/5.0

Behavior3/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.