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

Annotations already carry readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavior: results are ordered newest first, each comment carries author/timestamp/body plus a total count, and there is a rate limit of 10 linked-Jira reads per minute per person. That rate-limit disclosure is valuable and not derivable from structured fields.

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 sentences, front-loaded with the verb and the returned fields, then targeting rules, then access and rate context — no filler. The phrasing is slightly dense ('who wrote each, when and what') but each clause carries information.

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?

With no output schema, the description usefully explains what comes back (author, time, body, total count) and adds ordering, access scope for project members, and rate limits. It does not mention pagination or what happens when the issue has no linked Jira counterpart, which are the remaining gaps for a read tool of this shape.

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 100%, so all four parameters (issue, limit, jiraKey, project) are already documented in the schema, which sets the baseline at 3. The description adds the fallback relationship between 'project' and 'issue' that the schema only gestures at, but it never mentions 'limit' or its max of 30, so it does not meaningfully exceed what the schema provides.

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 and resource: read the comments of one issue in a project's linked Jira, newest first. It points to the related sibling get_linked_jira_issue for the issue itself, so an agent can tell this apart from the issue-fetch tool. It does not distinguish itself from the local-comment sibling get_comments or from search_linked_jira, which keeps it from a 5.

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 context is implied rather than stated: naming the project via 'project' or via an issue here, with the issue's own Jira key as the default, tells the agent how to target the call. There is no explicit 'use this instead of X when Y' guidance versus get_comments or search_linked_jira, and no statement of when not to use it.

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