Model Context Protocol (MCP) integration for Atlassian products (Jira and Confluence) that bridges AI language models with Atlassian tools while maintaining data privacy and security
Server has 16 tools spanning Jira and Confluence integrations. Tool naming follows verb-noun patterns consistently (jira_search_issues, confluence_create_page, etc.), which is positive. However, source code inspection reveals critical gaps: NO tool descriptions are visible in the provided code samples, parameter schemas are not shown in the excerpts, and output structures are not documented. The code shown (Dockerfile, pyproject.toml, utils/tools.py, servers/main.py) does not contain the actual tool definitions with descriptions or schemas. This forces reliance on inference rather than direct verification. Per the hard scoring rules, when tool definitions cannot be seen in source, scores must be capped at 50 per tool. Without documented input schemas, parameter descriptions, output schemas, or error handling guidance visible in the code, the server cannot score above the bottom quartile.
No tool descriptions visible in source code. Tool selection requires descriptions explaining WHAT the tool does, WHEN to use it, and WHEN NOT to use it. LLMs cannot select tools safely without explicit guidance.
CRITICAL: Add comprehensive tool descriptions (50-200 chars) to EVERY tool. Each description must state WHAT the tool does, WHEN to use it instead of similar tools, and what it returns. Reference: pattern:tool-description.
CRITICAL: Define input parameter schemas (JSON Schema) for EVERY parameter. Include: type (string/number/boolean/object/array), required flag, description, min/max/enum constraints, and format (date-time, email, etc.). Reference: pattern:constrained-input.
CRITICAL: Document output schemas showing what fields each tool returns, their types, and whether they are needed for downstream tool calls. This enables tool chaining and prevents broken references. Reference: pattern:response-shaper.
HIGH: Implement error handling that guides LLM recovery. For each failure mode (not found, permission denied, invalid input, API error), return a message like: 'Issue PROJ-999 not found. Try search_issues(key=PROJ) to find valid issue keys.' Reference: pattern:recovery-guide.
HIGH: Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to tool metadata. Mark WRITE tools as destructiveHint=true so agents know not to retry them without confirmation. Mark READ_ONLY tools as readOnlyHint=true. This is a current spec (2026-07-28) pattern that improves agent safety.
HIGH: Implement confirmation or dry-run for irreversible operations (jira_create_issue, jira_update_issue, jira_add_comment, confluence_create_page, confluence_update_page, confluence_add_comment). A dry-run mode returns 'This would create issue PROJ-123' without executing. Reference: pattern:confirmation-request.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No output schemas documented in source code. LLMs need to know what fields to expect from each tool so they can plan downstream tool calls and extract the right data for chaining.
No error handling guidance visible. When tools fail (e.g. issue not found, permission denied, API error), the response must tell the LLM what to do next: retry, call a different tool, ask the user, or give up. Raw errors or stack traces are not actionable.
WRITE tools (jira_create_issue, jira_update_issue, jira_add_comment, confluence_create_page, confluence_update_page, confluence_add_comment) have no visible confirmation or dry-run mechanisms. Irreversible operations should support confirmation or dry-run to prevent agents from making mistakes.
No tool annotations visible (readOnlyHint, destructiveHint, idempotentHint). LLMs need to know which tools are safe to retry, which modify state irreversibly, and which are read-only. This is a current spec (2026-07-28) best practice that guides agent reasoning.
Tool names use generic action verbs but lack disambiguating suffixes when multiple tools operate on the same resource. E.g., both jira_get_issue and jira_search_issues retrieve issues, but via different means. Names could be clearer with intent-specific suffixes like 'search' vs 'get_by_id'.
MEDIUM: Add pagination support to list/search tools (jira_search_issues, confluence_search_pages, jira_list_projects, confluence_list_spaces). Accept limit and offset/cursor parameters, and return total_count and next_cursor. Cap results at 20-50 items per call to avoid context window exhaustion. Reference: pattern:paginated-result.
MEDIUM: Ensure output includes IDs and references needed for tool chaining. If jira_search_issues returns issues, include issue_id (not just issue_key) so agents can pass it to jira_get_issue or jira_update_issue. Reference: pattern:tool-chain.
MEDIUM: Add natural-identifier support. Accept both human-friendly names (project names, user names) and system IDs (project keys, user IDs) in tool parameters, then resolve them server-side. Agents often have display names but not opaque IDs. Reference: mxe:natural-identifiers.
LOW: Improve parameter descriptions with examples of valid values and constraints. E.g., 'project_key (2-10 uppercase letters, e.g. PROJ, INFRA, MYAPP)' instead of just 'project_key'. Do NOT include live example IDs like 'JIRA-123', LLMs reuse these literally. Reference: pattern:tool-description.
LOW: Ensure consistency between list/search tools and detail tools on field naming. If jira_search_issues returns 'issue_key', then jira_get_issue should accept 'issue_key' (not 'key' or 'issueKey'). Mismatched naming forces LLM reasoning about field mappings. Reference: mxe:response-field-naming.