create_comment

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

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it's a write operation (implied by 'Add'), mentions automatic Markdown-to-ADF conversion, provides specific mention format syntax, and states what gets returned (comment ID and creation details). It doesn't cover error conditions or rate limits, but provides substantial operational 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 tightly packed sentences with zero waste: first states purpose, second covers formatting and conversion, third provides mention syntax and return values. Every sentence earns its place by adding distinct, necessary information. Well front-loaded with the core action.

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 write operation with no annotations and no output schema, the description does well by covering purpose, formatting behavior, mention syntax, and return values. It doesn't address error cases or authentication requirements, but provides sufficient context for basic usage given the comprehensive parameter schema coverage.

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?

With 100% schema description coverage, the baseline is 3. The description adds some value by repeating the body parameter formatting details and mention syntax, but doesn't provide additional semantic context beyond what's already in the schema descriptions for issueKey, body, and visibility.

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 specific action ('Add a comment') and target resource ('to a Jira issue'), distinguishing it from sibling tools like get_comments (reads) or delete_comment (removes). It specifies the verb+resource combination precisely without being tautological.

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 usage context through mention of formatting options and mentions, but doesn't explicitly state when to use this tool versus alternatives like update_comment or get_comments. No explicit when-not-to-use guidance or prerequisite tools are mentioned beyond the get_users reference for accountId.

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