The server defines 8 tools with basic schema coverage, but significant gaps undermine production readiness. Most tools lack proper output schema documentation, parameter descriptions are minimal or absent for several fields, and critical error handling patterns are missing. Naming is generally verb-first and clear, but descriptions are often too brief (20-50 chars) to guide LLM selection effectively. The codebase is TypeScript with mcp-sdk, but tool registration appears direct without formal annotation patterns. Field naming inconsistencies (e.g., 'email' param vs 'assignee' param) create friction. No evidence of pagination, rate limiting, or structured error recovery guides.
Tools (8)
create_issuewriteauth50/100
Create a new Jira issue or subtask
create_issue_linkwriteauth50/100
Create a link between two Jira issues
create_projectwriteauth50/100
Create a new Jira project
delete_issuedestructiveauth50/100
Delete a Jira issue
get_issuesread onlyauth50/100
Get issues from a Jira project, optionally filtered by JQL
Output schemas not documented. No visible return type definitions for any tool. LLMs cannot plan downstream operations or extract chaining fields (e.g., what fields does list_issue_types return?)
get_issues accepts 'projectKey' and 'jql' but has no pagination parameters (limit, offset, page_size). Jira projects can have hundreds of issues; returning all without limits will exhaust context windows.
create_issue and update_issue both accept 'assignee' as an email string. The code references 'get_user' for account ID lookup, but the parameters force string email input. No guidance on whether email resolution is automatic or if the user must call get_user first.
create_issueupdate_issueget_user
Recommendations
Add explicit output schema documentation to each tool. For get_issues, document: returns array of {issue_key: string, summary: string, status: string, assignee: {email: string, accountId: string}, created: ISO-8601, updated: ISO-8601}. Include total_count and has_more for pagination awareness.
Add pagination to get_issues: limit (1-100, default 20) and offset (default 0) parameters. Document in description: 'Returns max 20 results by default. Use offset for pagination. Call with jql to filter.' Return has_more boolean and total_count to enable agent planning.
Expand parameter descriptions to 50 - 150 characters. For 'projectTypeKey', add: 'Project type identifier: software (for agile/kanban), service_desk (for support), or business. Defaults to software if omitted.' For 'priority', add: 'Priority level: Lowest, Low, Medium, High, Highest. Must match Jira instance configuration.'
Add enum validation for constrained parameters. Example: projectTypeKey in [software, service_desk, business]; issueType resolved via list_issue_types; status resolved via available issue transitions; priority in [Lowest, Low, Medium, High, Highest].
Document assignee resolution flow in each tool description: 'Accepts user email. If you have only a display name, call get_user(email) first to resolve the accountId.' Or accept both email and account_id as separate optional parameters to reduce lookup burden.
Implement structured error responses. For create_project with duplicate key: return {error: 'Project key already exists', suggestion: 'try search_projects(key_prefix) to find similar projects or choose a different key', retryable: false}. Pattern: recovery-guide.
delete_issue marked DESTRUCTIVE but no confirmation step or dry-run option visible. Agents may delete issues unintentionally. Pattern:confirmation-request recommends a confirmation step for irreversible operations.
Parameter descriptions are minimal (under 20 chars for several). 'Optional project description' lacks context on length, format, or ADF vs plaintext. 'Optional array of labels' does not specify max array length or label naming rules.
Error handling responses not visible in tool code. No error classification (retryable vs user-fixable), no recovery guidance. If create_project fails due to duplicate key, does the LLM know to suggest search_projects or try a new key?
No evidence of input validation or enum constraints. 'projectTypeKey' accepts arbitrary strings with no guidance on valid values (software, service_desk, etc.). 'priority' similarly undefined.
Assignee resolution documented in code comments but not in tool descriptions. User must infer from the 'get_user' existence that email resolution is required. Parameter docs should state: 'Email address, if you only have a display name, call get_user() first.'
create_issueupdate_issue
Add idempotentHint and destructiveHint annotations to tool definitions. Mark delete_issue with destructiveHint and idempotentHint=false to signal that retries risk data loss. Consider adding a confirmation step or dry-run parameter.
Create a discovery tool or enrich list_issue_types response to show available status values, priorities, and issue type -> required fields mapping. This enables agents to validate inputs before attempting create/update.
For create_issue, document which fields are required vs optional per issue type. Subtasks require 'parent'; other types do not. Capture in description or return validation errors early.
Implement rate limiting and timeout guards. Document in server README: 'API calls have 60-second timeouts. Agents hitting rate limits will receive 429 with retry-after header. Implement exponential backoff.'
Strip irrelevant API metadata from responses (e.g., Jira's internal field objects, audit fields). Return compact summaries focused on what agents need to reason about next steps.