Kommo

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations beyond idempotentHint=true, which matches (calling with same token is idempotent). Description explains side effects: browser login, access token, session-only vs permanent connection. Adds value beyond annotations by clarifying the token flow and configuration alternative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with dense info, front-loaded with purpose and audience. Slightly flippant tone, but every part adds value. Could be split into clearer steps, but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 1 param, no output schema, and idempotent annotation, the description covers the essential behavioral aspects. Explains both usage modes and the recommended permanent config approach. Good enough for a simple auth tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has one 'token' param with 0% description coverage, but the description explains its meaning: JWT token to be pasted after user provides it. Also clarifies that calling without args returns a link. Adequately compensates for schema's lack.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear purpose: authenticate user, login via browser or token. Distinguishes from siblings like 'connect' and 'kommo_list_accounts' by focusing on auth. Title and description align. Could be more explicit about being the auth entry point.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use and how: with no args to get login link, or with token for session login. Also recommends permanent config-based token. Contrasts with session-only option, guiding agent on best practices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover safety. The description adds behavioral context by explaining the output shape under different conditions (authenticated vs. pending connections), which is useful 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, and every sentence adds crucial information about conditional outputs. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no parameters, no output schema), and annotations cover safety. The description explains the main behaviors (authenticated vs. missing credentials), which is sufficient for a status-check tool. Minor gap: it doesn't specify the format of the URLs, but that's not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema coverage is 100%. The description adds value by explaining what the tool returns (status, URLs, pending array), which is the primary semantic context an agent needs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: it returns connection status and URLs. It specifies the resource (connection status) and the action (returns), and it differentiates itself from siblings like authenticate by outlining what it returns when providers are connected or credentials are missing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: to check connection status and obtain connect URLs when credentials are missing. It does not explicitly exclude other tools, but the provided conditions (authenticated:true, missing credentials) imply its usage scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds value by detailing the exact fields returned and the optional `with` parameter for including users/fields/pipelines. It does not contradict annotations and provides concrete 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the purpose and key details without wasted words. It is highly concise and well-structured for quick parsing by an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with good annotations and a simple purpose, the description is mostly complete. It explains the output fields and optional expansions, but lacks any mention of the `account` parameter semantics or return format. Given the tool's simplicity, this is a minor gap, slightly reducing completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the `with` parameter as optional for including additional data, but the `account` parameter is not described at all. This partial coverage provides some meaning but leaves a significant gap for one of the two parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns data of the connected Kommo account, listing specific fields (id, nome, subdomain, currency, timezone) and the optional `with` parameter for additional data. It distinguishes from sibling tools like kommo_list_accounts by focusing on a single connected account rather than listing accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for retrieving account metadata, but it does not explicitly state when to use it versus alternatives like kommo_list_accounts or other kommo tools. No exclusions or conditional guidance are provided, leaving the agent to infer usage from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by mentioning bulk support and filterability. However, it does not disclose return format, pagination behavior, or how catalog_id and catalog_ids interact, which would be useful 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and avoids unnecessary words, fitting within a few lines. However, the action line ('action: list | elements') adds confusion rather than clarity, slightly reducing structure quality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, no output schema, and 0% parameter documentation, the description is insufficient. It does not explain how to use the tool effectively, what the response looks like, or how to combine parameters. The bulk support is mentioned but not detailed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It hints at filtering/searching ('filtrável/buscável') and bulk via catalog_ids, but it does not explain parameters like page, limit, query, filter, account, or catalog_id. The mapping between parameters and their usage is largely absent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it deals with catalogs and elements, listing both 'list' and 'elements' actions, but it's unclear which action this specific tool performs. The name suggests 'elements', and it mentions '[Flattened action: elements]', but the description still includes 'list' without clearly distinguishing from the sibling kommo_catalogs_list. This ambiguity reduces clarity about the tool's exact purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions bulk support with catalog_ids and filtering, but it does not explicitly state when to use this tool versus kommo_catalogs_list or other siblings. There is no clear 'use this for elements, use that for catalogs' guidance, leaving the agent to infer context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety traits. The description adds that the tool is 'filtrável/buscável' and supports 'bulk execution' via catalog_ids, which are useful behavioral traits beyond the schema. However, it omits details about paging, response format, or other side effects, resulting in partial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief, but it uses non-standard notation like '|', '[Flattened action: list]', which is cryptic and lacks clear structure. Every sentence is short, but the formatting is opaque, and the meaning could be misparsed by an agent. It is concise but not well-structured or readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only 7 parameters and no output schema, the description must explain the tool's behavior and parameter usage. It does not explain page/limit/query/filter/account/cataliada_id, and it muddles the catalog-versus-elements scope. The tool's overall behavior is unclear and could lead to incorrect invocation, so completeness is low.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter semantics. The only parameter explanation is that catalog_ids enables bulk execution. The other six parameters (page, limit, query, filter, account, catalog_id) are completely unexplained, leaving the agent without understanding their roles. The description adds marginal value but is largely inadequate for the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'action: list (todos os catálogos)' which clearly identifies it as a list tool for catalogs. However, it also mentions 'elements (itens de um catálogo)', which blends a separate capability better suited to kommo_catalogs_elements, introducing ambiguity. The primary verb and resource are present, but the dual-action phrasing 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.

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 like kommo_catalogs_elements. It mentions 'elements' but does not direct users to the dedicated sibling tool nor define exclusions. The lack of contextual or alternative references leaves the agent to guess from the name alone, earning a low score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is not read-only, but the description adds little about side effects. It mentions 'body em `data`' for create, which hints at the input structure, but does not disclose what happens on creation (e.g., response format, idempotency, or any side effects). The description relies on annotations without providing context beyond them, so transparency 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes unnecessary content (listing all actions) that is irrelevant to the flattened create action. The structure is confusing with the bracket note and bulk support comment, making it less concise and harder to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, no output schema, minimal annotations), this description is incomplete. It lacks information about return values, required fields, error handling, or the purpose of `ids` for bulk creation. The description does not provide enough context for an agent to use the tool safely and effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameters, but only `data` is mentioned as the body for create. All other parameters (id, ids, page, with, limit, order, query, filter, account) remain undefined. This does not compensate for the lack of schema documentation, leaving agents guessing about how to fill most fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description lists multiple actions (list, get, create, update) but then claims 'Flattened action: create', creating ambiguity about the tool's actual purpose. The title suggests create, but the description includes unrelated actions, making it vague and potentially misleading for an agent trying to select the correct tool among siblings like kommo_companies_get and kommo_companies_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is provided for when to use this tool versus alternatives. The description mentions multiple actions without clarifying that this tool is specifically for creating companies or when bulk mode should be used. There is no 'use this for X' or 'instead of Y' guidance, leaving the agent without clear decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include readOnlyHint: false, idempotentHint: false, and destructiveHint: false. The description does not contradict these but also doesn't add much beyond them. It clarifies that bulk execution is supported via ids, which is useful, but does not mention other behavioral aspects like whether the operation is destructive or has side effects. Since annotations already set the hints, the description adds minimal extra value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core action type, but it mixes Portuguese and English, which may cause confusion. It includes a redundant line '[Flattened action: get]' that duplicates what is already in the description. It is compact but could be clearer and better structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 10 parameters, no output schema, and no parameter descriptions in the schema, the description is incomplete. It fails to explain how to use parameters like 'filter', 'with', or 'order' for a get operation. The bulk support is mentioned, but details on how to structure batch requests are vague. This leaves significant gaps for the 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are 10 parameters with a schema description coverage of 0%. The description mentions 'id' for getting a single item, 'ids' for bulk, 'data' for create/update body, and generic 'filtros' for list, but does not explain individual parameters like 'page', 'limit', 'order', 'query', 'filter', 'account', or 'with'. This leaves the agent under-informed about how to use most parameters, especially since the schema provides no descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this tool handles kommo companies actions: list, get, create, update, and then highlights the flattened action 'get'. It specifies the resource (companies) and the operations supported, with a Portuguese note indicating pagination and filters for listing. However, it doesn't explicitly distinguish it from sibling tools like kommo_companies_list or kommo_companies_get, although the flattened action makes it clear this is the get operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the user that this tool can be used for get operations with bulk support via ids, and mentions other actions but does not provide when-to-use guidance or mention alternatives like kommo_companies_list for listing. It implies usage but doesn't explicitly state when to prefer this over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-readOnly, non-destructive, but description doesn't add meaningful behavioral context. It mentions 'paginada com filtros' but not what the response contains, or side effects. Since annotations are sparse, description should carry more weight but fails to.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is short but includes a lot of mixed information (multi-action overview and bulk support) that may be irrelevant to the list action. The 'Bulk support' line is generic and not specific to list. Front-loading is acceptable but could be more focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero schema coverage, no output schema, and 10 parameters, the description is incomplete. It doesn't explain what the list returns, how filters work, or how pagination is done. Sibling tools provide contrast, but description fails to position this tool adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and description provides no parameter details beyond 'list (busca paginada com filtros)'. Parameters like page, limit, filter, query are listed but their semantics are unexplained. Description should compensate for low schema coverage but doesn't.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states this is a 'list' action for companies with pagination and filters. It distinguishes from sibling tools like kommo_companies_get and kommo_companies_create by specifying the action and parameters. However, it's part of a flattened multi-action description, which slightly muddies the clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives beyond the action label. It mentions 'list' but doesn't explain what filters are available or when to use this over kommo_companies_get. Lacks context on prerequisites or typical scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral details beyond annotations: it discloses that update can be single or bulk, that `data` holds the body, and that bulk uses `ids`. This is useful context that annotations (readOnlyHint false, destructiveHint false) do not provide. However, it does not discuss side effects, required permissions, or field merge/replace behavior, so the transparency is partial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but poorly structured. It front-loads a generic list of actions and the cryptic 'Companies do Kommo.' before focusing on update. The 'Flattened action: update' meta-comment adds jargon, and the bulk support note appears at the end. The ordering does not clearly lead with the tool's update purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 10 parameters, no output schema, and annotations that don't detail behavior, the description only covers basic update modes (single/bulk) and the location of the body. It omits what fields can be updated, whether `id`/`ids` are required for update, what happens if neither is provided, and the response format. This is incomplete for a reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description must compensate. It explains the critical parameters `id` (single item), `data` (body), and `ids` (bulk), but the remaining 7 parameters (page, with, limit, order, query, filter, account) are left unexplained and appear to belong to other actions, causing confusion. This is insufficient for a 10-parameter schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description does mention 'update' as an action and explains single vs bulk semantics, but it is buried in a list of other actions ('list', 'get', 'create') with a vague opening 'Companies do Kommo.' The 'Flattened action: update' note clarifies the tool, but the purpose is not stated directly and unambiguously from the start.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides usage context by explaining the update behavior: 'com `id` = 1 item, sem `id` = bulk com array em `data`' and 'Bulk support: accepts ids for batched execution.' However, it does not explicitly differentiate from siblings like kommo_companies_create or when not to use this tool, leaving the guidance only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide no hints (all false), so the description must disclose behaviors. It reveals that 'create' posts body in `data` and that bulk support exists with ids, but it does not clarify side effects, whether the operation is idempotent, or what happens when `id` is present (potentially implying update behavior, which is confusing for a create tool). It also does not mention response format or error handling. The description is not contradictory, but it is insufficient 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief but poorly structured. It mixes informational content about all actions with the flattening note, and uses mixed language. It is not front-loaded with the create purpose. There is some wasted text about list/get/update that is irrelevant to the create tool, though it may be auto-generated from a template.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create operation with no output schema and low parameter clarity, the description is incomplete. It does not specify required fields (e.g., is `data` required?), the structure of `data`, or what the created contact looks like. It also misses guidance on bulk execution, despite mentioning it. Given 10 parameters and 0% schema coverage, the description must do more.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate but only vaguely mentions `data` and `ids`. It does not explain parameters like `page`, `with`, `limit`, `order`, `query`, `filter`, `account`, which are likely related to list actions but appear in a create tool schema. The description provides little meaning beyond the schema, leaving agents confused about which parameters are relevant for create.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a generic overview of Kommo contacts actions (list, get, create, update) but the flattened action is 'create'. It says 'create (cria, body em data)' which is vague and does not clearly specify what creating a contact entails or what the tool's primary purpose is. It does not distinguish from sibling tools like kommo_contacts_get or kommo_contacts_update beyond the action word, and the description is partially in Portuguese, which may reduce clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is minimal guidance on when to use this tool versus alternatives. The description mentions bulk support with ids but does not explain when one would choose create over update or other tools. It does not provide explicit context or exclusions. The flattened action suggests create is the focus, but there is no explanation of prerequisites or scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a read operation ('get'), but annotations state readOnlyHint=false, indicating it is not read-only. This is a direct contradiction. Additionally, the description does not disclose any side effects or safety details, and the bulk execution behavior is under-specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description wastes space listing actions for other tools (list, create, update) and then retracts to 'Flattened action: get'. It is not concise or front-loaded, and the structure is confusing due to mixed Portuguese and English.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, no output schema, and low schema coverage, the description is severely incomplete. It provides no information about return format, pagination behavior, filtering syntax, or error handling. The bulk support is mentioned but not elaborated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 10 parameters and 0% schema description coverage, the description must explain parameters. It only mentions 'id' for get and 'ids' for bulk, leaving page, limit, query, filter, with, order, account entirely unexplained. This does not 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description lists multiple actions (list, get, create, update) and then clarifies 'Flattened action: get', which is confusing. The tool name itself indicates 'get', but the description does not explicitly state what it does beyond 'Contacts do Kommo' and a convoluted action list. It fails to clearly specify that this tool retrieves a contact by ID or bulk via IDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It mentions that 'get' is by id and that bulk support accepts ids, but it does not explicitly say when to use this tool versus alternatives like kommo_contacts_list. There is no clear statement of use cases or exclusions, leaving the agent to infer the distinction from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, yet the description implies a list operation (typically read-only). This is a contradiction because the flattened action is 'list' but the tool is not marked as read-only. No additional behavioral details (e.g., pagination limits, filtering syntax, side effects) are disclosed beyond the conflicting annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but poorly structured. It mixes actions, uses mixed language (Portuguese/English), and includes a confusing note about flattened actions. The key purpose is buried, and there is no front-loading of the list-specific behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, no output schema, and no parameter descriptions, this description is grossly incomplete. It fails to explain what the list returns, pagination behavior, filter usage, or any response format. The tool is essentially unusable based on the provided description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It mentions 'data' and 'id' in context of create/update, but for the list action it only vaguely says 'busca paginada com filtros' without explaining parameters like page, limit, filter, query, with, order, or account. No parameter semantics are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description is ambiguous: it lists multiple actions (list, get, create, update) before noting '[Flattened action: list]', which muddles the tool's primary purpose. It doesn't clearly state that this tool is exclusively for listing contacts, and the inclusion of other actions confuses the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this list tool versus sibling tools like kommo_contacts_get, kommo_contacts_create, or kommo_contacts_update. The description only mentions bulk support and batched execution, but not selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotation contradicting description; readOnlyHint: false aligns with update being a write operation. The description adds context on bulk execution via ids but does not disclose potential impacts, permission requirements, or partial failure behavior. With no annotations beyond readOnly, the description carries some burden but only partially addresses it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact but poorly structured: the initial English fluff ('[Flattened action: update]' and 'Bulk support:') is metadata better placed elsewhere. The core information about single vs. bulk is buried in dense, mixed-language prose. A cleaner format could convey the same in fewer words with better readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and 10 params, the description is minimal. It gives the essential update logic but lacks parameter details, expected payload structure, and behavioral context (e.g., whether 'data' is a JSON string, how bulk handles failures). The lack of output schema means the description should clarify what the tool returns, which it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only mentions id, data, and ids, leaving seven other parameters undocumented. The description does not explain the format of the data parameter (e.g., JSON string) or the role of filter, query, page, etc. This is insufficient for a 10-parameter schema, though the single/bulk logic is a start.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool updates contacts, distinguishing between single (with id) and bulk (without id) operations, which differentiates it from sibling tools like kommo_contacts_create, kommo_contacts_get, and kommo_contacts_list. However, the opening sentence is confusingly phrased ('Contacts do Kommo. action: list...') and flips between Portuguese and English, undermining clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies that 'update' is the relevant action and distinguishes between single vs. bulk update based on presence of id, which is useful. It does not explicitly state when to prefer this tool over alternatives or any prerequisites, but the id/bulk distinction provides enough guidance for basic usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description does not add behavioral context beyond the annotations. It mentions 'Requires the customers module active' which is a prerequisite, and 'Bulk support' which is a behavior, but it does not explain what happens on creation (e.g., required fields, side effects, idempotency). The description is vague about the actual behavior of the create action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes extraneous information like listing all actions (list, get, create, update) when the tool is specifically for create. The 'Flattened action: create' is redundant and confusing. The bulk support note is useful but could be more concise. The description is not front-loaded with the most important information (that it creates a customer).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 10 parameters, no output schema, and no parameter descriptions, the description is severely incomplete. It does not explain what data is needed to create a customer, what the response looks like, or any constraints. The mention of module requirement and bulk support are helpful but insufficient for an agent to correctly invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. The description does not explain any of the 10 parameters. It mentions 'data' as a string but does not specify its structure or required fields for creation. The 'ids' parameter is mentioned for bulk support, but not explained. The description adds minimal value beyond the schema, which is empty of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool is for 'Clientes' (customers) in the Kommo recurring sales/RFM module and mentions the action 'create' in the flattened action. However, it does not clearly state that this tool creates a customer; it lists multiple actions (list, get, create, update) and then says 'Flattened action: create', which is confusing. It distinguishes from siblings by the resource name (customers) but not clearly by the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions that the customers module must be active in the account, which is a prerequisite. It also mentions bulk support for batched execution. However, it does not provide guidance on when to use this tool versus alternatives like kommo_customers_get or kommo_customers_update, nor does it explain the context for creating a customer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With all annotation hints false and no output schema, the description carries the burden of explaining behavior. It adds a prerequisite and bulk execution support, but does not disclose response format, error behavior, required permissions, or what happens with invalid IDs. This is helpful only at a very basic level.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and mostly scannable, and bulk support is clearly flagged. However, the 'action: list | get | create | update' line adds ambiguity and the '[Flattened action]' marker appears to be a generated note rather than a natural part of the description, making the structure feel a bit disjointed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, no output schema, no meaningful annotations, and several closely related siblings, this description is insufficient. It identifies the resource and batch behavior but does not tell the agent enough about how to form a correct get request or interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and there are 10 parameters. The description only clarifies that 'ids' can be used for batched execution; it does not explain 'id', 'page', 'limit', 'filter', 'order', 'with', 'query', or 'account'. Given the low coverage, the description only minimally compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource (Kommo customers in the recurring sales/RFM module) and includes '[Flattened action: get]', so an agent can infer this is the get variant. However, the first line says 'action: list | get | create | update', which muddies the specific operation and fails to clearly distinguish this tool from its list/create/update siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit 'use this when' or 'instead use X' guidance is present. The description only mentions a module prerequisite and bulk support, but does not say when to call kommo_customers_get versus kommo_customers_list or other customer tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are all false, so the description must convey behavioral traits. It states the module requirement and bulk support, but does not clarify read-only nature, side effects, or data output. The multi-action mention further obscures whether this is purely a read operation or also supports writes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but the structure is confusing: it starts with a generic module name, lists multiple actions, then clarifies 'Flattened action: list'. It could be more direct and front-loaded with the intended action. Not verbose, but lacks logical flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a list operation with many parameters and no output schema, yet the description is extremely sparse. It omits pagination, filtering, ordering, query syntax, response format, and any operational details beyond a vague bulk-support statement. Inadequate for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are 10 parameters and schema description coverage is 0%. The description does not explain any parameter except indirectly mentioning 'ids' for bulk support. It provides no meaning for 'data', 'page', 'with', 'limit', 'order', 'query', 'filter', or 'account', leaving agents completely unaided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The tool name 'kommo_customers_list' and the description's 'Clientes' and 'Flattened action: list' clearly indicate it is for listing customers. However, the mention of 'action: list | get | create | update' before the flattened action introduces ambiguity about which action is actually executed, reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus siblings like kommo_customers_get or kommo_customers_update. The only hint is the prerequisite of the customer module being active, but there is no when-to-use or when-not-to-use advice, nor any mention of alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not contradict the annotations, but annotations are sparse. It adds only that the customers module must be active and that batched ids are supported. It does not disclose update semantics such as partial vs. full replacement, permissions, side effects, or response behavior, which is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the resource name, but it wastes a line by listing all actions ('list | get | create | update') and then repeating the relevant one as '[Flattened action: update]'. It is readable but slightly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, no output schema, and minimal annotations, the description should cover the update workflow, parameter roles, and expected results. It only adds a module requirement and bulk ids note, leaving the tool under-specified for reliable selection and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and there are 10 parameters with no required fields. The description only adds meaning for 'ids' through the bulk-support note; the roles of 'data', 'query', 'filter', 'with', 'page', 'limit', 'order', and 'account' are left completely unexplained, making invocation risky.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource ('Clientes') and includes 'update' in the action list, with '[Flattened action: update]' clarifying the intended operation. However, it does not explicitly state what updating a customer does, and the generic 'action: list | get | create | update' line muddies the tool's specific purpose relative to sibling create/get/list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a prerequisite ('Requer o módulo de clientes ativo na conta') and notes bulk support via ids, but it gives no guidance on when to use update versus create/get/list, no exclusions, and no mention of required inputs for an update. The context is minimal and lacks actionable usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnly and idempotent behavior. The description does not contradict these and adds no additional behavioral information, which is acceptable given the low bar set by having annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. It is well-structured and immediately conveys the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides enough context for a simple list operation, including the entity types and a hint about the output (codes/ids). It does not elaborate on pagination or account handling, but these are optional and not critical for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description implicitly explains the 'entity_type' parameter by listing valid values. However, it does not clarify the purpose of 'page', 'limit', or 'account' parameters. Since these are optional but present, the description partially covers parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool deals with custom fields of an entity type (leads/contacts/companies/customers), and the name 'kommo_custom_fields' reinforces this purpose. It effectively distinguishes itself from other entity-specific tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage hint: 'Use the codes/ids retornados nos bodies de create/update.' This tells the user how to apply the returned data. However, it does not explicitly state when to use this tool versus alternatives, though the specific focus on custom fields 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds useful context by listing example event types and the filterable dimensions, but it does not disclose pagination behavior, ordering, or response details. This is sufficient but not rich behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two short sentences with front-loaded subject and examples, followed by the key filtering capability. Every phrase adds useful information, and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only event listing tool with no output schema, the description covers the basic purpose and main filter capability. However, it does not explain pagination parameters, the meaning of `with` or `order`, or the structure of `filter` JSON beyond general dimensions. It is adequate for initial selection but not fully complete for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 6 parameters. It only clarifies the `filter` parameter as a JSON value filtering by type, entity, and period. The remaining parameters (`page`, `with`, `limit`, `order`, `account`) are undocumented, leaving significant semantic gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as account events/activities and gives concrete examples (stage changes, creation). It indicates the filtering dimensions (type, entity, period), which helps distinguish it from other kommo_* entities. However, it lacks an explicit verb such as 'list' or 'retrieve', so the operation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to view account event history and filter it, but it does not explicitly state when to choose this tool over sibling list/get tools. No exclusions or named alternatives are provided, so the usage context is only implicitly conveyed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already signal that this is a mutating operation (readOnlyHint=false), and the description adds only that the body is in `data` and that ids are accepted for bulk execution. It does not disclose required authentication, return behavior, or what happens on partial bulk failure, so the behavioral context remains thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but cluttered with irrelevant action variants (list/get/update) that do not belong in a create-specific tool. It mixes Portuguese and English and uses an odd '[Flattened action: create]' marker, making the structure more confusing than helpful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create operation with no output schema, no required parameters, and no parameter descriptions, the description should explain required payload structure, response behavior, and bulk semantics. It provides only a minimal 'body em data' note and an unexplained bulk-support sentence, leaving significant gaps for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 10 parameters and 0% schema coverage, the description carries the full burden, but it only explains `data` (body) and vaguely mentions `ids` for bulk execution. The remaining parameters like `query`, `filter`, `page`, `with`, `limit`, `order`, and `account` are left completely unexplained, and it is unclear which ones even apply to the flattened create action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description does state 'create (cria, body em `data`)' and the tool name is kommo_leads_create, so the core purpose is identifiable. However, it also lists list/get/update actions, creating ambiguity about what this specific tool actually does versus its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No clear guidance is provided about when to use this tool instead of kommo_leads_get, kommo_leads_list, or kommo_leads_update. The mention of bulk support is the only contextual hint, but it does not explain when bulk execution is appropriate or how it differs from single-create.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=false, so the description isn't required to repeat safety information. It adds useful behavioral details like bulk execution via ids, and the update-without-id semantics, but it leaves 'Flattened action: get' unexplained and doesn't mention side effects or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but cluttered with inline Portuguese and a cryptic '[Flattened action: get]' note. The action list is packed into one run-on sentence, making it harder to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, multiple actions, and no output schema, the description is incomplete. It doesn't explain return values, action-selection mechanism (how the agent decides between actions from the parameters), or what '[Flattened action: get]' means.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must clarify parameters. It explains that 'id' selects a single item, 'data' holds the body for create/update, and 'ids' enables bulk. However, page, limit, order, with, filter, account, and query are only vaguely implied (filters) or not explained at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly enumerates the actions (list, get, create, update) and the resource (Kommo leads), so it states what the tool does. However, it does not differentiate from sibling tools like kommo_leads_create, kommo_leads_list, or kommo_leads_update, and the tool name 'get' conflicts with the multiple actions described.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus the dedicated sibling tools (create/get/list/update). It does not mention any exclusions, prerequisites, or contexts where one action should be preferred over another.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds useful behavior beyond the annotations: pagination/filtering is mentioned, `data`/`id`/`ids` semantics are partially described, and bulk support is disclosed. However, it does not specify return format, auth needs, or side-effect behavior for the list action itself, leaving the behavioral picture incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is short and begins with the resource and action, but it devotes space to get/create/update details that are irrelevant to a flattened list tool. The '[Flattened action: list]' line adds internal context rather than sharp user-facing guidance, so the structure is acceptable but not tightly focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, no output schema, and sparse annotations, a list tool needs fuller details on list semantics, parameter syntax, return shape, and account scoping. The description covers only a small fraction of the required context and spends much of its length on non-list actions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 10 parameters with 0% description coverage, so the description must compensate. It explains `data` (body), `id`/`ids` (single vs bulk) to some degree, and hints at page/filter via 'busca paginada com filtros', but it does not define `with`, `limit`, `order`, `query`, `account`, or the expected formats for `filter` and `data`.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource (Kommo leads) and the operation ('action: list ... busca paginada com filtros') and adds '[Flattened action: list]', so the core purpose is clear and distinguishable from the get/create/update siblings. However, it also enumerates get/create/update behaviors, blurring the focus and making the agent uncertain whether those actions are actually available in this flattened tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives some usage context: list is paginated and supports filters, and bulk execution accepts ids. But it never explicitly says when to choose this list tool over kommo_leads_get or when not to use it, and no alternatives or exclusions are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds some behavioral details beyond annotations, such as 'Bulk support: accepts ids for batched execution' and the distinction between single (with id) and bulk (without id, array in data). However, it does not mention that updates are mutations, potential side effects, or permission requirements. Given minimal annotations (all false), the description partially compensates but is incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single run-on sentence mixing multiple actions, languages (Portuguese and English), and includes an odd '[Flattened action: update]' tag. It is poorly structured, difficult to parse, and contains irrelevant information about list/get/create that does not belong in this tool's description. It is not concise or well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, no output schema, and no annotations providing guidance, the description is severely incomplete. It omits the expected data format for 'data', what fields can be updated, return values, error behavior, and any examples. The inclusion of unrelated list/get/create details wastes space and contributes to the incompleteness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must heavily explain parameter semantics. It only mentions that 'id' is for single updates and bulk uses an array in 'data', but it fails to describe the structure of 'data', the purpose of 'ids', or any of the other parameters (page, limit, query, etc.). This leaves most parameters unexplained and the agent guessing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'update' and explains single vs bulk behavior, which indicates this tool is for updating leads. However, it also lists list/get/create actions, making the purpose less focused and potentially confusing an agent about whether this tool handles multiple actions or just update. The presence of unrelated actions dilutes the clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool over alternatives like kommo_leads_create or kommo_leads_get. It mentions 'update' but lacks guidance on using the correct sibling based on the desired action. No exclusions or alternative suggestions are provided, leaving the agent without clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds useful practical details like bulk execution via `entity_ids`, which is not present in annotations. However, it does not disclose behavior such as duplicate handling, whether existing links are replaced, or what happens when the target 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and starts with the core resource, but the combined action list plus '[Flattened action: link]' creates a structurally muddled message. It could be tightened to state clearly that this tool creates links and then explain each relevant parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and virtually no parameter coverage in the schema, the description is not complete enough for reliable invocation. It fails to specify how `entity_id` and `entity_type` interact with `data`, whether `data` is required, or what a successful link call returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description does important work by explaining that `data` is a JSON object with `to_entity_id/to_entity_type` and that batch execution uses `entity_ids`. Still, it leaves `page`, `limit`, `filter`, and `account` unexplained, and it is unclear whether all listed fields are relevant to the link action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the tool as handling 'vínculos entre entidades' and gives a clear example of linking a contact to a lead. The '[Flattened action: link]' marker and tool name confirm this is the link operation, though the description also lists list/unlink actions, which causes some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied through the example and the action field, but there is no explicit guidance on when to use this tool versus kommo_links_list or kommo_links_unlink. It also does not mention prerequisites such as whether `data` is required when creating a link.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description does not clearly disclose what the tool actually does or its side effects. It mentions 'action: list' but also includes link/unlink actions, which are mutations. The annotations indicate readOnlyHint=false and destructiveHint=false, but the description does not clarify whether calling this tool modifies data. The mention of 'data' for link/unlink is irrelevant for listing and adds confusion. There is no statement about read-only behavior or lack of side effects. Given the low annotation coverage, the description fails to provide necessary transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes extraneous information about link/unlink actions that are not relevant to a listing tool. The structure is confusing: it starts with a general statement, lists all actions, then says '[Flattened action: list]' which is redundant and unclear. It could be much more concise by focusing solely on the listing behavior and omitting the unrelated actions. The message is not front-loaded and requires unnecessary parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is inadequate given the tool's complexity. It lacks information about the return format (no output schema), pagination semantics, filter usage, and how bulk execution affects results. It mentions bulk support via entity_ids but does not explain how that influences output. Given that there is no output schema and the description is sparse, agents are left without essential details 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 8 parameters with 0% description coverage, so the description should compensate. It only mentions 'entity_ids' for bulk support and 'data' for link/unlink, but does not explain the core parameters (entity_type, entity_id, page, limit, filter, account). The description does not clarify how these parameters are used for listing or what formats they expect. This is a significant gap, as agents cannot infer parameter semantics from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deals with links between entities (vínculos entre entidades) and specifically mentions 'action: list' for listing links of a record. The name kommo_links_list and sibling tools (kommo_links_link, kommo_links_unlink) reinforce that this is the listing variant. However, including link/unlink actions in the description introduces ambiguity and could confuse an agent about the tool's actual scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions three actions (list, link, unlink) but does not explicitly state when to use this tool versus the sibling link/unlink tools. It implies that this tool is for listing ('action: list') and mentions bulk support, but there is no clear guidance on when not to use it or which alternative to choose. The guidance is minimal and relies on the agent inferring from the name and sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide no hints (all false), so the description carries the burden. It discloses that `data` must be JSON with to_entity_id/to_entity_type and that bulk execution via entity_ids is supported. However, it does not describe side effects, what happens if a link doesn't exist, or any error behavior. It adds some value beyond the schema but remains sparse for a mutation-like tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately concise but somewhat tangled. It mixes multiple actions in one sentence, then clarifies with 'Flattened action: unlink'. The bulk support note is useful. It is not overly long, but could be structured better to focus on the unlink behavior. Overall, it is acceptable but not a model of clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 8 parameters, no output schema, and zero annotation support, the description is largely incomplete. It fails to clarify the meaning of core parameters like entity_id and entity_type, does not explain the return value or error cases, and only vaguely defines behavior. For a tool with this complexity, the description is inadequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate for parameter explanations. It only explains `data` (JSON with target entity info) and `entity_ids` (for bulk), but leaves other parameters (entity_id, entity_type, page, limit, filter, account) unexplained. The required `entity_type` gets no semantic clarification beyond the enum. This is insufficient for an 8-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly indicates the tool is about entity links and specifically for 'unlink' via the 'Flattened action: unlink' note. It uses a specific verb (unlink) and resource (entities), distinguishing it from sibling tools kommo_links_link and kommo_links_list. However, the inclusion of 'action: list | link | unlink' could be confusing, slightly reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for unlinking entities by mentioning 'Flattened action: unlink', but it does not explicitly state when to use it vs. the link or list tools. No alternative tools are named, only the general action list. The guidance is implied rather than explicit, and 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds output field context but does not disclose what the optional `account` parameter does or any pagination/limitation behavior, leaving some behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the main action, and every phrase adds value. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one optional parameter and no output schema, but the description leaves the parameter's role unexplained, which is a necessary detail for correct invocation. It provides the core purpose and output fields but lacks sufficient guidance for full self-contained understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no description for the `account` parameter (0% coverage), and the description only mentions using `account` in 'other tools', not in this tool. It fails to explain whether the parameter filters, selects, or does something else, so the agent cannot reliably decide how to set it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Lists the Kommo accounts connected to this install' with a specific verb, resource, and scope, and it reveals the output fields (id/subdomain, label). It also distinguishes its purpose from sibling tools by focusing specifically on account discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by explaining that the returned id/subdomain should be used in the `account` parameter of other tools, which implicitly tells when this tool is useful (before using other Kommo tools). However, it does not explicitly mention when NOT to use it or name alternative tools, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, so the creation nature is implied, but the description does not disclose any additional behavioral context beyond a brief mention of 'create' and 'data = JSON'. It does not state what happens on success (e.g., returns created note ID), side effects, or any prerequisites. Given annotations exist, the bar is lower, but the description adds minimal extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single overloaded sentence that mixes multiple actions and a flattened action note. It is not focused on the create-only operation and includes extraneous details about other actions, making it wordy and unfocused. A clearer structure would separate the specific create semantics from general entity notes information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters, no output schema, and no annotations on behavior, the description leaves many gaps. It does not mention return values, required authentication, or explain the data structure for creation. The inclusion of list-related parameters and actions adds confusion rather than completeness for a create tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only explains `data` as 'JSON' and mentions `entity_ids` for bulk. The required `entity_type` is not explained, and other parameters like `page`, `limit`, `order`, `filter`, `account`, and `entity_id` are left undefined. This is insufficient for an agent to correctly construct a valid request.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins by stating 'Notas de uma entidade' (Notes of an entity), then lists multiple actions (list, list_by_entity, create). Although it later says 'Flattened action: create', it does not explicitly state that THIS tool is solely for creating notes. The conflation of list and create actions makes it ambiguous whether the tool performs all actions or only the create one. The tool name provides some clarity, but the description fails to clearly articulate the specific purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool compared to sibling tools like kommo_notes_list or kommo_notes_list_by_entity. It mentions 'action: create' but does not explicitly say 'use this tool to create notes; for listing use the list tools.' The bulk support note is helpful but not enough to guide correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide no hints (all false), so the description must disclose behavior. It mentions bulk support ('Bulk support: accepts entity_ids for batched execution') but does not state that the tool is read-only or that it modifies data. Including 'create' in the description muddies whether this is a mutation operation, and the 'Flattened action: list' note is ambiguous. No side effects, return format, or authentication needs are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the tool's purpose, but the inclusion of multiple actions and the '[Flattened action: list]' note create a disjointed structure. The information is not presented in a logical flow, making it harder to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters, no output schema, and no helpful annotations, the description is severely incomplete. It does not explain how to perform a basic list call, what required parameters mean, how filtering works, or what the response looks like. The tool's complexity demands far more detail than provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions `data` (for create) and `entity_ids` (for bulk), neither of which is central to the list action. Parameters like page, limit, order, filter, account, entity_type are not explained at all. The description adds almost no value for understanding the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool lists notes for an entity type ('Notas de uma entidade... list (todas as notas do tipo de entidade)') and distinguishes this from listing by a single entity ('list_by_entity (notas de 1 registro)'). However, it also mentions 'create' as an action, which is redundant since separate tools exist and could confuse the agent about the tool's actual scope. The note '[Flattened action: list]' partially clarifies, but the presence of other actions weakens purpose clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given on when to use this tool versus alternatives. The description lists actions (list, list_by_entity, create) but does not clearly instruct that this tool is specifically for listing all notes of an entity type, or when to choose kommo_notes_list_by_entity instead. Since sibling tools exist, the lack of any 'use when' statement is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=false, destructiveHint=false, but no idempotentHint. The description doesn't disclose behavioral traits like whether listing is read-only, pagination behavior, or side effects. It mentions bulk support but not details like rate limits or data format. With annotations present, the bar is lower, but the description adds minimal behavioral context beyond the action list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively concise but includes a mix of actions (list, list_by_entity, create) that are not all relevant to the flattened action list_by_entity. The bulk support note is useful, but the structure could be clearer by focusing on the current action. It's not overly verbose, but the extraneous action list adds noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters, no output schema, and low schema coverage, the description is incomplete. It doesn't explain return values, pagination, filtering, or ordering. The bulk support is mentioned but not detailed. For a complex tool with many parameters, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions `data` = JSON for create action, but for list_by_entity it doesn't explain parameters like entity_id, page, limit, order, filter, account. The description only clarifies entity_type and entity_ids, leaving most of the 9 parameters undocumented. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists notes for an entity, with action list_by_entity for notes of one record. It distinguishes from sibling kommo_notes_list by specifying entity-scoped listing, though it doesn't explicitly name the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing notes by entity and mentions bulk support via entity_ids, but it doesn't explicitly state when to use this vs kommo_notes_list or other note tools. It provides some context but lacks clear exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

As anotações já informam readOnlyHint=true, idempotentHint=true e destructiveHint=false, então o comportamento de segurança está coberto. A descrição adiciona valor ao revelar o 'bulk support' para pipeline_ids e o flattening da ação get, que não são deduzidos apenas pelo schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

O texto é curto, direto e sem espaço desperdiçado. O formato em linhas com a ação, o flattened action e o suporte de lote permite rápida leitura e compreensão.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A descrição cobre o escopo, a ação e o modo batch, e conta com boas anotações de segurança. Ainda assim, sem schema de saída e sem descrição de estrutura de retorno ou tratamento das opções paginadas, há gaps relevantes para o agente saber o que esperar da resposta.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

A descrição cobre os parâmetros centrais: pipeline_id pelo contexto de 'get (funil por id)' e pipeline_ids pelo suporte a lote. Porém, o schema tem 0% de cobertura descritiva e a descrição não explica page, limit ou account, que podem ser confusos para um agente.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

A descrição identifica o recurso ('Funis/pipelines e seus estágios') e define a ação concreta ('get (funil por id)'), reforçada por '[Flattened action: get]'. Isso diferencia o tool dos irmãos kommo_pipelines_list e kommo_pipelines_statuses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

A descrição dá contexto de uso ao listar as ações possíveis ('list | get | statuses') e declarar que a ferramenta atual é a versão 'flattened' de get. Embora não diga explicitamente 'use list para listar e statuses para estágios', é possível distinguir pela própria descrição e pelos nomes dos irmãos.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds that it can return pipelines and stages, and mentions batch execution. However, it does not clarify that only the list action is available here, or disclose response format or pagination behavior, so the added transparency is limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes redundant action enumerations and a vague opening line. It is not poorly sized, but the structure is a bit disjointed—starting with a generic statement, then a list of actions, a flattened-action note, and a bulk note. Could be more streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should clarify the return structure. It only says 'Funis (pipelines) e seus estágios', implying pipelines and stages, but not how they are formatted, how pagination works (given page/limit params), or what account does. The description is incomplete for a tool with 5 parameters and unexplained output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain parameters. It only explains pipeline_ids for batch support. Parameters like page, limit, account, and pipeline_id are not described at all, leaving the agent without guidance on how to use them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it lists funis (pipelines) and their stages, with 'action: list' clearly identifying the primary behavior. However, it also mentions get and statuses actions, which could confuse, but the flattened action note clarifies that this tool is the list variant. It distinguishes from siblings like kommo_pipelines_get and kommo_pipelines_statuses, though not explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions bulk support via pipeline_ids, which is a usage hint, but it does not explicitly tell the agent when to use this tool versus the get or statuses siblings. It lists actions but does not state 'use this for list, use other tools for get/statuses', leaving guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat those. It adds a note about bulk support via pipeline_ids, which is useful; 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fragmented and includes an 'action' parameter that does not exist in the schema, causing confusion. It is not well-structured and contains redundant or misleading parts, though it is short.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the availability of sibling tools and annotations, the description still lacks essential context such as what the statuses represent, how to specify pipeline_id, and what the output format is. It does not fully cover the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema includes five parameters (page, limit, account, pipeline_id, pipeline_ids) but the description only hints at pipeline_ids for bulk execution. The other parameters are not explained, leaving most of the input semantics unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description mentions pipelines and their stages, but it ambiguously lists multiple actions (list, get, statuses) without indicating that this tool is specifically for statuses. It does not clearly state that this is for retrieving stage information, though the name suggests it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly say when to use this tool over the sibling tools kommo_pipelines_list or kommo_pipelines_get. It mentions bulk support, but lacks clear guidance on when this tool should be chosen.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the burden. It notes that the request uses the user's token, implying authentication context, but does not mention potential side effects, rate limits, or error handling. Since it can perform any HTTP method including DELETE, more transparency about destructive operations would be beneficial, but it is not contradictory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose and usage context. It includes useful examples and a documentation link, making it effective. It is slightly dense but every sentence serves a purpose, earning a high score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a raw request tool with 5 parametersable, no output schema, and minimal annotations, the description provides solid guidance on when to use it and how to structure the path, but lacks details on other parameters and potential error handling. It is reasonably complete for a flexible utility, but could be enhanced with examples of body or query_params.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (none of the parameters are documented in the schema), so the description must compensate. The description explains 'path' as relative (e.g., '/leads/unsorted'), and mentions method implicitly, but does not explain 'body', 'query_params', or 'account'. However, the general-purpose nature and examples help, yet it does not fully compensate for all undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a raw call to the Kommo v4 API for any endpoint, using the user's token. It explicitly names the tool as a fallback for endpoints without a dedicated tool, distinguishing it from the many sibling tools that cover specific resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Use when there is no dedicated tool' and lists the domains (chats/Salesbot/arquivos/Kommo IA/webhooks/fontes/widgets/templates) that are not covered, providing clear when-to-use guidance. It also gives examples of paths and a link to documentation, which is excellent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description says 'cria tags' (creates tags) and provides a simple JSON example for data, giving some insight into the action's behavior. However, it also mentions 'list' as an option, which contradicts the tool's actual create-only behavior. It does not disclose side effects, required permissions, or what happens after creation. The annotations only indicate readOnlyHint=false, so the description carries the burden but is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but not effective. It packs two unrelated actions into a single line, creating confusion. While brevity is appreciated, the lack of clarity outweighs the conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters, no output schema, and minimal annotations. The description provides almost no guidance on how to invoke the tool correctly, what the response looks like, or what the 'data' field should contain beyond a simplistic example. It fails to compensate for the sparse structured information, making the tool nearly unusable for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain all parameters. It only describes 'data' with an example, and does not explain 'page', 'limit', 'query', 'filter', 'account', or even the required 'entity_type'. The example for data is a minimal JSON array but does not clarify whether it is the only required parameter or how other parameters interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Tags de um tipo de entidade' (tags of an entity type) but then lists both 'list' and 'create' actions despite the tool name being 'kommo_tags_create'. It fails to clearly state that this tool is specifically for creating tags, and its mention of both actions confuses its purpose. It does not distinguish from the sibling 'kommo_tags_list' tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions both 'list' and 'create' actions, implying the tool can be used for listing, but the tool name and flattened action indicate it is only for creation. This is misleading and provides no guidance on when to use this tool versus the sibling 'kommo_tags_list'. There is no mention of prerequisites or selection criteria for using create over list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are sparse and readOnlyHint=false, which aligns with the description mentioning create. However, the description does not disclose behavior for the list action such as pagination, output shape, filtering semantics, or side effects; it mostly lists actions without explaining what happens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the entity type, but the create section is unnecessary for a list tool and conflicts with the tool name. The '[Flattened action: list]' line adds structural confusion rather than clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, no output schema, and weak annotations, the description is far from complete. It does not explain required entity_type usage, list search behavior, supported filters, pagination, or return values, making it insufficient for reliable agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for 7 parameters. It only adds meaning for `data` via a JSON example and vaguely alludes to search, but page, limit, query, filter, account, and entity_type are left unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource (tags of an entity type) and mentions a list action with search, but also includes a create action that belongs to the sibling tool kommo_tags_create. The '[Flattened action: list]' note and the tool name suggest create should not be here, making the purpose muddled.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus kommo_tags_create or other sibling tools. Instead, the description explicitly advertises a create action inside a list tool, which could mislead an agent into using this tool for tag creation instead of the dedicated create sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already define the tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat this. It adds value by explicitly stating the 'get' action and bulk support, which are behavioral traits beyond the annotations. It also notes that it's a 'diferencial' of Kommo, but this is marketing. The description does not mention any side effects, but they are consistent with a read-only get operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively concise, but it includes a note about the 'list' action and a bullet point for bulk support that is somewhat redundant with the mention of ids. The structure is a bit ad hoc: it mixes description, a bracketed note about the flattened action, and then bulk support. It could be tighter, though it is not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema, and 0% schema description coverage, the description should do more to explain the parameters and return behavior. It explains the purpose and gives a hint of filters, but it doesn't describe the expected response or how to use 'id' vs 'ids' effectively. For a get operation, it might be sufficient, but the bulk support and filter parameter are left undefined, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate for the parameters. It mentions 'filter' only for the list action, but since this is flattened to 'get', it doesn't explain 'id' or 'ids' explicitly, though those are obvious from the action. The description doesn't describe what 'account' does or how 'page' and 'limit' relate to get operations. It adds minimal meaning beyond what the schema provides; the context of 'get' implies id usage but lacks detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states this tool handles 'Conversas (talks) do inbox unificado' and specifies the 'get' action for retrieving a talk by id, which is distinct from listing. It also differentiates it by highlighting it as 'o diferencial do Kommo' for WhatsApp/Instagram/Telegram history, distinguishing it from sibling list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool supports 'get' for a single record by id and also mentions 'Bulk support: accepts ids for batched execution', which indicates usage for single or batch retrieval. It doesn't explicitly state when not to use it, but the context of 'inbox unificado' and the presence of sibling tools like kommo_talks_list implies when to use this get variant. No explicit alternative is named, but the action selection is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond annotations: bulk support via ids, filterable by contact_id/entity_id/only_in_work, and the cross-channel conversation history scope. It does not contradict annotations and no annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loads the core purpose. The '[Flattened action: list]' line is helpful but the 'get (por id)' mention is unnecessary and slightly confusing given the sibling tool. The phrase 'É o diferencial do Kommo' adds some context but is somewhat promotional filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters and no output schema, the description should provide more operational detail. It covers the main behavior, filtering, and bulk support, but omits pagination semantics, the meaning of `page`/`limit`/`account`, and what the returned list contains structurally. It is adequate for basic selection but not fully complete for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no descriptions and 0% schema description coverage, so the description must compensate. It does partially: it explains the `filter` JSON keys (contact_id/entity_id/only_in_work) and that `ids` enables bulk execution. However, `page`, `limit`, and `account` receive no semantic explanation, leaving significant gaps for a 6-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource ('Conversas (talks) do inbox unificado') and the main verb ('list'), further reinforced by '[Flattened action: list]'. However, it muddies the purpose by mentioning 'get (por id)' when a separate sibling tool kommo_talks_get exists, so it does not fully distinguish itself from that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful context: this lists unified inbox conversations from WhatsApp/Instagram/Telegram and can be filtered. But it gives no explicit when-to-use vs alternatives, such as 'use kommo_talks_get for a single conversation' or 'use kommo_events for event history'. Usage 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are weak (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden. It adds only 'body em data' and 'Bulk support: accepts ids for batched execution'; it does not disclose return behavior, required input format, side effects, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is short but structurally confusing: it front-loads an action list that is mostly irrelevant to a create-flattened tool and mixes Portuguese and English. '[Flattened action: create]' is buried after the multi-action description rather than serving as the clear lead.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, no parameter descriptions, no output schema, and no rich annotations, the description should specify how to construct a valid create request. It does not explain the data payload format, which fields are required, or what a successful create returns, so it is incomplete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and there are 10 parameters. The description adds partial meaning for 'data' (body), 'ids' (batch execution), and list filters, but leaves most parameters (account, with, query, page, limit, order, filter) unexplained and does not clarify the expected JSON structure for 'data'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource ('Tasks do Kommo') and the intended action ('create (cria, body em data)' plus 'Flattened action: create'), so an agent can infer it creates tasks. However, it opens by enumerating list/get/update actions that belong to sibling tools, so the create-specific purpose is muddled rather than crisply stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement about when to use this tool versus kommo_tasks_list/get/update. The 'Flattened action: create' hint suggests the action is fixed, but no when-to-use or exclusion guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only generic false flags, so the description carries the burden of behavioral disclosure. It adds one useful trait—'Bulk support: accepts ids for batched execution'—but does not explain side effects, auth requirements, return shape, or why readOnlyHint=false despite the 'get' name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is not concise because it spends most of its text on list, create, and update actions that do not belong in a get-focused tool. Bulk support is mentioned twice in different forms, and the '[Flattened action: get]' note adds confusion rather than clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 parameters, no output schema, and weak annotations, the description is far from complete. It fails to describe response format, paging/filtering behavior for the get action, error cases, or how the batch ids parameter interacts with other fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description explains almost none of the 10 parameters. It gives minimal clues for id ('get por id') and ids ('bulk support'), but page, with, limit, order, query, filter, and account are left entirely unexplained for this tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Tasks do Kommo' and lists list/get/create/update actions rather than stating that this specific tool retrieves tasks by ID. The 'get (por id)' phrase and '[Flattened action: get]' hint at the purpose, but the inclusion of unrelated create/update semantics makes the tool's actual behavior unclear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use kommo_tasks_get versus kommo_tasks_list, kommo_tasks_create, or kommo_tasks_update. The description mentions 'get (por id)' and bulk ids, but the mixed action list actively obscures the intended use case instead of clarifying it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false, which is somewhat contradicted by the description mentioning create/update actions, but the tool name is 'list' suggesting read-only. The description mentions 'paginada com filtros' (paginated with filters) and bulk support, which gives some insight, but it doesn't disclose rate limits, authentication needs, or what is destroyed/changed. The multi-action nature creates uncertainty about the default behavior when no action is specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but includes extraneous text like 'Tasks do Kommo' and a redundant mention of actions that are not the main focus. The structure is somewhat disorganized with a note about flattened action and bulk support. However, it is not overly verbose; it just lacks precision. Some sentences are useful, but the mix of languages and unrelated actions detract from clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool having 10 parameters and no output schema, the description does not explain how to use the list action, what filters are available, how pagination works, or what the response contains. The mention of bulk support is helpful but incomplete. Given the complexity, the description is severely inadequate for an agent to select and invoke this tool reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 10 parameters with 0% description coverage, and the description provides almost no parameter documentation. It mentions 'data' is body for create/update, and 'id' and 'ids' for bulk, but the key parameters for list (page, limit, filter, query, order, with, account) are left entirely unexplained. There is no added meaning for these parameters beyond their names, which is insufficient for correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Tasks do Kommo. action: list' which is unclear language mixing Portuguese and English, and the main action 'list' is not clearly defined as 'lists tasks' — it just says the action is 'list'. The description does not explicitly state that this tool lists tasks, and the verb is implicit. It lists multiple actions (list/get/create/update) even though the tool is named 'kommo_tasks_list', causing confusion about its primary purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this specific tool vs. sibling tools like kommo_tasks_get or kommo_tasks_create. The description mentions 'Flattened action: list' and 'Bulk support' but does not explain scenarios where this tool is preferred. It lacks exclusions or alternative suggestions, leaving usage decisions ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that it can perform bulk updates and explains the use of `id` vs bulk mode. It does not contradict the annotations (no read-only or destructive hints are set). However, it lacks details on side effects, error conditions, or required permissions, which would be useful given the minimal annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the action. However, it includes a redundant list of all actions (list, get, create, update) before the 'Flattened action: update' clarification, which adds minor noise. It is still efficient but could be more focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 10 parameters, no output schema, and minimal annotations. The description does not explain the purpose of most parameters, what the `data` body should contain, the expected response, or any prerequisites. It is insufficient for an agent to correctly invoke the tool beyond the simplest single-update case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 10 parameters with 0% coverage from the description. The description explains the role of `id`, `ids`, and `data` (e.g., 'com `id` = 1 item, sem `id` = bulk com array em `data`'), but the other parameters (page, with, limit, order, query, filter, account) are not explained at all. Since schema coverage is zero, the description only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states this tool updates tasks ('update (atualiza...') and distinguishes it from sibling tools like create, get, and list. It also clarifies bulk vs single-item update, which 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on when to use `id` for a single update and when to omit `id` for bulk updates using an array in `data`. However, it does not explicitly state when not to use this tool (e.g., for creating tasks) or mention alternatives, though the action name and context make this implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read nature is covered. The description adds useful details about the 'with' parameter and bulk ids support, but does not disclose more significant behavioral aspects such as output shape or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and mostly to the point, but the phrase 'action: list | get' combined with '[Flattened action: get]' creates redundancy and some noise. It is terse but not optimally structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are 6 parameters and no output schema, the description provides only enough context for a basic understanding: users, get by id, with expansion, and bulk support. Missing details about page/limit, id vs ids usage, and return semantics keep it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is zero schema description coverage, yet only the 'with' parameter is explained as accepting role/group, and 'ids' is only generally mentioned for bulk support. Core parameters such as id, page, limit, and account are not described or distinguished in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies that the tool deals with users of the account and that it fetches users by id ('get (por id)') with optional bulk support. The mention of 'action: list | get' creates some ambiguity, especially given that a sibling tool kommo_users_list exists, but the core resource and verb are present.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is mostly implied: the description signals that 'with=role,group' includes permissions/groups and that bulk execution is supported via ids. However, it does not explicitly explain when to prefer this tool over kommo_users_list or state exclusions/alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare it as read-only and idempotent, so the safety profile is covered. The description adds useful context about bulk support (accepts ids) and the 'with' parameter for enriching results. However, it does not describe return format, pagination behavior, or any side effects beyond what annotations imply. It 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief but somewhat cluttered with cryptic phrases like 'Flattened action: list' and 'action: list | get (por id)'. The structure is not ideal—multiple lines and a bracket notation that adds noise. It is concise but could be clearer and more organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema, and zero schema documentation, the description is insufficiently complete. It lacks explanations for pagination, filtering, the 'account' parameter, and expected return data. For a simple listing tool, a brief mention of output structure would be expected; this is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameters. It only elaborates on 'with' (role/group) and hints at 'ids' for bulk. Parameters like 'id', 'ids', 'page', 'limit', and 'account' are left unexplained, leaving significant ambiguity for an agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it deals with account users and supports list and get by id actions. The primary purpose is listing, as indicated by 'Flattened action: list'. However, it doesn't clearly differentiate from the sibling tool kommo_users_get, which exists specifically for getting a single user, causing slight ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives. It mentions the 'with' parameter for including permissions/groups and bulk support, but does not explain when to prefer this over kommo_users_get or other list tools. No exclusions or alternative recommendations are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given the annotations (readOnlyHint=false, openWorldHint=true) the description adds crucial behavioral context: invoke can run MCPs without installing, returns connect/checkout links for auth/payment, writes require owner/admin, and notes installed_in_toolkit vs workspace flags. It explains side effects of one-off installs and subscription handling, going well beyond the sparse annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but logically structured: overall purpose, core flow, special invoke behaviors, permissions, and then the prompt library. Every sentence carries information, and key points are front-loaded. A bit dense and could benefit from bullet lists, but it avoids redundancy and earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and 23 parameters, the description covers the primary workflows (search/describe/invoke/install), auth and billing edge cases, permission requirements, and the prompt sub-library. However, it leaves several parameters unexplained (e.g., immediate, tier_slug, conversation) and could clarify return formats, leaving room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description bears the burden. It explains the central 'action' enum and maps key parameters like mcp_id, tool_id, arguments, and prompt_slug to the flow. However, many parameters (limit, immediate, tier_slug, conversation, report_context, etc.) are not explicitly explained, leaving ambiguity for a 23-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence clearly identifies the tool as the official mcp.ai marketplace — a catalog and execution platform. It explicitly covers capability requests and outlines the core search→describe→invoke flow, distinguishing it from sibling CRM tools like kommo_* and general utilities like show_version.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', and explains the full core flow with action values. It also differentiates between search/describe, lists when to use list_tools, subscribe/cancel, report_bug, and request_mcp, and covers the prompt library separately. This is textbook-level guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds value by stating what the tool does (reporting) and the expectation to include a conversation array for reproduction. It doesn't contradict annotations; it expands on the purpose, though it doesn't detail side effects beyond reporting. Since annotations already convey safety, the description's additional context earns a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences and front-loaded with the core purpose. Every sentence earns its place: the first defines the tool's scope, the second provides critical usage detail (conversation array). No wasted words; ideal length for a reporting tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a simple purpose (report/feedback) with 3 parameters, no output schema, and no annotations beyond safety hints. The description covers the main use case and mentions the key reproduction data (conversation). It doesn't explain the 'context' parameter or how results are returned, but for a reporting tool with no output schema, it is sufficiently complete. A 4 is appropriate, given minor gaps in parameter explanation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 3 parameters but only 'message' is required IAW schema; 'context' and 'conversation' have defaults. Schema coverage is 0% (no descriptions in schema), so the description must compensate. The description mentions the 'conversation' array for reproduction but does not explain the 'context' parameter or the format for 'conversation'. It adds some meaning but not enough to fully cover all parameters. With 3 parameters at 0% coverage, a 4 is warranted because it explains one critical parameter but leaves others vague.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb ('report') and a resource ('bug') and covers multiple use cases. It distinguishes itself from siblings by its focus on reporting issues rather than performing standard Kommo operations, and it even instructs to include a conversation array for reproduction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some guidance on what to include (conversation array for reproduction), but it does not explicitly state when to use this tool versus alternatives. It is clear that this is for feedback/bug reporting, but it lacks exclusions or mention of alternative tools for other types of support. The guidance is adequate but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description repeats 'Show' but adds no behavioral context beyond what annotations provide, such as output format or whether network calls are made. It doesn't contradict annotations, but adds minimal value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no fluff. It front-loads the action ('Show') and clearly states the subject. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, zero-parameter, read-only tool with strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description is sufficient. It explains what versions are shown ('MCP platform and adapter'). No output schema exists, so the description could mention the return format, but the annotations and simplicity make this acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0 parameters and 0% schema description coverage is N/A. With no parameters, the description needs no parameter explanation. The baseline is 4 for zero-parameter tools, and the description appropriately focuses on the action and output content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: displaying the current MCP platform and adapter versions. It uses a specific verb ('Show') and identifies the resources ('MCP platform and adapter versions'), which clearly distinguishes it from sibling tools like 'toolkit_info' and 'marketplace'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is a diagnostic tool to check environment versions, nor does it compare with similar tools like 'toolkit_info' or 'show_version'. The usage context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying exactly what state information is returned, which is especially valuable because no output schema is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that front-loads the core action ('Returns the current toolkit state') and then enumerates the included items. Every clause contributes meaning without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only status tool, the description is nearly complete: it lists the key output categories and no output schema exists to fill gaps. It could go slightly deeper on the exact format or how connection status is represented, but this is sufficient for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so per the rubric the baseline is 4. The description does not need to explain parameter semantics, and it appropriately focuses on the output contents instead.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('returns') and names the exact resource ('current toolkit state') with concrete detail about the contents: installed MCPs, connection status, accounts, and catalog tool counts. This clearly differentiates it from sibling tools like authenticate or kommo_catalogs_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended usage is implied: call this to inspect overall toolkit connectivity and account status. However, it does not explicitly state when to use it versus alternatives or exclude cases where another tool would be better, such as checking a single account via kommo_list_accounts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.