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

Annotations already declare this is a non-readOnly, non-destructive, idempotent write. The description adds behavior the annotations cannot convey: comments are internal/team-only (visibility semantics), file uploads are unsupported, and idempotency is achieved by reusing requestId only for retries of the same call. That is genuinely additive context.

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?

Three short sentences, purpose front-loaded, rest split cleanly between formatting convention, a constraint, and an idempotency rule. No filler, though the fragments are terse enough that some needed context (cardId vs ticket identity) was omitted for brevity.

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 no-output-schema mutation whose annotations cover safety and idempotency, the description supplies visibility, formatting, and requestId semantics. It is close to complete; the only gap is not clarifying how cardId/projectId map to the 'ticket' referenced in the first sentence.

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 0% with four required parameters. The description compensates for two of them: body (mention syntax, no file uploads, implicitly text-only) and requestId (fresh UUID, retry-only reuse rule). projectId and cardId remain undocumented in both description and schema, leaving half the parameters unelaborated.

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?

Specifies the verb (add) and resource (comment) plus scope qualifier ('internal team comment'), which distinguishes it from a customer-visible reply. However it never explicitly contrasts itself with sibling update_ticket_comment or delete_ticket_comment, so sibling differentiation is left to inference.

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?

'No file uploads' functions as an implicit exclusion, steering agents toward an attachment tool, and the mention syntax tells how to notify teammates. But there is no explicit statement of when to add a comment versus updating an existing one, and no prerequisites or permission guidance.

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