iva_chat_messages

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

No annotations are provided, so the description must carry behavioral disclosure alone. It merely lists operations and does not mention that several actions (delete, delete_multiple, remove_attachment) are destructive, nor does it describe authentication requirements, rate limits, pagination behavior, or response shape. The version string 'Clients API v2.28.12' adds little behavioral insight. The enumeration does imply mutation, but lacks the necessary consequences and caveats.

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 one compact sentence and a short version suffix, efficiently summarizing the tool's scope without unnecessary prose. The list of operations is front-loaded before the API version. It could be structured slightly better (for example grouping read vs write vs destructive actions), but it is appropriately concise.

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 a complex 20-parameter polymorphic tool with no output schema and no annotations, the description is only an overview. The rich schema compensates for parameter documentation, but the description does not explain that the tool is an action dispatcher, which actions are destructive and require confirmation, or what kind of response to expect. It is adequate as a high-level entry point but not fully sufficient on its own.

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 100%, so the structured schema already documents each parameter meaning. The tool description adds no extra parameter semantics beyond the schema. Per calibration baseline, with full schema coverage a score of 3 is appropriate: the description is not harmful but does not compensate for anything missing.

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 ('IVA chat messages') and lists the main operations: send/edit/delete/star messages, search attachments, get messages/changes/starred, typing notification, read receipt. It is not merely a tautology and gives an agent a useful overview. It does not explicitly contrast with siblings like iva_chat, but the focus on messages is reasonably distinctive.

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 prose description gives no guidance on when to choose this tool over alternatives such as iva_chat or iva_conference_chat. Some per-action usage hints (e.g., use 'send' when the user says 'отправь сообщение') exist inside the action enum, but those are structured schema content rather than the tool description. Without explicit when-to-use or when-not-to-use guidance, the agent is left to infer routing from the operation list.

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