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.