This Jira MCP Server enables AI assistants to interact with Jira Cloud instances for comprehensive issue management and workflow operations.
Issue Management: Create, retrieve, update, and assign Jira issues with support for custom fields, labels, priorities, and rich formatting using Atlassian Document Format (ADF).
Search & Discovery: Search issues using JQL (Jira Query Language), list all accessible projects, search for users by name or email, and discover required fields, custom fields, and allowed values for creating issues.
Comments: Add comments with rich formatting and retrieve existing comments, with support for mentions.
Workflow Management: Get available status transitions for issues and execute transitions to change issue status with optional comments.
Technical Features: Securely connects using API token authentication (email + API token), automatic account ID lookup from email addresses, and JQL-powered advanced search capabilities.
Enables comprehensive Jira Cloud integration including issue management (create, update, assign), JQL search, comments, workflow transitions, metadata discovery, user search, and project listing with custom field support
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Jira MCP Server create a bug in PROJ for the login button not working"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Jira API integration. This server enables AI assistants like Claude to interact with Jira Cloud instances for issue management, search, comments, workflow transitions, and attachment handling.
Issue Management: Get, create, update, and assign Jira issues with custom field support
JQL Search: Search issues using Jira Query Language
Comments: Add and retrieve comments on issues
Workflow: Get available transitions and change issue status
Metadata Discovery: Get field requirements and allowed values for projects
User Search: Find users by email or name for assignments
Projects: List all accessible projects
Attachments: List, upload, delete attachments and retrieve their content — text files returned as text, images rendered inline via Claude vision
Issue Links: Add, remove, and list relationships between issues (relates, blocks, duplicates) without touching the constrained parent hierarchy field
Token Efficient: 6 compound tools instead of 17+ flat tools — ~50% fewer tokens per session
Related MCP server: Jira MCP
npm install -g @nexus2520/jira-mcp-serverClone the repository:
git clone https://github.com/pdogra1299/jira-mcp-server.git
cd jira-mcp-serverInstall dependencies:
pnpm installBuild the project:
pnpm run buildNode.js >= 16.0.0
A Jira Cloud account with API access
Jira API token (generate from Atlassian Account Settings)
JIRA_EMAIL: Your Atlassian account email
JIRA_API_TOKEN: Your Jira API token
JIRA_BASE_URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
Add the following to your Claude Desktop MCP settings file:
Location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Configuration (if installed via npm):
{
"mcpServers": {
"jira": {
"command": "npx",
"args": [
"-y",
"@nexus2520/jira-mcp-server"
],
"env": {
"JIRA_EMAIL": "your-email@company.com",
"JIRA_API_TOKEN": "your-api-token-here",
"JIRA_BASE_URL": "https://yourcompany.atlassian.net"
}
}
}
}Configuration (if built from source):
{
"mcpServers": {
"jira": {
"command": "node",
"args": [
"/absolute/path/to/jira-mcp-server/build/index.js"
],
"env": {
"JIRA_EMAIL": "your-email@company.com",
"JIRA_API_TOKEN": "your-api-token-here",
"JIRA_BASE_URL": "https://yourcompany.atlassian.net"
}
}
}
}Click "Create API token"
Give it a label (e.g., "Claude MCP")
Copy the generated token
Use it in your configuration
This server exposes 6 compound tools — each with an action parameter that selects the operation. This design reduces the token overhead of tool definitions by ~50% compared to 17+ flat tools, leaving more context for actual work.
Tool | Actions | Description |
|
| Full issue lifecycle management |
|
| Search and discovery |
|
| Read and write comments |
|
| Status transitions |
|
| File attachments |
|
| Issue link relationships |
jira_issuesManage the full lifecycle of Jira issues.
Required: action
Action | Description | Required params | Optional params |
| Fetch full issue details |
| — |
| Create a new issue |
|
|
| Edit fields on an existing issue |
|
|
| Set or clear the assignee |
| — |
Tips:
Always call jira_search with action=create_metadata before creating issues to discover required custom fields and allowed values.
Pass assignee: "-1" to unassign an issue.
description accepts plain text or an Atlassian Document Format (ADF) object.
customFields is a key-value map: {"customfield_10000": "value"}.
Examples:
Get details for PROJ-123
Create a Bug in project PROJ with summary "Login button broken"
Update PROJ-123 priority to High
Assign PROJ-123 to john.doe@company.comjira_searchSearch and discover Jira resources.
Required: action
Action | Description | Required params | Optional params |
| Search issues via JQL |
|
|
| List all accessible projects | — |
|
| Find users by name or email |
|
|
| Get field requirements for creating issues |
|
|
Common JQL examples:
project = PROJ AND status = Open
assignee = currentUser() AND status != Done
priority = High AND created >= -7dTips:
Use create_metadata before jira_issues create to understand what fields are required for a project/issue type.
Use users to look up account IDs for assignments — pass the returned account ID or email to jira_issues assign.
fields (for issues) controls which JIRA fields are fetched per result — e.g. ["summary","status","priority","duedate","assignee"]. Defaults to ["summary"].
Structured output: the issues action and jira_issues get return a structuredContent JSON payload alongside the markdown, so programmatic consumers can read fields directly without parsing markdown. For issues it is { jql, count, isLast, nextPageToken, issues: [{ key, id, self, fields }] }.
jira_commentsRead and write comments on a Jira issue.
Required: action, issueKey
Action | Description | Required params |
| Fetch all comments on an issue | — |
| Post a new comment |
|
comment accepts plain text or an ADF object.
Examples:
Get all comments on PROJ-123
Add a comment to PROJ-123: "Fixed in PR #456"jira_workflowManage issue status transitions.
Required: action, issueKey
Action | Description | Required params | Optional params |
| List available status transitions | — | — |
| Move issue to a new status |
|
|
Tip: Always call get_transitions first — transition IDs vary per project and issue type. The transitionId from the response is what you pass to transition.
Examples:
Get available transitions for PROJ-123
Move PROJ-123 to "In Progress" (use get_transitions first to find the ID)jira_attachmentsManage file attachments on Jira issues.
Required: action
Action | Description | Required params | Optional params |
| List all attachments with metadata |
| — |
| Download and return file content |
|
|
| Attach a local file to an issue |
|
|
| Remove an attachment by ID |
| — |
Content types returned by get_content:
Text files (text/*, application/json, application/xml): returned as readable text
Images (image/*): returned as base64 — Claude will render them inline
Other types (PDF, zip, etc.): returns file metadata with a descriptive message
Tips:
Use list first to get attachment IDs before calling get_content or delete.
fileName in upload overrides the filename shown in Jira (defaults to the file's basename).
Examples:
List attachments on PROJ-123
Get the content of attachment 136904
Upload /tmp/report.pdf to PROJ-123
Delete attachment 136904jira_linksManage relationships between issues independently of Jira's project hierarchy config — useful when you need to associate a Bug with a Story but the project doesn't allow Bug → Story as a parent-child relationship.
Required: action
Action | Description | Required params | Optional params |
| List available link type names for this Jira instance | — | — |
| Create a link between two issues |
|
|
| List all links on an issue, with link IDs |
| — |
| Delete a link by ID |
| — |
Link direction:
Symmetric types (Relates, Duplicate): direction doesn't matter.
Directional types (Blocks, Cloners, Causes): direction: outward means issueKey is the outward side (e.g. issueKey blocks linkedIssueKey); direction: inward means issueKey is the inward side (e.g. issueKey is blocked by linkedIssueKey). Defaults to outward.
Tips:
Run get_link_types first — link type names vary per Jira instance config.
Use list to find a linkId before calling remove.
Examples:
List the link types available in Jira
Link PROJ-1 to PROJ-2 as Relates
Mark PROJ-1 as blocking PROJ-2
List all links on PROJ-1
Remove link 10042This server uses the Jira REST API v3.
Make sure you've set the environment variables in your MCP configuration.
Verify your API token is correct
Ensure your email matches your Atlassian account
Check that your JIRA_BASE_URL doesn't have a trailing slash
The API token uses the permissions of the user who created it. Make sure your account has the necessary permissions for the actions you're trying to perform.
MIT
Parth Dogra
Feel free to open issues or submit pull requests for improvements!
Add a comment to a Jira issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key to comment on (e.g., PROJ-123) | |
| comment | Yes | The comment in ADF format or plain string. Example ADF: {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Comment text"}]}]} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Add a comment') but lacks details on permissions needed, whether it's idempotent, error handling, or response format. This is a significant gap for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the tool's purpose without unnecessary elaboration.
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 the complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like authentication needs, potential side effects, or what the tool returns, leaving gaps that could hinder an AI agent's correct 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 description coverage is 100%, so the input schema already documents both parameters thoroughly. The description doesn't add any meaning beyond what the schema provides, such as clarifying the comment format or issueKey usage. Baseline 3 is appropriate when the schema does the heavy lifting.
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 verb ('Add') and resource ('a comment to a Jira issue'), making the purpose specific and understandable. However, it doesn't distinguish this tool from potential alternatives like 'update_issue' which might also handle comments, leaving room for improvement in sibling differentiation.
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. With sibling tools like 'update_issue' that might modify issues, there's no indication of whether this is the preferred method for adding comments or if it has specific prerequisites, such as requiring an existing issue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a Jira issue to a user
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key to assign (e.g., PROJ-123) | |
| assignee | Yes | User account ID, email (will auto-lookup account ID), or "-1" to unassign |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action without disclosing behavioral traits. It doesn't mention required permissions, whether assignment is reversible, rate limits, error conditions, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is inadequate.
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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a simple tool with good schema documentation.
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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, error handling, permissions needed, or side effects. Given the complexity of assignment operations in Jira, more context is warranted.
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 the schema already documents both parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., no examples beyond 'PROJ-123', no clarification of '-1' behavior). Baseline 3 is appropriate when schema does the heavy lifting.
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 action ('assign') and resource ('a Jira issue to a user'), making the purpose immediately understandable. It distinguishes from siblings like 'update_issue' or 'transition_issue' by focusing specifically on assignment, though it doesn't explicitly mention these alternatives.
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?
No guidance is provided on when to use this tool versus alternatives like 'update_issue' (which might also handle assignment) or 'unassign' scenarios. The description implies usage for assignment but offers no context about prerequisites, permissions, or 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.
Create a new Jira issue with specified fields. IMPORTANT: Always use get_create_metadata first to discover required fields, custom fields, and allowed values for the project and issue type.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | The project key where the issue will be created (e.g., PROJ, DEV) | |
| summary | Yes | The issue summary/title | |
| issueType | Yes | The issue type (e.g., Bug, Task, Story) | |
| description | No | The issue description in Atlassian Document Format (ADF). Can be a simple string for plain text, or an ADF object for rich formatting. Example ADF: {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Description text"}]}]} | |
| priority | No | Priority name (e.g., High, Medium, Low) - optional | |
| assignee | No | Assignee account ID or email (will auto-lookup account ID from email) - optional | |
| labels | No | Array of labels - optional | |
| customFields | No | Custom fields as key-value pairs (e.g., {"customfield_10000": "value"}) - optional. Use get_create_metadata to discover available fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a creation/mutation operation and provides important workflow guidance about using get_create_metadata first. However, it doesn't disclose other behavioral aspects like authentication requirements, rate limits, error handling, or what happens on successful creation.
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 perfectly structured with two sentences: the first states the core purpose, the second provides critical usage guidance. Every word earns its place, and the important 'IMPORTANT' warning is appropriately front-loaded for maximum visibility.
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 creation tool with 8 parameters, no annotations, and no output schema, the description does well by providing clear purpose and essential workflow guidance. However, it could be more complete by mentioning what happens on success (e.g., returns issue ID/key) or addressing common failure scenarios, given the tool's complexity.
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 the schema already documents all 8 parameters thoroughly. The description adds minimal parameter-specific information beyond the schema, mainly reinforcing the need to use get_create_metadata for customFields discovery. This meets the baseline expectation when schema coverage is high.
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 ('Create a new Jira issue') and resource ('with specified fields'), distinguishing it from siblings like update_issue, assign_issue, or add_comment. It provides a complete, unambiguous purpose statement.
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 explicitly states 'IMPORTANT: Always use get_create_metadata first' with clear reasoning ('to discover required fields, custom fields, and allowed values'). This provides specific guidance on when to use this tool versus alternatives and establishes a prerequisite workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all comments for a Jira issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key (e.g., PROJ-123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action but doesn't cover key traits: whether this is a read-only operation (implied by 'Get' but not explicit), what the return format looks like (e.g., list structure, pagination), or any rate limits or permissions required. This leaves significant gaps for an agent.
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 a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., comment objects with fields like author, body, timestamps) or behavioral aspects like error handling. For a tool with no structured support, this minimal description is inadequate.
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 the schema already documents the single parameter 'issueKey' with its description. The description adds no additional meaning beyond what the schema provides, such as example usage or constraints, meeting the baseline for high coverage.
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 verb 'Get' and resource 'all comments for a Jira issue', making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get_issue' or 'add_comment' beyond the specific resource type, which prevents a perfect score.
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 like 'get_issue' (which might include comments) or 'add_comment'. It lacks context about prerequisites, such as needing an existing issue, or exclusions, like not being able to filter comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get field requirements and metadata for creating issues in a project. Shows required fields, custom fields, and allowed values.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | The project key (e.g., PROJ, DEV) | |
| issueType | No | Optional: Filter by specific issue type (e.g., Bug, Task) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the tool as a read operation ('Get'), which implies non-destructive behavior, but doesn't disclose other traits like authentication needs, rate limits, or response format. The description adds some context about what metadata is returned, but lacks behavioral details beyond the basic purpose.
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 concise and front-loaded, stating the purpose in the first sentence and elaborating with specifics in the second. Both sentences earn their place by clarifying scope and outputs. It could be slightly more structured by explicitly mentioning parameters, but it's efficient with zero waste.
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 the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It explains what metadata is returned but lacks details on behavioral aspects like error handling or usage prerequisites. Without annotations or output schema, it should do more to cover operational context, but it meets minimum viability.
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?
The input schema has 100% description coverage, with clear documentation for both parameters ('projectKey' and 'issueType'). The description adds no additional parameter semantics beyond what the schema provides, such as examples or constraints. With high schema coverage, the baseline is 3, as the description doesn't compensate but doesn't detract either.
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's purpose: 'Get field requirements and metadata for creating issues in a project.' It specifies the verb ('Get') and resource ('field requirements and metadata'), and lists what it shows ('required fields, custom fields, and allowed values'). However, it doesn't explicitly differentiate from siblings like 'create_issue' or 'get_issue' beyond implying it's for metadata before creation.
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 ('for creating issues in a project'), suggesting it should be used before 'create_issue' to understand requirements. However, it doesn't explicitly state when to use this tool versus alternatives (e.g., not for actual creation or issue retrieval) or provide exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a Jira issue by its key or ID
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key (e.g., PROJ-123) or issue ID (e.g., 378150) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves 'detailed information' but doesn't specify what that includes (e.g., fields returned, pagination, error handling for invalid keys). For a read operation without annotations, this lacks critical details like rate limits, authentication needs, or response format, though it doesn't contradict any 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 a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part ('Get detailed information about a Jira issue by its key or ID') contributes directly to understanding the tool, making it highly concise and well-structured.
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 the complexity of a Jira issue retrieval tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'detailed information' entails, how errors are handled, or the response structure, leaving significant gaps for an agent to use the tool effectively. This is inadequate for a tool that likely returns complex data.
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?
The input schema has 100% description coverage, with the parameter 'issueKey' fully documented in the schema. The description adds minimal value beyond the schema by reiterating that it accepts 'key or ID' but doesn't provide additional semantics like format examples or validation rules. Baseline 3 is appropriate since the schema does the heavy lifting.
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 verb ('Get detailed information') and resource ('about a Jira issue'), making the purpose immediately understandable. It distinguishes the tool from siblings like 'search_issues' by focusing on retrieving a single issue by identifier rather than searching. However, it doesn't explicitly mention what constitutes 'detailed information' (e.g., fields, comments, attachments).
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 by specifying 'by its key or ID,' suggesting this tool is for retrieving known issues rather than searching. However, it doesn't explicitly state when to use this versus alternatives like 'search_issues' (for unknown issues) or 'get_comments' (for specific issue components). No exclusions or prerequisites are mentioned, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available status transitions for a Jira issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key (e.g., PROJ-123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool does but does not describe behavioral traits such as whether it requires specific permissions, how it handles errors, or the format of the returned transitions. This is a significant gap for a tool with no annotation coverage.
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 a single, clear sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and efficient, making it easy to understand at a glance.
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 the complexity of Jira operations and the lack of annotations and output schema, the description is incomplete. It does not explain what the tool returns (e.g., a list of transitions with details), potential errors, or how it integrates with sibling tools like 'transition_issue'. This leaves gaps for effective agent use.
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?
The input schema has 100% description coverage, with the 'issueKey' parameter clearly documented. The description does not add any meaning beyond what the schema provides, such as examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate.
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 verb ('Get') and resource ('available status transitions for a Jira issue'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'get_issue' or 'transition_issue', which might handle related but distinct operations, so it falls short of a perfect score.
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. For example, it does not specify if this should be used before 'transition_issue' to check possible transitions, or how it relates to 'get_issue' for issue details. This lack of context leaves usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all accessible Jira projects
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of projects to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'accessible' projects, hinting at permission constraints, but doesn't specify authentication requirements, rate limits, pagination behavior, or what 'accessible' means in practice. For a read operation with zero annotation coverage, this leaves significant gaps.
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 a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it easy to understand at a glance.
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 the tool's simplicity (one optional parameter, no output schema, no annotations), the description is minimally adequate. However, it lacks information about return format, pagination, or error handling that would be helpful for a list operation, especially with no output schema provided.
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?
The input schema has 100% description coverage, with the single parameter 'maxResults' clearly documented in the schema. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline score when schema coverage is high.
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 action ('List') and resource ('accessible Jira projects'), making the tool's purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'search_issues' or 'get_issue' that also retrieve Jira data, so it doesn't reach the highest score.
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 like 'search_issues' or 'get_issue', nor does it mention any prerequisites or context for usage. It simply states what the tool does without indicating appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Jira issues using JQL (Jira Query Language). Returns issue keys and titles. Use get_issue for full details.
| Name | Required | Description | Default |
|---|---|---|---|
| jql | Yes | JQL query string (e.g., "project = PROJ AND status = Open") | |
| maxResults | No | Maximum number of results to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'returns issue keys and titles' which describes output format, but doesn't mention important behavioral aspects like whether this is a read-only operation, authentication requirements, rate limits, pagination behavior, or error handling. The description adds some value but leaves significant gaps.
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 perfectly concise with just two sentences that each serve a clear purpose: the first explains what the tool does, the second provides crucial usage guidance. There's zero wasted language, and the most important information (the tool's purpose) 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?
For a search tool with 2 parameters (100% schema coverage) but no annotations and no output schema, the description provides adequate but incomplete context. It explains the basic purpose and distinguishes from siblings, but lacks behavioral details about the search operation's scope, limitations, or output structure beyond 'issue keys and titles'. The absence of annotations and output schema means more context would be helpful.
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 the schema already fully documents both parameters (jql and maxResults). The description doesn't add any parameter-specific information beyond what's in the schema. It mentions JQL generally but doesn't provide additional syntax examples or constraints. Baseline 3 is appropriate when the schema does all the parameter documentation work.
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's purpose with specific verb ('search') and resource ('Jira issues'), and distinguishes it from sibling tools by specifying it returns 'issue keys and titles' and directing users to 'get_issue for full details'. This differentiates it from other issue-related tools like get_issue, create_issue, or update_issue.
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 explicit guidance on when to use this tool versus alternatives: 'Use get_issue for full details' clearly indicates this tool is for searching and returning basic information, while get_issue should be used when detailed information is needed. This helps the agent choose between sibling tools appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Jira users by name or email to get their account ID. Use this to find account IDs for assigning issues.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query - can be email, name, or partial match (e.g., "john.doe@company.com" or "John Doe") | |
| maxResults | No | Maximum number of results to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the search functionality and the goal of obtaining account IDs, but lacks details on error handling, authentication requirements, rate limits, or the format of returned results. While it covers the basic intent, it misses operational nuances that would help an agent invoke it reliably.
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 two sentences, front-loaded with the core purpose and followed by usage guidance. Every word earns its place, with no redundancy or fluff. It efficiently communicates essential information without unnecessary elaboration, making it easy for an agent to parse quickly.
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 the tool's moderate complexity (search with two parameters), no annotations, and no output schema, the description is partially complete. It explains the purpose and usage but lacks details on return values, error conditions, or behavioral constraints. For a search tool without structured output documentation, this leaves gaps in full contextual understanding.
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 the schema already fully documents both parameters ('query' and 'maxResults'). The description adds no additional parameter semantics beyond what the schema provides, such as examples or edge cases. It meets the baseline for high schema coverage but does not enhance parameter understanding.
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 ('Search for Jira users by name or email'), the resource ('Jira users'), and the purpose ('to get their account ID'). It distinguishes this from sibling tools like 'search_issues' by focusing on user lookup rather than issue search, making the purpose unambiguous and well-defined.
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 explicitly states when to use this tool: 'to find account IDs for assigning issues.' This provides clear context for its application, distinguishing it from other user-related operations (e.g., no sibling tool like 'create_user' exists) and guiding the agent toward its primary use case in issue assignment workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the status of a Jira issue by transitioning it
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key to transition (e.g., PROJ-123) | |
| transitionId | Yes | The transition ID to execute (get from get_transitions) | |
| comment | No | Optional comment to add with the transition |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool performs a status change (implying a mutation), but doesn't address critical aspects like required permissions, whether the transition is reversible, potential side effects (e.g., triggering workflows), or error conditions. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly. Every word earns its place in conveying the core purpose.
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 the tool's complexity (a mutation operation in Jira with 3 parameters), lack of annotations, and no output schema, the description is insufficiently complete. It doesn't explain what happens after the transition (e.g., success/failure responses, returned data), nor does it cover behavioral nuances like authentication needs or rate limits. For a tool that changes issue states, more context is needed for reliable agent use.
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 the input schema already documents all three parameters thoroughly. The description adds no additional meaning about parameters beyond what's in the schema (e.g., it doesn't explain the relationship between 'transitionId' and status changes, or provide examples of valid transitions). This meets the baseline for high schema coverage but doesn't enhance parameter understanding.
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 verb ('Change the status') and resource ('a Jira issue'), making the purpose understandable. However, it doesn't explicitly distinguish this from sibling tools like 'update_issue' which might also modify issue states, leaving some ambiguity about when to use this specific transition-focused tool versus broader update operations.
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. It doesn't mention prerequisites (e.g., needing to call 'get_transitions' first to obtain transition IDs), nor does it clarify when to choose this over 'update_issue' or other sibling tools that might handle status changes differently. This leaves the agent with minimal context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields of an existing Jira issue. TIP: Use get_create_metadata to discover available custom fields and their allowed values for the project.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | The issue key to update (e.g., PROJ-123) | |
| summary | No | New summary/title - optional | |
| description | No | New description in ADF format or plain string - optional | |
| priority | No | New priority name - optional | |
| assignee | No | New assignee account ID or email (will auto-lookup account ID from email) - optional | |
| labels | No | New labels array - optional | |
| customFields | No | Custom fields as key-value pairs (e.g., {"customfield_10000": "value"}) - optional. Use get_create_metadata to discover available fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it correctly identifies this as an update operation, it doesn't mention important behavioral aspects like what permissions are required, whether the update is atomic or partial, what happens to unspecified fields, or error conditions. The tip about custom fields adds some context but doesn't compensate for the lack of mutation-specific behavioral information.
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 appropriately brief with two sentences, both of which add value. The first sentence states the core purpose, and the second provides a practical tip. There's no wasted verbiage, though it could be slightly more structured with clearer separation between purpose and guidance.
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 mutation tool with 7 parameters, no annotations, and no output schema, the description is minimally adequate. It identifies the operation type and provides one helpful tip, but doesn't address important contextual aspects like what the tool returns, error handling, or how it differs from similar mutation tools in the sibling set. The lack of output information is particularly notable given there's no output schema.
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?
The schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema - it mentions 'fields' generally and provides a tip about custom fields, but doesn't explain parameter interactions, constraints, or provide additional semantic context that isn't already in the parameter descriptions.
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 action ('Update fields') and resource ('existing Jira issue'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from similar siblings like 'assign_issue' or 'transition_issue' which also modify issues, missing the highest level of sibling distinction.
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 a helpful tip about using 'get_create_metadata' to discover custom fields, which gives some context about when this tool might be needed. However, it doesn't explicitly state when to use this tool versus alternatives like 'assign_issue' or 'transition_issue' for specific modifications, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_commentassign_issuecreate_issueget_commentsget_create_metadataget_issueget_transitionslist_projectssearch_issuessearch_userstransition_issueupdate_issueScored across 12 tools
Each tool has a clearly distinct purpose targeting specific Jira operations like issue management, metadata retrieval, or user search. The descriptions reinforce this separation, such as distinguishing search_issues (returns keys/titles) from get_issue (full details), preventing misselection.
All tools follow a consistent verb_noun pattern with snake_case (e.g., create_issue, get_comments, list_projects). The naming is predictable and readable throughout, with no deviations in style or convention.
With 12 tools, this server is well-scoped for Jira operations, covering core workflows like issue CRUD, commenting, transitions, and metadata. Each tool earns its place without bloat, aligning with typical domain needs.
The toolset provides complete coverage for Jira issue lifecycle management, including create, read, update, assign, transition, and comment operations. It also supports essential metadata and user search, leaving no obvious gaps for agent workflows.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Give your AI agents the tools to build, manage, and run automation workflows.
