clickup_create_list_comment

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

The description clearly discloses the tool's behavior: it creates a comment (write operation) and returns a confirmation string or error. It details possible error responses for 404 and 403. Annotations (readOnlyHint=false, destructiveHint=false) are consistent. No contradictions. The description adds valuable context beyond 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 tightly organized with clear sections: single action line, HTTP endpoint, usage conditions, return format, example, and error handling. Every sentence serves a purpose, no redundancy. It is front-loaded and efficiently scannable.

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 presence of an output schema, the description adequately explains the return format (confirmation with id, hist_id, timestamp) and error strings. Usage context (list vs. task comment) is clarified, and error codes are provided. All necessary information for invocation is covered without relying on external references.

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 fully describes all parameters with detailed descriptions. The free-text description provides an example but does not elaborate on parameter semantics beyond what the schema offers. Schema description coverage is 0% (description doesn't explicitly list parameters), but the schema compensates. The example adds marginal value, so a baseline of 3 is appropriate.

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 with 'Add a comment to a List's info panel,' which clearly states the verb and resource. It immediately distinguishes from commenting on a task by specifying 'not on an individual task' and referencing the sibling tool clickup_create_task_comment. The purpose is unambiguous and differentiated.

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?

Explicit 'When to Use' and 'When NOT to Use' sections are provided. 'When to Use' gives a concrete example (status update visible to all). 'When NOT to Use' identifies the alternative precisely. Error handling hints further guide correct usage. This is exemplary guidance.

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