Add a comment

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral facts beyond them: the comment is attributed to the token owner and visibly badged "via AI" to other users, mentions trigger notifications to those people, and the call requires comments:write. These are the side effects an agent must know before invoking.

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?

Front-loads the mutation and its attribution, then covers mentions and the permission requirement in three compact sentences. Dense but each clause carries information; only the badge detail is arguably decorative.

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 3-parameter write tool with no output schema and full schema coverage, the description covers identity, user-visible effect, notification side effect, mention mechanics, and auth requirement. It does not say what the call returns or how duplicate/duplicate-mention edge cases resolve, but nothing critical to calling it correctly is missing.

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 coverage is 100%, so baseline is 3, but the description adds genuine semantics the schema does not: the `mentions` array interacts with `text` by consuming existing "@Name" occurrences, and any unmatched entries are appended at the start of the comment. That parsing rule is not derivable from the schema's per-field descriptions.

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?

States a specific verb+resource ("Add a comment to a ticket") plus the identity the comment is attributed to ("as the token owner"). No sibling tool does this, so the agent can distinguish it immediately from update_ticket or create_ticket.

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?

Usage is implied by the exclusive nature of the operation — none of the siblings post comments — but the description never explicitly says when to use this versus e.g. update_ticket for discussion-style text, nor any exclusions (e.g. closed tickets). It gives operational context (mentions, permission) rather than selection guidance.

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