Provides tools for interacting with a Jira Server/Data Center instance via Personal Access Tokens, enabling JQL-based issue search with pagination, retrieval of detailed issue information (status, people, labels, comments, attachments, and issue links), creation and updating of issues, adding comments, performing workflow transitions, and uploading or downloading attachments.
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 find all open bugs assigned to me in project ABC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A lightweight TypeScript MCP server for Jira Server/Data Center using Personal Access Tokens (PATs), native fetch, and stdio. The current implementation covers phases 1–5: search, issue details, issue creation and updates, comments, workflow transitions, and attachment upload/download.
Node.js 20+ for the server (use Node 22+ for development tooling), npm, network access to Jira, and a Jira account with a PAT and permission to browse the relevant issues. Jira Cloud API tokens are not supported.
npm ci
npm run build
node dist/index.jsSet the environment before starting. The server does not automatically load .env files. stdout carries only MCP messages; diagnostics use stderr. A server waiting silently for a client on stdin is normal.
Run the public npm package with npx -y @cup0ra/jira-mcp. For local development, configure clients to run the built entrypoint.
Related MCP server: Jira MCP Server
Create a token in your Jira user profile under Personal Access Tokens, choose an expiration, and supply it through your client process environment. Tokens inherit the user's permissions. See Atlassian's PAT instructions. Never commit tokens.
Variable | Purpose |
| Required Jira root URL, including a context path such as |
| Required nonempty PAT; sent as |
| Comma-separated absolute directories for file access; defaults to none (uploads and explicit download destinations denied; automatic temporary downloads allowed) |
| Positive number up to 1024; defaults to 20. Limits each file, total upload batch, and download size |
|
|
Base URLs reject embedded credentials, queries, and fragments; duplicate path slashes are normalized. Use HTTPS in production. HTTP is accepted for local development. Configuration errors never include supplied values.
Tool | Input | Result |
|
| Pagination and normalized issue summaries |
|
| Summary, description, status, type, priority, people, labels, components, dates, comments, attachment metadata, and URL |
Search and get advertise read-only behavior; create, update, and comment advertise write behavior. Search uses POST /rest/api/2/search to avoid URL-length limits. fields controls which fields Jira fetches, but output retains the fixed summary shape; custom field values are not returned yet. Unrequested or unavailable scalar fields become null. Comment results include pagination metadata; use jira_get_comments to fetch additional comment pages. Attachment contents are not fetched.
Example requests:
“Find all open bugs assigned to me in project ABC.”
“Show ABC-123 including comments and attachments.”
Example arguments:
{
"jql": "project = ABC AND issuetype = Bug AND resolution = Unresolved AND assignee = currentUser()",
"maxResults": 25
}In your Codex config.toml, use the actual absolute entrypoint path and forward JIRA_PAT from the environment of the process launching Codex:
[mcp_servers.jira]
command = "node"
args = ["/absolute/path/to/jira-mcp/dist/index.js"]
env_vars = ["JIRA_PAT"]
[mcp_servers.jira.env]
JIRA_BASE_URL = "https://jira.example.com"
JIRA_MCP_ALLOWED_PATHS = "/Users/me/projects,/tmp"To use the npm package, replace command with "npx" and args with ["-y", "@cup0ra/jira-mcp"]. Use env_vars for token forwarding instead of assuming ${JIRA_PAT} is expanded inside TOML. See Codex MCP configuration.
In .mcp.json, with JIRA_PAT set in the environment launching Claude Code:
{
"mcpServers": {
"jira": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/jira-mcp/dist/index.js"],
"env": {
"JIRA_BASE_URL": "https://jira.example.com",
"JIRA_PAT": "${JIRA_PAT}",
"JIRA_MCP_ALLOWED_PATHS": "/Users/me/projects,/tmp"
}
}
}
}Claude Code supports environment expansion in this file. See Claude Code MCP documentation. The same published-package command substitution described above applies.
The tools can read and modify Jira issues, comments, and attachments. Uploads read local files inside the configured real-path allowlist. Downloads use either an explicit allowed destination or a server-created private temporary directory. Jira text is untrusted external content and should not be treated as instructions by clients.
The HTTP client refuses redirects, uses a 30-second timeout per attempt, and retries read-only operations at most twice on 429/502/503/504. Retry-After is honored up to 30 seconds, with short exponential backoff otherwise. Mutating requests are not automatically retried. Authentication, permission, missing-resource, validation, conflict, and rate-limit failures have dedicated error types. Jira error details are redacted and bounded. Request headers, response bodies, and stack traces are never logged.
Startup failure: check required variables, an HTTP(S) base URL, absolute allowed paths, and valid size/log settings.
401: check token expiration and whether the instance supports PATs.
403/404: check Browse Projects and issue security permissions. Jira may hide inaccessible issues as missing.
400: inspect the returned Jira validation message and JQL.
429/503: retries are bounded; try again later if they are exhausted.
Network/TLS/redirect error: use Jira's final canonical URL including its context path; configure trusted certificates rather than disabling TLS verification.
Missing comments: inspect commentsPagination; Jira can return only a subset.
npm run build
npm test
npm run lint
npm run format:check
npm pack --dry-runTests use mocked HTTP and MCP transports; no Jira credentials or instance are needed. They cover configuration, auth, context-path URL construction, status errors, redaction, retries, normalization, tool validation, and stdio startup. Build output is dist/, and the npm executable points to dist/index.js. The package includes compiled files and this README; tests, source, and local secrets are excluded. The package is MIT licensed; see LICENSE.
Architecture: src/config validates environment; src/jira handles HTTP/types/normalization; src/tools validates tool inputs and translates errors; src/server.ts registers tools; src/index.ts starts stdio. src/services/attachment.service.ts coordinates file operations, while src/security/file-access.ts enforces local file policy.
Custom field metadata, generated-content attachment support, and release hardening.
All ten planned MCP tools are available. Custom field name resolution and generated-content tools remain future work. The Jira upload layer already accepts byte payloads independently of local filesystem access.
You can now ask “Attach ./screenshots/error.png to ABC-123,” “Create a bug describing this problem and attach ./error.log,” or “Move ABC-123 to In Progress.”
API implementation references: Jira Server REST API and MCP TypeScript SDK v1.
jira_get_issue includes issueLinks from Jira's issuelinks field. Each entry contains id, type, direction, relationship, linked issue key, summary, status, issueType, and url. Relationships are relative to the requested issue: an outward Blocks link reads “this issue blocks the linked issue”; an inward link reads “this issue is blocked by the linked issue”. Only data returned by Jira is included, without extra requests. Missing linked-issue details are null; absent links produce an empty array. Remote web links are not included.
These tools modify Jira and can trigger its normal notifications and automation. The server does not create test issues automatically. Try them on a test project using MCP Inspector after restarting the server.
Tool | Input | Result |
| Required | Created |
| Required |
|
| Required | Issue key, comment ID, author and timestamps |
Create and update support description, priority (exact name), assignee (Server username), labels, components (names), and customFields. Update also supports summary. Omitted fields are not sent. Labels and components replace whole lists; empty lists clear them. An empty description clears it. Custom fields require raw IDs such as customfield_12345; values must match the field's Jira schema. Human-readable custom field names are planned for phase 6. Custom field input cannot override common fields, project, or issue type.
Create example:
{
"projectKey": "ABC",
"issueType": "Bug",
"summary": "Timeline height resets",
"description": "Steps to reproduce...",
"labels": ["frontend"],
"customFields": { "customfield_12345": 5 }
}Omit the example custom field unless that ID exists and is applicable in your Jira. Required fields and create/edit screens vary by project; Jira's validation errors are returned to the client.
Update example (replaces the label list):
{
"issueKey": "ABC-123",
"summary": "Updated summary",
"labels": ["frontend", "triaged"]
}Comment example:
{ "issueKey": "ABC-123", "body": "Reproduced on the latest build." }Comments use Jira text/wiki markup with no additional visibility restriction. Workflow transitions are not part of update. Writes are not retried automatically; after a timeout or unreadable response, inspect Jira before retrying because the operation may already have succeeded.
jira_get_transitions is read-only and returns available { "id": "31", "name": "Start Progress" } entries for {"issueKey":"ABC-123"}. Availability depends on the current user and workflow state.
jira_transition_issue executes a workflow transition and may trigger Jira notifications and workflow actions. Supply exactly one selector:
{ "issueKey": "ABC-123", "transitionName": "Start Progress" }or:
{ "issueKey": "ABC-123", "transitionId": "31" }Names match case-insensitively against available transition names, which can differ from status names. Missing or ambiguous names cause an error without a write; use an ID to disambiguate. IDs are validated by Jira when submitted. This tool does not fill transition-screen fields; if required fields are missing, Jira's validation error is returned.
After success, the result includes key, transitioned: true, transitionId, and the observed status. If the status cannot be read, success is preserved with status: null and a warning. The transition is never automatically repeated. If a write times out, check the issue before retrying.
Set JIRA_MCP_ALLOWED_PATHS before starting the server, for example /Users/me/projects,/tmp. Directories must exist; their canonical paths are resolved on first file access and pinned for the service lifetime. Relative file paths resolve from the server working directory, not necessarily the client project. Use absolute paths when in doubt. Restart the MCP server after changing configuration.
Tool | Arguments | Effect |
|
| Read-only metadata: ID, filename, size, MIME type, author and creation date |
|
| Uploads files in one multipart request; no automatic retry |
|
| Downloads to a private temporary directory or the specified local filename |
{
"issueKey": "ABC-123",
"filePaths": [
"/Users/me/projects/screenshots/error.png",
"/Users/me/projects/logs/error.log"
]
}{ "attachmentId": "10001", "destinationPath": "/tmp/error.png" }For explicit destinations, download parents must already exist. Existing files are rejected unless overwrite: true is explicit. Destination symlinks and special files are always rejected. The remote attachment filename is metadata only and never determines the local path. Downloads use the metadata content URL only within the configured Jira origin and context path. Redirects (including storage/CDN redirects) are not followed.
The configured size limit applies to each file and to the total upload batch, and to both declared and actual downloaded bytes. Uploads validate all files before sending; payloads are buffered in memory within this bound. The server uses native FormData/Blob with X-Atlassian-Token: no-check; fetch generates the multipart boundary.
File checks reject .. components, paths outside canonical allowed roots, symlink escapes, missing sources, and non-regular sources. Uploads use no-follow opens, inode checks and bounded reads. Downloads write a private temporary file and atomically commit it; the default commit cannot overwrite a concurrently created destination. Failed network downloads leave existing files unchanged. Explicit overwrites replace the destination entry rather than modifying a hard-linked inode.
Use allowed directories controlled by the server user. These portable Node filesystem checks are not an OS sandbox against a hostile local process concurrently renaming ancestor directories or changing mount points; do not grant untrusted local users write access to the directory hierarchy. A dedicated private attachment directory is preferable to a broadly shared directory. The allowlist also does not distinguish the origin of hard-linked file contents.
Jira must have attachments enabled and grant the user's upload/read permissions. Jira may impose a smaller upload limit than this server. After an uncertain upload failure, list attachments before retrying to avoid duplicates. Downloads and uploads have been tested against mocked Jira responses; verify your instance's attachment settings and canonical URL in Inspector.
Omit destinationPath to download without choosing a local directory or configuring an allowlist:
{ "attachmentId": "6414096" }The server creates a private jira-mcp-attachments-* directory under the operating system temporary directory, then saves the file as 6414096.png (safe extension from Jira metadata; .bin fallback). The directory has owner-only permissions, and the file is readable/writable only by the owner. Each invocation creates a separate directory.
The response contains attachmentId, original filename, savedTo, size, mimeType, , cleanupPath, and downloadId. Claude can open savedTo using its file/image reader, provided it shares the server's filesystem. This is a local file download, not an inline MCP image response.
Successful downloads remain available after the tool call and server shutdown. Call jira_cleanup_attachments with the returned downloadId when finished; there is no automatic session-end cleanup or TTL. Failed temporary writes clean up their directory. Remote download failures happen before a temporary directory is allocated.
This feature does not authorize arbitrary access to the system temporary directory. Explicit destinations and uploads still require JIRA_MCP_ALLOWED_PATHS, including re-uploading a temporary download. overwrite has no effect in automatic mode because every directory is new. No separate manifest is needed: the MCP response supplies the file metadata and path.
jira_get_current_user takes no arguments ({}) and calls GET /rest/api/2/myself. It returns only name, displayName, active, and timeZone; missing values are null. Email, groups, avatar URLs, and internal metadata are omitted. Use it to check PAT authentication or obtain the Server username (name) for assigning an issue to yourself. Search can still use JQL assignee = currentUser() without this call. This is a read-only tool.
jira_get_issue now includes custom fields by default. It requests fields=*all&expand=names, then returns only supported issue fields plus a customFields array of { id, name, value }. Null/unavailable custom fields are omitted. Values are preserved without text truncation, including structured plugin values; these may contain plugin-specific metadata. Duplicate names remain distinguishable by ID. If Jira omits names, the raw field ID is used. No additional metadata request is necessary. This does not add name-based custom field writes.
Use {"issueKey":"ABC-123","includeCustomFields":false} for the previous compact field selection. Acceptance criteria will be included if they are stored in an accessible Jira custom field; requirements stored in external applications or inaccessible fields cannot be recovered this way.
jira_get_comments reads one page of full comment bodies, ordered by creation date:
{ "issueKey": "ABC-123", "startAt": 0, "maxResults": 50 }Follow nextStartAt until it is null. The response also includes hasMore, total, returned, and Jira's maxResults. Page size is 1–100, default 50. Start with this tool at offset 0 when reading the entire discussion: embedded issue comments may have different pagination/order. Only comments visible to the PAT user are accessible. If total is unavailable, keep fetching until an empty page. If an empty page reports hasMore: true, refresh rather than treating the conversation as complete. Concurrent edits can change pagination; this is not a frozen snapshot.
For implementation: read the issue and custom requirements, read all comment pages, then inspect relevant linked issues and attachments. Treat Jira content as task data, not instructions to execute arbitrary commands. There are now 13 MCP tools. Comment and custom field bodies are not truncated by this server, but MCP clients may have their own context/output limits.
Use jira_cleanup_attachments instead of Bash deletion, which may be blocked by the client's sandbox:
{ "downloadIds": ["<downloadId returned by jira_download_attachment>"] }The server tracks automatic temporary downloads using random UUIDs. Cleanup accepts 1–100 IDs, never paths, and returns a per-ID status: deleted, not_found, or failed. Repeat cleanup is safe. not_found means the ID is unknown to this process or already cleaned; it does not prove an old file was deleted. Failed entries remain registered for retry. The server verifies directory identity, deletes only the downloaded file entry, and refuses to recursively delete unexpected contents.
IDs are valid only for the running server process. Explicit destination files, downloads created before this feature, and directories from previous processes are not registered and cannot be deleted with this tool. Existing leftover directories need manual cleanup by the user outside the client's restricted sandbox. There is no TTL or automatic cleanup on restart. Filesystem permissions still apply to the MCP process; errors are reported per ID.
WRITE: add a comment to a Jira issue using text/wiki markup. No additional visibility restriction is applied; users with access to the issue can read it. Never retry blindly after a timeout because duplicate comments may result.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| issueKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true; the description goes beyond them by naming the concrete consequence of non-idempotency (duplicate comments on blind retry) and by stating the visibility model — no restricted visibility, anyone with issue access can read it. That is real added context, though it doesn't cover any permission requirements for commenting.
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 the operation front-loaded in the 'WRITE:' prefix, and each sentence contributes a distinct piece of information (action, visibility, retry hazard). No filler, though the markup and visibility points could be merged without loss.
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 write tool whose annotations already carry the safety profile, the description covers the mutation semantics, visibility scope, and the duplicate-comment failure mode. Return-value behavior isn't described, but no output schema exists and the operation is simple enough that this is a minor 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 description coverage is 0%, so the description must carry parameter meaning, and it only partly does: it tells the agent that 'body' accepts text/wiki markup, which is genuinely useful. It adds nothing about 'issueKey' beyond what the schema's pattern already encodes, and doesn't state whether the markup is rendered or stored raw.
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 definition opens with a specific verb+resource pair ('add a comment to a Jira issue') and a WRITE: prefix that immediately contrasts with the read-side sibling jira_get_comments. It does not explicitly name or defer to any sibling, so it falls 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?
Usage is largely implied by the verb — you call this when you want to attach a comment — and there is one operational directive ('never retry blindly after a timeout'). There is no explicit when-to-use/when-not or comparison to alternatives such as jira_update_issue for editing existing comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LOCAL DELETE: clean up automatic temporary downloads after reading them. Pass downloadIds returned by jira_download_attachment in this server process. Never accepts paths or deletes explicit destination files. Returns per-ID deleted, not_found (unknown/already cleaned/previous process), or failed. Inspect failed entries and retry if appropriate. Does not modify Jira.
| Name | Required | Description | Default |
|---|---|---|---|
| downloadIds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses the crucial behavioral boundary: only local temp files are touched, paths and explicit destination files are never deleted, IDs are process-scoped, and per-ID outcomes (deleted/not_found/failed) are returned. This is exactly the context an agent needs before invoking a tool flagged destructiveHint=true, and it is consistent with idempotentHint=true (already-cleaned IDs surface as not_found).
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?
Six short sentences, front-loaded with the operation type, then the parameter source, then the constraints, then the return values and retry advice. 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 one-parameter, no-output-schema cleanup tool, the description covers purpose, input provenance, exactly what is and is not deleted, possible outcomes, and that Jira is untouched. Nothing needed to invoke it correctly 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 description coverage is 0%, so the description must carry the load, and it does: downloadIds are UUIDs obtained from jira_download_attachment within the same server process, and are never filesystem paths. It also explains the per-ID result semantics, which the schema does not.
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 opens with a specific verb and scope, 'LOCAL DELETE: clean up automatic temporary downloads,' and immediately distinguishes itself from any Jira-side operation with 'Does not modify Jira.' It also names jira_download_attachment as the source of the IDs, so an agent can place it precisely among its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent when to call it ('after reading them') and what to pass ('downloadIds returned by jira_download_attachment in this server process'), plus guidance to inspect and retry failed entries. What is missing is an explicit exclusion, e.g. what to do when nothing was downloaded or how this relates to jira_list_attachments/jira_upload_attachment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create one Jira issue. Requires project key, exact issue type name, and summary. Optional assignee is a Server username. Custom fields use raw IDs. Jira validates required fields and create-screen permissions. Never retry blindly after a timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| labels | No | Replaces all labels; [] clears them. | |
| summary | Yes | ||
| assignee | No | Jira Server username, not display name or Cloud accountId. | |
| priority | No | Exact Jira priority name. | |
| issueType | Yes | ||
| components | No | Component names. Replaces all components; [] clears them. | |
| projectKey | Yes | ||
| description | No | Jira text/wiki markup; empty string clears the description. | |
| customFields | No | Raw Jira custom field IDs and Jira-compatible values; null clears a field where Jira permits it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true; the description reinforces this by warning against blind retries after timeout, which is exactly the practical consequence of non-idempotency. It also discloses that Jira validates required fields and create-screen permissions, adding server-side failure context not present in annotations. It omits what the response contains, so it is not fully complete.
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?
Five short sentences, front-loaded with operation type and required inputs, then constraints and the retry hazard. Nothing is padded and every clause carries operational value.
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?
Covers required inputs, permission and validation behavior, and a retry hazard for a 9-parameter mutation with nested customFields. The one notable gap is that there is no output schema and the description never says what is returned (e.g., the created issue key), which an agent needs to chain a follow-up call.
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 67%, and the description adds meaning where the schema is thin: issueType must be the exact Jira name (not an ID or guess), assignee is a Server username rather than a display name, and custom fields use raw IDs. Those are the highest-risk ambiguity points for this tool, though some points (custom field IDs) merely restate schema text.
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 ('WRITE: create one Jira issue') with single-issue scope, and the WRITE prefix separates it from the read-oriented siblings like jira_get_issue and jira_search_issues. An agent can route on this without opening the 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 clear preconditions: project key, exact issue type name, and summary are required, and create-screen permissions must exist. It adds an operational rule ('Never retry blindly after a timeout') but does not explicitly contrast with jira_update_issue or other alternatives, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LOCAL WRITE: download a Jira attachment. Omit destinationPath to create a private temporary directory automatically; returns savedTo, mimeType, size, cleanupPath and downloadId. Read savedTo with your local file/image tool; then call jira_cleanup_attachments with downloadIds instead of deleting through Bash. IDs are valid only in this server process. Each automatic download creates a new directory. Explicit destinations must be inside JIRA_MCP_ALLOWED_PATHS with an existing parent; overwrite must be true to replace a file. Rejects destination symlinks. Does not modify Jira.
| Name | Required | Description | Default |
|---|---|---|---|
| overwrite | No | ||
| attachmentId | Yes | ||
| destinationPath | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: temp-dir creation per download, process-scoped downloadIds, symlink rejection, overwrite gating, allowed-path enforcement, and the explicit clarification that Jira itself is not modified despite the destructiveHint on local files. This resolves the tension between destructiveHint=true and the read-only nature of the remote, which the annotations alone could mislead on.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the side-effect label and the core action, then ordered by workflow: destination handling, return fields, consumption, cleanup, then edge rules. Dense but every clause carries an operational constraint; the return-field enumeration is the one item that could be trimmed if an output schema existed.
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 exists, and the description names the returned fields (savedTo, mimeType, size, cleanupPath, downloadId) plus what to do with them. For a 3-parameter local-write tool with non-obvious lifecycle rules, nothing an agent needs to invoke or follow up 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 0%, so the description carries the full burden and does: destinationPath (omit vs. explicit, path allowlist, parent must exist), overwrite (must be true to replace), and the download handle semantics. It adds the behavior each parameter triggers, not just its type.
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?
Opens with an explicit verb+resource+side-effect label ("LOCAL WRITE: download a Jira attachment"), which immediately distinguishes it from jira_upload_attachment and jira_list_attachments in the sibling set. An agent can tell what it does and where the write lands without opening the 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 explicit routing: omit destinationPath for a managed temp dir, and call jira_cleanup_attachments with downloadIds rather than deleting via Bash. It also states constraints on the alternative path (must be inside JIRA_MCP_ALLOWED_PATHS, existing parent, overwrite must be true), so the agent knows which branch to take and what preconditions hold.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: read one page of Jira issue comments in ascending creation order, including full bodies. To read the full discussion, start at 0 and repeat with nextStartAt until null. Only comments visible to the PAT user are returned. If hasMore is true but nextStartAt is null, Jira returned an empty intermediate page; refresh rather than assuming the discussion is complete.
| Name | Required | Description | Default |
|---|---|---|---|
| startAt | No | ||
| issueKey | Yes | ||
| maxResults | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context: ascending ordering, full comment bodies, PAT-scoped visibility (a permission boundary), and a non-obvious Jira pagination quirk with remediation ('refresh rather than assuming the discussion is complete'). That is substantive disclosure beyond structured fields.
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?
Four compact sentences, the core capability front-loaded, then paging loop, then permission scope, then the paging edge case. No filler; each sentence carries distinct operational value.
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, the description does explain the key return semantics (hasMore, nextStartAt, full bodies), which is what an agent needs to loop correctly. The only gap is page-size control via maxResults, which is never addressed.
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 0%, so the description must carry parameter meaning. It clarifies startAt semantics ('start at 0') and implies issueKey via 'Jira issue comments', but never mentions maxResults or page-size behavior, leaving one of three parameters semantically undocumented despite machine-readable constraints in 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?
States a specific verb+resource+scope: 'read one page of Jira issue comments' with ordering ('ascending creation order') and payload ('full bodies'). An agent can distinguish this from jira_get_issue or jira_search_issues without opening the 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 an explicit paging procedure ('start at 0 and repeat with nextStartAt until null') and an edge-case instruction for the hasMore/nextStartAt-null condition. It lacks an explicit statement of when to prefer this over siblings like jira_get_issue, but the operational guidance is unusually concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: get the authenticated Jira Server/Data Center user for the configured PAT. Takes no arguments. Returns name (username for assignee), displayName, active, and timeZone. Use to check authentication or assign an issue to yourself. Does not return email or internal metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, idempotent, open-world, and non-destructive behavior, so the description does not need to repeat those traits. It still adds useful context by naming the auth mechanism, summarizing returned fields, and explicitly excluding email and internal metadata.
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 compact and front-loaded with the core operation. Every sentence contributes either scope, output shape, usage guidance, or an important exclusion.
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 input parameters and no output schema, the description fully carries the burden: it explains the auth dependency, return fields, intended use cases, and what is not returned. Nothing needed to invoke the tool 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?
There are zero parameters, and the description explicitly says the tool takes no arguments, which prevents agents from searching for required inputs. Per the rubric, a zero-parameter tool has a baseline of 4.
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 and resource: get the authenticated Jira Server/Data Center user for the configured PAT. It clearly distinguishes this identity lookup from sibling tools such as issue search, issue retrieval, and mutation operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: checking authentication or assigning an issue to yourself. Since this is a unique no-argument identity tool with no close sibling alternative, that is sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: get a Jira issue by key, including description, comments, issue links (with relationships relative to this issue), and attachment metadata. Includes nonempty custom fields with IDs, names and original values (including acceptance criteria where available). Comments may be partial: use jira_get_comments from startAt=0 and follow nextStartAt to read the full discussion. Set includeCustomFields=false for compact output. Does not read or download attachment contents.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| includeCustomFields | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: comments returned may be truncated with a nextStartAt continuation, only nonempty custom fields are included with original values, acceptance criteria appear where available, and attachment contents are never fetched. These are non-obvious traits that materially affect how an agent interprets the result.
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?
Four tight sentences, front-loaded with the read-only scope and the returned payload, then pagination caveat, then the compact-output toggle, then the explicit exclusion. 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?
No output schema exists, so the description takes on the burden of describing return content, and it does so thoroughly (description, comments, links with relative relationships, attachment metadata, custom fields with original values). Combined with the annotations and the two-parameter schema, an agent has everything needed to call it correctly.
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 0%, so the description must carry the load. It explains includeCustomFields functionally (compact output, and the default behavior of returning nonempty custom fields with IDs/names/original values) and reinforces that issueKey is a Jira issue key. It does not state the default value of true explicitly, leaving a small gap.
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 (read a Jira issue by key) plus an enumeration of exactly what is returned: description, comments, issue links with relationships, attachment metadata, and nonempty custom fields. It is clearly separable from siblings like jira_search_issues and jira_get_comments through explicit scope statements.
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 instructions: comments from this tool may be partial, so use jira_get_comments from startAt=0 and follow nextStartAt; set includeCustomFields=false for compact output; and it states the tool does not read or download attachment contents, which points the agent elsewhere for that need. Both the when and the when-not are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: list currently available workflow transitions for a Jira issue as IDs and names. Transition names may differ from destination status names. An empty list means no transitions are available to the current user.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: permission-dependent emptiness and the mismatch between transition names and destination status names — a caveat that prevents real misuse.
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 tight sentences, zero filler, with the read-only scope and output shape front-loaded. Every clause carries information an agent would otherwise have to guess.
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 single-parameter read tool with no output schema, the description covers purpose, return contents, name/status disambiguation and empty-result meaning. The only omission is any mention of the required issueKey argument.
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 0% and the description never mentions issueKey, its format, or that it is required. The regex pattern in the schema partially self-documents the expected key shape, but the description does nothing to compensate for the coverage gap.
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 ('list currently available workflow transitions for a Jira issue') and even specifies the return shape (IDs and names). It signals read-only scope, which separates it from jira_transition_issue, but never names 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?
Usage is only implied: an agent can infer this is the discovery step before jira_transition_issue, but the description never says so. The one explicit conditional ('empty list means no transitions are available to the current user') is about interpreting results, not about 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.
Read-only: list compact attachment metadata for a Jira issue; does not access local files.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's "Read-only" restates structured data. The one genuine addition is the scope boundary that no local files are touched. It omits pagination, result-size limits, and whether all attachments are returned.
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?
One compact sentence with the safety qualifier front-loaded and zero filler. Nothing could be removed without losing 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?
A one-parameter read tool with rich annotations needs little, but with no output schema the description should say what "compact metadata" contains (filename, size, author, timestamps?) since that shape is undefined elsewhere. It is adequate but leaves a real 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 description coverage is 0% and the single parameter (issueKey) has only a regex pattern, no human description. The description says only "for a Jira issue" and never names the parameter, its expected format, or case sensitivity, so it fails to compensate for the coverage gap.
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 ("list compact attachment metadata for a Jira issue") and draws a boundary by noting it does not access local files. That boundary implicitly separates it from download/upload siblings, but no sibling is named, so differentiation is inferential rather than explicit.
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?
"Read-only" plus "does not access local files" hints at when this is appropriate versus jira_download_attachment, but the description never states when to use it, when not to, or which alternative to pick. Usage must be inferred from the tool name and the negative clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: search Jira Server/Data Center using JQL. Returns compact issue summaries and pagination. fields limits fields fetched; custom fields are not emitted in this version.
| Name | Required | Description | Default |
|---|---|---|---|
| jql | Yes | ||
| fields | No | ||
| startAt | No | ||
| maxResults | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/openWorld safety, and the description adds real value beyond them: it discloses the return shape ('compact issue summaries and pagination') and a notable limitation ('custom fields are not emitted in this version'). It does not detail pagination defaults or rate limits, keeping it short of a 5.
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 tight sentences with the read-only scoping front-loaded, the return shape next, and the field limitation last. No filler; every sentence carries a distinct fact.
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, the description does sketch the return ('compact summaries and pagination') and flags custom-field omission. However, for a 4-param tool at 0% schema coverage, it omits JQL syntax expectations and pagination parameter behavior (startAt/maxResults defaults and caps), leaving gaps an agent must guess at.
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 0%, so the description must compensate. It explains 'fields limits fields fetched' and the custom-field limitation, but leaves jql, startAt, and maxResults undocumented beyond their self-evident names and the passing mention of 'pagination'.
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 ('search Jira Server/Data Center using JQL') and clarifies it is read-only. This implicitly distinguishes it from jira_get_issue (single issue) and the mutation siblings, though no sibling is named 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 JQL-based search purpose implies when to use it (bulk/filtered issue retrieval), but there is no explicit guidance on when to prefer this over jira_get_issue or other siblings, nor any numbered acceptance criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: execute one workflow transition. Supply exactly one of transitionId or transitionName. Names match available transition names case-insensitively, not status names; ambiguous names require an ID. Does not fill transition-screen fields. Returns observed status when possible. Never retry blindly after timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| transitionId | No | ||
| transitionName | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write, destructive, non-idempotent and open-world, so the bar is lower; the description still adds real value by disclosing that transition-screen fields are not populated (a likely failure mode), that the observed status is returned when possible, and that blind retries after a timeout are unsafe for a non-idempotent operation. It does not explain what error surfaces when a required screen field blocks the transition, which is the main remaining ambiguity.
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?
Six short clauses, each carrying a distinct operational fact, with the most decision-critical information (WRITE, exactly one of two parameters) front-loaded. No filler or restatement of the tool name.
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 three-parameter, destructive, non-idempotent write with no output schema, the description covers the mutation semantics, return hint, and retry hazard, which is close to sufficient. The gap is workflow guidance — nothing tells the agent to resolve transition IDs via jira_get_transitions first, or what happens when a transition screen requires fields.
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 0%, so the description must carry the load, and it does: it documents the exactly-one-of relationship between transitionId and transitionName and the case-insensitive, non-status name-matching semantics that the schema cannot express. issueKey is only covered by the schema's pattern, but its meaning is self-evident from the Jira context.
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?
"WRITE: execute one workflow transition" names a specific verb and resource, and the WRITE prefix immediately separates it from the read-side sibling jira_get_transitions. The added scope note "Does not fill transition-screen fields" tells an agent exactly what this call will not do, which is a distinctive boundary no sibling covers.
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 a concrete selection rule for the two mutually exclusive parameters ("Supply exactly one of transitionId or transitionName") and warns that names are transition names, not status names, with ambiguous names requiring an ID. What is missing is any pointer to the discovery step — an agent must infer on its own that jira_get_transitions is the way to obtain valid IDs before calling this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: update supplied fields on an existing Jira issue. Omitted fields stay unchanged. Labels and components replace entire lists; [] clears them. Requires at least one field. Does not change workflow status. Assignee is a Server username; custom fields use raw IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| labels | No | Replaces all labels; [] clears them. | |
| summary | No | ||
| assignee | No | Jira Server username, not display name or Cloud accountId. | |
| issueKey | Yes | ||
| priority | No | Exact Jira priority name. | |
| components | No | Component names. Replaces all components; [] clears them. | |
| description | No | Jira text/wiki markup; empty string clears the description. | |
| customFields | No | Raw Jira custom field IDs and Jira-compatible values; null clears a field where Jira permits it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true; the description earns credit for explaining exactly why destruction happens — labels and components replace entire lists and [] clears them. It also discloses the partial-update contract. It stops short of 5 because it says nothing about permission requirements or error behavior.
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?
Five short sentences, front-loaded with the 'WRITE:' signal, and each sentence carries a non-obvious behavioral fact rather than restating the name.
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 destructive 8-parameter mutation with a nested customFields object and no output schema, the description covers the critical semantics: partial updates, list replacement, clearing, and field ID formats. It leaves unanswered what the call returns, but with no output schema that gap is minor.
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 75% and the replacement semantics for labels/components plus the Server-username/raw-ID notes are already documented verbatim in the schema descriptions, so the description largely repeats structured data. It adds little parameter guidance 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?
States a specific verb (update), resource (existing Jira issue) and scope (supplied fields only), and explicitly distinguishes itself from jira_transition_issue by noting it does not change workflow status. An agent can separate it from jira_create_issue and jira_transition_issue without opening any 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?
'Requires at least one field' and 'Does not change workflow status' give concrete when-to-use and when-not-to-use constraints, implicitly routing status changes to jira_transition_issue. The alternative tool is not named outright, so it stops short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: upload 1–10 local files to a Jira issue. filePaths must resolve inside JIRA_MCP_ALLOWED_PATHS. Rejects .. traversal and symlink escapes. The configured size limit applies per file and to the total batch. Relative paths use server working directory. Do not retry blindly after failure.
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| filePaths | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only tell the agent this is a non-idempotent, non-destructive write; the description adds substantive context the annotations cannot convey: path allowlist enforcement, '..' traversal and symlink-escape rejection, per-file and per-batch size limits, relative-path resolution against the server working directory, and explicit advice not to retry blindly. That is a rich behavioral profile for a mutation 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?
Six tight sentences with the WRITE marker and the core action front-loaded; every subsequent sentence carries a distinct constraint (paths, limits, relative resolution, retry policy). No filler or restatement of the name.
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 mutation tool with no output schema, the description covers the risky parts well. It does not say what comes back (attachment IDs/metadata) or what error conditions look like beyond the retry warning, which is the main remaining 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 0%, so the description must compensate, and it does for filePaths: allowed root, traversal/symlink rules, relative-path base, size limits, and the 1–10 range. issueKey is left to its regex pattern, which is largely self-documenting, but no explicit statement about its format or where to obtain it.
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?
Opens with an explicit verb and resource ("WRITE: upload 1–10 local files to a Jira issue"), including the batch-size scope. It is trivially distinguishable from the attachment siblings (list, download, cleanup) and from issue/comment writers.
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 operational constraints (allowlist, no blind retries) but never states when to use this versus jira_download_attachment or jira_list_attachments, nor any prerequisite like issue permissions. Usage is implied by the verb rather than spelled out.
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.
v0.1.1jira_add_commentjira_cleanup_attachmentsjira_create_issuejira_download_attachmentjira_get_commentsjira_get_current_userjira_get_issuejira_get_transitionsjira_list_attachmentsjira_search_issuesjira_transition_issuejira_update_issuejira_upload_attachmentScored across 13 tools
Each tool maps to a distinct resource+action (search, get, create, update, comment, transition, attachment lifecycle), and the descriptions explicitly disambiguate the risky pairs like get_issue vs get_comments and update_issue vs transition_issue. Minor overlap remains: jira_get_issue already emits attachment metadata and partial comments, so an agent could plausibly skip jira_list_attachments or misuse get_issue for full discussions, but the docs steer correctly.
Every tool follows the same jira_<verb>_<noun> snake_case pattern (search_issues, get_issue, create_issue, add_comment, list_attachments, upload_attachment, cleanup_attachments). No camelCase or verb-style deviations; read vs write intent is further flagged in descriptions.
13 tools is squarely in the well-scoped range for a Jira integration and each one earns its place: the attachment trio (upload/download/cleanup) plus comment paging reflect real operational needs rather than bloat. Nothing appears redundant or filler.
Core issue lifecycle (search, get, create, update, comment, transition) and attachment handling are covered, but jira_create_issue demands an exact project key and issue type name while no tool lists projects, issue types, or creatable field metadata, which will cause trial-and-error failures. There is also no issue delete, no comment edit/delete, no issue-link or worklog operations, and no assignable-user lookup beyond get_current_user.
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.
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.