add_comment

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

The description clearly states the tool mutates an incident by adding text, and distinguishes visibility based on the work_note flag. With no annotations provided, this description carries the full burden and does an adequate job, though it doesn't mention authentication requirements or that the tool assumes an existing incident.

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 brief and structured with a docstring-style Args section, making it easy to parse. It is not overly verbose, though the Args section partially repeats schema field names without adding new info for number_or_sys_id.

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 simple tool (3 params, no nested types, no enums), the description adequately covers the purpose and key behavioral differences. An output schema exists, so return value details are not needed. It does not explain prerequisites like 'incident must exist' or what happens if the incident is already resolved, but for a straightforward comment tool, this is sufficient.

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 description adds significant meaning beyond the schema: it explains that comment is customer-visible by default and that work_note makes it internal. Since schema coverage is 0% and there are 3 parameters, the description compensates well, though it could clarify that number_or_sys_id uniquely targets an incident.

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 it adds either a customer-visible comment or an internal work note to an incident, using specific verbs and resources. It distinguishes from sibling tools like create_incident or update_incident by focusing on commentary, not incident creation or field modification.

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 explains the core use case (adding a comment vs work_note) but does not explicitly state when not to use this tool or mention alternatives. Given the sibling tools, an agent might infer that for broader updates they should use update_incident instead, but no direct guidance is offered.

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