Jira MCP is an MCP server that lets an AI assistant read and write Jira Server/Data Center tickets (REST API v2) via a set of tools.
Read tickets: get_ticket fetches full ticket details (comments, worklogs, attachment names, and image attachments as viewable images, all opt-in); get_comment fetches a single comment cheaply.
Search: search_tickets runs JQL queries with adaptive, token-efficient output.
Create/update tickets: create_ticket opens new issues (summary, project, type, assignee, dates, estimates, labels, parent); update_ticket changes summary, description, assignee, priority, dates, labels, estimation, epic link, parent, and appends implementation notes.
Transition status: transition_ticket changes a ticket's status name/alias-aware across workflows.
Comments: add_comment, update_comment, delete_comment.
Worklogs: log_work (with optional WorklogPRO Type of Work/Activity), update_worklog, delete_worklog.
Issue linking: link_issues and unlink_issues (Blocks, Clones, Relates, etc.).
Watchers: add_watcher, remove_watcher.
Agile/sprints: move_to_sprint moves tickets into active/future sprints by name or ID.
Release notes: generate_release_notes produces Markdown notes grouped by issue type for a fix version.
Jira Server plain-text descriptions, configurable custom fields (start date, epic link), timezone, retries on transient failures, and credentials via JIRA_HOST/JIRA_USERNAME/JIRA_PASSWORD.
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. Run the command in a regular terminal, not inside a Claude Code session. Pick the block for your shell, since each one continues lines differently.
bash / zsh (macOS, Linux, Git Bash or WSL on Windows):
claude mcp add g-jira-mcp \
-e JIRA_HOST="https://jira.company.com" \
-e JIRA_USERNAME="your_username" \
-e JIRA_PASSWORD="your_password" \
-- npx -y g-jira-mcp@latestPowerShell (Windows):
claude mcp add g-jira-mcp `
-e JIRA_HOST="https://jira.company.com" `
-e JIRA_USERNAME="your_username" `
-e JIRA_PASSWORD="your_password" `
-- npx -y g-jira-mcp@latestCommand Prompt (cmd.exe): put the whole command on one line, or end each line with ^ instead of \.
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; for a single comment use |
|
| 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 |
|
| Replace the text of an existing comment (IDs come from |
|
| Delete a comment from a Jira ticket (cannot be undone) |
|
| Get one comment by ID, e.g. from a focusedCommentId link; cheaper than get_ticket |
|
| Log work (time) on a Jira ticket, optionally setting WorklogPRO Type of Work and Type of Activity |
|
| Edit a worklog's time, start or comment (IDs come from |
|
| Delete a worklog from a Jira ticket (cannot be undone) |
|
| Create a link between two Jira tickets |
|
| Remove a link between two Jira tickets (either direction) |
|
| Add a user as a watcher of a Jira ticket |
|
| Remove a user from the watchers of a Jira ticket |
|
| Move tickets into an active or future sprint |
|
| 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. Each comment line starts with its ID (#10001), which update_comment and delete_comment take.
get_ticket lists attachment file names in an Attachments: line whenever the ticket has any. Pass include_images=true to also receive image attachments (PNG, JPEG, GIF, WebP) as MCP image content, so the caller can see screenshots referenced as !image.png! in the description or comments. Images are off by default because each one costs far more tokens than the text. At most 5 images are returned by default (raise it with image_limit, up to 20), each up to about 3.7 MB and about 7.5 MB in total, so the response stays inside Claude's vision limits (5 MB base64 per image on Bedrock and Google Cloud, 32 MB per request). Images are sent as-is; the model API downscales large ones itself. Each image costs one extra download request; an Images: section maps [image N] to its file name, reports each skipped image with its reason (too large or total size cap reached), reports failed downloads, and when image_limit is hit, says how many images were left out. Raising image_limit brings back only images that hit the count limit; images skipped for size will not reappear.
get_comment returns a single comment as #id [date] author: body. Pass include_images=true to fetch and return only the image attachments that comment embeds via !filename.png! or !filename.png|width=…! markup (by contrast, get_ticket returns all images on the ticket). Fetching attachments costs one extra request only when the comment embeds something. Images follow the same per-image and total size limits as get_ticket, up to 20 max. Use get_comment instead of get_ticket for ?focusedCommentId= links, or when only a single comment matters.
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'.
move_to_sprint takes a sprint name or numeric ID. A name is looked up among the active and future sprints of the scrum boards of the first ticket's project (Agile API, /rest/agile/1.0); if it matches none, or several, nothing is moved and the error lists the open sprints with their IDs. To list a sprint's tickets, use search_tickets with JQL such as sprint = "GEM Sprint 12" or sprint in openSprints().
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). If work_type or activity is set and the WorklogPRO form is unavailable, nothing is logged and the call fails (safe to retry); it never falls back to REST, which cannot set those attributes. A failed form submit is an error and is never retried, because the worklog may already exist. Start times are interpreted in the Jira server timezone (configurable via JIRA_TIMEZONE).
get_ticket with include_worklogs=true appends the ticket's worklogs, each line starting with its ID (#20001), which update_worklog and delete_worklog take. This costs one extra request (GET /issue/{key}/worklog), capped at the 20 most recent like comments. log_work returns no ID when it goes through the WorklogPRO form, so this is where to find it. update_worklog edits time, start and comment over REST only; to change Type of Work or Type of Activity, delete the worklog and log it again with log_work.
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 rsbuild
pnpm lint # biome check + tsc + prettier (markdown)
pnpm release # release-it: bumps version, commits, tags, pushes (runs lint + build first, no pre-commit needed)Questions 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.
Add a user as a watcher of a Jira ticket
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Jira username to add | |
| 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 the full behavioral burden for a mutation tool. It does not say whether adding an existing watcher is idempotent or errors, what permissions are required, or whether notifications are triggered — all material for a write operation.
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?
A single front-loaded sentence with zero filler. It is appropriately terse for a simple two-parameter tool, though there was room to fold in one clause of behavioral context at little cost.
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 is simple, fully required parameters are documented in the schema, and no output schema exists, so little is strictly missing. However, for a mutation with no annotations, the absence of permission/idempotency guidance leaves the definition only minimally viable.
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%: both username and ticket_id already carry descriptions, including the format example 'GEM-234'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Add) and resource (a user as watcher of a Jira ticket), so the action is unambiguous. It does not explicitly name or contrast with its natural sibling remove_watcher, but the verb+object pairing makes the direction of the operation obvious.
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 gives no context on when to use this versus remove_watcher or any other tool, and it omits prerequisites such as whether the caller needs permission to modify watchers or whether the user must already exist in Jira. Usage must be entirely inferred.
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.
Delete a comment from a Jira ticket. This cannot be undone. Comment IDs are shown by get_ticket with include_comments.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| comment_id | Yes | Comment ID, e.g. 10001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, and it does disclose the most important trait: the deletion 'cannot be undone'. It does not mention required permissions, error behavior on invalid IDs, or side effects, but the irreversibility warning is the critical disclosure for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and immediately followed by the irreversible-destruction warning. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity 2-parameter destructive tool with no annotations and no output schema, the description covers purpose, danger, and ID sourcing. It could add permission requirements or failure behavior to be fully complete, but nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real value by telling the agent where comment_id values come from (get_ticket with include_comments). That is information the schema's 'Comment ID, e.g. 10001' does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Delete) and resource (a comment from a Jira ticket), which cleanly separates it from the sibling add_comment and update_comment tools. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the destructive nature rather than stated; there is no when/when-not guidance versus update_comment or alternatives. The pointer to get_ticket with include_comments is a helpful prerequisite but is framed around obtaining an ID, not around when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a worklog from a Jira ticket. This cannot be undone. Worklog IDs are shown by get_ticket with include_worklogs.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| worklog_id | Yes | Worklog ID, e.g. 20001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, but it does disclose the most important trait: 'This cannot be undone.' It omits permission/auth requirements, behavior when the worklog_id is invalid or already deleted, and any error/response shape, leaving real gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with zero waste: the action leads, the irreversibility warning follows immediately, and the ID-source hint closes. Nothing is padded or repeated.
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 two-parameter, no-output-schema delete tool, the description covers action, irreversibility, and prerequisite ID source. It is close to complete, with only permission/error semantics left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description adds value beyond the schema by explaining how to obtain worklog_id via get_ticket. It does not clarify the ticket_id format beyond the schema's own example.
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?
Specific verb+resource ('Delete a worklog from a Jira ticket') that cleanly separates it from update_worklog, log_work, and delete_comment. The scope (deleting an existing worklog, not the ticket) is unambiguous.
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?
Tells the agent where the required worklog_id comes from ('shown by get_ticket with include_worklogs'), which is genuine routing guidance toward a sibling. It does not, however, discuss when not to delete or contrast with update_worklog for corrections.
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 | |
| image_limit | No | Max images to return with include_images (default 5, max 20); the total size cap still applies | |
| include_images | No | Return image attachments (screenshots referenced as !name.png! in the description/comments) as viewable images (default false) | |
| include_comments | No | Include the ticket's comments (default false) | |
| include_worklogs | No | Include the ticket's worklogs with their IDs (default false, one extra request) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, and it does almost none of it. It says 'full details' without clarifying that comments, worklogs, and images are excluded by default and cost extra requests, nor does it state that the operation is a safe read. 'Full details' is if anything slightly misleading given the default-excluded sections.
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?
A single front-loaded sentence with zero padding; the required key is prioritized. It is efficient, though its brevity is part of why the behavioral gaps exist.
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 five-parameter retrieval tool with no annotations and no output schema, the description is barely minimum viable. The schema covers parameter mechanics, but nothing signals that optional sections (comments, worklogs, images) are off by default, which an agent should know before assuming it has complete ticket content.
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% with all five parameters documented in the schema, including defaults for include_comments, include_worklogs, include_images, and image_limit. The description adds only the emphasis on the required key, so the baseline 3 applies.
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 states a specific verb and resource ('Get full details of a Jira ticket') and pins the lookup key ('by its key'), so an agent knows exactly what this tool retrieves. It does not explicitly distinguish itself from the read-oriented sibling search_tickets, which keeps it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus search_tickets (bulk/query retrieval) or how it relates to the update_* siblings. The agent is left to infer that this is the single-ticket fetch, with no stated exclusions 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.
Move Jira tickets into an active or future sprint, by sprint name or ID
| Name | Required | Description | Default |
|---|---|---|---|
| sprint | Yes | Sprint name (e.g. "GEM Sprint 12") or numeric sprint ID | |
| ticket_ids | Yes | Issue keys to move, e.g. ["GEM-1", "GEM-2"] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only discloses the sprint-state constraint. It does not say whether moving a ticket already assigned to another sprint overwrites it, what permissions are required, whether the operation is idempotent, or how failures on individual tickets are reported.
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?
A single tight sentence with the verb and destination front-loaded and zero filler. Every clause earns its place.
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 operation is low-complexity (2 fully documented params, no nesting), so the schema does most of the work. Still, as a mutation with no annotations and no output schema, the description leaves side effects (overwriting existing sprint assignment, partial failure handling) unexplained.
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 both parameters (sprint, ticket_ids) are already fully documented with examples. The description's "by sprint name or ID" merely restates the schema's sprint field and adds no new syntax or format detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ("Move"), resource ("Jira tickets") and destination ("active or future sprint"), which is precise and actionable. No sibling tool touches sprints, so no sibling differentiation is needed or given; the scope constraint (active/future only) adds useful precision.
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 phrase "active or future sprint" implies when the tool applies (not closed sprints), giving implied usage guidance. However, it never states prerequisites (e.g., board/sprint membership, permissions) or when to use this versus update_ticket/transition_ticket, so guidance remains incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a user from the watchers of a Jira ticket
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Jira username to remove | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state what happens when the user is not currently a watcher, whether the operation is idempotent, what permissions are required, or what the response indicates.
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?
A single front-loaded sentence with no filler. Every word earns its place and the action is immediately 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?
For a simple two-parameter mutation with a fully documented schema and no output schema, the description is minimally viable. It omits error/edge-case behavior (user not a watcher, invalid ticket) that an agent would benefit from knowing before calling.
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 documented in the schema (including the GEM-234 issue-key format), so the schema does the heavy lifting. The description adds no format or constraint detail beyond that, making 3 the correct baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (remove) and resource (user from watchers of a Jira ticket), which is unambiguous. It implicitly distinguishes itself from the sibling add_watcher via the verb, but never names or contrasts that sibling explicitly.
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 gives no when-to-use context, no prerequisites, and no alternates (e.g. add_watcher for the inverse). Usage is only inferable from the verb itself, which is minimal guidance.
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 a Jira ticket's status. Matches the transition name or its target status; common aliases (Closed/Resolved -> Done, Reopen -> Re-Open) resolve to whatever the workflow offers. Valid options vary per issue and are listed in the error when no match is found.
| 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 carries the full behavioral burden. It usefully discloses alias resolution and the error-carries-valid-options contract, but says nothing about permissions, side effects like notifications, or whether the transition is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, and each sentence contributes (core purpose, matching rules, error contract). No padding, though the alias parenthetical is slightly dense.
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 two-param mutation with no annotations and no output schema, the description covers argument resolution and error recovery but omits preconditions and post-state effects. Adequate to invoke, incomplete for understanding consequences.
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 already 100%, but the description goes beyond it by defining that 'status' may be a transition name or a target status and that aliases (Closed/Resolved -> Done) are accepted. That matching semantics is not derivable from the schema's 'Target status name' text, so it adds real value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Change a Jira ticket's status'), which cleanly separates it from the generic update_ticket sibling. It stops short of naming that sibling explicitly, so the differentiation is implied rather than spelled out.
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?
Explains how the status argument is matched (transition name or target status, with alias fallback) and that valid options surface in the error, which is genuinely useful retry guidance. However, it never says when to prefer this tool over update_ticket for status changes, so alternative selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a link between two Jira tickets. Direction does not matter. If several links connect them, pass link_type to pick one.
| Name | Required | Description | Default |
|---|---|---|---|
| link_type | No | Link type name or verb, e.g. "Blocks", "Relates", "is bug of" | |
| ticket_id | Yes | Jira issue key, e.g. GEM-1 | |
| linked_ticket_id | Yes | The other issue key, e.g. GEM-2 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that link direction is irrelevant and that multiple links can coexist, but says nothing about permissions, error behavior for nonexistent links, or whether only the matching link type is removed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action, then the two behavioral caveats. No filler or redundancy.
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 three-parameter tool with full schema coverage and no output schema, the description covers the essential action and the multi-link case. Minor gaps remain around failure modes and permissions, but nothing an agent needs to invoke it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: link_type is optional and only needed when several links connect the two issues, which the schema's 'Link type name or verb' text does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Remove a link between two Jira tickets.' The inverse relationship to the sibling link_issues is inferable, but the description never names or contrasts that sibling explicitly, so it falls short of the top 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?
Usage is only implied by the operation itself. It explains the link_type disambiguation case ('If several links connect them, pass link_type to pick one') but gives no guidance on when to use this versus link_issues or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the text of an existing comment on a Jira ticket. Comment IDs are shown by get_ticket with include_comments.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | New comment text (plain text) | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| comment_id | Yes | Comment ID, e.g. 10001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Replace the text' usefully discloses overwrite semantics (vs. appending), which the name update_comment alone does not convey. It still omits permissions required, reversibility, and error behavior for a mutation tool, leaving material 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?
Two short sentences, no filler, with the core action front-loaded and the ID-sourcing note appended. Every sentence earns its place.
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 three-required-parameter mutation with no output schema and no annotations, the description covers the action and how to source an ID. It does not address permissions, what happens to existing content/metadata, or failure modes, so it is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only adds that comment IDs come from get_ticket with include_comments, a small sourcing hint that does not change the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Replace) and resource (text of an existing comment on a Jira ticket), which cleanly separates it from add_comment and delete_comment in the sibling list. It does not name any sibling explicitly, so it earns a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence tells the agent where to obtain comment_id (from get_ticket with include_comments), which is genuinely useful invocation guidance. However, it gives no when-to-use/when-not guidance and does not contrast it with update_ticket or add_comment, so it stays at implied-usage level.
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 | |
| epic_key | No | Epic ticket key to set as this issue's Epic Link (shows under the Epic's "Issues in Epic" panel, not Linked Issues) | |
| 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?
With no annotations, the description carries the full burden. It discloses one meaningful behavioral trait: the REST API limitation around Sub-task conversion and the recommended workaround. It says nothing about permissions, whether unspecified fields are left untouched, or other side effects of an update.
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, front-loaded with the core action and followed by the most valuable caveat. No filler or restatement of the title, though it is arguably too terse for a 13-parameter mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description is the only place behavioral context could live, and it covers only the Sub-task caveat. For a 13-param mutation tool the coverage is thin, though the exhaustive schema mitigates the parameter side.
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 every one of the 13 parameters is already documented in the schema (formats like YYYY-MM-DD, empty string to unassign, epic_key semantics). The description adds no parameter-level meaning beyond that, so the baseline 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 states a specific verb and resource ("Update fields of a Jira ticket"), so the agent immediately knows this is a mutating tool for existing issues. It does not explicitly differentiate itself from siblings like transition_ticket, but the scope is unambiguous.
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?
It gives one concrete exclusion — issue-type conversion between standard and Sub-task must be done via Jira's UI — which is genuinely useful. However, it offers no guidance on when to reach for this versus transition_ticket (status changes) or add_comment, which is the most likely sibling confusion for a ticket-mutation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a worklog's time, start or comment. Worklog IDs are shown by get_ticket with include_worklogs. To change Type of Work/Activity, delete the worklog and log_work again.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | New worklog comment | |
| started | No | Start datetime ISO, e.g. '2026-06-29T09:00:00.000+0700' | |
| ticket_id | Yes | Jira issue key, e.g. GEM-234 | |
| time_spent | No | Time spent, e.g. '2h 30m', '1d', '45m' | |
| worklog_id | Yes | Worklog ID, e.g. 20001 |
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 does disclose one genuinely non-obvious trait — that Type of Work/Activity is immutable here and requires delete-plus-re-log — but says nothing about permission requirements, whether omitted fields are left unchanged (partial vs. full replace), or reversibility of edits.
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 tight sentences with zero filler; the core capability is front-loaded and the ID-sourcing hint and immutability caveat follow in priority order.
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 definition covers the edit scope and one key constraint but omits partial-update semantics, required permissions, and what a successful response contains. Adequate to invoke, incomplete to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters including ticket_id and worklog_id already carry examples and formats. The description names the editable fields but adds no syntax or format detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Edit) plus the exact mutable fields (time, start, comment) on a named resource (worklog), and implicitly separates itself from log_work (creation) and delete_worklog by describing the delete+re-log path for Activity changes. An agent can distinguish it from all four worklog/comment siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete routing: worklog IDs come from get_ticket with include_worklogs, and it explicitly names the alternative (delete_worklog + log_work) for the one case this tool cannot handle. It stops short of stating prerequisites like edit permissions or whether the caller must own the worklog.
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.7.0add_watcherdelete_commentdelete_worklogget_ticket1 field changedInput schema / properties / include_worklogsAdded value: +{
+ "description": "Include the ticket's worklogs with their IDs (default false, one extra request)",
+ "type": "boolean"
+}move_to_sprintremove_watcherupdate_commentupdate_worklogv2.6.0get_ticket2 fields changedInput schema / properties / image_limitAdded value: +{
+ "description": "Max images to return with include_images (default 5, max 20); the total size cap still applies",
+ "maximum": 20,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / include_imagesAdded value: +{
+ "description": "Return image attachments (screenshots referenced as !name.png! in the description/comments) as viewable images (default false)",
+ "type": "boolean"
+}unlink_issuesupdate_ticket1 field changedInput schema / properties / epic_keyAdded value: +{
+ "description": "Epic ticket key to set as this issue's Epic Link (shows under the Epic's \"Issues in Epic\" panel, not Linked Issues)",
+ "type": "string"
+}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 17 tools
Each tool targets a distinct resource and action (e.g., add_comment vs update_comment vs delete_comment; log_work vs update_worklog vs delete_worklog). The only potential overlap is update_ticket vs transition_ticket, but descriptions clearly separate field updates from status changes.
All tools follow a consistent snake_case verb_noun pattern (get_ticket, create_ticket, add_comment, delete_worklog, etc.). Minor variations like move_to_sprint and generate_release_notes remain readable and do not break the overall convention.
17 tools is slightly above the typical 3-15 range, but each tool covers a necessary Jira operation with no obvious redundancy. The count is justified by the breadth of ticket management tasks.
The set covers core ticket lifecycle operations (create, read, update, search, transition, comments, worklogs, watchers, links) but lacks delete_ticket and some project/sprint management functions. Agents can work around most gaps using JQL and existing tools.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Helpdesk tickets from your AI: find, reply, take, hold, complete — within your own role. OAuth.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Search tickets, people, organizations and KB articles in Deskpro, and create tickets and replies.