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

Annotations only cover read-only/open-world safety, and the description adds substantial behavior beyond them: the 12000-character description truncation, a per-person rate limit of 10 linked-Jira reads/minute, the trust framing ("written by people on that site"), and an enumerated set of refusal states including not_connected with the connecting 'url'.

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-loaded with the core action and dense with useful detail; nearly every clause carries information (truncation, rate limit, error states). Some phrasing is idiosyncratic and roundabout ("What it says was written by people on that site"), which slows reading slightly, but nothing is filler.

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?

There is no output schema, and the description compensates by enumerating the returned fields (summary, type, status, priority, assignee, reporter, dates, labels, versions, parent, sub-tasks, links, description) plus the full failure taxonomy. An agent has everything needed to call it and interpret the result.

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 the baseline is 3, but the description adds precedence semantics the schema only hints at: 'issue' resolves the project and supplies the default Jira key unless another key is given. That conflict-resolution rule is genuinely useful invocation guidance.

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 one issue of the project's own linked Jira) and explicitly contrasts it with a sibling: "it is not an issue of this tracker (get_issue)". It also names the connection tool (get_jira_connection) that establishes the resource, so an agent can place it precisely among the Jira siblings.

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?

Gives clear selection rules: name 'project' for a project's Jira, or 'issue' for a local issue whose Jira key becomes the default, and clarifies the audience ("for the people who work in the project"). It does not, however, steer an agent to search_linked_jira vs. this tool or to get_linked_jira_comments for comment retrieval.

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