jira_add_comment

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

Annotations already carry readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the bar for additional disclosure is moderate. The description adds genuinely useful context beyond the annotations: writes may be gated behind platform approval (approval_ref: 'Approved platform task UUID when resuming a write'), effect claims are verified by Spring, and routing is restricted to the exact governed connector authority. It does not elaborate on side effects, but it does not contradict the annotations.

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 compact and well-structured: one identifier line, one governance line, followed by a clean Args list. The first line is slightly redundant with the tool name, and the 'Exact project correlation reference' gloss is vague, but there is no wasted prose and the format is easy to scan.

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?

An output schema exists, so return-value documentation is not required, and the wrapper parameters are all glossed. Yet the essential payload (`arguments`) is undocumented, and the relationship between the parameters (e.g., whether project_id and project_ref are alternatives or both required, how arguments should be shaped for Jira's add_comment) is unexplained. An agent cannot confidently construct a correct invocation, which is a critical gap for a tool that performs a write.

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 0% schema description coverage, the description carries the full burden and does provide a one-line gloss for every parameter (project_id, project_ref, connector_account_ref, idempotency_key, effect, approval_ref), which is better than nothing. However, the most important parameter, `arguments`, is described circularly as 'JSON string of arguments for the connector operation' without telling the agent what fields the Jira add_comment operation expects (e.g., issueId, comment body), leaving the actual payload opaque.

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 identifies a specific verb and resource ('add_comment' as a Jira connector operation) and names the underlying platform tool `jira.add_comment`, so an agent can tell this is the Jira comment-adding operation. It does not explicitly state the target entity (e.g., a Jira issue) or differentiate itself from siblings like jira_add_attachment or jira_create_issue beyond the operation name, which is largely a restatement of the tool name.

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 no guidance on when to use this tool versus alternatives, no exclusions, and no mention of sibling tools. The only contextual statement ('Routes only through the exact project/account governed connector authority') is about governance routing, not about selection criteria.

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