Comments

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the key behavioral note about Taiga soft-deletes comments on delete, which provides insight into the delete operation's reversibility. This goes beyond the annotations without contradicting them (soft-delete aligns with destructiveHint=false). No auth or rate-limit context, but the soft-delete note is valuable.

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: one sentence stating the purpose, a short soft-delete note, and a clean markdown table mapping ops to required/optional args. Every element is functional, 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?

The tool has 7 parameters and no output schema. The description covers all operations and the soft-delete behavior, which is sufficient for basic usage. It could mention pagination or the return format for list, but the operation table and soft-delete note make it reasonably complete for a CRUD-style 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 coverage is 100%, but the description adds a critical semantic layer via the operation table, which specifies which parameters are required or optional for each op. For example, the schema only marks 'op' as required, but the table shows that 'type' and 'item' are required for all operations, and 'text' or 'commentId' are required for specific ops. This conditional requirement is not in the schema and is essential for correct tool use.

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 specific verbs ('List, add, edit, or delete') and identifies the resource ('comments on issues, user stories, tasks, epics, and wiki pages'). It clearly distinguishes from sibling tools like attachments or wiki by scoping the domain to comments.

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 what item types are supported and lists operations. While it doesn't explicitly name alternative tools for exclusion, the scope is well-defined enough that an agent can infer when to use this tool versus siblings. No explicit when-not guidance is given, but the purpose is unambiguous.

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