Comment on Task

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

Beyond the annotations, the description discloses that the comment is authored as the connected member, visible to the whole org, and that the tool returns the created comment. It also emphasizes work-relevance, adding context about the intended normative use. No contradictions with annotations exist.

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 three sentences, front-loaded with the action, then usage context, then a prerequisite. Every sentence contributes information without redundancy, making it concise and well-structured.

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?

For a two-parameter write tool with no output schema, the description is complete: it states the action, return value, visibility, and usage context. The annotation set covers safety, and no additional behavioral details are needed for an agent to invoke it 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?

Schema description coverage is 100%, with both id and body described. The description reinforces that both are required and adds the prerequisite to resolve the id via get_task or list_tasks, but this is already implied in the schema's parameter descriptions. Thus the description adds minimal semantic value beyond the schema.

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 comment to a task', and clarifies it is authored as the connected member and returns the created comment. This clearly distinguishes it from sibling tools like add_note or post_to_channel, which target different resources.

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 usage context: 'Use to record progress, a decision, or a handoff' and warns that comments are visible to the whole org, so keep it work-relevant. It also gives a prerequisite to resolve the task id first with get_task or list_tasks, but does not explicitly mention when not to use or name alternatives.

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