Link Jira Issue to Test Manager Test Case

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

With no annotations, the description carries full burden. It discloses that linking is a persistent action, explains the observable effect on the test case's links and query results, and notes the org requirement. However, it does not detail error conditions or idempotency.

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 only four sentences, each adding distinct value: purpose and effect, required params, org prerequisite, and caution against speculative use. No wasted words and the key action is front-loaded.

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?

Given low complexity and no output schema, the description adequately covers purpose, prerequisites, effect, and a caution. It lacks mention of return value or error handling, but the context is mostly complete for selection and safe invocation.

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 0%, so description must compensate. It provides a format example for jira_issue_id ('PROJ-123') and states project_id and test_case_id are required, but does not explain their purpose, how to obtain them, or expected formats beyond minLength.

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 tool links a Jira issue to a test case, specifies the effect on the test case's Jira links and the get_testExecutionHistoryByJiraId, and implicitly distinguishes from the sibling unlink_jiraIssue tool.

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?

Specifies required parameters (project ID, test case ID), prerequisite that the Jira issue must belong to the LT_ORG_ID org, and explicitly warns against speculative calls by stating the action is real and persistent. This provides both when-to-use and when-not-to-use guidance.

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