add_checklist_item

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description is consistent with that ('Изменяет задачу' — it modifies the issue). Beyond the annotations it adds a genuine behavioral requirement not encoded anywhere else: the pre-call confirmation step for text, assignee and deadline. It still says nothing about error behavior or whether additions are reversible.

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 short sentences, front-loaded with the action and followed immediately by the constraint. Every clause earns its place with no 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?

An output schema exists, so return values need not be explained, and the safety profile is covered by annotations. The description covers the mutation nature and the confirmation workflow, leaving only minor gaps such as the undocumented required issue_id and deadline_type semantics.

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% across 6 parameters, so the description carries the burden, and it names only three (text, assignee, deadline) — and only in the context of user confirmation rather than semantics. The required issue_id, plus checked and deadline_type, remain completely undocumented in both schema and 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 states a specific verb and resource ('Добавить пункт чек-листа' = add a checklist item) and the name cleanly separates it from siblings like update_checklist_item and delete_checklist_item. It does not, however, explicitly contrast itself with those siblings or note that the parent issue must already exist.

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 one concrete usage rule — show the text, assignee and deadline to the user before invoking — which is real guidance for a mutating tool. But there is no when-to-use/when-not-to-use statement relative to update_checklist_item or the checklist read tools, so routing guidance is only implied by the name.

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