The Jira MCP server integrates AI assistants with Jira Server/Data Center via REST API v2, enabling full ticket management and more:
Get Ticket (get_ticket): Retrieve full details of any Jira ticket by its key (e.g. GEM-234).
Search Tickets (search_tickets): Search for tickets using JQL query language, with configurable result limits.
Create Ticket (create_ticket): Create new issues (Story, Task, Bug, Sub-task) with optional fields like description, labels, due date, start date, parent key, and time estimate.
Update Ticket (update_ticket): Modify existing ticket fields including summary, description, issue type, parent, labels, dates, estimate, assignee, priority, and append implementation notes.
Transition Ticket (transition_ticket): Change a ticket's status by target status name (e.g. "In Progress", "Done").
Add Comment (add_comment): Post a plain-text comment to any Jira ticket.
Log Work (log_work): Record time spent on a ticket, with optional start time, comment, and WorklogPRO custom fields.
Link Issues (link_issues): Create directional links between two tickets using types like Blocks, Clones, Relates to, or Duplicate.
Generate Release Notes (generate_release_notes): Produce Markdown-formatted release notes for a fix version, grouped by issue type (Features, Improvements, Bug Fixes, Other), optionally filtered by project.
Provides tools for interacting with Jira Server/Data Center, including reading and writing tickets, searching with JQL, creating, updating, transitioning tickets, adding comments, logging work, linking issues, and generating release notes.
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 Get details for ticket ABC-123"
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.
MCP server for Jira Server/Data Center (REST API v2). Lets an AI assistant (Claude Code, Claude Desktop, ...) read and write your Jira directly.
A Jira Server/Data Center account (username + password).
Node.js 18+.
Related MCP server: Jira MCP Server
Use Claude Code CLI:
claude mcp add g-jira-mcp npx -y g-jira-mcp@latest \
--env JIRA_HOST="https://jira.company.com" \
--env JIRA_USERNAME="your_username" \
--env JIRA_PASSWORD="your_password"Or manually add to .claude/settings.json (or claude_desktop_config.json):
{
"mcpServers": {
"g-jira-mcp": {
"command": "npx",
"args": ["-y", "g-jira-mcp@latest"],
"env": {
"JIRA_HOST": "https://jira.company.com",
"JIRA_USERNAME": "your_username",
"JIRA_PASSWORD": "your_password"
}
}
}
}Restart Claude Code/Desktop after editing the config.
Variable | Required | Description |
| yes | Base URL, e.g. |
| yes | Jira username |
| yes | Jira password |
| no | Custom field ID for "Start date" (default |
| no | Custom field ID for "Epic Link" (default |
| no | Timezone for WorklogPRO form (default |
To discover custom field IDs on your instance:
curl -u user:pass https://jira.company.com/rest/api/2/field | jq '.[] | select(.name | test("story|point|start"; "i")) | {id, name}'Tool | Description | Key parameters |
| Get full details of a Jira ticket by its key |
|
| Search Jira tickets using JQL query language |
|
| Create a new Jira ticket |
|
| Update fields of a Jira ticket |
|
| Change a Jira ticket's status by name, alias-aware |
|
| Add a comment to a Jira ticket |
|
| Log work (time) on a Jira ticket, optionally setting WorklogPRO Type of Work and Type of Activity |
|
| Create a link between two Jira tickets |
|
| Generate Markdown release notes for a fix version, grouped by issue type |
|
Jira Server uses plain text for descriptions — no ADF format.
get_ticket omits unset fields rather than printing placeholder text. Key, Summary, Status and Assignee are always present (Assignee shows "Unassigned" when empty); other fields appear only when set. Pass include_comments=true to append the ticket's comment thread; comments are off by default to keep output small and save tokens. The same Jira request fetches everything, so including comments costs no extra API call. Comments are capped at 20 most recent; if a ticket has more, the header reads Comments (20 most recent of 45): so the caller knows older comments exist and can open the ticket in Jira to see them.
search_tickets output is adaptive: empty columns (no value anywhere) are dropped entirely, and constant columns (same value on every row, when there are 3+ rows) are stated once in the header as All: Status=In Progress and removed from the table. When columns are dropped, the header also notes which ones were empty across all results (e.g. Unset for every row: Priority, Parent, Start Date) so the caller can tell "no ticket has a due date" from "this tool doesn't return due dates". KEY and Summary are always kept. This keeps results focused and token-efficient. The header's Found N issue(s) (showing M) reports when the result was truncated — raise max_results above the default 25 to see more.
create_ticket and update_ticket both accept an assignee parameter (Jira username as a string, sent as {name: assignee}). In create_ticket, an empty assignee value is ignored. In update_ticket, pass assignee="" to unassign.
create_ticket applies original_estimate in a follow-up PUT rather than in the create payload: Jira Data Center answers a bare 500 Internal server error when timetracking is present in POST /issue, while the same value applies cleanly as an update afterwards. The ticket key is reported even if that second call fails, with a warning to set the estimate via update_ticket — so a failed estimate never sends you back to create a duplicate.
duedate is a standard field (YYYY-MM-DD); "Start date" is a custom field, configurable via JIRA_START_DATE_FIELD.
update_ticket's epic_key sets the Epic Link field (a custom field, configurable via JIRA_EPIC_LINK_FIELD, default customfield_10001) so the ticket shows under the epic's "Issues in Epic" panel — not the same as link_issues, which only creates a generic Linked Issue (e.g. "Relates"). Epic Link can only be set on standard issue types (Story/Task/Bug), not on Sub-tasks or Epics themselves.
search_tickets uses JQL syntax, e.g. project = GEM AND status = 'In Progress'.
transition_ticket resolves the transition ID automatically, matching either the transition's own name ("Resolve Issue") or the status it lands on ("Done"). Common aliases map onto whatever the workflow actually offers (Closed/Resolved/Complete → Done, Reopen → Re-Open, Todo → To Do, Cancelled → Won't Do), so the same call works across workflows with different status names. Exact matches win, then aliases, then a substring fallback. When nothing matches, the error lists every valid option for that issue as Transition -> Target Status; the tool description cannot list them because they vary per issue and workflow.
update_ticket only changes the fields you pass; omit a field to keep its current value. Pass assignee="" to unassign. implementation_notes appends to the description. Converting a standard issue type (Story, Task, Bug) to Sub-task or vice versa is a Jira REST API limitation — use the Jira UI "Move" action instead.
log_work advertises one canonical name per work type (code, deploy, design, fix, management, meeting, misc, operation, qa, req, research, translation) and per activity (correct, create, review) so its schema stays small; every alias still works as input (coding, dev, testing, ops, requirement, other, and the rest). activity is required when work_type is set. If neither is set, logs via plain REST (no WorklogPRO form). Start times are interpreted in the Jira server timezone (configurable via JIRA_TIMEZONE).
generate_release_notes groups tickets by type into Features / Improvements / Bug Fixes / Other.
Register the server as g-jira-mcp and use that key in every project. The key becomes the tool prefix (mcp__g-jira-mcp__get_ticket), so a project that registers it under a different name exposes different tool names — an agent carrying the habit of one name into a project configured with the other gets No such tool available.
Transient Jira failures (429, 500, 502, 503, 504) are retried up to twice with a 250ms/500ms backoff. Only GET, PUT and DELETE are replayed — a POST that returned 500 may already have created the comment, worklog or transition, so it fails fast instead of risking a duplicate.
All logs go to stderr; stdout is reserved for the MCP protocol.
"Search tickets in project GEM that are In Progress"
"Create a Story in GEM titled 'Release notes v2.0' due 2026-08-01"
"Update GEM-234, set the assignee to namcp and add label BugFix"
"Add a comment to GEM-234: 'Review done'"
"Generate release notes for fix version v2.4 in project GEM"
401/403: recheck JIRA_USERNAME/JIRA_PASSWORD and whether the account can access the project.
Connection/timeout: verify JIRA_HOST format (starts with https://, no trailing /), and whether VPN/internal network is required.
Start date not saving: confirm JIRA_START_DATE_FIELD matches your instance (see the discovery command above).
No error logs: server logs go to stderr — check the MCP client (Claude Code/Desktop) output, not stdout.
pnpm install
cp .env.example .env # edit with your credentials
pnpm build # bundle to dist/index.js via esbuild
pnpm lint # biome check + tsc + prettier (markdown)
pnpm release # release-it: bumps version, commits, tags, pushes (runs lint + build first, no pre-commit needed)
pnpm archive # package release/jira-mcp-v<version>.zipQuestions or issues? Email NamCP.
If this project helps you, consider buying me a coffee:
Add a comment to a Jira ticket
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Comment text (plain text) | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Add a comment'. It does not disclose whether the operation is idempotent, requires permissions, or what the response looks like. Minimal behavioral info.
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 sentence, front-loaded, and contains no wasted words.
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 has 2 parameters with full schema descriptions and no output schema, the description is minimal. It lacks behavioral transparency and usage guidelines, making it insufficient for a complete contextual picture.
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 (body and ticket_id) with descriptions. The tool description adds no additional meaning beyond the schema.
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 'Add a comment to a Jira ticket' clearly identifies the verb (Add), resource (comment), and context (Jira ticket). It effectively distinguishes from sibling tools like create_ticket, update_ticket, and transition_ticket.
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. For example, it does not mention that it is for adding new comments as opposed to editing existing ones, nor does it reference any prerequisites.
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 ticket
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Description text | |
| labels | No | Labels to assign | |
| project | Yes | Project key, e.g. GEM | |
| summary | Yes | Issue title | |
| assignee | No | Assignee username, e.g. username | |
| due_date | No | Due date YYYY-MM-DD | |
| issue_type | Yes | Issue type: Story, Task, Bug, Sub-task | |
| parent_key | No | Parent ticket key for Sub-task | |
| start_date | No | Start date YYYY-MM-DD | |
| original_estimate | No | Time estimate e.g. "2h" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond creation, such as permissions, side effects, or error cases.
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 concise sentence with no fluff, but it could benefit from slightly more detail for a tool with 10 parameters.
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, no annotations, and 10 parameters, the description is severely incomplete; it fails to explain return values, error conditions, or post-creation behavior.
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% (all 10 parameters have descriptions in the schema), so the description adds no additional parameter meaning; baseline 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 'Create a new Jira ticket' clearly states the verb (create) and resource (Jira ticket), distinguishing it from sibling tools like get_ticket or update_ticket.
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 on when to use this tool versus alternatives like update_ticket or transition_ticket; the description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate Markdown release notes for a fix version, grouped by issue type
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Limit to project key, e.g. "GEM" | |
| fix_version | Yes | Release version label, e.g. "v2.4" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks behavioral details. Does not state whether it is read-only, what happens if fix_version is invalid, any permissions needed, or side effects.
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?
Single sentence, efficient and front-loaded. No wasted words, but could potentially add more context without becoming verbose.
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?
No output schema, no annotations. Description omits details like scope of tickets included, required project, any filters applied. Incomplete for an agent to assess applicability.
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 covers both parameters with descriptions (100% coverage). Description adds grouping context but no deeper parameter meaning beyond schema.
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?
Clear verb 'Generate', specific resource 'Markdown release notes', and constraints 'for a fix version' and 'grouped by issue type'. Distinct from siblings which are CRUD and workflow actions.
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 on when to use this tool vs alternatives. No mention of prerequisites, when-not-to-use, or context like requiring an existing fix version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a Jira ticket by its key
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| include_comments | No | Include the ticket's comments (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It does not disclose behavioral traits beyond the action. It fails to mention that the operation is read-only, what 'full details' includes, or any rate limits/auth requirements.
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, front-loaded sentence with no wasted words. It directly conveys the tool's 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?
For a simple read tool with no output schema, the description adequately states the purpose but could mention the structure of returned data. Given the low complexity, it meets the minimum viable threshold.
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% with both parameters having descriptions. The description adds no extra meaning beyond the schema; it repeats 'by its key' for ticket_id but does not elaborate on include_comments. Baseline 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 action (get full details), the resource (Jira ticket), and the identifier (by its key). It distinguishes from sibling tools like search_tickets (search) and update_ticket (mutation).
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 explicit when-to-use or when-not-to-use guidance. The usage is inferable from the action name and siblings, but the description does not provide any context about alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a link between two Jira tickets
| Name | Required | Description | Default |
|---|---|---|---|
| link_type | No | Link type: Blocks, Clones, Relates to, Duplicate, etc. | Blocks |
| inward_issue | Yes | Issue key being linked FROM, e.g. GEM-1 | |
| outward_issue | Yes | Issue key being linked TO, e.g. GEM-2 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must fully convey behavioral traits. It only says 'Create a link' without disclosing whether the operation is idempotent, what happens if the link already exists, authorization requirements, or side effects.
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?
Extremely concise (one sentence, 9 words). It earns its place but lacks some behavioral detail. Slightly too sparse for optimal completeness.
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 and well-documented parameters via schema, the description is minimally adequate. However, missing behavioral context and usage guidance make it less complete.
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% with clear descriptions for each parameter (e.g., 'Issue key being linked FROM'). The tool description adds no extra meaning beyond the schema, so baseline 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 action ('Create a link') and the resource ('between two Jira tickets'). It distinguishes from sibling tools which deal with individual tickets (get, update, transition) or comments, not linking.
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 on when to use this tool versus alternatives. No mention of when not to use it, prerequisites, or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log work (time) on a Jira ticket, optionally setting WorklogPRO Type of Work and Type of Activity
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | Optional work log comment | |
| started | No | Start datetime ISO, e.g. '2026-06-29T09:00:00.000+0700' | |
| activity | No | Type of Activity (required when work_type is set): correct, create, review | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| work_type | No | Type of Work: code, deploy, design, fix, management, meeting, misc, operation, qa, req, research, translation | |
| time_spent | Yes | Time spent, e.g. '2h 30m', '1d', '45m' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as idempotency, permissions required, or side effects. It only states the basic action without deeper 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?
Single sentence, front-loaded with action, no superfluous words. Efficient and clear.
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?
Missing return value description and error handling context. For a mutation tool with no output schema, the description should explain what the response indicates (e.g., worklog ID), which is absent.
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 description adds limited value beyond parameter names and descriptions. The mention of WorklogPRO provides minimal extra context, but mostly restates schema info.
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 uses a specific verb ('log') and resource ('work/time on a Jira ticket'), clearly distinguishing it from sibling tools like add_comment or update_ticket.
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 on when to use this tool versus alternatives like add_comment or transition_ticket. The description does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Jira tickets using JQL query language
| Name | Required | Description | Default |
|---|---|---|---|
| jql | Yes | JQL query, e.g. 'project = GEM AND status = "In Progress"' | |
| max_results | No | Max results to return (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks any behavioral details such as pagination behavior, error handling, authentication requirements, or rate limits. Only states the obvious 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?
Single sentence, concise and front-loaded. However, it sacrifices informational value for brevity.
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?
Simple tool with 2 parameters and no output schema, but description fails to mention return format, sorting, or any constraints. Missing key behavioral context.
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 covers 100% of parameters with descriptions (e.g., jql with example, max_results with default). Description adds no additional meaning beyond what schema already 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?
Description clearly states verb 'Search', resource 'Jira tickets', and method 'JQL query language'. Distinguishes from sibling tools like get_ticket (single retrieval) and add_comment (add operation).
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 on when to use this tool vs alternatives like get_ticket for individual tickets, or when JQL is appropriate. No exclusion criteria or context provided.
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 ticket by status name
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Target status name, e.g. "In Progress", "Done" | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It fails to state whether the transition is irreversible, if it triggers notifications, how invalid transitions are handled (error or no-op), or if authorization is needed. The minimal phrase 'change the status' implies mutation but provides no safety or side-effect context.
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 function. There is no fluff or repetition. However, it could be slightly expanded with a use-case hint without harming conciseness.
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 simple 2-parameter tool with no output schema, the description covers the basic purpose. However, it lacks information about valid status values (e.g., are they restricted to workflow transitions?), error handling, or idempotency. The lack of annotations amplifies this gap.
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%, with both parameters having clear descriptions ('Target status name' and 'Jira issue key') and examples. The description adds no additional meaning beyond the schema, so 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 action ('Change the status') and the resource ('a Jira ticket') with the method ('by status name'). It distinguishes itself from siblings like 'update_ticket' by specifying the exact operation on status. However, it could be more explicit about being a state transition (e.g., 'transition a ticket to a new status using the workflow'), but it's still clear.
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. For example, it doesn't mention that 'update_ticket' might be more appropriate for other field changes, or that transitions depend on workflow rules. The agent is left to infer usage from the purpose alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields of a Jira ticket. Converting between a standard issue type and Sub-task is a Jira REST API limitation — use Jira's UI "Move" action instead.
| Name | Required | Description | Default |
|---|---|---|---|
| labels | No | Labels to set | |
| summary | No | Replace ticket summary/title | |
| assignee | No | Username to assign, or empty string to unassign | |
| due_date | No | Due date YYYY-MM-DD | |
| priority | No | Priority name, e.g. "High", "Medium", "Low" | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| issue_type | No | Issue type: Story, Task, Bug, Sub-task | |
| parent_key | No | Parent ticket key for Sub-task | |
| start_date | No | Start date YYYY-MM-DD | |
| description | No | Replace full description | |
| original_estimate | No | Time estimate e.g. "2h", "1d 4h" | |
| implementation_notes | No | Append implementation notes to description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only mentions the issue type conversion limitation. Other important traits like whether updates are additive or replace, permission requirements, and side effects are not addressed.
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?
Two sentences: first states purpose, second warns about a critical limitation. Front-loaded and no redundant 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?
The tool has 12 parameters and no output schema or annotations. The description lacks essential behavioral context (e.g., whether updates are incremental or full replacements, required permissions) and does not explain return values or error handling.
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 baseline is 3. Description adds no extra parameter meaning beyond the schema. It does not clarify behavior for fields like labels (replace vs append) or interaction between parameters.
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 'Update fields of a Jira ticket', which is a specific verb+resource. It implicitly distinguishes from sibling tools like transition_ticket (status changes) and get_ticket (read).
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?
Only minimal guidance: warns about the issue type conversion limitation and suggests using the UI 'Move' action instead. No explicit guidance on when to use this tool versus siblings like transition_ticket or create_ticket.
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.
v2.2.0create_ticket1 field changedInput schema / properties / assigneeAdded value: +{
+ "description": "Assignee username, e.g. username",
+ "type": "string"
+}get_ticket1 field changedInput schema / properties / include_commentsAdded value: +{
+ "description": "Include the ticket's comments (default false)",
+ "type": "boolean"
+}log_work3 fields changedInput schema / properties / activityAdded value: +{
+ "description": "Type of Activity (required when work_type is set): correct, create, review",
+ "type": "string"
+}Input schema / properties / started / descriptionPrevious value: -"Start datetime ISO format, e.g. '2026-06-29T09:00:00.000+0700'. Defaults to now."New value: +"Start datetime ISO, e.g. '2026-06-29T09:00:00.000+0700'"Input schema / properties / work_typeAdded value: +{
+ "description": "Type of Work: code, deploy, design, fix, management, meeting, misc, operation, qa, req, research, translation",
+ "type": "string"
+}search_tickets2 fields changedInput schema / properties / max_results / defaultPrevious value: -50New value: +25Input schema / properties / max_results / descriptionPrevious value: -"Max results to return (default 50)"New value: +"Max results to return (default 25)"v1.2.0update_ticket1 field changedInput schema / properties / priorityAdded value: +{
+ "description": "Priority name, e.g. \"High\", \"Medium\", \"Low\"",
+ "type": "string"
+}v1.1.1add_commentcreate_ticketgenerate_release_notesget_ticketlink_issueslog_worksearch_ticketstransition_ticketupdate_ticketScored across 9 tools
Each tool has a clearly distinct purpose: get, transition, update, comment, search, create, release notes, link, and log work. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_ticket, add_comment, link_issues). No deviations.
9 tools cover core Jira ticket operations without being excessive. The count is well-scoped for the server's purpose.
Covers create, read, update, transition, search, comments, linking, release notes, and work logging. Missing delete ticket is a minor gap.
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 AI agents access to form submissions — read, search, update, and process file attachments.
