kommo-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.0
Disambiguation2/5
Many tools overlap heavily: every entity has both update (batch) and update_one variants, causing confusion. Analytics tools (kommo_leads_summary, kommo_pipeline_analytics, kommo_sales_report) and search/list tools (kommo_leads_search vs kommo_leads_list) have unclear boundaries. Several call-related tools (kommo_incoming_leads_add_call vs kommo_calls_add) serve similar purposes.
Naming Consistency3/5
Most tools follow a kommo_<entity>_<action> pattern with list/get/create/update/delete, but there are notable deviations like kommo_files_create_session, kommo_files_upload_part, kommo_dashboard_get, and kommo_sales_report. The consistent use of 'update_one' and 'assign_one' as suffixes is predictable, but mixed verbs like 'add' vs 'create' and 'launch'/'stop' for bots break the uniformity.
Tool Count1/5
152 tools is an extreme number for any MCP server. While the Kommo API is broad, exposing every endpoint individually creates an unwieldy surface. This far exceeds reasonable scoping, overwhelming agents and requiring significant selection effort.
Completeness3/5
The tool set covers a wide range of CRM resources (leads, contacts, companies, pipelines, tasks, notes, tags, files, etc.), but several gaps exist: no tag deletion, no catalog custom field delete, no salesbot update/delete, and no direct lead delete tool. The analytics and search conveniences compensate somewhat, but dead ends remain.
Average 3.2/5 across 152 of 152 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare openWorldHint and idempotentHint, which cover side-effect potential and idempotency, but the description adds no additional behavioral context such as permissions required, what properties are editable, or consequences of updating roles. It largely restates the tool's name with no extra detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short ('Edit user roles.'), which is not concise but under-specified. It offers minimal information beyond the title and fails to include essential usage or parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though the tool is simple (1 param, no output schema), the description is insufficient to invoke it correctly. It does not explain the required structure of the roles array or how updates are applied. The combination of a generic schema and a terse description leaves the agent without adequate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single 'roles' array parameter with no defined object structure (propertyNames and additionalProperties are generic). The description provides zero parameter information, leaving the agent without knowledge of what each role object should contain (e.g., ID, name, permissions). With 0% schema coverage, this is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Edit') and a resource ('user roles'), but the phrase 'user roles' is ambiguous—it could mean editing role definitions or editing roles assigned to users. It distinguishes from siblings by operation (update vs create/delete), but the vagueness of the target resource reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus kommo_roles_create/list/delete, nor any prerequisites or context. The description does not mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare (openWorldHint, idempotentHint). It does not disclose whether updates replace or merge existing fields, side effects, permission requirements, or what happens on partial failure, leaving the agent to guess.
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?
The description is a single short sentence with no redundant wording, making it highly concise and easy to parse. However, it is so terse that it borders on under-specification, similar to 'Process'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This mutation tool lacks an output schema and provides minimal description. The critical behavior is undefined: whether the update is additive, replaces the entire field set, or only touches specified fields. Given the existence of update_one, the incomplete explanation is particularly problematic for correct agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not compensate. The 'fields' parameter is an array of arbitrary objects with propertyNames but no semantics—what keys are allowed, how to identify existing fields, or the expected format. 'catalog_id' is only implied by the name, not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (catalog custom fields) and action (update), but it is essentially a restatement of the title with no additional specifics. It does not distinguish itself from the sibling tool kommo_catalog_custom_fields_update_one, nor does it clarify whether this is a batch operation or what 'update' entails beyond a generic verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many update-related siblings (update_one, update for other entities), there is no mention of batch vs. single-field scope, or any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint=true, but the description adds no behavioral context beyond that. It does not disclose what the free-form body requires, what happens after creation, or any side effects. For a tool that creates a plugin/chat button, expectations about required fields or external effects are entirely absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, essentially restating the title. It is under-specified rather than concise, providing no structured breakdown of inputs or outcomes. The slash creates ambiguity without clarifying the resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a free-form body parameter, no output schema, and openWorldHint, the description should provide examples or field expectations. It does not. The tool is likely unusable without external knowledge of the Kommo CRM API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the schema only defines a generic 'body' object with no property constraints. The description does not explain what the body should contain (e.g., plugin name, chat widget settings). The single parameter is semantically opaque.
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?
The description uses the verb 'Create' with resource 'CRM plugin / website chat button', which clearly identifies a create operation distinct from sibling tools like list, get, update, and connect_chat. The slight ambiguity of the slash between 'CRM plugin' and 'website chat button' prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that listing, retrieving, updating, or connecting chat are handled by other tools, nor does it explain prerequisites or typical scenarios. The description is purely a definition, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations provide idempotentHint and openWorldHint, but the description adds no behavioral context beyond what the annotations already tell us. It does not explain what the update does, whether it is a partial or full update, or what side effects may occur. The description merely restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it is under-specified to the point of being a tautology. It adds no information beyond the tool title and does not help the agent understand usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and low-parameter schema descriptions, the description should explain what the tool returns and what the body should contain. It does neither. The tool is a simple update but relies on a complex, undocumented body object, making the description highly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the description does not explain the 'id' or 'body' parameters. For 'body', there is no indication of expected fields or structure, which is critical because the schema allows arbitrary properties. The description completely fails to compensate for the lack of schema descriptions.
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?
The description uses a clear verb ('Update') and resource ('CRM plugin / website chat button'). It distinguishes the tool from siblings like list/get/create, though the slash creates slight ambiguity about whether plugins and chat buttons are the same resource. It does not differentiate from 'connect_chat', but the overall purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, nor does it explain when to use this update tool versus the 'update_one' variants seen across other resource types. No exclusions or alternatives are noted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the action of linking. With only the openWorldHint annotation (which relates to schema openness, not behavior), there is no information about side effects, reversibility, permissions, or what happens to the leads. The burden falls on the description, and it fails to provide context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence), but this brevity is a symptom of under-specification, not effective conciseness. It lacks critical information about parameters, behavior, and usage, so the single sentence does not earn its place as a useful specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters (including a nested object), no output schema, and minimal annotations, the description must provide substantial context. It does not explain what linking means, how the request should be structured, what the response might be, or any required prerequisites. This is critically incomplete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to the parameters. The schema only shows 'uid' (string) and 'body' (object) with 'link payload' as the body description, which is vague. Schema coverage is only 50% (the body has a weak description, uid none). The description does not explain what uid represents or what structure the body should take, leaving the agent without needed semantic guidance.
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?
The description clearly states the action ('Link') and the specific resource ('incoming lead') and target ('existing lead'), which distinguishes it from generic link tools like kommo_links_link. However, it does not elaborate on what 'link' entails beyond the action itself, so it is clear but not fully detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are no mentions of prerequisites, exclusions, or scenarios where another tool would be preferred. The purpose implies a situation (having an incoming and existing lead), but it does not explicitly address alternatives or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations include idempotentHint and openWorldHint, but the description adds no extra behavioral context beyond stating the operation. It does not explain whether updates are partial, what fields are affected, or any side effects, leaving the agent reliant on assumptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, making it front-loaded and technically concise. However, this brevity comes at the cost of omitting critical details, so it is not appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested 'element' parameter, lack of an output schema, and a large set of sibling tools, this one-line description is severely incomplete. It provides insufficient context for an agent to safely invoke the tool without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description provides no explanation of the 'element' object parameter, which is a complex nested object. The only parameter mentioned is 'ID', leaving the agent with no understanding of how to structure the update payload.
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?
The description clearly states the action (update), resource (catalog element), and scope (single element by ID). This distinguishes it from list/get/create operations, though it does not explicitly differentiate it from the sibling 'update' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_catalog_elements_update or create. There are no exclusions, prerequisites, or context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats the action of creating. It does not disclose any additional behavioral traits such as idempotency, validation behavior, or response format. The annotation 'openWorldHint' provides some context but is not leveraged or explained in the description.
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?
The description is a single front-loaded sentence with no wasted words. However, it is so terse that it fails to convey necessary context, which slightly detracts from its conciseness value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the freeform array of objects with no schema details and no output schema, the description is severely incomplete. It provides no information about required fields, validation, return values, or error scenarios, making it nearly unusable for an agent without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to the 'companies' parameter. The schema merely says 'Company object per Kommo API' without field details, and the tool description gives no help on constructing valid objects.
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?
The description clearly states the verb ('Create') and resource ('companies'), and specifies batch capability ('one or more'). It distinguishes from sibling tools by resource and action, though it lacks any scope clarifications like the get_calls example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites, no exclusions. The only implied usage is from the verb 'Create', which is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a state-changing action ('Link') but does not disclose effects such as overwriting existing connections, required permissions, or reversibility. The openWorldHint annotation provides minimal behavioral context, leaving the description to carry the burden, which it fails to do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy, but it is under-specified rather than appropriately concise. While it avoids fluff, the brevity sacrifices essential information, making it less useful than a slightly longer description with parameter context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters including a nested object, no output schema, and minimal annotations, so the description must explain parameters and return behavior. It provides almost no context, missing details about the id meaning, body requirements, and what the result of linking looks like. This is inadequate for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate by explaining the parameters. It does not mention 'id' or 'body' at all, leaving the meaning of these fields entirely ambiguous (e.g., which ID is expected, what body contains). The generic parameter names provide no additional insight beyond the schema.
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?
The description states a specific action (link an online chat) with a specific resource (a CRM plugin), which clearly distinguishes it from CRUD operations on plugins in the sibling list. However, it is slightly ambiguous whether 'CRM plugin' refers to a Kommo plugin or the website button mentioned in the title, and it does not explicitly differentiate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context (e.g., setting up website chat), or when not to use it. The description solely states the action without any situational cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the fact that it updates a field. Annotations include idempotentHint and openWorldHint but not readOnly/destructive hints, so the agent is left uninformed about side effects, permissions, or whether the update is partial or full replacement. The description does not contradict annotations, but it also does not enrich them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, demonstrating conciseness. However, it approaches under-specification: it adds only 'by ID' beyond the title and provides minimal value relative to the tool's parameters and context. It is not verbose, but it fails to earn its place by omitting nearly all useful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three required parameters (one being a complex nested object), no output schema, and sparse annotations, the description is far too thin. It does not explain return values, error scenarios, or the structure of the update payload, leaving the agent without essential context for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'ID', leaving the required 'entity_type' enum and the nested 'field' object completely unexplained. The agent must infer the meaning of these parameters solely from the schema, which is inadequate for correct tool usage.
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?
The description states a specific verb ('Update'), resource ('custom field'), and scope ('one ... by ID'), which clearly communicates the tool's core function. It is distinguishable from sibling tools like kommo_custom_fields_update (likely batch) by the word 'one', though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as kommo_custom_fields_update, kommo_custom_fields_create, or kommo_custom_fields_delete. There is no mention of prerequisites, entity type selection, or suitability for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint: true. The description simply restates the action and endpoint, adding no behavioral context such as side effects, expected response format, required permissions, or error conditions. With such sparse annotations, the description carries a heavy burden and fails to disclose meaningful behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one line containing the action and endpoint—which is easy to scan. However, the brevity sacrifices essential detail, so it is under-specification rather than efficient minimalism. It earns a midpoint score for structure but loses points for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has no output schema and minimal annotations, so the description must explain request requirements and expected results. It provides neither: no information about the items schema, what the API returns, or how form leads differ from other lead sources. The description is inadequate for safely invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The sole parameter 'items' is an array of objects with no property descriptions, and the description does not mention it at all. The agent cannot infer what items should contain, how many are valid, or any structure requirements, making the parameter effectively undocumented.
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?
The description clearly states the action ('Add') and resource ('incoming leads from forms') and includes the endpoint 'POST /leads/unsorted/forms', which distinguishes it from sibling tools like kommo_incoming_leads_add_call. However, it does not elaborate on what 'forms' data looks like or the unsorted-lead context, so it stops just short of full clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as kommo_leads_create or kommo_incoming_leads_add_call. There are no stated prerequisites, exclusions, or context for form-based incoming leads, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint, which adds minimal behavioral context. The description does not disclose side effects, validation behavior, return values, or any other operational aspects, leaving the agent without critical behavioral safety information.
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?
The description is extremely concise, consisting of a single short sentence with no filler. It is front-loaded and to the point, though it sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested array parameter, lack of output schema, and sparse annotations, this description is severely under-specified. The agent cannot determine what 'sources' entails or what happens after creation, making it inadequate for reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single parameter 'sources' with 0% description coverage, and the description does not explain what this parameter should contain. The agent has no information about required fields, format, or semantics of the source objects.
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?
The description clearly states the verb 'Create' and the resource 'integration sources', making it evident this is a creation operation. However, it doesn't distinguish this from other source-related actions like update or delete beyond the verb itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like kommo_sources_update or kommo_sources_delete. The description provides no context about prerequisites, use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint: true already signals destructive behavior, and the description's 'Destructive' adds no extra context beyond that. It does not disclose irreversibility, required permissions, rate limits, or response behavior, so it adds minimal value beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, but 'Destructive' is redundant because the annotation already says destructiveHint: true. It could have used that space for more valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple tool with one parameter and no output schema, the description leaves out essential context: what 'sources' are, how to structure the batch input, what happens after deletion, and any prerequisite conditions. The annotation covers destructive intent, but the description is too sparse for an agent to reliably invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description was expected to explain the 'sources' parameter, but it only says 'Delete sources in batch.' It does not clarify that sources is an array of objects with id fields, nor what those ids refer to. The input schema exists but the description adds no semantic meaning.
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?
The description 'Delete sources in batch' clearly states the verb, resource, and scope, distinguishing it from the singular kommo_sources_delete tool. However, it could have explicitly named the sibling alternative for even clearer differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this batch deletion tool versus kommo_sources_delete for single deletions. The description implies batch use but does not explicitly state alternate scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide openWorldHint and idempotentHint, but the description adds little beyond 'batch' and does not disclose overwrite semantics, required identifiers, partial-failure behavior, or whether updates are full replacements. For a mutating tool, this is thin.
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?
The description is a single, front-loaded sentence with no filler; every word contributes meaning. However, it is extremely sparse given the complexity of a batch update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a vague input schema, no output schema, and no behavioral detail, the description is insufficient for confident invocation. Critical aspects like payload item structure and update semantics are entirely unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the lone 'templates' parameter is a generic array of arbitrary objects. The description does not explain what each object should contain (e.g., template id, fields to update), so the agent cannot construct a valid request.
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?
The description states the action ('Edit'), resource ('chat templates'), and scope ('in batch'), making it clear this is a bulk update tool. It distinguishes itself from sibling create/delete/get/list operations, though it doesn't detail which template fields can be changed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, no prerequisites are mentioned, and there is no mention of single-template updates or relationship to related tools. The only implied use case is editing multiple templates at once.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The openWorldHint annotation is present, but the description adds no behavioral context beyond the annotation. It does not explain side effects, reversibility, or what 'edit status' implies for the WABA review process. The description merely restates the action without illuminating consequences.
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?
The description is a single short sentence with no filler, making it very concise. While it is technically efficient, the brevity borders on under-specification, but it earns credit for absolute lack of verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested 'body' parameter, requires an id, and has no output schema, so the description must explain the expected payload and workflow. It does not. The agent lacks information about valid status values, review semantics, or response behavior, making the description critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description gives no explanation of the 'id' or 'body' parameters. The agent cannot infer what the body object should contain (e.g., status value, review action) or what the id references, making correct invocation nearly impossible.
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?
The description uses the specific verb 'Edit' and names the resource 'WABA template review/status,' which helps distinguish it from sibling tools like kommo_templates_update that likely handle content editing. However, the phrase 'review/status' is ambiguous—it could mean either review or status, or both—so it is not fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as kommo_templates_update or kommo_templates_waba_submit. There is no mention of prerequisites, context, or exclusion criteria, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include openWorldHint, offering no behavioral disclosure. The description implies a state-changing action but does not explain consequences like the template becoming pending, being locked for edits, or requiring additional permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and concise in length, but it is under-specified. It states the core purpose but lacks necessary detail, so it doesn't fully earn its place as a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, an unexplored nested object parameter, and no behavioral context, the description is severely incomplete. It fails to clarify what moderation entails, what the body should contain, or what response to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 'id' or 'body' parameters. The nested 'body' object is entirely unexplained, leaving the agent to guess its structure and purpose.
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?
The description clearly states the tool submits a WABA template for moderation, using a specific verb and resource. It distinguishes from sibling template tools like create/update/delete by indicating a moderation submission action, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus other template tools, nor does it mention any prerequisites or context. It simply restates the action without explaining the approval workflow or alternative paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only an openWorldHint annotation and no readOnly/destructive hints, the description must disclose behavioral context. It does not mention permission requirements, idempotency, what happens to existing users, or validation behavior. 'Add users to the account' adds negligible insight beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one short sentence, but it is under-specified and merely restates the title and tool name. It lacks the substance expected for a create operation and does not earn its place by adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a create tool with an unstructured parameter array and no output schema, the description is severely inadequate. It fails to explain what constitutes a valid user object, what the response will be, or what permissions are needed. The annotation does not compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage; the 'users' array's object structure is completely unconstrained. The description does not explain what fields each user object must contain, the expected format, or any constraints. This leaves the agent without critical information for invocation.
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?
The description uses a specific verb 'Add' and resource 'users' with scope 'to the account', clearly distinguishing it from sibling user tools like kommo_users_list, kommo_users_get, kommo_users_activate, and kommo_users_deactivate. It is unambiguous about the create semantic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, exclusions, or context. It merely states the action without any situational or alternative-tool information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation openWorldHint suggests uncertain side effects, but the description does not add any behavioral context such as implications for existing fields, validation, idempotency, or response format. The description carries no extra transparency beyond the basic action, which is insufficient for a mutation with open-world hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is under-specified for a tool with two required parameters and nested schema. It does not earn its place as it provides minimal value beyond the tool name. Conciseness is not a substitute for missing crucial information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested array of arbitrary objects), no output schema, and only an openWorldHint annotation, the description is grossly incomplete. It lacks details about required field properties, constraints, expected response, and typical usage. The description does not adequately inform an agent how to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of catalog_id or the structure of the fields array. The field parameter is an array of objects with arbitrary properties, and the description gives no hint about required properties or field naming conventions. The description fails to compensate for the lack of schema documentation.
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?
The description 'Add custom fields to a catalog' clearly identifies the action (create/add), the target resource (catalog custom fields), and distinguishes from sibling tools like kommo_custom_fields_create and kommo_catalog_custom_fields_update. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes kommo_custom_fields_create and kommo_catalog_custom_fields_update, but the description does not clarify that this tool is for catalog-specific fields or distinguish its use case. Missing exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only restates the tool name ('List talks/conversations') and adds the scope 'in the account'; it does not disclose any behavioral traits beyond the annotations already indicate (readOnlyHint true, openWorldHint true), such as pagination or filtering behavior.
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?
The description is a single, focused sentence that wastes no words; it is front-loaded with the verb and resource, making it efficient and easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters and no output schema, the description does not explain how to use filters or what the response contains; it is too minimal for effective use beyond a simple list call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description contains no parameter information, and the schema has 0% description coverage; thus the agent must infer from parameter names alone (page, limit, filter_*) without knowing valid values or semantics, making it impossible to use filters correctly.
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?
The description states 'List talks/conversations in the account' with a clear verb and resource, and the scope 'in the account' distinguishes it from conversation-specific operations like get or messages_list. However, it does not explicitly name alternatives or clarify whether 'talks' and 'conversations' are synonymous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the various siblings; there is no mention of filtering, pagination, or why one would choose this over kommo_conversations_get or kommo_conversations_messages_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals no behavioral details beyond the action itself. It doesn't explain whether the update is a partial or full replacement, what happens to omitted fields, or the response format. The annotations (openWorldHint, idempotentHint) provide only minimal context and no contradiction, but the description fails to add meaningful transparency.
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?
The description is a single, concise sentence with no filler. It front-loads the verb and clearly names the resource. While it could be more informative, it is appropriately sized for a simple statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is grossly inadequate for this tool's complexity: it fails to explain the entity_type parameter (which accepts one of five enums), the group object structure, or the update semantics. With no output schema and only minimal annotations, the agent is left without critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description needed to explain the parameters. It only mentions 'by ID', giving minimal semantics for the id parameter. The entity_type and group parameters are completely undocumented, leaving the agent to guess their purpose and structure.
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?
The description 'Edit a field group by ID' uses a clear verb and resource, distinguishing it from sibling create/delete/get tools. However, it lacks specificity about the entity_type scoping and what edits are possible, so it doesn't fully rise to a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like the entity_type requirement or that the field group must already exist. Usage must be inferred from the tool's name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, but the description adds no context about consequences (e.g., whether links are permanently removed, if it can be undone, or if it affects other entities). It does not contradict annotations, but it also adds minimal value beyond the title.
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?
The description is a single terse sentence with no fluff, which is concise. However, it is under-specified for a complex operation, but conciseness itself is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, complex nested 'links' parameter, and a destructive hint, the description is insufficient. It provides a basic action but fails to explain what constitutes a valid 'link', what 'parent' means, or return behavior. This is a clear gap for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides zero information about the parameters. The schema itself has 3 required params (entity_type, entity_id, links) with unclear semantics, and the description does not clarify what 'parent' refers to or the structure of 'links'. The agent must guess.
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?
The description 'Unlink entities from a parent' clearly states the action (unlink) and the resource (entities from a parent). It distinguishes from sibling kommo_links_link by being the inverse operation, though 'entities' and 'parent' are somewhat generic without schema context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or contrast with kommo_links_link or kommo_links_list. The agent is left to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint:true, which does not describe read/write safety, so the description carries the full burden. It states the action but omits side effects, idempotency, return behavior, or errors if the note is not pinned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it is terse to the point of under-specification. Title and description overlap heavily, adding little unique information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations, the description is insufficient for a state-changing tool. It does not explain what unpinning entails, how the system responds, or what happens when the note is not pinned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter-level detail. It only echoes 'note' and 'entity' without explaining entity_type values or how entity_id and note_id relate.
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?
The description clearly states a specific action ('Unpin') and resource ('a note on an entity'), making the tool's purpose unambiguous. It does not explicitly differentiate from kommo_notes_pin, but the verb alone distinguishes it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like kommo_notes_pin, nor does it mention prerequisites such as the note needing to be pinned. No contextual or exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the generic update action. Annotations provide idempotent and openWorld hints, but the text does not explain whether the update is partial or full replacement, how missing IDs are handled, or any side effects. It only restates the obvious.
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?
The description is a single, clear sentence that states the core action efficiently. It is front-loaded and has no wasted words, though its brevity borders on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested 'source' object and absence of an output schema, the description is insufficiently complete. It does not explain the expected format of the source object, the nature of the update (merge vs replace), or what the response contains. More context is needed for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description needed to explain the parameters, but it only mentions 'by ID' for the id parameter and does not clarify the 'source' object structure or valid fields. The schema itself is minimal, so the description fails to compensate for the lack of parameter meaning.
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?
The description clearly states the tool updates a source by ID, identifying the verb and resource. However, it does not differentiate from the sibling tool kommo_sources_update, which likely has a similar purpose, so it lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_sources_update. There is no mention of preferred scenarios, prerequisites, or exclusions, leaving the agent without explicit decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the word 'Edit.' Annotations declare openWorldHint and idempotentHint, but the description does not clarify whether updates are partial or full, which fields are affected, or any side effects. No contradiction exists, but the description fails to leverage the annotation context.
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?
The description is a single, concise sentence with no fluff. It is front-loaded and easily parseable, though its brevity sacrifices essential detail. It earns points for efficiency but not for informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—three required parameters, a nested object, and no output schema—the description is far too sparse. It does not explain the status schema, the update behavior, or expected return values, making the tool difficult to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain pipeline_id, status_id, or the structure of the status object. The nested status object is completely undocumented, leaving the agent without any guidance on what to include.
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?
The description uses the verb 'Edit' to indicate a modification operation on a 'stage in a pipeline,' which clearly distinguishes it from list/get/create/delete sibling tools. It is specific about the resource but does not explicitly name alternatives or describe the scope of editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings like kommo_stages_create or kommo_stages_delete. The description does not mention prerequisites, use cases, or exclusions, leaving the agent to infer context from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint annotation, the description carries the full burden of behavioral disclosure. 'Create' clearly implies a write operation, but there is no information about idempotency, validation, partial failure behavior, or what happens if templates already exist. No contradiction with annotations exists, but the description is too sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is structurally clean, but it is under-specified. It seems more like a placeholder than a deliberate, concise explanation. Valuable information such as template structure and constraints is missing, so brevity is not an asset here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, one might argue a short description suffices, but this lacks critical context. There is no output schema, and the description does not mention return values, limits, or field requirements. For a creation operation, an agent needs more detail to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'templates' with 0% description coverage. It is a generic array of objects with no property details. The description merely says 'chat templates' and does not compensate by explaining the structure or required fields for each template object. The agent is left without essential information to construct valid input.
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?
The description clearly states the tool's function: 'Create chat templates in batch.' It uses a specific verb ('Create') and resource ('chat templates') and distinguishes it from sibling tools like kommo_templates_update or kommo_templates_delete. The batch scope is an additional useful qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or situations where other tools (e.g., kommo_templates_update) would be more appropriate. The only implied context is 'batch', but that is not explicit enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Install a widget into the account by code' with no details on side effects, reversibility, required permissions, or response behavior. The openWorldHint annotation indicates external effects, but the description itself adds no behavioral context beyond the basic mutation. Without any safety-related annotations like readOnlyHint or destructiveHint, this is a significant omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it is under-specified. It's not verbose, but the brevity sacrifices necessary detail. This is a middle ground: appropriately sized in word count but lacking substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters including a nested object, no output schema, and only openWorldHint annotation. The description fails to mention return values, the effect of settings, or any post-install behavior. Given this moderate complexity, the description is too sparse to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain both parameters. It only hints at 'code' (which maps to widget_code) but doesn't clarify its format or meaning. The 'settings' object parameter is completely unexplained. This falls short of compensating for the undocumented schema.
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?
The description clearly states the action ('Install') and resource ('a widget'), and specifies 'by code' which hints at the widget code parameter. This distinguishes it from sibling tools like kommo_widgets_list, kommo_widgets_get, and kommo_widgets_uninstall. However, it doesn't explicitly contrast with those siblings, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when installation is appropriate, or what to use instead (e.g., kommo_widgets_list for listing, kommo_widgets_uninstall for removal). This is a clear gap for a tool with many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation (listing is a read operation) but adds no new behavioral context beyond the annotations. It does not mention pagination, sorting, or error behavior, though with readOnlyHint present, the baseline bar is lower and the description is neither contradictory nor misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but it is almost a tautology of the title, adding minimal new information. It is concise but not effectively structured to convey additional value, such as usage context or parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with three parameters and no output schema, the description is incomplete: it does not explain return format, pagination behavior, or the significance of the required catalog_id. The annotations and schema partly compensate, but the description itself leaves the agent without a full understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the page, limit, or catalog_id parameters. The agent must infer all semantics from parameter names alone, with no compensating details in the description.
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?
The description states the verb 'List' and the resource 'custom fields for a catalog', which clearly indicates the tool's purpose. It is distinguished from the sibling tool kommo_custom_fields_list by the 'catalog' qualifier, but it does not explicitly contrast with alternatives or clarify the ambiguous parenthetical '(list)'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives like kommo_custom_fields_list or kommo_catalog_custom_fields_get. The only hint is the 'catalog' scope in the name, which provides weak implied usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint: true, which covers the safety profile, but the description adds no behavioral context beyond that. It does not mention what happens when the ID is not found, whether the response is a single object or array, or any error conditions. With annotations present, the bar is lower, but the description provides no extra transparency, so it remains minimal.
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?
The description is a single sentence, directly states the action and target, and contains no filler or redundant information. It is appropriately front-loaded and easy to parse, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is quite minimal. It does not explain what a 'CRM plugin / website chat button' is within the Kommo context, nor does it describe the return value, which is necessary because no output schema exists. The presence of many sibling tools, including both kommo_plugins and kommo_crm_plugins, further demands contextual guidance that is absent. This is below the minimum viable for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' with no description (schema description coverage 0%), and the description merely says 'by ID', which only restates the parameter name. It does not clarify what the ID represents, how to obtain it, or its format beyond the integer type already in the schema. The description fails to compensate for the zero schema coverage.
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?
The description clearly states the action ('Get') and the resource ('a CRM plugin / website chat button') with an ID parameter, which distinguishes it from the sibling list, create, update, and connect tools. It does not explicitly name alternatives, but the 'by ID' phrasing implies a single-item retrieval. This is clear but not as fully differentiated as examples that explicitly compare to sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as kommo_crm_plugins_list or kommo_crm_plugins_update. The description only states the function without any context or exclusions, so an agent may not know when to choose this over other plugin-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (openWorldHint, idempotentHint) provide some behavioral hints, but the description adds no context about whether updates merge or replace existing fields, what happens to unspecified fields, or required permissions. No contradiction with annotations.
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?
The description is a single, front-loaded sentence with no filler. It is appropriately concise for a simple tool, though it sacrifices necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, 0% parameter documentation, and a vague 'fields' array, the description is insufficient for an agent to construct a correct request. Sibling tools exist but are not referenced. The tool needs significantly more explanation to be usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It fails to explain the structure of the 'fields' array, the meaning of object keys, or how entity_type relates to the update. This is a critical gap for correct invocation.
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?
The description uses a specific verb ('Update') and resource ('custom fields') with the qualifier 'multiple', clearly distinguishing it from the sibling tool kommo_custom_fields_update_one. It states exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_custom_fields_update_one, kommo_custom_fields_create, or kommo_custom_fields_delete. The description gives no context, prerequisites, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and openWorldHint=true, so the agent knows it is destructive with potential side effects. However, the description adds no further context about what happens when a lead is declined (e.g., irreversible, moves to lost state, requires specific permissions), leaving the behavioral implications largely undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse and contains a redundant duplicate 'Decline/decline', making it awkward and under-specified. It is not a well-formed concise statement; it sacrifices clarity for brevity, providing minimal value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with an open-world hint and a nested payload parameter, the description is far from complete. It does not explain the effect of declining leads, how to construct the body (beyond vague uids/user_id), or what the response might be. The single-sentence description is inadequate for the tool's complexity.
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?
The schema’s description for the single 'body' parameter is 'Decline payload with uids / user_id', giving 100% coverage. The tool description adds no additional parameter information, so it does not exceed the baseline of 3 for schema-heavy coverage. The nested structure of the payload is still vague (additionalProperties allowed), but the description does not compensate further.
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?
The description states the action (decline) and the resource (unsorted/incoming leads), which is clear and specific. However, the phrasing 'Decline/decline unsorted leads' is redundant and does not explicitly distinguish from sibling tools like kommo_incoming_leads_accept, though the verb itself implies the opposite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context such as 'use this to reject leads that should not be accepted'. It is purely a two-word action with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no behavioral context such as pagination behavior, filtering semantics, authentication requirements, or response format. It essentially restates the operation without enriching the annotation information.
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?
The description is a single, front-loaded sentence with no wasted words. It is extremely concise and to the point, though it may be too terse to carry sufficient information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, no output schema, and a potentially overlapping sibling tool, the description is inadequate. It does not define what notes are, explain how filtering and sorting work, or describe the return structure. The minimal sentence covers only the basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter description coverage is only 10%, with only 'with' having a description. The tool description does not explain the meaning of parameters like filter_note_type, order_updated_at, or the pagination controls. It simply repeats the entity_type enum from the schema, failing to compensate for the low schema coverage.
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?
The description clearly states it lists notes for an entity type, with the allowed entity types enumerated in parentheses. However, it does not distinguish from the sibling tool kommo_notes_list_by_entity, which likely does the same thing, so sibling differentiation is lacking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_notes_list_by_entity or other list tools. The intended usage is implied but not explicitly stated, and no exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint=true, indicating side effects, but the description adds no specifics about what pinning does—such as whether it affects note ordering, visibility, or if there are restrictions. No behavioral traits beyond the broad annotation are disclosed.
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?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and efficiently states the core action. However, it may be too terse to convey important context, but that is a completeness issue, not a conciseness/structure issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing tool, the description is minimal. It does not explain the semantics of pinning, what outcome to expect, how it relates to unpinning, or any failure modes. The openWorldHint annotation signals side effects but does not specify them, leaving the agent without enough context to use the tool correctly beyond the obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (note_id, entity_id, entity_type). While the parameter names and the enum for entity_type provide some implicit context, the description fails to compensate for the lack of schema descriptions.
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?
The description 'Pin a note on an entity' uses a specific verb and resource, clearly indicating the action of pinning a note to an entity. It is concise and understandable, though it does not explicitly differentiate from sibling tools like kommo_notes_unpin in the description text itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of appropriate contexts, prerequisites, or comparisons to related operations like unpinning or listing notes. The sibling list includes kommo_notes_unpin, but the description does not reference it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not disclose whether the update is a partial merge or a full replacement, what happens if the pipeline does not exist, or what the response contains. Annotations indicate idempotency and open-world hints, but the description itself fails to explain the actual effect of the edit.
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?
The description is a single, front-loaded sentence that conveys the essential action without any filler. It earns its place entirely and is appropriately sized for the operation, though it sacrifices detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested object parameter and no output schema, yet the description provides minimal context. It does not explain the return value, the semantics of the pipeline object, or any side effects, leaving a critical gap in the agent's ability to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the opaque pipeline parameter, but it only mentions 'by ID' and leaves the 'pipeline' object completely undocumented. The 'pipeline' parameter is a nested object with arbitrary properties, and there is no guidance on required fields or structure, making it impossible for an agent to construct a valid update payload.
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?
The description uses a clear verb ('Edit') and specifies the resource ('a pipeline') with an identifier ('by ID'), which makes the tool's function unambiguous. It distinguishes from pipeline create/delete/list/get siblings, though it does not elaborate on what fields can be edited.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as pipeline create or delete, or how it relates to other update tools. There are no preconditions, exclusions, or alternative tool mentions, leaving the agent to infer usage solely from the generic 'Edit' phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only and open-world behavior. The description adds only the scope 'in the account' but does not disclose any additional behavioral traits such as pagination, filtering, or response format. It does not contradict 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words. It is appropriately front-loaded and easy to parse, though it lacks detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema and incomplete parameter documentation, this description is too sparse. It doesn't explain pagination, the meaning of 'with', or any usage context, making it insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. With schema coverage at only 33% (only 'with' is described), the description fails to compensate for the undocumented 'page' and 'limit' parameters. It adds no meaning beyond the schema.
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?
The description clearly states the tool lists users in the account, using a specific verb and resource. It distinguishes from sibling get/create/deactivate tools by saying 'list' rather than 'get' or 'create', though it doesn't explicitly call out alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives like kommo_users_get or kommo_users_create. The description simply states the action without providing context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint=true, which gives no safety or read/write clues. The description adds no information about batch size limits, required element structure, return values, or side effects, so the agent lacks transparency for a mutating operation.
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?
The description is one short sentence—'Add elements to a catalog.'—which is concise and front-loaded. However, it's too terse to convey usage or parameter details, but that's not necessarily a conciseness failure; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with two required parameters (catalog_id, elements) and no output schema, the description is insufficient. It does not specify how elements are structured, whether the catalog must already exist, or what a successful response looks like, leaving the agent with significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no parameter descriptions). The description does not explain catalog_id or the elements array, nor does it mention the requirement that elements must have at least one item. It is effectively a restatement of the tool's name.
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?
The description 'Add elements to a catalog' clearly names the verb (add) and resource (elements to a catalog), distinguishing it from sibling tools like kommo_catalog_elements_list/get/update. The tool name corroborates this, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as kommo_catalogs_create or kommo_catalog_elements_update, and there are no prerequisites or context clues. An agent would have to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint and openWorldHint, but the description adds no extra behavioral context. It does not disclose whether the update is partial or replaces the entire contact, what happens to unspecified fields, or error/response behavior. Since annotations do not cover destructive effects, the description carries this burden but fails to address it.
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?
The description is a single, clear sentence with no unnecessary words. It efficiently communicates the core action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with an open-world nested object, no output schema, and minimal annotations, the description is far too thin. It does not explain update semantics (partial vs full), error handling, return values, or how to construct a valid contact object, making the tool difficult to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (the contact object has a vague reference to the Kommo API, and id has no description). The description merely says 'by ID,' adding minimal clarity about the id parameter but nothing about the structure or required fields of the contact object, which is an open-world nested object.
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?
The description clearly states the verb (update), resource (contact), and scope (single, by ID). This distinguishes it from list/get/create tools, though it does not explicitly contrast with the sibling kommo_contacts_update (which likely updates multiple contacts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like kommo_contacts_update, nor any context about prerequisites such as auth, existing contact ID, or behavior on missing IDs. The only implied usage is that an ID is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats 'Destructive,' which is already captured by the destructiveHint annotation. It adds no additional behavioral context beyond the annotation, such as irreversibility, cascading deletion of field values, or permission requirements.
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?
The description is extremely brief ('Delete a custom field. Destructive.'), which is concise and front-loaded. However, it is perhaps too terse, missing opportunities to convey useful context without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description is incomplete. It does not mention that deletion is permanent or that it may affect associated data across entities. The destructiveHint annotation provides some safety awareness, but the description should elaborate on the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description provides no information about the parameters (id and entity_type). It does not explain how to specify which custom field to delete or what the enum values mean, leaving the agent with only raw schema names.
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?
The description clearly states the tool's function: 'Delete a custom field.' It uses a specific verb (delete) and resource (custom field), and this distinguishes it from sibling tools like create, update, list, or get for custom fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as choosing between custom fields and catalog custom fields, or any prerequisites. The description only states the action and a warning, with no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint, so safety is covered. The description adds no behavioral context beyond the action—no details about return format, error behavior, or relationship to the parent file.
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?
The description is a single, concise sentence with no wasted words. It is appropriately sized for a simple lookup operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and only sparse annotations. The description doesn't explain how version_uuid is obtained, what a version represents, or what response is expected. This is a simple read operation, but more context is needed for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), and the description doesn't mention the parameters. The agent must rely on the parameter names 'file_uuid' and 'version_uuid', which are somewhat self-explanatory but lack format or source guidance.
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?
The description clearly identifies the action ('Get') and resource ('specific file version'), distinguishing it from file-level operations like kommo_files_get. It doesn't elaborate on what a version is, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this over related tools. The description doesn't mention alternatives or context such as needing version history or when a file has multiple versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the action without disclosing side effects, permissions, idempotency, or return behavior. The openWorldHint annotation does not clarify safety or operational details, so the description adds little beyond the obvious.
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?
The description is a single concise sentence with no fluff, but it may be too terse to convey essential details. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's creation purpose and nontrivial parameter structure, the description is incomplete. It lacks context about role semantics, required fields, or what the response contains, and the openWorldHint annotation does not compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'roles' with 0% description coverage. The description does not explain what the roles array should contain, what properties each role object needs, or any constraints, leaving the agent without guidance for constructing a valid call.
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?
The description clearly states the action ('Create') and the resource ('user roles'), distinguishing it from sibling role tools like kommo_roles_list/get/update/delete. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as when creating multiple roles at once or how this relates to kommo_roles_update. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true and openWorldHint: true. The description's 'Destructive' label only repeats the annotation without adding new behavioral context such as cascading effects on deals, irreversibility, permissions, or what happens after deletion. The description adds no value beyond the structured annotation.
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?
The description is concise with two sentences: one for the action and one for the destructive warning. Both sentences earn their place with no fluff. However, it borders on under-specification, though for the purpose clarity dimension it remains focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple (2 integer params, no output schema), it is a destructive action. The description fails to explain the impact of deletion (e.g., whether deals are affected, if it's permanent, or what the response looks like). The annotations cover the destructive hint but not the operational consequences, leaving a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no additional meaning for the two parameters (pipeline_id and status_id). The parameter names are somewhat self-explanatory, but the description does not clarify the relationship between pipeline and stage, nor the expected values. There is no compensation for the schema's lack of descriptions.
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?
The description clearly states the verb 'Delete' and the resource 'a stage from a pipeline', which unambiguously distinguishes it from sibling tools like kommo_pipelines_delete (delete a pipeline) and kommo_stages_update (update a stage). The 'Destructive' warning further reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of conditions or prerequisites, and no explicit exclusions. The description merely states the action without contextual advice, which is insufficient for an agent choosing among the many stage and pipeline tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include only openWorldHint, with no readOnlyHint or destructiveHint, so the description must carry the behavioral burden. It states 'Add call notes' which implies mutation, but gives no details on side effects, permissions, return values, or consequences. The openWorldHint is not clarified.
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?
The description is two concise sentences with no filler. It front-loads the action and provides a useful field list. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no parameter descriptions, and minimal annotations, the description should provide more context. It fails to explain what 'entities' means, how to structure the calls array, or what happens after adding. The tool is simple, but the lack of guidance leaves too many gaps.
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?
The input schema is minimal with a single 'calls' array and no property descriptions. The description compensates somewhat by listing typical fields: 'phone, source, duration, call_status, call_result, link, direction, uniq, created_at.' However, it uses 'typically' without explaining types or requirements, so the added meaning is incomplete.
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?
The description states a specific action: 'Add call notes (call in/out) to entities.' This clearly identifies the verb and resource, and the mention of 'call in/out' adds specificity. However, it does not explicitly differentiate from sibling tools like kommo_incoming_leads_add_call, which also adds calls but to incoming leads specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention suitable entity types, prerequisites, or exclusions. There are many sibling tools for adding notes/calls, but no comparison or context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations contribute openWorldHint and idempotentHint, but the description adds no behavioral context beyond that. It does not disclose whether updates are partial or full replacements, how invalid element IDs are handled, or what the response looks like—critical gaps for an update operation.
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?
The description is a single, focused sentence that leads with the verb, making it concise and front-loaded. However, it is so brief that it sacrifices useful detail, though for conciseness alone it is excellent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a bulk update tool with no output schema and minimal annotations, the description should explain update semantics, response behavior, and error handling. It provides none of these, leaving the agent under-informed about how to correctly invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters. It implies the 'elements' array holds multiple elements but does not clarify its structure or the role of 'catalog_id'. Since the description fails to compensate for the missing schema descriptions, parameter meaning is largely undetermined.
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?
The description clearly states the action ('update'), the resource ('catalog elements'), and the scope ('multiple'), which distinguishes it from the sibling tool kommo_catalog_elements_update_one that handles a single element. This is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like update_one or create. The description only states what it does, not when it should be preferred, leaving the agent to infer usage from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare openWorldHint=true and idempotentHint=true, so the description adds no extra behavioral context. It does not disclose anything about partial failure, atomicity, required fields, or side effects. Sibling update tools often benefit from such context, but here the description is a bare restatement.
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?
The description is extremely concise and front-loaded, with no wasted words. However, its brevity borders on under-specification, making it effective for scanning but insufficient for understanding. It earns a high score for conciseness but not perfection due to lacking necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk update tool with no output schema and a vague open-world input schema, the description should explain what to pass and what to expect in return. It offers neither, leaving the agent with incomplete information to invoke the tool correctly. The low parameter description coverage and missing return-value semantics make this tool under-described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description must compensate. It only says 'catalogs' are updated, giving no clue about the structure of each catalog object or how the array is interpreted (e.g., partial vs full replace). With additionalProperties allowed, the agent is left without guidance on what fields to include.
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?
The description clearly states the action ('update') and the resource ('catalogs'), and specifies the scope ('multiple'), which distinguishes it from the sibling tool kommo_catalogs_update_one. It directly answers what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The word 'multiple' implies a bulk operation, but there is no mention of single-update alternatives, prerequisites, or scenarios where this tool is appropriate. The description does not help an agent decide between this and kommo_catalogs_update_one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint and openWorldHint, but the description adds no behavioral context. It does not disclose any side effects, permission requirements, or response behavior associated with updating a catalog, leaving the agent without critical operational details.
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?
The description is a single, front-loaded sentence with no redundant words. It is as concise as possible while stating the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested object parameters and no output schema, the description is drastically underspecified. It fails to describe the catalog object shape, update semantics, or how this differs from sibling update tools, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'id' or 'catalog' parameters. 'by ID' hints at the id parameter, but the 'catalog' object's structure and accepted fields are entirely unspecified, offering no value beyond the raw schema.
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?
The description 'Update a catalog by ID' clearly states the verb (update), resource (catalog), and scope (single item by ID). This distinguishes it from bulk update siblings like kommo_catalogs_update, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. No mention of when to use 'update_one' vs 'update' or any prerequisites, so the agent must infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, lowering the bar. The description adds context ('timeline activity') and indicates filters exist, but does not disclose pagination behavior, default ordering, or response structure, which are relevant for a list tool.
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?
The description is a single, front-loaded sentence with no wasted words. However, it is arguably too terse given the tool's complexity: 9 optional parameters and no output schema mean more detail would be justified while still remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no output schema, and minimal schema descriptions, the description does not provide enough context for an agent to understand response shape, pagination, or how filters interact. The readOnlyHin lowers safety concerns, but informational completeness is still lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 22%, and the two provided schema descriptions are value lists, not explanations of purpose. The description's generic 'with filters' does not map to any specific parameter, leaving 7 parameters completely unexplained. This is insufficient compensation for the schema gap.
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?
The description 'List account events (timeline activity) with filters' clearly identifies the operation (list) and resource (account events), adding the clarifying term 'timeline activity'. It distinguishes from siblings like kommo_events_get by using 'list' rather than 'get', but does not explicitly contrast with kommo_events_types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as kommo_events_get or kommo_events_types. The phrase 'with filters' implies filtering capability but does not explain filtering use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the openWorldHint annotation, which itself is not explained. It does not disclose side effects, permissions, reversibility, or what the response might look like.
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?
The description is a single sentence with no redundant words. While it is lean, it might be too sparse to fully carry the necessary information, but as a conciseness measure it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool involves a nested array parameter and an openWorldHint annotation, yet the description provides minimal context. It does not explain the array item structure, entity type implications, or side effects, making it incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'entity type' (matching the entity_type parameter) but does not explain the structure or semantics of the 'groups' parameter, leaving the agent without critical information for constructing valid input.
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?
The description clearly states the action (create), the resource (field groups), and the target context (entity type). It distinguishes from sibling field group tools (list, get, update, delete) by using a specific verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites, or exclusions. The description is a bare statement without any usage context or comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description merely repeats the 'Destructive' flag already present in annotations (destructiveHint=true), adding no additional behavioral context such as irreversibility, cascading effects, or permission requirements. With openWorldHint=true, more explanation would be valuable.
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?
The description is extremely concise at two short sentences, with no filler or redundant text beyond the necessary warning. It is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation with no output schema, the description offers only a terse warning. It does not explain what happens to associated data, whether the action is reversible, or how the required entity_type and id should be selected, leaving critical context absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention parameters. While the schema defines id and entity_type with an enum, the description fails to compensate for the lack of explanation about their meaning or relationship.
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?
The description clearly states the action 'Delete' and the resource 'field group', which precisely distinguishes it from sibling field group tools (list, get, create, update). It is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only warns 'Destructive' but does not explain prerequisites or scenarios for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, so the safe-read nature is already known. The description adds no additional behavioral context—nothing about return format, error handling, permissions, or how entity_type affects behavior. It simply repeats the action implied by the title.
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?
The description is a single concise sentence, well-structured and front-loaded. However, it is nearly redundant with the title, adding only 'by ID', so it is concise but at the expense of substantive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters, one of which (entity_type) is non-obvious, the description is incomplete. There is no explanation of how entity_type relates to field groups, what the response will include, or any caveats. The openWorldHint annotation is also unexplained, leaving the agent without sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'by ID', partially clarifying the id parameter, but gives no meaning for the required entity_type parameter with its enum of entity types. The description does not help an agent understand the purpose or valid values for entity_type.
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?
The description clearly states the tool retrieves a specific field group by ID, distinguishing it from list, create, update, and delete siblings. The verb 'Get' and resource 'field group' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_field_groups_list. It doesn't mention that this should be used when an ID is known, nor does it explain the need for entity_type. No usage context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds no additional behavioral context such as pagination behavior, response format, or filtering semantics. It merely restates the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy, but it is under-specified for a tool with six parameters. Still, it is concise and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and low annotation coverage, the description is too minimal. It omits crucial context about filtering, pagination, and what 'linked entities' means, making it inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, and the description does not explain parameters like filter_to_entity_id or page/limit. The entity_type enum is self-explanatory, but filter_to_entity_type expands beyond the main entity types (including catalog_elements) without clarification.
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?
Description uses specific verb 'List' and specifies resource ('entities linked to a lead, contact, company, or customer'), clearly distinguishing it from sibling link management tools like kommo_links_link/unlink.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other list tools or link management tools. No exclusions or alternatives mentioned; usage must be inferred from the title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint annotation, the description carries the transparency burden but only says what the tool does, not how it behaves (e.g., whether it validates, overwrites, or returns a result). It also contains a parameter-name mismatch (entity_id vs entity_type) that could mislead. No side effects or permissions are disclosed.
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?
The description is very brief (two sentences) and front-loaded with the key requirement. However, the repetition of 'Create notes' from the title is unnecessary, and the conciseness sacrifices critical clarity about the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters, no output schema, and no parameter descriptions, the description should fully compensate. It does not: it omits the entity_type enum, leaves the notes array structure opaque, and includes a conflicting 'entity_id' reference. The tool is underspecified for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions entity_id, note_type, and params, but the schema uses entity_type and a notes array. It gives a partial example ({ text }) but fails to explain the notes array structure or the allowed entity_type values, and the entity_id reference is misleading.
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?
The description states a clear verb ('Create') and resource ('notes'), distinguishing it from sibling list/get/update/pin/unpin tools. However, it introduces confusion by mentioning 'entity_id' while the schema uses 'entity_type', and the title is near-tautological with the first sentence.
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?
Usage is implied by the name and description: this is the creation tool for notes. There is no explicit contrast with alternatives like update or list, nor when/not to use it. The description only hints at required data, not context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds no additional behavioral context such as pagination behavior, return format, or permissions. The description 'List user roles' merely restates the title without enriching understanding.
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?
The description is a single concise sentence, which is appropriately brief for a simple list tool. However, it sacrifices useful detail, making it slightly under-specified. It earns points for brevity and front-loading the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a list operation with optional pagination and a mysterious 'with' parameter, yet the description provides no clarity on these. No output schema exists, so the description should explain what the agent can expect from the response, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (page, with, limit). While 'page' and 'limit' suggest pagination, 'with' remains ambiguous, and this ambiguity is not addressed. The description must compensate for the schema gap but fails to do so.
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?
The description 'List user roles' uses a specific verb (list) and resource (user roles), clearly distinguishing it from sibling kommo_roles_get which retrieves a single role. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention that kommo_roles_get should be used for a specific role, nor any context about prerequisites or pagination. The agent gets no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is clear. The description adds no extra behavioral context such as return format, errors, or whether the source might be external. It merely restates the operation, adding no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the verb and object, making it easy to parse. Perfectly sized for a simple get operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should help the agent understand what a source is and what the response looks like, but it provides none of that. For a tool with one parameter and simple semantics, the description is still too sparse to be considered complete in context.
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?
The schema has zero description coverage for the single 'id' parameter, so the description carries the burden. 'Get a source by ID' confirms that 'id' is the source identifier, but it does not explain what a source is or the format of the ID beyond the schema's numeric constraints. This minimal compensation merits a midpoint score.
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?
The description clearly states the verb 'Get' and resource 'source by ID', which distinguishes a single-item fetch from the sibling list operation. However, it does not explicitly contrast with other source tools like create/update/delete, so it falls short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of required context (e.g., needing a source ID from a prior list call) or any exclusions, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description offers no behavioral details beyond the action itself. It does not disclose side effects, idempotency, permission requirements, or impact on existing stages. The openWorldHint annotation exists but remains generic; the description does not clarify what this means for this specific tool.
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?
The description is a single, clear sentence with no redundant phrasing. It is front-loaded and easy to parse, which is appropriate for a simple tool name and title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters, zero schema descriptions, an openWorldHint annotation, and no output schema. The description does not explain what the tool returns, how statuses relate to pipeline stages, or what side effects to expect. It is insufficient for an agent to invoke the tool with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter semantics, yet it says nothing about the format or structure of 'statuses' or 'pipeline_id'. The word 'stages' only restates the resource without explaining how the statuses array should be populated, key names, or constraints.
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?
The description 'Add one or more stages to a pipeline' uses a specific verb ('Add') and clearly identifies the resource ('stages') and target context ('pipeline'). This distinguishes it from sibling tools like kommo_stages_list, get, update, and delete, which handle different operations on stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or situations where another tool (e.g., kommo_pipelines_update) would be more appropriate. Usage is only implied by the name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Update tags,' which implies a write operation, but does not disclose whether it replaces all existing tags, merges with tags_to_add, or deletes via tags_to_delete. It also omits details about behavior on invalid entity IDs, error handling, or permissions. With no readOnlyHint or destructiveHint in annotations, this lack of depth leaves the agent without critical behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words, which earns structural credit. However, it is under-specified: the sentence provides only the core action and misses essential details about the body parameter and usage context. This is not concise richness but terse incompleteness, warranting a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—a nested 'body' object with three possible operations, three required parameters, no output schema, and minimal annotations—the description is far too sparse. It does not explain how the body keys work together, differentiate from kommo_tags_assign, or indicate what the response looks like. An agent would need to infer or test extensively to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'body' has a description), and the tool description does not compensate. It adds no explanation of what the 'body' object expects beyond mirroring the schema's key names ('tags', 'tags_to_add', 'tags_to_delete'), nor does it clarify 'entity_type' or 'id' semantics. The one sentence focuses on the operation, leaving parameter meaning almost entirely to the schema.
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?
The description clearly states the tool's action: 'Update tags on a single entity by ID.' This includes a specific verb ('update'), a resource ('tags' on an 'entity'), and a scope ('single entity by ID'), which distinguishes it from the sibling kommo_tags_assign (likely for multiple entities). The title reinforces this by explicitly saying 'Assign tags to one entity,' making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as kommo_tags_assign, kommo_tags_create, or kommo_leads_update. While the 'single entity' wording implies use for one entity, it does not explicitly mention when to prefer this over the batch operation or other tag-related tools. No prerequisites, excluded scenarios, or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true and openWorldHint=true, so base safety is covered. However, the description adds no behavioral depth—it does not mention error handling, response shape, authorization requirements, or the effect of the 'with' parameter. It simply reiterates the operation without new context.
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?
The description is a single sentence with zero wasted words, front-loading the core action and target. However, it is so minimal that it merely mirrors the title, offering no additional structured guidance. It is concise but not necessarily well-developed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description is partially sufficient, but the undocumented 'with' parameter and lack of output schema information leave gaps. Annotations confirm read-only behavior, but the description does not explain what data is returned or how the optional parameter alters the response, which is necessary for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implicitly references the 'id' parameter ('by ID') but gives no detail on the 'with' parameter, which remains entirely unexplained. The description fails to clarify that 'with' might control related data inclusion or output formatting.
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?
Description says 'Get a user by ID' which clearly specifies a single-user retrieval operation with a specific verb, resource, and identifier. It distinguishes from sibling kommo_users_list by explicitly scoping to a single ID rather than a collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like kommo_users_list or kommo_users_create. There are no stated prerequisites, exclusions, or context cues for selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond what the annotations already convey (idempotentHint, openWorldHint). It does not explain how the 'field' object is applied (e.g., merge or replace), what happens on invalid input, or any side effects, leaving the agent with minimal understanding of the operation's nuances.
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?
The description is a single, focused sentence with no wasted words. It is front-loaded and to the point, though it could have included more useful details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested object parameters, no output schema, and no behavioral details, this description is severely incomplete. It fails to explain the structure of 'field', the response format, or any edge cases, making it difficult for an agent to invoke the tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions exist in the schema. The description does not compensate by explaining the meaning of catalog_id, id, or especially the 'field' object, whose structure is unclear (free-form object with string keys). The agent cannot reliably construct the required parameters.
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?
The description clearly states the action ('Update'), the resource ('catalog custom field'), and the scope ('a single'), distinguishing it from bulk update siblings like kommo_catalog_custom_fields_update and from non-catalog custom field tools like kommo_custom_fields_update_one.
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 word 'single' implies this is for updating one catalog custom field at a time, contrasting with possible bulk operations. However, it provides no explicit guidance on when to use this tool over alternative update tools, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is disclosed by structured data. The description adds no extra behavioral context such as pagination behavior, output details, or scope limitations, but it does not contradict the annotations either.
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?
The description is a single concise sentence with the action and resource front-loaded. It contains no filler, though the phrase 'CRM plugins / website chat buttons' is slightly ambiguous in whether these are the same or separate categories.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, optional pagination parameters, and absence of an output schema, the description is minimally adequate but not complete. It lacks guidance on pagination, the relationship to get/create/update plugin tools, and what exactly constitutes a 'website chat button.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines page and limit with types and constraints but contains no descriptions, so schema description coverage is 0%. The description does not clarify these parameters or how pagination works, leaving the agent to rely solely on the parameter names.
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?
The description uses the specific verb 'List' and identifies the resource as 'CRM plugins / website chat buttons,' clearly matching the title. It distinguishes the operation as listing, though it does not explicitly differentiate from closely related tools like kommo_crm_plugins_get or kommo_widgets_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Sibling tools such as kommo_crm_plugins_get, kommo_crm_plugins_create, and kommo_widgets_list exist, but the description gives no hints about choosing this list tool over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, providing the safety profile. The description adds the context of the 'drive host' backend but does not disclose pagination behavior, default limits, response format, or filtering semantics. Since annotations cover the core behavioral safety, a mid-range score is appropriate.
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?
The description is a single sentence that front-loads the primary action ('List files from the Files API'). It is concise and wastes no words, though it could be more informative. The structure is acceptable for such a short description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations, the description should provide more context about return values, pagination, or differences from sibling tools like kommo_files_entity_list. It does not, leaving the agent with an incomplete picture of the tool's behavior and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, but it merely says 'Supports filters via query params documented by Kommo', which points to external documentation without explaining what filter_name or filter_extensions mean. It adds no value beyond the parameter names already present in the schema.
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?
The description clearly states 'List files from the Files API (drive host)', using a specific verb and resource. It distinguishes from siblings like kommo_files_get (which retrieves a single file) and kommo_files_entity_list (which lists files by entity) by focusing on the general files listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention kommo_files_entity_list or kommo_files_get, and only vaguely notes that filters are supported via query params, without explaining when filtering might be appropriate or how this tool relates to other file-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, so the read-only behavior and non-exhaustive nature are disclosed. The description is consistent with these hints but adds no additional context (e.g., pagination, auth needs, ordering, or handling of missing entities).
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?
The description is a single concise sentence that front-loads the action and scope. No filler words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief for a tool with 5 parameters and no output schema. It doesn't mention supported entity types, pagination, or what 'with' controls. While sibling tools and annotations provide some context, the description alone is insufficient for selecting and invoking correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate but does not. It only references 'entity ID' while ignoring the required entity_type parameter and optional with/page/limit. The enum and other parameters are left to the schema entirely.
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?
The description uses a specific verb ('List') and identifies the resource ('notes') and scope ('for a specific entity ID'), distinguishing it from a general notes list. However, it does not explicitly mention the entity_type parameter or alternatives like kommo_notes_list, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as kommo_notes_list (all notes) or kommo_notes_get (single note). The 'for a specific entity ID' phrasing implies a use case, but there are no explicit alternative references or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint: true, which indicates external world interaction, but the description adds no behavioral details such as side effects, reversibility, or authorization requirements. Launching a salesbot likely has significant side effects, yet the description remains silent on them.
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?
The description is a single, focused sentence with no redundancy. It is concise and front-loaded with the primary action. However, it could be slightly more structured by separating payload guidance from the overall purpose, but it remains appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the action-oriented nature of this tool, no output schema, and only openWorldHint annotation, the description is insufficient. It omits return values, error handling, whether launch is synchronous, and any required permissions or conditions. The minimal description leaves many important context gaps.
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?
The input schema only describes 'body' as 'Launch payload(s)', which is vague. The tool description adds meaningful context by specifying that the body 'typically includes bot_id and entity_id / entity_type', providing actionable guidance beyond the schema. This helps agents construct valid requests.
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?
The description clearly states the action (Launch a Salesbot) and the target resource (entities), which distinguishes it from sibling tools like kommo_salesbots_list and kommo_salesbots_stop. However, it lacks detail on what 'entities' means specifically (e.g., leads, contacts, companies), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The 'typically includes' phrase gives payload hints but does not explain the context or decision-making process for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds some context (running call, caller ID/softphone UX) but does not disclose any side effects, permissions, or what happens after notification. The openWorldHint annotation already signals open-ended behavior, but the description does not enrich it with specifics like whether the call record is created or if there are ordering constraints.
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?
The description is a single, tightly worded sentence that front-loads the action and context. No unnecessary words or filler; it earns its place by conveying the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an open schema and no output schema, the description is insufficient for an agent to successfully invoke it. It lacks any explanation of the input format, expected behavior, or return value, and does not fully clarify the difference from similar call-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'notifications' but provides no property definitions (additionalProperties: {}), and schema description coverage is 0%. The description does not mention the parameter at all, leaving the agent with no guidance on how to structure the array or what fields to include.
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?
The description uses a specific verb ('Notify') and identifies the resource ('Kommo about a running call for a phone number'). It clearly distinguishes from sibling tools like kommo_calls_add by emphasizing the real-time 'running call' aspect and caller ID/softphone UX context.
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 description implies when to use the tool (during a running call, for caller ID/softphone UX) but does not explicitly mention alternatives or when not to use it. No exclusions are stated, and there is no reference to sibling tools for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. However, the description adds no additional behavioral context such as error conditions, response format, or relation to other resources. It simply restates the action without enriching beyond annotations.
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?
The description is a single concise sentence with no fluff. It is front-loaded with the action and resource, making it easy to scan. Ideal length for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, minimal annotations), the description is under-specified. It fails to define what a catalog custom field is, which parameter is the primary ID, or what the response contains. This leaves room for ambiguity, especially with 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It says 'by ID' but does not clarify which parameter is the custom field ID versus the catalog ID, nor does it explain the relationship between them. Parameter names are somewhat self-explanatory, but the description adds no semantic value beyond the schema.
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?
The description 'Get a catalog custom field by ID' uses a specific verb ('Get') and resource ('catalog custom field'), directly distinguishing it from sibling tools like kommo_custom_fields_get by including 'catalog'. The scope is clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., list tools or non-catalog getters). Usage is only implied by the name and common patterns, but no explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds no behavioral information such as return format, error conditions, or the effect of the 'with' parameter. However, for a simple get operation, this is acceptable and not contradicting.
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?
The description is a single, grammatically simple sentence that immediately conveys the core function. No unnecessary words or repetition. It earns perfect marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, the lack of output schema, and the presence of annotations, the description is mostly adequate but leaves the 'with' parameter unexplained. The return data structure is not described, which could matter for downstream use. It is a minimal viable description with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents 'id' as 'Contact ID', but the 'with' parameter has no description and the tool description does not clarify it. With 50% schema coverage and no additional explanation in the description, the agent is left guessing what 'with' accepts. This is a significant gap.
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?
The description clearly states the verb 'Get' and the resource 'single contact by ID'. It distinguishes from sibling tools like list or create by focusing on a single record retrieval, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives like kommo_contacts_list. The implied usage from the name is not necessarily enough; a clearer note about using it when you have a specific contact ID would help. There are no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which covers the safety profile. The description adds no extra behavioral context such as return format, error conditions, rate limits, or auth requirements. It merely restates the action without disclosing anything beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of seven words. It is front-loaded with the verb and resource, and there is no fluff. However, it is so minimal that it sacrifices useful context, so it does not earn a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with a single parameter and strong annotations, the description is minimally adequate. However, with no output schema, it does not state what is returned or how errors are signaled, leaving some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'by ID', but that merely echoes the parameter name 'id' and does not explain the ID's origin, format, or any constraints. The description adds little semantic value over the schema.
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?
The description clearly states a specific action ('Get') and resource ('conversation/talk') with an explicit scope ('by ID'). This distinguishes it from sibling tools like kommo_conversations_list (which lists multiple) and kommo_conversations_close (which mutates state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention, for example, using kommo_conversations_list to find an ID first, nor does it state any prerequisites beyond the ID parameter already visible in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the basic action. With only openWorldHint: true in annotations and no readOnly/destructive hints, the description should explain side effects (e.g., notifying participants, irreversibility, required permissions) but does not. No contradiction with annotations, but no added transparency.
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?
The description is a single concise sentence that directly states the core action. No wasted words; it is easily digestible and front-loaded. It is appropriately minimal for a tool whose name already conveys the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested object parameter (body) adding complexity, and no output schema exists to describe return values. The description does not explain how to structure the body for different message types, what the API expects beyond 'per Kommo API', or what the response contains (e.g., message ID). Despite the simplicity of the action, the lack of guidance on the body object and return behavior makes it incomplete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds nothing about the parameters. The schema already documents body as 'Message payload (text, attachments, etc. per Kommo API)' but conversation_id is undescribed. Since schema coverage is 50% and the description does not compensate (e.g., by explaining how to construct the payload or that conversation_id refers to an existing conversation), it fails to add value beyond what is already in the schema.
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?
Clearly states the action: 'Send a message to a conversation.' Uses a specific verb ('send') and resource ('message', 'conversation'), fully distinguishing it from siblings like kommo_conversations_messages_list (list messages) or kommo_conversations_close (close conversation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., conversation must exist), nor any exclusions or comparisons to related tools like kommo_calls_add or kommo_notes_create. The usage context is only implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral context beyond the creation action itself. With only openWorldHint: true in annotations, there is no mention of validation rules, idempotency, permission requirements, side effects, or what happens on duplicate field names. The description adds no transparency value beyond the annotation.
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?
The description is a single, front-loaded sentence with no filler. It earns its place by stating the core action and scope, though the brevity borders on under-specification. For conciseness and structure alone, it is excellent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two required parameters, no output schema, and minimal annotations, the description must provide more contextual detail to be complete. It does not explain the expected shape of field definitions, allowed field types, or response behavior, leaving a significant gap for an agent trying to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It mentions 'entity type' but gives no meaning to the fields array structure, such as what fields do, what propertyNames constraints apply, or how entity_type values map to API behavior. The description adds almost no parameter semantics.
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?
The description clearly states a create operation on custom fields scoped to an entity type. The verb 'create' plus resource 'custom fields' is specific and distinguishes it from sibling update/list/delete custom-field tools, though it doesn't explicitly mention the catalog vs. core entity distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like kommo_custom_fields_update, kommo_custom_fields_list, or kommo_catalog_custom_fields_create. The only implied usage is the bare action 'create', which offers little decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a small amount of behavioral context beyond the annotations: the verb 'detach' implies the files are unlinked from the entity rather than permanently deleted, which is more specific than the generic destructiveHint. However, it does not disclose consequences such as whether the files remain accessible or how the operation affects file ownership.
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?
The description is a single sentence with no redundant words, meeting the conciseness criterion. The action is front-loaded and every word earns its place, though the brevity sacrifices useful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's three required parameters and lack of output schema, the description is too sparse to be complete. It does not explain the entity types supported, the format of the files list, or the outcome of the detach operation, leaving the agent under-informed for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description carries the full burden of parameter explanation, but it offers none. The agent must rely solely on parameter names like 'entity_type' and 'files' without any guidance on required values, the structure of the 'files' array, or the meaning of 'file_uuid'.
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?
The description states the tool's action precisely: 'Detach files from an entity'—a specific verb and resource that contrasts with sibling tools like kommo_files_entity_attach. The one-sentence description is unambiguous and distinguishes its role among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when this should be used (e.g., to undo an attachment) or how it relates to kommo_files_entity_attach or listing endpoints, leaving the agent to infer context from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no details about the update's effects—whether the note is replaced wholly or merged, whether existing fields are preserved, or whether any permissions are required. The annotations (idempotentHint, openWorldHint) are present but unexplained, and the description does not leverage them to add context. No contradiction exists.
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?
One sentence, front-loaded with verb and object. No wasted words, ideal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 required parameters, one nested object, and no output schema. The description is too minimal to convey how to construct a valid request, what the tool returns, or any prerequisites. The lack of return-value description is especially problematic given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should clarify the parameters. It fails to explain the 'note' object structure, the purpose of 'entity_type', or the format of 'id'. The enum in the schema gives choices but not semantics, and the nested object is entirely opaque.
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?
The description uses a specific action verb ('Update') and a resource ('a single note by ID'), which clearly differentiates it from the sibling kommo_notes_update (bulk update) and other note tools. The phrase 'by ID' also clarifies the single-record scope.
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 description does not explicitly state when to use this tool over alternatives. It implies single-note updates, but does not mention kommo_notes_update for bulk operations or the list/get tools for reading. This leaves the agent to infer context from naming conventions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint, which does not disclose behavior. The description does not explain side effects (e.g., whether it's reversible), required permissions, or impact on ongoing bot activities. With no meaningful annotation support, the description carries the full burden and falls short.
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?
The description is a single concise sentence, front-loaded with the key action and resource. It is appropriately short for a simple operation, though the extreme brevity omits useful context. No wasted words, but it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a nested body parameter, no output schema, and minimal annotations, the description leaves many unknowns: valid entity types, idempotency, potential errors, and what exactly happens when a bot is stopped. It is not complete enough for an agent to reliably invoke this tool without additional knowledge.
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 coverage is 50% (bot_id has no description, body does). The description adds that bot_id identifies the Salesbot, but the body parameter remains vague. It mentions 'for an entity' which loosely relates to the body, but doesn't clarify valid entity types or required fields within body. Partial compensation, but not enough to fully understand parameter usage.
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?
The description clearly states the action (Stop) on a specific resource (Salesbot) and provides the scope ('for an entity by bot ID'). This is a specific verb+resource combination that distinguishes it from sibling tools like kommo_salesbots_launch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like launch or list. There are no prerequisites, scenarios, or exclusions mentioned. The description only states the basic action without any contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true and openWorldHint=true, which already convey that the operation is read-only and possibly unbounded. The description adds no behavioral context beyond what annotations state, such as pagination, ordering, or any side effects. Since it does not contradict annotations but also adds no value, a score of 2 is appropriate.
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?
The description is a single sentence, 'List stages for a pipeline.', which is concise and front-loaded with the action. It contains no unnecessary words and is easy to parse, achieving very high conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, read-only annotation), the description is minimally sufficient but leaves gaps. It does not describe the return structure (though 'list' implies a list of stages) or mention potential edge cases like invalid pipeline IDs. It is not as complete as needed for a tool without an output schema, but it is adequate for basic invocation.
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?
The input schema has only pipeline_id with no description, leaving 0% schema coverage. The description's phrase 'for a pipeline' indicates that pipeline_id identifies the pipeline whose stages are listed, adding some meaning. However, it does not elaborate on the parameter's format or additional constraints, so it partially compensates but not fully. A score of 3 reflects this minimal semantic addition.
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?
The description 'List stages for a pipeline' clearly states the verb (List) and resource (stages) with a pipeline scope. It distinguishes from siblings like 'kommo_stages_get' (which implies getting a single stage) and 'kommo_pipelines_list' (which lists pipelines). However, it does not explicitly differentiate itself from these alternatives, so it falls 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as kommo_stages_get or kommo_pipelines_list. It does not mention scenarios, exclusions, or alternative tool recommendations, so it earns a 2 for no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already provide. It does not disclose whether the update is partial or full replacement, how invalid IDs are handled, or authorization requirements. The openWorldHint and idempotentHint annotations exist, but the description fails to add any extra context about side effects or response behavior.
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?
The description is a single, concise sentence that conveys the core action without any filler. It is appropriately sized and front-loaded, earning a top score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that updates a nested task object with no output schema, the description is inadequate. It lacks information about which task fields are updatable, update semantics (patch vs put), and expected response. Sibling patterns suggest _update_one tools share a common pattern, but the description alone leaves significant gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% and the description does not compensate. The only parameter semantics provided is 'by ID', which minimally clarifies the id parameter, but the 'task' object remains vague as 'Task object per Kommo API'. The description does not explain what fields can be updated or how to structure the object, leaving the agent under-informed.
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?
The description 'Update a single task by ID' uses a specific verb and resource, clearly stating it updates exactly one task. The phrase 'single' and 'by ID' distinguishes this from the sibling kommo_tasks_update, which likely handles batch updates. This meets the 5 criterion of specific verb+resource with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as kommo_tasks_update or kommo_tasks_create. There is no mention of prerequisites, exclusions, or preferred scenarios. It is a bare statement without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats 'Destructive,' which is already captured by the destructiveHint annotation. It adds no additional behavioral context such as irreversibility, cascade effects, or authorization requirements.
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?
The description is extremely concise with two short sentences. Every word serves a purpose and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description covers the core action but lacks details about return values, error behavior, and differentiation from the sibling delete tool. This makes it adequate but not fully complete in context.
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?
The schema has 0% description coverage, so the description's 'by ID' clarifies that the 'id' parameter is the template identifier. However, it does not provide further details like source, format, or typical usage, making it minimally compensating.
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?
The description clearly states 'Delete a single template by ID' with a specific verb and resource. It is unambiguous about the operation, though it does not explicitly distinguish from the sibling tool 'kommo_templates_delete'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the similarly named 'kommo_templates_delete' or other delete tools. The sibling list reveals potential ambiguity without further context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which conveys the read-only, side-effect-free safety profile. The description adds no extra behavioral context beyond the retrieval action, so it neither enhances nor contradicts 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, terse sentence with no redundant words. It is efficiently structured and front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool, the description is minimally adequate but leaves gaps: it doesn't mention the shape of the returned widget info, error cases, or prerequisites like whether the widget must be installed. With no output schema, a bit more detail would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists widget_code without any description (0% coverage), and the description merely repeats 'by its code' without explaining what a widget_code is, its format, or how to obtain it. This provides minimal added semantic value over the schema property name.
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?
The description specifies a clear action ('Get'), resource ('widget info'), and lookup method ('by its code'), making the tool's purpose unmistakable. However, it doesn't contrast with sibling tools like kommo_widgets_list or install, so some sibling differentiation is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as kommo_widgets_list or install/uninstall. The phrase 'by its code' implies a prerequisite but fails to explain selection criteria or exclude cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats 'Destructive,' which is already declared by destructiveHint=true in annotations. It adds no new behavioral context such as whether deletion is permanent, supports batch deletion, or affects linked entities. No annotation contradiction exists.
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?
The description is extremely concise, consisting of two short sentences. It front-loads the action and includes a concise destructive warning, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, it is minimally adequate, but lacks critical context such as return values, irreversibility, permission requirements, and batch behavior. The absence of an output schema makes the lack of return-value information more impactful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely states 'by UUID,' which adds minimal meaning beyond the schema's 'files' array of objects with 'uuid.' With 0% schema description coverage, the description fails to explain that multiple files can be deleted or how the array should be structured.
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?
The description 'Delete files by UUID' uses a clear verb+resource and specifies the identifier type. It clearly distinguishes from sibling tools like kommo_files_restore and kommo_files_edit, and the additional word 'Destructive' reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives such as restore or edit. There are no prerequisites, reversibility notes, or context about permanent vs. soft deletion, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses only the basic action, not behavior like whether this appends or replaces existing attachments, side effects, or whether the entity/file must exist. The 'openWorldHint' annotation is vague and the description adds little insight.
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?
One short sentence, front-loaded with the action, no wasted words. Perfectly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple attach operation, but it omits contextual details like whether the file UUIDs must come from a prior upload session, whether attachments are additive, or any error conditions. The schema provides entity_type options, but the description doesn't help the agent understand the full workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description only clarifies that files are referenced by UUID. It doesn't explain entity_type or entity_id semantics beyond their names, leaving the agent to rely entirely on the schema.
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?
The description uses a specific verb ('Attach') and resource ('files...to an entity'), clearly distinguishing it from sibling tools like kommo_files_entity_detach. The 'by UUID' qualifier adds precision about how files are referenced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs. alternatives. It doesn't mention prerequisites (e.g., file must exist, entity must exist) or contrast with detach/entities_with_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the action itself. It does not disclose side effects, whether restore is reversible, permission requirements, or error conditions, and the openWorldHint annotation does not mitigate this gap.
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?
The description is a single, direct sentence without unnecessary words, making it very concise. However, it is under-specified, but that is more a completeness issue than a conciseness issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutation tool with no output schema and minimal annotations, the description is inadequate. It does not explain what happens after restore, how to obtain the UUIDs, or any special conditions, so the agent may not know how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the 'files' parameter or provide any guidance on its structure or required UUIDs. With 0% schema description coverage, the description fails to compensate, leaving the agent to infer the parameter semantics solely from the schema.
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?
The description clearly states a specific action (restore) and resource (previously deleted files), distinguishing it from sibling file tools like kommo_files_delete and kommo_files_list.
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 description implies usage for files previously deleted, but does not explicitly state when to use it versus alternatives, nor does it mention any prerequisites such as needing the file UUID from a deletion or listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include idempotentHint and openWorldHint, which already indicate retry safety and flexible schema. The description adds minimal behavioral context beyond the id requirement; it does not disclose whether updates merge or replace fields, how missing IDs are handled, or any side effects. No contradiction with annotations, but the added value is low.
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?
The description is very brief and every sentence earns its place: it states the core purpose and a critical input requirement. It could be slightly more detailed, but it is economical and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sparse annotations, the description is incomplete for a batch update tool. It does not explain entity_type options, update semantics, failure handling, or return format. The agent is left without enough context to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions that each notes object needs an id, but does not explain the entity_type parameter or the structure of the notes array. This leaves significant ambiguity for the agent about how to construct valid inputs.
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?
The description says 'Update multiple notes,' which clearly identifies the action (update), the resource (notes), and the scope (multiple). This distinguishes it from the sibling tool kommo_notes_update_one, which handles single notes.
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 description implies usage for batch updates by stating 'multiple notes,' but does not explicitly say when to use this tool versus kommo_notes_update_one or provide exclusions. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. The readOnlyHint and openWorldHint already indicate this is a safe, read-only operation, but the description does not disclose other relevant behaviors such as response format, error handling, or what happens if the ID does not exist.
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?
The description is a single, front-loaded sentence with no filler. It immediately states the action and target, fully earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with read-only annotations, this description is minimally adequate for selecting the tool and understanding its basic purpose. However, it lacks detail about the return value (especially since there is no output schema) and provides no context about the Salesbot resource itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required integer 'id' with no description (0% coverage). The description's 'by ID' essentially restates the parameter name and tool purpose, adding no additional meaning about the ID's format, domain, or constraints beyond the schema's type and range.
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?
The description uses a specific verb ('Get') and resource ('Salesbot') with clear scoping ('by ID'). This distinguishes it from sibling tools like kommo_salesbots_list (which lists salesbots) and kommo_salesbots_launch/stop (which act on salesbots).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternatives. It does not mention kommo_salesbots_list for retrieving multiple salesbots or any selection criteria. The phrase 'by ID' implies a known identifier, but no alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide openWorldHint and idempotentHint. The description adds only the batch behavior, which is useful but does not disclose effects like what data is updated or error conditions. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It is well-structured and front-loaded with the action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is extremely sparse, with no mention of what 'sources' are, what the request payload should contain, or what the response looks like. Given the absence of an output schema and the vague parameter schema, the description is inadequate for an agent to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single 'sources' parameter, and the description does not explain the structure or fields of the array items. This leaves the parameter semantics completely undocumented.
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?
The description uses a specific verb 'Update' with resource 'sources' and scope 'in batch', clearly distinguishing it from sibling tools like kommo_sources_update_one. It states exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in batch' implies use when updating multiple sources at once, but it does not explicitly mention when to use an alternative (e.g., kommo_sources_update_one) or provide exclusions. The usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description need not cover safety. It adds the behavioral detail of pagination and filter support, but does not explain default behavior, response format, or filter semantics beyond the generic phrase.
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?
The description is a single concise sentence, front-loaded with the verb and resource, with no redundant words. It is appropriately sized for a simple listing operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 optional parameters and only 10% schema coverage, the description leaves most functionality unspecified. It lacks information on filter semantics, pagination defaults, or any usage constraints, making it incomplete for an agent to confidently invoke with correct parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10% (one parameter has a description). The description mentions 'pagination and filters' but does not explain specific filter parameters or their meanings, failing to compensate for the sparse schema descriptions.
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?
The description clearly states the tool lists tasks and mentions pagination and filters, offering a specific verb+resource+scope. However, it does not explicitly differentiate from related tools like kommo_tasks_get, relying on the name for distinction.
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 description implies usage for fetching task lists with pagination and filters, but provides no explicit guidance on when to use this versus alternatives like kommo_tasks_get or other list tools. No exclusions or alternative recommendations are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and openWorldHint, lowering the bar for the description. The description adds the requirement that each object include id and the behavior that is_completed=true completes a task. However, it does not disclose whether unmentioned fields are preserved or how partial failures are handled, so it adds only limited behavioral context.
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?
The description is concise: two short sentences that state the purpose and the key field requirement, with no filler. Every sentence earns its place, and the structure front-loads the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the open object schema, no output schema, and only moderate annotations, the description is insufficiently complete. It fails to state the response format, what happens for missing/invalid ids, or how to update other fields beyond is_completed. An agent would likely need to consult API docs to use this tool effectively.
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 coverage is 0%, so the description carries the burden. It explains that each task object must include id and gives the is_completed example, but it does not enumerate other updatable fields or clarify that arbitrary fields may be included. This is minimal compensation for the open schema.
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?
The description clearly states 'Update one or more tasks,' giving a specific verb, resource, and scope. It distinguishes from the singular sibling kommo_tasks_update_one through the 'one or more' phrasing, though it does not explicitly name the alternative or clarify overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like kommo_tasks_update_one or kommo_tasks_create. There is no mention of batch update scenarios or exclusions, leaving the agent to infer usage from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint: true and openWorldHint: true, so the safety profile is known. The description adds no extra behavioral context, such as pagination behavior or response format, but it does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently communicates the core purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description is extremely minimal. It does not cover parameter behavior, return values, pagination, or edge cases, making it insufficient for an agent to use the tool correctly without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description carries the burden of explaining parameters, but it only mentions 'in a catalog' which hints at catalog_id. It fails to explain page, limit, query, with, or how they affect results, leaving the agent to guess.
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?
The description clearly states the action (list) and the resource (elements in a catalog), with an explicit example (products). This distinguishes it from sibling tools like kommo_catalogs_list (lists catalogs) and kommo_catalog_elements_get (retrieves a single element).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to use catalog_elements_get for individual elements or how this differs from other list tools. Usage is only implied by the verb 'list' and the resource name, with no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the bare action. The openWorldHint annotation indicates schema flexibility, but the description does not mention any side effects, permissions, required auth, or success/failure behavior. There is no contradiction, but also no added value beyond the annotation.
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?
The description is a single, front-loaded, and concise sentence with no wasted words. It immediately conveys the action and resource, making it easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a simple schema but no output schema and low schema coverage, the description is too sparse. It does not explain how to construct a valid catalog object, what fields are expected, or what the API returns on success or failure. This is inadequate for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The phrase 'one or more catalogs' correctly implies that the 'catalogs' parameter is an array, but it provides no details about the structure of each catalog object, required fields, or example values. This leaves significant ambiguity for an open-ended schema.
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?
The description clearly states the verb 'Create' and the resource 'catalogs', which is specific and distinguishes it from sibling tools like kommo_catalogs_list, kommo_catalogs_get, and kommo_catalogs_update. There is no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'create' (e.g., for adding new catalogs, not modifying existing ones), but the description lacks explicit guidance on when to prefer this tool over alternatives like update or delete. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds no extra behavioral context such as return format, error handling, or permission requirements. It merely restates the operation without disclosing anything beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the simplicity of the tool, a fuller description would help explain what a catalog is, what the response includes, and any edge cases (e.g., not found). The current description is too bare to be fully complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must compensate. The description says 'by ID' but does not elaborate on the meaning of the 'id' parameter beyond the parameter name itself. It adds minimal semantic value over the schema's property name.
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?
The description clearly states the action ('Get') and the resource ('catalog') with the required identifier ('by ID'). It distinguishes itself from sibling tools like list/create/update by specifying a single catalog lookup.
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 usage context is implied by the phrase 'by ID' — use when you have a catalog ID. However, there is no explicit guidance on when not to use it (e.g., for listing all catalogs) or mention of alternative tools like kommo_catalogs_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds the scope 'all available', implying no filtering, but does not disclose return shape, localization behavior, or whether event types are translated based on language_code. No contradiction with annotations.
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?
The description is one concise sentence with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits what event types are used for, the expected output format, and how language_code affects results. Since there is no output schema, an agent must infer these details from the title and sibling tools; this is minimally adequate but not fully self-contained.
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 coverage is 100% for the single parameter language_code, which includes examples 'en, es, pt, ru'. The description adds no additional parameter semantics; baseline 3 is appropriate when the schema fully documents parameters.
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?
The description 'Get all available event types' clearly identifies a read-only enumeration of event type definitions. It distinguishes from siblings like kommo_events_list (which lists events) by naming 'event types' as the resource, though it does not explicitly explain the relationship to the events domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus kommo_events_list or kommo_events_get. It does not mention that this tool provides a controlled vocabulary for event filters or any context for when the language_code parameter should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read nature is covered. However, the description adds no extra behavioral context (e.g., response format, pagination, entity types) beyond restating the title.
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?
The description is a single sentence that is direct and front-loaded. It contains no unnecessary words and is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, the description is minimally adequate. However, it lacks information about the return structure and does not clarify the distinction from kommo_files_entity_list. Given no output schema, the agent may not know what to expect in response.
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?
The schema has one required param 'uuid' with no description. The description clarifies that this is a 'file UUID', which adds minimal meaning beyond the schema. It does not explain format, validation, or where to get the UUID.
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?
The description clearly states the verb 'Get' and the resource 'entities associated with a file UUID'. It distinguishes this tool from sibling file tools by specifying the direction (entities linked to a file) and the required UUID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like kommo_files_entity_list or kommo_files_get. The description does not provide context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the scope 'unsorted/incoming leads in the inbox,' which is useful context. However, it does not disclose pagination behavior, return format, or how filtering interacts with the 'inbox' scope.
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?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters, no output schema, and several sibling list tools, the description is too minimal. It does not explain how filters work, what 'incoming' means in relation to pipeline stages, or how this list differs from kommo_leads_list. The description leaves the agent without enough context to make informed decisions about parameter use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only filter_category has a description). The description does not compensate by explaining page, limit, filter_uid, order_created_at, or filter_pipeline_id. Parameter names are self-explanatory to some degree, but the description adds no additional meaning beyond the schema.
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?
The description uses a specific verb and resource: 'List unsorted/incoming leads in the inbox.' This clearly identifies the tool's function and distinguishes it from siblings like kommo_leads_list (general leads) and kommo_incoming_leads_get (retrieve a single incoming lead).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. Sibling tools like kommo_leads_list and kommo_incoming_leads_summary exist, but the description does not mention them or explain when this list is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint and openWorldHint, covering the safety profile. The description adds no behavioral context beyond the title, such as the effect of the 'with' parameter on the response or the exact return format, so it provides minimal additional transparency.
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?
The description is a single sentence with zero waste, front-loading the essential action and resource. It is appropriately concise and directly to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET-by-ID tool, the description is minimal, but the presence of the undocumented 'with' parameter and the lack of an output schema leave significant gaps. The agent is not informed about what data is returned or how 'with' alters the response, making the description insufficiently complete for full autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description carries the burden of explaining parameters. It implicitly identifies 'id' as the role identifier but says nothing about the 'with' parameter, leaving its semantics and possible values unexplained.
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?
The description uses a specific verb 'get', identifies the resource 'role', and includes the qualifier 'by ID'. This clearly distinguishes it from sibling tools like kommo_roles_list, kommo_roles_create, and kommo_roles_update.
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 description implies that this tool is used when you have a specific role ID and need its details. However, it does not explicitly state when to use it instead of alternatives like kommo_roles_list, nor does it mention any exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description merely repeats 'Destructive' without adding any new behavioral context. It fails to mention irreversibility, permissions, or side effects on related data. Since annotations already cover safety, the description contributes no additional transparency.
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?
The description is extremely concise: two short sentences. The first states the core function clearly, and the second adds a cautionary warning. There is no unnecessary prose or repetition of schema details, making it very efficient.
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?
This is a simple delete tool with one parameter and destructive annotations. The description covers the key aspects: what it deletes and that it is destructive. It does not explain where template IDs come from or error behavior, but for a low-complexity tool with sufficient annotations, this is mostly adequate. The lack of output schema and simple input reduce the need for additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining the parameter structure. It only says 'Delete one or more templates,' which is a high-level restatement of the schema. The array structure with an 'id' field is self-evident from the schema, but the description adds no specific guidance about how to identify templates or handle invalid IDs.
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?
The description clearly states the action 'Delete' and the resource 'templates', specifying that one or more can be deleted. This distinguishes it from sibling tools such as kommo_templates_delete_one, which deletes a single template. The purpose is unambiguous and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention kommo_templates_delete_one or any other sibling tools, nor does it state prerequisites or exclusions. The phrase 'one or more' implies batch usage, but this is implicit at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint, which signals potential side effects but does not describe them. The description does not disclose permissions needed, whether activation is reversible, what effects it has on users, or what the response looks like. For a mutation tool, this is a significant transparency gap.
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?
The description is a single, front-loaded sentence with no filler. It efficiently communicates the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers the basic purpose adequately. However, it lacks usage guidelines, behavioral side-effect details, and any mention of return values or outcomes, leaving notable gaps for an agent deciding how to use it.
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 0%, but there is only one parameter ('users') that is well-defined by the schema itself (an array of objects requiring an 'id'). The description adds the word 'bulk', which implies multiple users, aligning with the array type, but provides little additional meaning beyond the schema.
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?
The description states the exact action 'Activate users in bulk' with a specific verb (activate) and resource (users). It is clearly distinct from the sibling tool kommo_users_deactivate, which performs the opposite action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool, prerequisites, or alternatives. It only states what it does, with no context for when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds context that catalogs are also called lists and may contain products, but it does not describe pagination, return format, or other behavioral traits beyond what annotations already convey.
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?
The description is a single sentence that is direct and free of filler. It front-loads the verb and keeps only essential information, perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list operation with two optional pagination parameters and no output schema. The description states what it lists but does not mention pagination behavior or return structure. It meets the minimum viable threshold but leaves gaps that could be filled with a note about pagination or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation, but it does not mention page or limit at all. While parameter names are self-explanatory to some degree, the description adds no clarification about their purpose, such as pagination behavior.
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?
The description uses the specific verb 'List' and names the resource 'catalogs', clarifying it operates at account level. The parenthetical '(lists)' and '(products, etc.)' provide useful disambiguation, distinguishing it from single-item get, create, or update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like kommo_catalogs_get. It does not mention exclusions or preferred scenarios, leaving the agent to infer that list is for multiple items and get is for a single one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds no behavioral context beyond the annotation, such as error handling, return format, or effects of the optional 'with' parameter. Since it adds no extra transparency, the score is low despite annotations lowering the bar.
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?
The description is a single, front-loaded sentence with no filler or redundant words. It communicates the essential purpose clearly and efficiently, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters and no output schema, so the description doesn't need to be extensive. However, it omits key details: what the return value looks like, behavior when the company is not found, and the purpose of the 'with' parameter. These gaps make it minimally adequate for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It clarifies that 'id' is used to identify the company, but it completely ignores the optional 'with' parameter, leaving its purpose and effect undocumented. The description adds minimal semantic meaning beyond the schema itself.
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?
The description 'Get a single company by ID' uses a specific verb ('Get') and identifies the resource ('company') with a clear qualifier ('by ID'). It distinguishes this tool from sibling list/create/update operations (e.g., kommo_companies_list, kommo_companies_create) and matches the tool name and title precisely.
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 description implies usage: call this when you need one company identified by its ID. However, it provides no explicit guidance about when to choose it over alternatives like kommo_companies_list or kommo_companies_get (for other entities). No exclusions or alternative tool mentions exist, but the context is clear enough for a simple get-by-ID operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral traits beyond the verb 'update'. Annotations indicate idempotency and open-world hints, but the description does not clarify whether the update is partial or full replacement, nor any side effects. It does not contradict annotations, but it adds minimal value beyond them.
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?
The description is a single sentence, front-loaded with the action 'Update', and contains no unnecessary words. It is effectively concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the minimal description conveys the core purpose, but it leaves gaps. The lack of detail about the `company` object format and the potential ambiguity with the sibling `kommo_companies_update` tool are not addressed. The annotations provide some context, but the description alone is adequate yet not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the `id` or `company` parameters. With schema description coverage at 50% and the `company` object only vaguely described as 'Company object per Kommo API', the description does not compensate for the low coverage or explain how to construct the object.
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?
The description clearly states the action (update), the resource (company), and the scope (single by ID). This distinguishes it from the sibling tool kommo_companies_update, which likely handles bulk updates.
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 phrase 'single company by ID' implies it is for updating one entity, but it does not explicitly mention when not to use it or call out the alternative kommo_companies_update for bulk operations. The guidance 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is openWorldHint, which provides no safety or behavioral context. The description 'Accept unsorted leads into the pipeline' implies a state-changing mutation but does not disclose consequences, reversibility, permissions required, or effects on the lead.
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?
The description is a single sentence with no filler words. It is front-loaded and concise, effectively conveying the core purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation behavior, one complex nested parameter, and no output schema, the description is too sparse. It does not explain the payload structure, required fields, or operational implications, leaving an agent under-equipped to invoke it correctly.
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?
The schema covers 100% of parameters by describing the 'body' object with 'uids / user_id / status_id', but the tool description adds no additional parameter semantics. Baseline 3 is appropriate since the schema carries the burden.
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?
The description clearly states the action ('Accept') and the resource ('unsorted leads') with a destination ('into the pipeline'), which distinguishes it from sibling tools like kommo_incoming_leads_decline and kommo_incoming_leads_link.
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 description implies usage for unsorted incoming leads but does not explicitly mention alternatives or exclusion criteria. It lacks guidance on when to use this tool versus decline/link, so it only partially supports decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. However, the description adds no additional behavioral context—such as error behavior, response contents, or access requirements—beyond the plain read action. It does not contradict the annotations but also does not enrich them.
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?
The description is a single, focused sentence of eight words. It front-loads the action and resource, includes the key identifiers, and contains no unnecessary words or repetition.
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 read-only tool with two required integer parameters and no output schema, the description is largely sufficient. It states what the tool does and the identifiers needed. It lacks explicit return-value details or use-case scenarios, but the operation is straightforward and sibling tools provide context for when this single-stage fetch might be used.
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?
With 0% schema description coverage, the description provides essential semantic mapping by referring to 'pipeline ID' and 'stage ID', which correspond to pipeline_id and status_id respectively. This helps the agent understand what each parameter means, though it does not elaborate on validation, relationships, or typical values. It partially compensates for the lack of schema descriptions.
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?
The description clearly specifies a single action ('Get') on a specific resource ('a stage') and names the required identifiers ('pipeline ID and stage ID'), which distinguishes it from sibling tools like kommo_stages_list or kommo_stages_update. It provides exactly the information needed to understand what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as kommo_stages_list or when a single stage fetch is appropriate. There are no prerequisites, exclusions, or alternative recommendations, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation openWorldHint provides minimal behavioral context. The description adds the limitation that color can only be set for leads, which is useful, but it does not disclose other behaviors like idempotency, duplicate handling, or return values.
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?
The description is two concise sentences with the primary action front-loaded. It contains no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with two parameters and no output schema, the description is minimal but lacks important context such as whether tags are unique per entity type, how duplicates are handled, and the relationship to assignment tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the parameters in detail, and schema description coverage is 0%. It only mentions color for leads, which is already noted in the schema, leaving the entity_type enum and tags structure to be inferred from the schema.
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?
The description clearly states the tool creates tags for an entity type, using a specific verb ('Create') and resource ('tags'). It effectively distinguishes from sibling tools like kommo_tags_assign and kommo_tags_list by focusing on the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as assigning existing tags. The description implies basic usage but does not explain scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is clear. The description adds scope ('chat response templates') but does not disclose pagination, filtering behavior, or return format, which are not covered by annotations.
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?
The description is a single sentence with no filler. It is front-loaded with the verb and resource, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a read-only list tool with optional filters, the description and annotations provide adequate basic context. However, the cryptic 'with' parameter and lack of any output format information leave gaps for an agent seeking full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%, with just 'with' having a description ('reviews'). The tool description does not explain page, limit, filter_external_id, or the meaning of 'with', leaving agents to guess parameter purpose.
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?
The description uses a specific verb ('List') and resource ('chat response templates'), adding scope with 'including WhatsApp/WABA'. This clearly distinguishes it from sibling tools like kommo_templates_get, kommo_templates_create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like kommo_templates_get or kommo_templates_create. The only signal is the verb 'list', which implies usage but does not explicitly state exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the description does not need to repeat that. It adds that pagination and filters are supported, which is useful, but it does not clarify default pagination behavior, filter semantics, or return format. The added behavioral detail is minimal beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, terse sentence that conveys the core function with no wasted words. It is front-loaded and easy to parse, making it an efficient pointer to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and sparse annotations, the description is far from complete. It does not explain how pagination works, what filters are available, what fields are returned, or any defaults. An agent would have significant unknowns after reading this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the 8 parameters. It only vaguely mentions 'pagination and filters' without defining specific parameters like 'page', 'limit', 'query', 'with', or 'order_updated_at'. This leaves agents guessing at parameter meanings.
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?
The description clearly states the action (list), the resource (companies), and the scope (with pagination and filters). It distinguishes itself from sibling tools like kommo_companies_get by explicitly indicating a list operation rather than a single-entity fetch.
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 description implies when to use the tool (when a paginated or filtered list of companies is needed) but does not explicitly contrast it with alternatives such as getting a single company. There is no mention of when not to use it or which other tools to prefer in specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include idempotentHint and openWorldHint, but the description adds minimal behavioral context beyond the update action and id requirement. It does not clarify partial vs. full field replacement, response format, or error behavior, which is notable for a mutation tool without readOnly/destructive hints.
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?
The description is a single concise sentence, front-loaded with the action and the key requirement. There is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core requirements (what and the required id) for a simple batch update, but lacks details about update semantics and response behavior. With no output schema and minimal schema info, more context would improve completeness, yet the description is minimally viable.
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?
The schema has zero description coverage for the 'companies' parameter. The description compensates by stating each object must include 'id', which is essential, but it does not explain other accepted fields or the object structure, leaving reliance on the vague 'Company object per Kommo API'.
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?
The description uses a specific verb 'Update' and resource 'companies', and explicitly notes 'one or more' to indicate batch capability. This distinguishes it from kommo_companies_update_one, making the tool's purpose clear.
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 description implies usage for batch updates by saying 'one or more' and provides a prerequisite ('Each object must include id'). However, it does not explicitly contrast with the single-update tool or state when to use one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include openWorldHint and idempotentHint, already conveying that additional fields are allowed and retries are safe. The description adds the essential requirement that each object must include id, but it does not disclose whether unspecified fields are preserved, how partial updates behave, or what the response contains.
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?
The description is two short, front-loaded sentences with no filler. Every phrase adds operational value: the scope is clear and the id requirement is stated outright.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk update tool, the description barely covers prerequisites (id) and scope, while ignoring response format or behavior on missing fields. Given there is no output schema and the input schema is very generic, more context would be expected, but the openWorldHint and idempotentHint help slightly.
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?
The schema for 'contacts' is a generic array of free-form objects with no required per-item fields, so the description's note that 'Each object must include id' adds crucial meaning. However, beyond that requirement, it leaves the actual fields and their semantics to the Comma API, offering minimal compensation for the 0% schema coverage rate.
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?
The description clearly states the tool updates one or more contacts, using a specific verb and resource. It distinguishes itself from the sibling kommo_contacts_update_one by indicating batch capacity ('one or more'), though it doesn't explicitly name the alternative.
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 phrase 'one or more' implies a batch update use case, and 'Each object must include id' provides a key precondition. However, no explicit guidance is given about when to prefer this over the single-contact update tool or what other prerequisites might exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds only the 'entity type' scoping, which is somewhat redundant with the schema. It does not disclose pagination behavior or other operational details, so the description adds minimal extra context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded. It contains no filler or redundant information, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a list tool with no output schema and five parameters including pagination and filtering options. The description only states the basic purpose and does not mention pagination, filtering, or the nature of the returned data. Annotations cover the safety profile but not operational completeness, so the description leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only filter_type has a description). The description mentions 'entity type' but does not explain page, limit, order_id, or filter_type beyond what the schema enums provide. With low schema coverage, the description should compensate, but it does not.
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?
The description clearly states the verb 'List' and the resource 'custom fields' with a scope of 'for an entity type.' It effectively distinguishes this list operation from sibling tools like create, update, delete, and get for custom fields.
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 description implies usage when one needs to list custom fields for an entity type, but it does not explicitly state when to use this over alternatives, nor does it mention exclusions or prerequisites. Given the large number of sibling tools, more explicit guidance would be helpful, but the basic use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already signal safe, read-only behavior, so the bar is lower. However, the description adds no additional behavioral context such as whether results are paginated, what fields appear in the response, or how entity types map to the enum values. It merely restates the operation without enriching transparency.
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?
The description is a single, clear sentence with no filler or redundancy. It front-loads the action and resource, making it immediately scannable and memorable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and read-only annotations, the description is minimally sufficient but incomplete. It does not mention the return format, pagination, or any caveats, and there is no output schema to fill the gap. The missing details are not critical for basic use, but more context would improve completeness.
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?
The schema provides the entity_type parameter with an enum but no description (0% coverage). The tool description clarifies that entity_type means the type of entity whose field groups are being listed, adding meaning beyond the bare schema. However, it does not explain the enum values or what a 'field group' represents, so the compensation is partial.
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?
The description 'List custom field groups for an entity type' uses a specific verb ('List') and clearly identifies the resource ('custom field groups') and scope ('for an entity type'). This distinguishes it from sibling tools like kommo_field_groups_get (which fetches a single group) and kommo_custom_fields_list (which lists fields, not groups).
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 description states what the tool does but does not explicitly explain when to prefer it over alternatives like kommo_field_groups_get or kommo_custom_fields_list. It implies usage context ('for an entity type') but provides no exclusions or comparative guidance against siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations provide idempotentHint and openWorldHint but do not specify destructive behavior. The description adds that it edits a file name or active version, but offers no further context about side effects, permissions, or whether the operation is reversible. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single brief sentence with no redundant information. It is appropriately concise for a simple edit operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a freeform body object and no output schema, yet the description provides no detail about accepted body properties, the response format, or prerequisites. This leaves significant gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the uuid or the body object. The mention of 'file name or active version' hints at body fields but does not explicitly map them, leaving the agent without clear parameter semantics for a freeform body object.
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?
The description clearly states the tool edits a file's name or active version, which is a specific verb and resource. It distinguishes this from sibling tools like kommo_files_delete, kommo_files_restore, and kommo_files_versions_get.
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?
Usage context is implied: use this when you need to modify a file's name or active version. However, there is no explicit guidance on when not to use it or mention of alternatives such as kommo_files_update or kommo_files_versions_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint as an annotation, the description carries the full burden of behavioral disclosure. It reveals that this is a POST operation ('Add... POST /leads/unsorted/sip'), implying mutation, but it does not mention required permissions, whether duplicates are rejected, how existing leads are affected, or what the response contains. Minimal value is added beyond the tool name.
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?
The description is two short sentences with no filler. It front-loads the action and resource, then gives the exact endpoint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple schema and no output schema, the description is too sparse for an agent to safely invoke the tool. It does not explain the shape of the required 'items' array, any constraints on item fields, or clarify how this differs from other call/incoming-lead tools. The endpoint and type hint are useful but not enough for complete operational understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single 'items' parameter is an array of arbitrary objects with no property definitions. The description does not explain what each item should contain (e.g., phone number, source_uid, pipeline_id), nor does it provide any field-level guidance. It only hints at the lead type, which is insufficient for an agent to construct valid input.
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?
The description clearly states the action ('Add') and the specific resource ('incoming leads of type sip/call'), plus the exact HTTP endpoint. This distinguishes it from siblings like kommo_incoming_leads_add_form, which handles form-type leads, and kommo_calls_add, which covers calls through a different path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is specifically for adding SIP/call incoming leads. It implies a scope (sip/call) that differentiates it from form-based incoming leads, but it does not explicitly name alternatives or state when not to use this tool, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply restates the name and parameter without adding behavioral context. Annotations already declare readOnlyHint=true and openWorldHint=true, so the description provides no additional transparency about return format, errors, or lead properties.
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?
The description is a single sentence, concise and front-loaded. It communicates the essential action and parameter without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool, the description covers the core purpose. However, there is no output schema to describe the return value, and the description does not mention what an incoming lead is or what data will be returned, leaving some context incomplete.
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?
The schema has 0% description coverage for the 'uid' parameter. The description clarifies that uid is the unique identifier used to fetch the lead, which adds meaning beyond the bare type string. However, it doesn't provide format or validation details.
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?
The description clearly states the action (get) and the resource (incoming lead) with the specific lookup key (UID). It distinguishes this from list/summary tools by indicating a single entity retrieval.
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 description implies usage when you have a UID and need a single incoming lead, but it doesn't explicitly state when to avoid using this tool (e.g., when listing or when using regular leads). No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool can create multiple pipelines in one call ('one or more') and can optionally include stages. This goes beyond the bare action, but it does not disclose permissions, idempotency, or side effects. The openWorldHint annotation does not cover safety aspects, and no contradictions exist.
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?
The description is a single, concise sentence that front-loads the verb and resource. Every word adds context, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a create tool with a permissive schema and no output schema. It does not specify required fields for a pipeline (e.g., name) or how to structure nested stages. The openWorldHint annotation hints at flexibility, but the description fails to guide an agent on how to construct a valid request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the lack of parameter details. It does mention that the 'pipelines' parameter is an array of pipeline objects and may include stages, providing some semantic hint. However, it still leaves the internal structure of each pipeline unspecified, which is insufficient given the schema's generic additionalProperties.
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?
The description clearly states the action ('Create') and the resource ('pipelines'), with scope ('one or more') and an optional feature ('with stages'). This distinguishes it from sibling tools like kommo_pipelines_list, kommo_pipelines_update, and kommo_pipelines_delete.
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 description implies usage for creating pipelines but provides no explicit guidance on when to use this tool versus alternatives such as kommo_stages_create. It does not mention any exclusions or preconditions, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true. The description adds the context 'cannot be undone,' which reinforces the destructive nature but does not disclose potential cascading effects (e.g., what happens to stages, deals, or associated data). This goes slightly beyond the annotation flag but lacks richer behavioral detail.
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?
The description is just two short sentences, front-loaded with the core action. No fluff or redundant wording, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema) and the presence of destructive annotations, the description is reasonably adequate. However, it omits information about side effects (e.g., whether related stages/deals are deleted), which is significant for a destructive operation. The warning about irreversibility helps, but the openWorldHint is not explained.
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?
The schema provides no description for the 'id' parameter (0% coverage), so the description's 'by ID' clarifies that the parameter identifies the pipeline to delete. However, it does not elaborate on how to obtain the ID or special constraints, which is a modest but useful addition.
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?
The description states a specific verb ('Delete'), a specific resource ('pipeline'), and the identification method ('by ID'). It clearly distinguishes from sibling tools like kommo_pipelines_list, kommo_pipelines_get, kommo_pipelines_create, and kommo_pipelines_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as updating instead of deleting. The warning 'Destructive — cannot be undone' is a cautionary note but does not explain appropriate usage context or prerequisites, so it offers minimal usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation openWorldHint: true indicates external side effects, and the description adds context by presenting two input modes ('tags' array vs. tags_to_add / tags_to_delete) and noting that tags can be referenced by id or name. However, it does not disclose whether providing a 'tags' array replaces existing tags or merges, nor does it mention error handling, idempotency, or permission requirements. It adds some value beyond annotations but leaves key behavioral aspects vague.
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?
The description is compact, comprising only two sentences with no superfluous content. The first sentence states the purpose, and the second gives a usage pattern. The second sentence's cryptic phrasing and ambiguous 'or' detract slightly from structural clarity, but it remains efficient and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and only openWorldHint as an annotation, the description is too sparse. It does not clarify whether existing tags are replaced or merged, what the tool returns, whether entities must already exist, or what permissions are required. The brevity leaves an agent under-equipped to predict the tool's full behavior or handle edge cases, especially when compared to richer tool descriptions.
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?
With schema description coverage at 0%, the description is the only source for understanding the entities parameter structure. It supplies a template: each entity item contains 'id' and a 'tags' array with elements that identify a tag by id or name, with an alternative using tags_to_add / tags_to_delete. The ambiguity of the 'or' (likely alternative item shapes, but not formally reflected in the schema) keeps this from being higher, yet it provides necessary semantic grounding.
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?
The description uses the specific verb 'Add/update' and identifies the resource as 'entities,' which are further enumerated in the schema (leads, contacts, companies, customers). It distinguishes from the sibling tool kommo_tags_assign_one by its plural focus and array-based invocation, making the batch nature clear.
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 description implies a batch operation by telling the caller to pass an array of entity objects, but it does not explicitly state when to use this tool versus kommo_tags_assign_one or other tag management tools. No exclusions, prerequisites, or alternative tool references are provided, so the guidance remains at the implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare 'destructiveHint: true' and 'openWorldHint: true', so the destructive nature is covered. The description adds that deletion is based on destination/events, but does not disclose whether all matching webhooks are deleted if only 'destination' is provided, or whether the operation is reversible. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the core action and criteria efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with openWorldHint and ambiguous parameter semantics, the description is too terse. It fails to explain the meaning of 'settings', the exact semantics of 'and/or' (whether it can match multiple webhooks), and the behavior when no parameters are supplied. Since the schema does not compensate, the tool is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It mentions 'destination URL' and 'events', but the schema parameters are 'settings' (array of strings) and 'destination' (uri). The description does not explicitly map 'events' to 'settings', nor does it clarify that at least one parameter must be provided despite the schema listing zero required parameters. This ambiguity leaves an agent guessing about how to populate the parameters.
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?
The description clearly states the verb 'Delete' and the resource 'webhook', and adds the identification criteria 'by destination URL and/or events'. This distinguishes it from sibling tools like 'kommo_webhooks_list' and 'kommo_webhooks_add'.
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 description implies use when a webhook needs to be removed, but it does not explicitly state when to use it versus alternatives, nor does it reference 'kommo_webhooks_list' for discovering existing webhooks. It provides no exclusions, but for a simple delete operation the context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description carries a lower burden. The description adds no extra behavioral context beyond the ID parameter, such as error behavior or return format, but for a simple read operation this is adequate. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundant information. It is appropriately sized for the tool's simplicity and immediately conveys the core operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of readOnlyHint and openWorldHint, the description provides a basic understanding. However, it omits key context such as the meaning of the two parameters and any potential error cases or constraints, making it less complete for an agent that must invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two required integer parameters (id and catalog_id) with zero description coverage. The description only says 'by ID' without clarifying which parameter is which or how they relate. This leaves ambiguity about the role of each ID, failing to compensate for the lack of schema descriptions.
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?
The description clearly states the tool's function with a specific verb ('Get') and resource ('catalog element'), and adds the scope ('by ID'). This distinguishes it from catalog listing tools and other read operations, making the purpose unambiguous.
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 description implies usage when you need a specific catalog element by ID, but provides no explicit guidance on when to use this tool over alternatives (e.g., 'Use catalog_elements_list to browse all elements'). No exclusions or alternative suggestions are mentioned, so it falls between minimal guidance and an implied use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint annotation, the description adds useful behavioral context by noting bulk creation ('one or more') and the custom_fields_values format for phone/email. However, it does not disclose required fields, validation behavior, or response details. No contradiction with annotations.
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?
Two sentences, both concise and relevant. The first states the purpose, the second gives a specific API tip, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with an open-ended schema and no output schema, the description omits essential information such as required contact fields (e.g., name), response format, error behavior, or a link to API docs. The phone/email tip is helpful but leaves the agent under-equipped for successful invocation.
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 0%, so the description partially compensates by explaining how to set phone/email via custom_fields_values. But it leaves other contact fields and the overall structure of each object unspecified, so the compensation is incomplete.
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?
The description clearly states the verb 'Create' and resource 'contacts', specifying 'one or more contacts', which distinguishes it from list/get/update siblings. The additional phone/email tip reinforces the tool's function without ambiguity.
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 description implies usage for creating new contacts and provides a specific how-to for phone/email via custom_fields_values, but it does not explicitly state when to prefer this tool over alternatives like kommo_contacts_update, nor does it mention exclusions such as using lead creation tools for leads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and scope. The description adds behavioral context beyond that: it supports pagination and filters, and query performs full-text search on name/phone/email. This gives the agent useful expectations about the tool's behavior without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose. The first sentence is essential; the second adds a quick query hint but is somewhat redundant with the schema description for 'query'. No waste, but the second sentence could be replaced with more valuable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter list tool with no output schema and only 25% schema description coverage, the description is too thin. It does not explain how to use filter_id, filter_responsible_user_id, order_id, or the 'with' parameter, nor does it mention default behavior (e.g., default page/limit). The annotations provide safety but not operational completeness for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with descriptions for only 'with' and 'query'. The description's mention of query search simply repeats the schema description ('Full-text search (name, phone, email)') and does not explain the six other parameters (page, limit, order_id, filter_id, order_updated_at, filter_responsible_user_id). The agent gains no additional meaning for the undocumented filtering, pagination, or ordering parameters.
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?
Description clearly states 'List contacts with pagination and filters' – a specific verb (list) and resource (contacts). This distinguishes it from sibling tools like kommo_contacts_get (single contact) or kommo_contacts_create via the verb and resource. It also adds scope details (pagination, filters) making the purpose unambiguous.
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 description implies usage for listing contacts with pagination and filters, and gives parameter-level guidance ('Use query to search by name, phone, or email'). However, it does not explicitly state when to choose this tool over alternatives (e.g., kommo_contacts_get for a single contact, or kommo_leads_list for leads), nor any exclusions. Usage is implied but not prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to disclose safety. It adds context about the Chats API add-on but does not describe return format, pagination, or any other behavioral traits. No contradiction with annotations. The additional context is minimal but not required.
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?
The description is a single concise sentence, front-loaded with the core action and resource. The parenthetical adds useful context without bloat. Every word earns its place; there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one required parameter and no output schema, the description is adequate but lacks details about pagination, ordering, or the actual message structure returned. The annotation openWorldHint suggests broader context, but the description does not elaborate. It is minimally viable with clear gaps in operational specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: conversation_id is described in the schema as 'Talk/conversation ID', but the optional 'limit' parameter has no description. The tool description mentions 'messages from a conversation' but does not explain limit or any additional parameter semantics, failing to compensate for the undocumented parameter.
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?
The description clearly states the verb 'Retrieve' and the resource 'messages from a conversation,' distinguishing it from sibling tools like kommo_conversations_list (conversations themselves) and kommo_conversations_messages_send (sending messages). The parenthetical 'Chats API add-on / talks messages' further clarifies the specific domain.
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 description implies usage for fetching message history from a conversation but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The purpose is clear enough that an agent can infer the use case, but there is no explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and world interaction. The description adds the behavioral detail that it returns 'metadata' (not file content), which is useful. However, it does not disclose error behavior, authorization requirements, or what 'metadata' includes, leaving room for ambiguity.
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?
The description is two short sentences with no filler. It front-loads the core purpose and includes only essential information. Every word contributes to clarity.
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?
Given the tool's simplicity (one required param, no output schema), the description adequately covers what it does and what it returns. It does not mention error cases or output structure, but the 'metadata' note gives a clear expectation. With annotations providing safety context, this is near-complete for a lookup tool.
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?
The schema defines a single 'uuid' parameter with no description, and the schema description coverage is 0%. The description clarifies that the parameter is the file UUID via 'by UUID', but does not elaborate on format, source, or how it relates to other file operations. For a single simple parameter, this is acceptable but not rich.
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?
The description clearly states the verb ('Get') and resource ('file metadata by UUID'), which distinguishes it from sibling tools like kommo_files_list or kommo_files_edit. It specifies the exact scope (metadata) and the key (UUID), leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this should be used only when a file UUID is already known, nor does it suggest kommo_files_list for discovering UUIDs. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, signaling a safe read operation. The description adds that the reasons are 'configured in the account', providing context that these are account-level settings. It does not disclose additional behavioral traits like pagination behavior or response structure, but with annotations covering the safety profile, this is adequate.
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?
The description is a single, concise sentence that front-loads the action and resource. There is no wasted verbosity or redundant information, making it easy to parse at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional pagination parameters and no output schema, the description covers the core purpose but omits details about pagination behavior and response format. Annotations provide safety context, but an agent might still wonder what fields are returned or whether all results are returned in one call. Overall, it is minimally viable but lacks some helpful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two parameters (page, limit). It does not mention pagination or explain the parameters. While the parameter names are fairly self-explanatory, the description adds no meaning beyond what the schema provides, leaving a clear gap for an agent unfamiliar with Kommo's pagination conventions.
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?
The description is specific: 'List all lead loss reasons configured in the account.' It clearly states the verb (list), resource (loss reasons), and scope (all, account-level). This differentiates it from sibling kommo_leads_loss_reasons_get, which presumably retrieves a single reason, though the alternative is not explicitly named.
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 description implies usage: use this tool to retrieve all loss reasons. It does not explicitly state when to use it vs alternatives, such as the 'get' variant for a specific reason. There is no mention of exclusions or prerequisites, but the simple nature of the tool makes the context fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already establish the read-only, side-effect-free nature, and the description aligns with them. However, the description adds no extra behavioral context, such as pagination, sorting, or the effect of the 'favorite' parameter on the response.
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?
The description is a single, concise sentence that immediately states the tool's function. No filler or redundant words are present, making it optimally front-loaded.
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 list operation with one optional parameter and read-only annotations, the description is mostly complete. It lacks explicit mention of return format or pagination, but these are not critical for such a straightforward tool given the schema coverage.
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?
The input schema has 100% description coverage for the single 'favorite' boolean parameter. The tool description itself does not mention parameters, but the schema fully describes the only parameter, so the description need not add more.
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?
The description 'List Salesbots in the account' uses a specific verb and resource, clearly identifying it as a list operation. It naturally distinguishes from sibling tools like kommo_salesbots_get (single retrieval), launch, and stop by describing the list action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, nor any mention of when not to use it. There is no explicit context or exclusion suggested, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds minimal context by scoping the list to 'integration sources for incoming leads,' but it does not disclose pagination behavior, ordering, or what fields are returned. With annotations providing the read-only cue, this is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and resource. There is no wasted wording or redundant information. It earns its place as an efficient and front-loaded description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with annotations but no output schema, the description is adequate but incomplete. It clarifies what the tool lists but does not mention pagination parameters, result shape, or any filtering context. Given the tool's simplicity, the gap is noticeable but not severe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (page, limit) with no descriptions, and schema_description_coverage is 0%. The description does not mention or explain these parameters, so the agent must infer their meaning from common pagination conventions. Since the description does not compensate for the low schema coverage, it falls below the baseline.
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?
The description 'List integration sources for incoming leads' uses a specific verb ('List') and resource ('integration sources'), clearly distinguishing from sibling tools like kommo_leads_list (which lists leads) and kommo_incoming_leads_list (which lists incoming leads). It adds the scope 'for incoming leads,' differentiating it from other source-related operations like get, create, or update.
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 description implies usage: when you need to list integration sources for incoming leads. However, it does not explicitly provide when-to-use vs alternatives, such as 'use kommo_sources_get to retrieve a single source' or 'use kommo_sources_create to add a source.' The context is clear but lacks explicit exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and openWorldHint, so the destructive nature is known. The description adds the 'bulk' detail, but does not disclose other behavioral traits such as reversibility, effects on user sessions, or whether deactivation is permanent.
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?
The description is a single, concise sentence with no filler. Every word contributes to the core meaning, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity (one parameter, no output schema) and annotations cover safety. However, the description lacks details about what deactivation entails, whether it is reversible, or any prerequisites, which is a notable gap for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'users' parameter beyond implying an array. It does not state that each item requires an 'id' or what that id represents, leaving the schema to carry the full burden.
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?
The description 'Deactivate users in bulk' clearly states the action (deactivate), resource (users), and scope (bulk). It distinguishes itself from sibling tools like kommo_users_activate by specifying bulk deactivation.
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 description implies usage for bulk deactivation but provides no explicit guidance on when to use this tool versus alternatives (e.g., kommo_users_activate) or any exclusions. Usage is inferred from the name and simple statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by specifying which widgets are included (public installed and private uploaded), but it does not mention pagination, filtering behavior, or response characteristics, which would be useful given openWorldHint.
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?
The description is a single, front-loaded sentence with no wasted words. It communicates the essential scope immediately and is appropriately sized for a straightforward list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with read-only annotations, the description is minimally adequate. It clearly identifies the resource and scope, but it omits any discussion of pagination or the filter parameter, leaving gaps for an agent that needs to understand all optional inputs and open-world behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does not mention 'page,' 'limit,' or 'filter_widget_code' at all, leaving the agent to infer their meaning from names alone. The filter parameter especially lacks needed context about what a 'widget_code' is.
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?
The description uses a specific verb ('List') with a clear resource ('widgets') and explicitly scopes the result to 'public widgets installed and private widgets uploaded by the user.' This clearly distinguishes it from sibling tools like kommo_widgets_get, kommo_widgets_install, and kommo_widgets_uninstall.
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 description implies when to use this tool (to list widgets) but provides no explicit guidance on when not to use it or which alternative to choose. The scope and verb make the basic use case clear, but there are no exclusions or comparisons to related widget operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the HTTP method (PATCH) and endpoint (/leads/{id}), which is useful context beyond the annotations. Annotations already indicate idempotent and non-destructive behavior, so there is no contradiction, but the description does not disclose side effects, response format, or error handling.
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?
The description is a single sentence with no wasted words. It front-loads the verb and resource, then adds the endpoint in parentheses, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with a nested object, this is a minimal but functional description. It lacks guidance on the return value or response format (there is no output schema), and it does not explain how the lead object fields are applied or validated. However, given the clear annotations and schema, this is a minor 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?
The input schema provides descriptions for both parameters (id and lead), achieving 100% coverage, so the baseline is 3. The description adds no extra parameter semantics beyond what the schema already provides; it only references the ID in the endpoint.
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?
The description clearly states the action ('Update'), the resource ('a single lead'), and the method of identification ('by ID'), and adds the HTTP method and endpoint (PATCH /leads/{id}). This precisely distinguishes it from sibling tools like kommo_leads_update or kommo_leads_create.
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 description implies usage context: when you need to update one existing lead by its ID. However, it does not explicitly state when not to use this tool or name alternatives, such as a bulk update tool. The word 'single' provides a hint but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. The word 'Destructive' merely repeats the destructiveHint=true annotation. It does not disclose any additional side effects, irreversibility details, permission requirements, or impact on related data.
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?
The description is extremely concise, consisting of two short sentences ('Delete a role by ID. Destructive.'). It is front-loaded and contains no filler, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple delete operation with a single parameter and annotations confirming destructive behavior, the description is minimally adequate. However, the openWorldHint suggests potential unstated side effects, and the description does not address what happens when deleting a role that is in use or if there are any return implications, leaving some gaps.
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?
With zero schema description coverage, the description's 'by ID' clarifies that the sole required 'id' parameter refers to the role's unique identifier. This adds meaning beyond the bare schema definition, though it does not elaborate on the integer type or range constraints.
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?
The description clearly states the action with a specific verb and resource: 'Delete a role by ID.' This is unambiguous and distinguishes it from sibling tools like kommo_roles_get, kommo_roles_create, and kommo_roles_update.
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 description implies usage (when you need to delete a role) but provides no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites or side-by-side comparison with related role operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the 'Destructive' trait already declared by the destructiveHint annotation, without adding extra context such as irreversibility, cascading effects, or permission requirements. With annotations present, the bar is lower, but the description fails to provide any added behavioral insight beyond what annotations already convey.
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?
The description is a single, front-loaded sentence with no waste. 'Delete a source by ID' is direct, and the redundant word 'Destructive' is brief and not verbose. Every word serves the purpose of conveying the operation.
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 one-parameter destructive tool, the description combined with annotations is nearly complete. It specifies the action and destructive nature, though it could mention irreversibility or impact on related data. Given the tool's simplicity and annotation coverage, it is sufficiently complete, just not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for the 'id' parameter, and the description only mentions 'by ID' without elaborating on the parameter's semantics, format, or source. It adds minimal value over the schema, insufficient to compensate for the 0% coverage gap.
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?
The description 'Delete a source by ID' clearly states a specific verb (delete), resource (source), and the parameter (ID). It distinguishes from sibling tools like kommo_sources_delete_many by specifying single-ID deletion, making the tool's purpose immediately unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when deleting a single source by its ID, and the inclusion of 'by ID' implicitly contrasts with delete_many. However, it does not explicitly state alternatives or when not to use, lacking a direct exclusion or alternative reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds no further behavioral details such as error handling or return format, but it is consistent with the annotations and does not contradict them.
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?
The description is a single sentence, front-loaded, with no unnecessary words. It is extremely concise and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with good annotations and a single parameter, the description is minimally sufficient. However, without an output schema, it doesn't specify the return structure or error conditions, leaving some gap for an agent relying solely on the description.
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?
The schema has one parameter 'id' with integer constraints but zero description coverage. The phrase 'by ID' in the description clarifies that the parameter is the template's ID, providing the essential semantic meaning, though it doesn't elaborate on where to find the ID or any additional context.
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?
The description uses the specific verb 'Get' with resource 'a template' and scope 'by ID', clearly distinguishing it from sibling tools like kommo_templates_list which retrieves multiple templates. The intent is unambiguous and aligns with the tool's name and title.
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 description implies usage: call when you need a specific template and have its ID. However, it does not explicitly state when not to use it or mention alternatives like the list tool, so guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The openWorldHint annotation signals side effects, but the description adds no behavioral context beyond 'Create a webhook.' It does not disclose idempotency, duplicate behavior, or what happens after successful creation.
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?
Two concise sentences with no filler. The first sentence states the primary action, and the second directs attention to the key parameters. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter creation tool, this covers the basics. However, without an output schema, it would benefit from describing expected response or post-condition behavior. The description is adequate but minimal.
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 descriptions cover both parameters at 100%, so the baseline is 3. The description adds value by giving concrete event examples (add_lead, update_contact), which clarifies the expected format beyond the schema.
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?
The description states 'Create a webhook' with a specific verb and resource, and adds examples of events. This clearly distinguishes it from sibling tools like kommo_webhooks_list and kommo_webhooks_delete.
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 description implies usage for creating webhooks but provides no explicit guidance on when to use this tool instead of alternatives. It does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral detail: closing may launch an NPS bot, and force_close=true skips it. This goes beyond the sparse openWorldHint annotation. However, it doesn't mention irreversibility or permissions, so it's not fully transparent but adds meaningful context.
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?
Two sentences, perfectly concise, with the purpose front-loaded and no filler. Every word earns its place.
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?
The tool is simple with only two parameters and no output schema. The description covers the key behavior and the force_close nuance, making it sufficiently complete for the complexity, though it could be more explicit about post-close outcomes.
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?
With 0% schema description coverage, the description adds value by explaining force_close's effect. The id parameter is left implicit but is fairly obvious from context. This partial explanation is adequate but not comprehensive.
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?
The description clearly states the main action 'Close a conversation' with a specific verb and resource. The addition of 'or launch NPS bot' introduces a dual purpose that slightly muddies the primary intent, but it still distinguishes this tool from conversation list/get/message siblings.
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 description indicates the primary use case (closing a conversation or launching NPS) but doesn't provide explicit alternatives or when-not-to-use guidance. Given the large sibling list, more direction would help, but the basic context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this as a safe read operation, but the description adds no additional behavioral context such as response format, error handling for missing IDs, or authentication requirements. It essentially restates the parameters already visible in the schema.
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?
The description is a single, well-structured sentence that is front-loaded and contains no redundant or filler language. Every word contributes meaning.
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?
This is a simple read-only getter with two clearly described parameters and a readOnlyHint annotation. No output schema exists, but the return value is reasonably inferred as the custom field object. The description is adequate for selecting and invoking the tool, though it could mention the response shape for extra clarity.
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?
With schema description coverage at 0%, the description compensates by clarifying that 'id' is the custom field ID and 'entity_type' scopes the lookup. This gives enough semantic meaning for both parameters, though it lacks extra detail like value formats or relationships.
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?
The description 'Get a custom field by ID for an entity type' clearly specifies the action (get), resource (custom field), and required constraints (by ID, for an entity type). It distinguishes from list operations and other entity-specific getters by explicitly targeting a single custom field.
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?
Usage is implied via the phrase 'by ID for an entity type', indicating this is for retrieving a specific custom field rather than listing all. However, there is no explicit direction to alternatives like kommo_custom_fields_list or any when-not-to-use guidance, leaving the choice somewhat inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no extra behavioral context such as error handling, response format, or rate limits. It is neutral and does not contradict annotations.
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?
The description is a single, front-loaded sentence that conveys the essential information without any fluff. Every word earns its place.
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 single-get tool with one parameter, annotations, and no output schema, the description is adequate. It could mention that the return is the event object, but the name and 'get by ID' make that implicit. The simplicity of the tool makes this complete enough.
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% with the parameter 'id' described as 'Event ID'. The tool description adds no additional meaning beyond the schema, so it stays at the baseline for high coverage.
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?
The description uses a specific verb 'Get' and resource 'single event by ID', clearly distinguishing this from siblings like kommo_events_list (which lists events) and kommo_events_types. The phrase 'by ID' removes ambiguity about the operation's scope.
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 description implies usage when you need a single event by ID, but does not explicitly state when to use this tool versus list or types. No exclusions or alternatives are mentioned, so it relies on common CRUD patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The openWorldHint annotation already signals a non-read-only operation, but the description adds value by specifying that the tool returns upload URLs and a session token, and supports both new files and new versions. It does not contradict the annotation and provides useful behavioral context beyond the generic hint, though it omits details like session expiration or the need to use the URLs with upload_part.
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?
The description is two short sentences, front-loaded with the action, and contains no fluff. Every phrase contributes meaning: the action, the modes, and the return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations, the description covers the essential action and return value, but it is incomplete for a multi-step upload flow. It lacks context such as the relationship to kommo_files_upload_part, prerequisites, or constraints (e.g., file size limits), and does not explain several parameters. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only file_uuid has a description), and the tool description does not compensate. It only hints at file_uuid via 'new version', which is already in the schema, and fails to explain file_name, file_size, content_type, or with_preview, leaving the agent without crucial semantic information for those parameters.
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?
The description uses a specific verb ('Create') and resource ('upload session'), and distinguishes the tool from siblings by explicitly mentioning 'new file or new version' and the return of upload URLs/token. This clearly separates it from kommo_files_upload_part and other file-related tools.
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 description implies the tool is the first step for uploading files, but it does not explicitly state when to use it versus alternatives like kommo_files_upload_part or mention the subsequent steps. There are no exclusions or alternative tool names given, so usage is implied rather than clearly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the readOnlyHint and openWorldHint annotations. It adds no additional behavioral context beyond the fact that it fetches a single loss reason, but the annotations already cover the safety profile. A neutral score is appropriate.
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?
One short sentence with no filler or redundant information. The description is extremely concise and easy to parse.
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 single-parameter read operation with readOnly and openWorld annotations, the description provides the essential information. It doesn't explicitly state return value/error behavior, but the simplicity of the tool makes this less critical.
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?
The input schema fully describes the single parameter 'id' as 'Loss reason ID' with 100% coverage. The description's 'by ID' restates the schema without adding additional semantics, so a baseline of 3 is given.
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?
The description clearly states the action (get), the resource (loss reason), and the qualifier (by ID), which differentiates it from the sibling tool kommo_leads_loss_reasons_list that retrieves all loss reasons.
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 phrase 'by ID' implies this tool should be used when a specific loss reason ID is known, while the list sibling would be used otherwise. However, no explicit alternative is mentioned, leaving the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark readOnlyHint=true, and the description adds behavioral context by noting the summary is client-side and that pagination is controlled via max_pages. It does not disclose whether totals may be partial when pagination limits are hit, but given the annotation coverage, this is a reasonable level of transparency.
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?
Two concise sentences front-load the core purpose, followed by parameter-related behavior. No filler or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description doesn't detail the return format, but it explains core functionality, pipeline filtering, and pagination. The main gap is ambiguity about whether pagination limits may cause counts/price totals to be partial, which is important for a summary tool.
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 descriptions are absent (0% coverage), so the description carries the burden. It explicitly mentions pipeline filtering (pipeline_id) and pagination via max_pages, adding meaning beyond bare integer bounds. However, it does not specify defaults or behavior when max_pages is omitted.
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?
The description clearly states the tool produces a client-side summary of leads with counts and price totals, optionally filtered by pipeline. It distinguishes from sibling tools like leads_list by focusing on aggregation rather than raw lead listing, though it lacks an explicit action verb.
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 description implies this tool is for aggregate summaries rather than raw lead lists, but it does not explicitly state when to prefer it over alternatives like kommo_sales_report, kommo_pipeline_analytics, or kommo_incoming_leads_summary. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds the behavioral constraint that the note is located by both entity type and note ID, which is a useful scoping detail. However, it does not disclose return format, error behavior, or other runtime traits beyond what the schema and annotations imply.
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?
The description is a single, front-loaded sentence with no redundant words. Every word contributes to the purpose, making it highly concise and well-structured.
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 get-by-ID tool with good annotations and an enum schema, the description is largely sufficient. It covers the essential operation and parameters. However, since there is no output schema, a brief note about the return value (e.g., the note object) would make it slightly more complete, but it is not critical given the tool's clear behavior.
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 0%, so the description must compensate. It clarifies that 'id' is the note ID and 'entity_type' scopes the lookup, but it does not elaborate on the enum values or the relationship further. This adds some meaning beyond the raw schema, but not enough to fully cover the missing property descriptions.
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?
The description 'Get a note by entity type and note ID' clearly specifies the verb (get), resource (note), and the required scoping (entity type and note ID). It distinguishes from sibling tools like kommo_notes_list_by_entity by emphasizing a single note retrieval by ID, making its purpose unambiguous.
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 description implies this tool is for fetching a specific note when both entity_type and note ID are known, but it does not explicitly state when to use it over alternatives like kommo_notes_list or kommo_notes_list_by_entity. There is no mention of exclusions or alternative tools, so guidance is present but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, establishing safety. The description adds the behavioral detail that stages are included in the response, which is useful context. However, no other behaviors (error handling, auth) are described, but annotations lower the burden.
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?
A single, front-loaded sentence with no wasted words. All critical information is present.
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 get-by-ID tool with one well-documented parameter and read-only annotations, the description is sufficient. It communicates the key behavior (including stages) and the schema covers the parameter, so no gaps remain.
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?
The schema fully describes the 'id' parameter as 'Pipeline ID' (100% coverage). The description adds no additional parameter meaning, so baseline 3 is appropriate.
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?
The description uses a specific verb ('Get') and identifies the resource ('pipeline by ID') while adding the detail 'including stages,' which clearly differentiates it from pipeline list and stage-specific tools.
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?
No explicit when-to-use vs alternatives is given, but 'by ID' implies a targeted lookup. The phrase 'including stages' hints at a use case but does not mention sibling tools like pipelines_list or stages_get. Thus, usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds no additional behavioral context like pagination behavior, response format, or filtering nuances, but for a simple list operation this is acceptable.
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?
The description is a single, concise sentence that conveys the core purpose without any filler or redundancy. It is perfectly sized for its content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and only a minimal description, the tool lacks detail on pagination, filtering, and expected return values. It covers the basic 'list tags' use case but is incomplete for an agent needing to fully leverage all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (query and filter_name have descriptions). The tool description adds no parameter-level detail, leaving page, limit, filter_id, and entity_type behavior under-explained. The entity types are mentioned in the description, but pagination/filter parameters remain ambiguous.
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?
The description clearly states the action ('List') and the resource ('tags') with explicit entity types (leads, contacts, companies, customers). This distinguishes it from sibling tag tools like kommo_tags_create and kommo_tags_assign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving tags associated with the specified entity types, providing clear context. However, it does not explicitly mention alternatives or when not to use this tool, stopping short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool can create multiple tasks at once ('one or more') and lists typical fields, which adds context beyond the bare schema. However, it does not explain permissions, validation behavior, or the response format. The openWorldHint annotation hints at an open schema, but the description does not elaborate on the consequences of using unlisted fields.
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?
The description is a single concise sentence that immediately states the action and then enumerates typical fields. No unnecessary words or repetition. It is front-loaded and easy to parse, making it an efficient communication of the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool being relatively simple (one array parameter), the description leaves important gaps. It does not specify the return value of the create operation (no output schema exists), nor does it clarify required fields or how errors are reported. Given the openWorldHint and the lack of structured property descriptions, an agent would need more context to invoke the tool correctly and interpret results.
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?
With 0% schema description coverage, the description compensates by listing typical fields (text, complete_till, entity_id, entity_type, responsible_user_id, task_type_id) and noting that complete_till is a unix timestamp. This provides meaningful parameter guidance that the schema itself lacks. However, it does not clarify which fields are required or optional, leaving some ambiguity.
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?
The description clearly states the tool's function with a specific verb and resource: 'Create one or more tasks.' It distinguishes from sibling tools like kommo_tasks_list, kommo_tasks_get, and kommo_tasks_update by focusing solely on creation. The title 'Create tasks' reinforces this purpose.
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 description implies the tool is for creating tasks, but does not explicitly contrast it with alternatives or state when not to use it. It does not mention that updates should use kommo_tasks_update or that listing uses kommo_tasks_list. The usage context is implied by the verb 'Create' rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only restates the basic get-by-ID operation and adds no behavioral context beyond what the readOnlyHint annotation already provides. It does not mention return format, error handling, or access requirements. Since the annotations cover the read-only nature, the description provides minimal additional value.
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?
The description is a single short sentence that immediately states the purpose with no unnecessary words. It is front-loaded and easy to parse.
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 read operation with a single parameter, the description conveys the essential information. However, with no output schema, it would be helpful to mention that it returns the task object. The absence of such detail is a minor gap, but overall the description is adequate for the tool's simplicity.
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?
The input schema provides only the parameter name 'id' with no description (0% coverage). The description's phrase 'by ID' clarifies that the parameter is the task's identifier, which is essential for correct invocation. This compensates for the schema gap, though it doesn't add type or format details beyond the schema's integer type.
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?
The description uses the specific verb 'Get' with the resource 'task' and identifies the lookup mechanism 'by ID', making it unambiguous what the tool does. It clearly distinguishes from sibling tools like kommo_tasks_list or kommo_tasks_update.
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?
There is no explicit guidance on when to use this tool versus alternatives like kommo_tasks_list. However, the description implies it should be used when a specific task ID is known and a single task is needed. No exclusions or alternative recommendations are provided, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the entity-scoping behavior ('attached to a lead/contact/company/customer') but does not disclose additional traits such as pagination, return format, or behavior when the entity does not exist.
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?
The description is a single, front-loaded sentence with no filler. Every word contributes to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema covers the two required parameters, but the description does not mention pagination, output shape, or error behavior. With no output schema, some of this burden falls on the description, which leaves gaps.
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 coverage is 0%, so the description must compensate. It does add meaning by naming the entity types and conveying that files are attached to an entity, which helps infer the role of entity_id. However, it does not explicitly explain the entity_id parameter or how the two parameters combine.
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?
The description uses the specific verb 'Get' and identifies the resource as 'files attached to a lead/contact/company/customer.' This clearly distinguishes the tool from sibling tools like kommo_files_list (all files) and kommo_files_get (a single file).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you need files attached to a specific entity type. It does not explicitly mention alternatives or when-not-to-use scenarios, but the entity-type scope is sufficient to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare `readOnlyHint: true`, and the description's 'Get' verb is consistent with that. However, the description adds no extra behavioral context such as authentication requirements, rate limits, or how the summary counts are structured. It is consistent but not additive.
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?
The description is a single, front-loaded sentence conveying the core purpose without unnecessary jargon or repetition. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and zero parameters, the description should clarify what 'summary counts' includes (e.g., grouped by status, source, or overall total). The ambiguity could cause an agent to misunderstand the return format. However, for a simple no-parameter summary tool, it provides enough to differentiate from list/get tools, so it is minimally adequate.
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?
The input schema is empty with no parameters. The baseline for zero parameters is 4, and the description does not need to compensate for missing parameter details. It correctly adds no irrelevant parameter information.
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?
The description clearly uses the verb 'Get' and specifies the resource 'summary counts for incoming leads,' which is a specific action on a specific resource. It distinguishes from sibling tools like `kommo_incoming_leads_list` (lists leads individually) and `kommo_leads_summary` (summarizes all leads, not just incoming).
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 description implies usage for retrieving summary counts of incoming leads but does not explicitly state when to use this tool versus alternatives like `kommo_incoming_leads_list` or `kommo_leads_summary`. No exclusions or alternative references are given, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation openWorldHint is minimal and doesn't convey safety or side effects. The description adds a useful behavioral detail: 'Body is base64-encoded bytes.' However, it omits other operational traits like error handling, idempotency, or single-use URL behavior, leaving some gaps. It doesn't contradict annotations.
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?
Two concise sentences, front-loaded with the action and key requirement. Every word earns its place with no redundancy.
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 two-parameter tool with no output schema, the description adequately covers the core usage and correctly places it within the create-session upload flow. It could mention that multiple chunks may be required, but it's sufficient for an agent to select and call it correctly.
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 coverage is 100% with descriptions for both parameters. The tool description largely restates schema info ('absolute upload URL from the session', 'base64-encoded bytes') without adding new semantic meaning. This meets the baseline for well-documented schemas.
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?
The description uses a specific verb 'Upload' and clearly identifies the resource: 'a chunk to an absolute upload URL returned by create session.' This distinguishes it from sibling file tools like files_create_session or files_delete, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly references 'create session', indicating this tool is used after session creation. It provides clear context for when to invoke it, though it doesn't explicitly exclude alternatives or mention when not to use it. This matches the 'clear context, no exclusions' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint in annotations and no readOnly/destructive hints, the description adds some context by mentioning 'duplicate control supported' and indicating a multi-entity complex create. However, it does not disclose potential side effects, partial-failure behavior, or authentication requirements, so it provides moderate additional transparency beyond the annotation.
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?
The description is a single sentence that includes the endpoint, conveys the primary action, and highlights the duplicate-control feature. It is front-loaded and contains no wasted words.
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 create operation with one self-describing parameter, the description is largely adequate: it states the action, the scope (contacts and companies), and a key feature. However, it omits response format and any caveats about partial failures or duplicate resolution behavior, which would be valuable for a complex create; thus it is not a 5.
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?
The input schema's 'items' parameter already has a detailed description listing name, price, _embedded.contacts, _embedded.companies, and metadata, achieving 100% schema coverage. The tool description adds no further parameter meaning, so it meets the baseline of 3.
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?
The description uses the specific verb 'Create' with the resource 'leads' and explicitly mentions 'with contacts and companies in one request', which clearly differentiates it from the simple lead creation sibling (kommo_leads_create). It also notes duplicate control and provides the endpoint, unambiguously stating what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in one request' implies the use case of atomically creating a lead along with its contacts and companies. This clearly signals when to use it, but it does not explicitly name the alternative (e.g., kommo_leads_create) or state when not to use it, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare openWorldHint=true and destructiveHint=false, indicating a non-destructive operation. The description adds that the return value includes created leads with IDs, which explains the response shape. It does not cover failure modes or partial success, but given the annotations provide the safety profile, this is acceptable.
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?
Three short, front-loaded sentences: action, input instruction, and output promise. Every sentence is necessary and contributes to the overall clarity.
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 create tool with one parameter, the description sufficiently covers purpose, input structure, and return value. It does not discuss edge cases like partial failures or validation rules, but these are not critical for the core function.
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?
The only parameter, 'leads', has a detailed schema description that includes examples of fields (name, price, status_id, etc.), providing 100% coverage. The tool description's 'Pass an array of lead objects' is largely redundant with the schema, so it adds minimal new meaning.
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?
The description uses a specific verb-resource pair ('Create one or more leads'), explicitly states the operation scope, and clearly indicates the return value (created leads with IDs). This clearly distinguishes it from sibling read/update tools via its create action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool's purpose and hence implies when to use it, but it does not explicitly exclude or contrast with the sibling kommo_leads_complex_create, which could be an alternative for complex creation scenarios. Still, the context is clear enough for an agent to infer basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral constraints: 'Max 250 per page' and 'Rate limit 7 req/s.' These disclose pagination limits and rate limiting, which are not available in annotations or schema. The mention of 'optional embedded entities' also gives insight into response customization.
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?
The description is a single, well-structured sentence that front-loads the primary action ('List leads') and packs in three key aspects (pagination, filters, embedded entities) plus two critical constraints (max 250 per page, rate limit 7 req/s). There is no redundancy or filler.
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 tool with 17 parameters and no output schema, the description is reasonably complete. It mentions pagination, filtering, embedded entities, and rate limits—enough for an agent to select and invoke the tool. However, it could briefly note that the response is a paginated list of leads (though the name/title imply this) and that filters are optional. The detailed schema compensates for omitted parameter specifics.
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?
The input schema provides 100% coverage with descriptions for all 17 parameters, so the description does not need to add much. The description references 'pagination, filters and optional embedded entities' at a high level, but it does not add new semantic details beyond the schema. Baseline of 3 is appropriate given high schema coverage.
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?
The description clearly states the tool 'List leads with pagination, filters and optional embedded entities,' which is a specific verb-resource combination that distinguishes it from sibling tools like kommo_leads_get (single lead) and kommo_leads_search (search). The mention of pagination and filters clarifies the scope of the collection operation.
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 description implies usage context (listing leads with pagination/filters) but does not explicitly state when to use this tool versus alternatives. It does not mention exclusions or alternatives such as 'use kommo_leads_get for a single lead' or 'use kommo_leads_search for keyword search.' Thus, usage guidance is primarily implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and open-world behaviors. The description adds the loss_reason_id requirement for lost statuses, which is useful. But it does not elaborate on other effects like pipeline changes or reversibility, so transparency is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and every sentence adds value. No fluff or redundancy.
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 mutation tool with idempotentHint and fully described parameters, the description covers the essential action and the key lost-status rule. It may not explain how to source valid status_ids or return behavior, but given the annotations and schema, it is reasonably complete.
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 descriptions cover 100% of the parameters, including the 'Required when moving to a lost status' note on loss_reason_id. The description repeats this but adds no new parameter-level meaning beyond the schema.
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?
The description clearly states the verb 'Move' and the resource 'lead' to 'another pipeline stage', which is specific and distinguishes it from general update tools. The added note about loss_reason_id for lost statuses further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for stage transitions and provides a concrete rule for lost statuses. However, it does not explicitly contrast with sibling tools like kommo_leads_update or kommo_leads_update_one, which could also modify status_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is covered. The description adds the behavioral nuance of 'full-text search' and 'by name/query', but does not explain pagination, result ordering, or the meaning of the 'with' parameter. No contradiction with annotations.
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?
The description is two concise sentences: the first states the purpose and the second provides an alternative. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with read-only and open-world annotations, the description is mostly adequate, but it does not explain the 'with' parameter or mention limit semantics or result expectations. The sibling distinction helps, but some parameters remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only query has a description 'Search text'). The description confirms query searches by name/query but leaves 'with' and 'limit' unexplained. Since coverage is low, the description should have compensated more for these undocumented parameters.
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?
The description clearly states the tool performs full-text search for leads by name/query, using a specific verb and resource. It also explicitly distinguishes itself from the sibling tool kommo_leads_list by saying 'Prefer kommo_leads_list for advanced filters.'
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?
It gives direct usage guidance: use this for convenient full-text search, and use kommo_leads_list for advanced filters. This provides a clear when-to-use and when-not-to-use comparison with an alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (idempotentHint, destructiveHint) already cover safety and idempotency. The description adds the id requirement but does not clarify update semantics (e.g., partial vs full replace) or failure behavior. No contradiction with annotations.
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?
The description is two short sentences, front-loaded with the core action, and every word adds meaning. No filler or redundancy.
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?
Given a single parameter, a detailed schema, and annotations, the description adequately covers usage. It could mention return behavior but is sufficiently complete for a batch update tool with low complexity.
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 high (100%) with detailed field descriptions. The description adds essential semantic value by requiring each object to include id, which is not enforced in the schema's item structure, and clarifies usage for a single lead.
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?
The description clearly states the tool updates one or more leads, with a specific verb and resource. It distinguishes from related tools like kommo_leads_create and kommo_leads_update_one by noting batch capability ('one or more leads').
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 description provides the prerequisite that each object must include id, and notes single-lead usage with id + fields. However, it does not explicitly mention alternatives like kommo_leads_update_one for single updates, leaving the choice of tool 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint annotations already communicating the safe read nature, the description adds only the 'when embedded' nuance about stages. This is useful but lacks details on response format, pagination, or error behavior. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant words. It delivers the core action and a relevant qualifier in a compact format.
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 no-parameter, read-only list tool with good annotations, the description adequately covers purpose and scope. Minor gaps include lack of explicit return type or pagination details, but the tool's simplicity and openWorldHint annotation mitigate the need for more.
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?
The input schema has zero parameters, so baseline is 4. The description correctly avoids inventing parameters and adds no unnecessary param-related details. No further semantic elaboration is needed.
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?
The description uses the specific verb 'List' with the resource 'lead pipelines', and clarifies scope with 'all' and the optional inclusion of stages. This clearly distinguishes it from sibling tools like kommo_pipelines_get (retrieve one) or kommo_pipelines_create.
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 description implies use for retrieving all pipelines, but does not explicitly state when to prefer this over kommo_pipelines_get or kommo_stages_list. No alternatives or exclusions are mentioned, so the guidance is largely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the date format and API endpoint, which is useful but does not disclose response format, pagination, or the effect of the report_type parameter. This matches a baseline where annotations carry the safety burden.
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?
The description is a single sentence that front-loads the action and resource, includes the endpoint, and appends the date format hint. Every word earns its place, with no filler or redundancy.
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?
The tool is simple (3 params, all documented in schema) and has annotations covering read-only/open-world behavior. The description explains the core purpose and required inputs. It does not mention the optional report_type parameter or return format, but the schema covers report_type and no output schema exists, so the description is adequate for this complexity.
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%, so the baseline is 3. The description repeats the date format (YYYY-MM-DD) already present in the schema and does not add meaning for report_type. It provides no additional parameter insight beyond the structured schema.
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?
The description explicitly states 'Fetch leads sales report for a date range' and provides the exact API endpoint (GET /api/v4/leads/reports), clearly identifying the resource and scope. This distinguishes it from sibling tools like kommo_leads_list or kommo_pipeline_analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: when a leads sales report for a specific date range is needed. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds a minor scope detail ('configured in the account') but does not disclose additional behavioral traits such as pagination, response format, or permissions. No contradiction with annotations.
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?
The description is a single, concise sentence that directly states the action and resource. It is front-loaded and contains no unnecessary words or repetition.
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 list operation with no parameters and no output schema, the description is mostly complete. It states what it does (lists webhooks) and the scope (in the account). It does not describe the response format, but the simplicity of the tool makes that less critical, and the title reinforces the behavior.
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?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the schema coverage is trivially 100%. There is nothing to add beyond the fact that no input is required.
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?
The description uses a specific verb 'List' with a clear resource 'webhooks' and scope 'configured in the account.' This clearly distinguishes it from sibling tools like kommo_webhooks_add and kommo_webhooks_delete, which handle creation and deletion.
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 description implies usage when you need to view existing webhooks, but it does not explicitly mention when to use this tool versus alternatives, nor any exclusions or prerequisites. The context of the sibling tools (add/delete) provides some implicit differentiation, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the behavioral safety is covered. The description adds the optional embedding behavior, but it does not disclose what happens for missing IDs, response format, or any rate limits. Given the simplicity and existing annotations, this is adequate but not enriched.
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?
The description is a single concise sentence of 12 words, front-loaded with the action ('Get a single lead') and the primary parameter ('by its ID'). Every word contributes value, with no filler or redundancy.
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 simple, read-only get-by-ID tool with 100% parameter schema coverage and no output schema, the description is complete. The annotations cover safety and open-world behavior, and the schema covers parameter syntax, so the agent has all necessary information to invoke the tool correctly.
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%, with both 'id' and 'with' having meaningful schema descriptions. The description's phrase 'embedding related entities' merely paraphrases the 'with' parameter and does not enumerate valid entity types or provide examples, so it adds little beyond the schema.
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?
The description uses a specific verb ('Get') and resource ('a single lead by its ID'), which clearly distinguishes it from sibling tools like kommo_leads_list (list all leads) and kommo_leads_search (search). The mention of optional embedded entities adds additional scoping beyond a generic 'get lead'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: fetch one lead when the exact ID is known, possibly with related entities embedded. It does not explicitly name alternatives like kommo_leads_list or kommo_leads_search, nor does it state when not to use it, but the context is unambiguous for a get-by-ID operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint annotation (which is a schema hint, not a safety/behavior hint), the description shoulders most of the burden. It discloses the metadata caveat for catalog links, but does not state that this is a mutating operation, mention side effects, or describe return behavior. This is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. Effectively front-loaded with the primary action and immediately provides the critical parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation operation with no output schema and minimal annotations, the description is somewhat thin. It explains what is needed but omits any mention of return values, error behavior, or the effect of creating a new link. Still, the core usage is clear and sufficient for an agent to attempt the call.
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?
The schema has 0% description coverage and the links item is an open object with no property definitions. The description compensates by naming the internal fields (to_entity_id, to_entity_type) and the metadata requirement, adding essential meaning beyond the raw schema.
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?
The description clearly states the action: 'Link entities to a parent.' It uses a specific verb and resource, and the mention of required fields (to_entity_id, to_entity_type) distinguishes this from sibling tools like kommo_links_list and kommo_links_unlink.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on how to use the tool, specifying that each link needs to_entity_id and to_entity_type, and notes a special case for catalog links. It implies this is for creating new links but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint=true and openWorldHint=true annotations by disclosing that endpoint availability depends on account plan/API support, and by giving the exact HTTP method and path. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first states the purpose and endpoint immediately; the second adds the critical availability caveat. No wasted words or repetition of schema content.
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 parameterless, read-only tool with no output schema, the description sufficiently covers what is fetched, the endpoint, and a key constraint. A minor gap is that it does not hint at what the dashboard payload contains, but this is acceptable given the tool's simplicity.
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?
With zero parameters and an empty schema (100% coverage vacuously), the baseline is 4. The description's inclusion of the endpoint implicitly confirms that no input is required, which is all that can be expected here.
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?
The description uses a specific verb ('Fetch') and a clear resource ('Kommo dashboard payload'), and includes the exact endpoint (GET /api/v4/dashboard). It is unmistakably distinct from the 100+ sibling tools, which target specific resources like leads, contacts, or pipelines.
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 description provides a useful operational caveat ('Availability depends on account plan/API support') but does not explicitly state when to use this tool versus alternatives. As the only dashboard-related tool among siblings, usage is implied rather than directly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations indicating read-only and open-world behavior, the description adds significant context: it reveals a fallback to paginated lead list aggregation, the fact that only open leads are considered, and that results are grouped by status/owner. This discloses external API calls and potential pagination behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, information-dense sentence. It front-loads the core purpose and includes fallback behavior without wasted words, making it easy to scan.
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?
With no output schema, the description gives a reasonable indication of the return shape ('aggregates open leads by status/owner'). It explains the fallback and scoping to open leads. However, it does not describe the exact structure of the native analytics response or potential limitations, leaving slight ambiguity.
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 75%, so the schema already documents most parameters. The description adds context that aggregation is by status/owner and uses pagination, but it does not add specific parameter-level meaning beyond what schema descriptions already provide (e.g., date formats, max_pages default).
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?
The description clearly states a specific action ('aggregates open leads by status/owner') and resource ('pipeline analytics'), with a clear fallback mechanism. It distinguishes itself from sibling tools like kommo_pipelines_list or kommo_leads_list by focusing on analytics rather than raw data.
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 description implies usage for pipeline analytics and describes a fallback path ('Native pipeline analytics if available'), but it does not explicitly state when to prefer this tool over alternatives such as kommo_sales_report or kommo_leads_summary. No exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. It adds value by specifying what core data is returned and how to request optional embedded data, giving agents a clear behavioral picture without redundancy.
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?
Two sentences: the first states the core function and return fields, the second explains the optional parameter. Every word earns its place, and the information is front-loaded for quick scanning.
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 simple read-only account getter with one optional parameter and no output schema, the description is complete. It states what will be returned, how to request extras, and annotations cover safety. No critical information is missing.
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?
The schema already documents the 'with' parameter with 100% coverage, listing valid extras and 'etc.' The description briefly repeats a subset of these values, but doesn't add new semantic meaning beyond the schema. This matches the baseline of 3 for full schema coverage.
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?
The description uses the specific verb 'Get' with a clear resource 'current Kommo account information' and lists the key data fields (name, id, subdomain, users count). This makes it unambiguous and distinguishes it from sibling tools that target leads, contacts, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: to retrieve account-level information. It also explains how to extend the response using the 'with' parameter. While it doesn't explicitly contrast with alternatives, the resource is unique enough that no exclusions are necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, and the description reinforces and expands on this by specifying that the destruction targets 'that integration'. This adds context about the scope of the destructive action without contradicting 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and contains no filler or redundant information. Every word contributes to understanding the tool's purpose and danger.
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 one-parameter tool with a destructive annotation and no required output schema, the description sufficiently covers the key aspects: what it does, what parameter is needed, and that it is destructive. Minor gaps like reversibility or permissions are not critical given the annotations.
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 description coverage is 0%, but the description compensates by explaining the sole parameter: uninstall occurs 'by code', which maps directly to widget_code. This provides essential meaning that the bare schema lacks, though it could offer more detail on sourcing the code.
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?
The description uses a specific verb 'uninstall' with a clear resource 'widget' and identifies the method 'by code'. This distinguishes it from sibling tools like kommo_widgets_install, kommo_widgets_list, and kommo_widgets_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (to uninstall a widget) and adds a warning that it is 'destructive for that integration', which guides the agent to use caution. It does not explicitly mention alternatives, but the single-purpose nature makes the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![kommo-mcp MCP server](https://glama.ai/mcp/servers/runitsolutions/kommo-mcp/badges/card.svg)](https://glama.ai/mcp/servers/runitsolutions/kommo-mcp)

Score Badge

Copy to your README.md:

[![kommo-mcp MCP server](https://glama.ai/mcp/servers/runitsolutions/kommo-mcp/badges/score.svg)](https://glama.ai/mcp/servers/runitsolutions/kommo-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/runitsolutions/kommo-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server