list_comments

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

With no annotations provided, the description carries the full burden. It discloses that only trimmed fields are returned, the ordering is oldest first, and provides detailed insight into the inline_assets array and presigned URLs, including their time-limited nature. While it does not explicitly state it is a read-only operation, the verb 'list' implies that. The description adds significant behavioral context beyond a simple list call.

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 moderately sized with three sentences. The first sentence is front-loaded with the core purpose, the second lists fields, and the third provides necessary detail about inline images. Each sentence earns its place, though the third sentence is somewhat long. It is concise without being terse.

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 tool's simplicity (one parameter) and the existence of an output schema, the description is quite complete. It explains the return fields, ordering, and a niche edge case (inline images with presigned URLs). It does not mention pagination or error handling, but those are often covered by the output schema or are less critical for a basic list operation. Overall, it provides sufficient context for an agent to use the tool correctly.

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 already describes issue_id as 'Task UUID' with 100% coverage. The description adds minimal meaning by linking the parameter to the task context ('comments on a task'), but this does not go beyond what the schema implies. The baseline of 3 is appropriate since schema does the heavy lifting.

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 'List comments on a task, oldest first', which uses a specific verb, resource, and scope. It distinguishes itself from sibling tools like list_tasks and get_task by specifying it operates on comments, not tasks. The additional detail about returned fields further clarifies its purpose.

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 implies its use case: when you need to list comments on a task, with ordering specified. It does not explicitly mention when not to use it or compare to alternatives, but given the sibling tools (e.g., add_comment, list_tasks), the context is clear. It lacks explicit exclusions or alternative recommendations, so a 4 is appropriate.

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