Provides tools for interacting with Jira, enabling issue management, search, JQL queries, custom filters, workflow transitions, and comment management.
Click on "Install 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 Server show me my open issues in project DEV"
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 FastMCP server that enables AI assistants to interact with self-hosted Jira instances through token authentication.
✅ Issue Management: Create, read, and update Jira issues with automatic custom field validation
✅ Smart Custom Field Handling: Automatically discovers and validates project-specific custom fields
✅ Schema Caching: Intelligent caching reduces API calls by 80%+
✅ Health Check: Verify connectivity and authentication
✅ Schema Introspection: Debug tool to explore available fields
✅ Robust Search: Search issues by project, assignee, status, priority, labels, and date ranges
✅ JQL Support: Execute raw JQL queries directly with full Jira Query Language support
✅ Custom Filters: Save and reuse complex search queries with full CRUD operations
✅ Filter Execution: Run saved filters with pagination support
✅ Workflow Transitions: Move issues through workflow states
✅ Transition Discovery: Get available transitions for any issue
✅ Comment Management: Full CRUD operations for issue comments (add, list, update, delete)
✅ Comment Permissions: Author and admin permission controls for update/delete
✅ Jira Markup Support: Full support for Jira text formatting in comments
Related MCP server: Jira MCP Server
Python 3.8 or higher
Self-hosted Jira instance (version 7.0+)
Jira API token with appropriate permissions
pip install fastmcp-jira-serverGet your Jira API token:
Log into your Jira instance
Go to Profile → Personal Access Tokens
Create a new token and copy the value
Configure environment variables:
export JIRA_MCP_URL="https://jira.yourcompany.com"
export JIRA_MCP_TOKEN="your-api-token-here"Or create a .env file (see .env.example):
JIRA_MCP_URL=https://jira.yourcompany.com
JIRA_MCP_TOKEN=your-api-token-hereRun the server:
fastmcp-jira-serverVerify connection:
Use the jira_health_check tool through your MCP client to verify the connection.
The FastMCP Jira Server can be used with any MCP-compatible AI assistant. Below are configuration instructions for popular tools.
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"jira": {
"command": "fastmcp-jira-server",
"env": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
}
}
}
}After updating the config, restart Claude Desktop. The Jira tools will appear in the MCP tools menu.
Add to your Cline MCP settings (~/.cline/mcp_settings.json):
{
"mcpServers": {
"jira": {
"command": "fastmcp-jira-server",
"env": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
}
}
}
}Restart VS Code after updating the configuration.
Add to your Windsurf configuration:
macOS/Linux: ~/.windsurf/mcp_config.json
Windows: %USERPROFILE%\.windsurf\mcp_config.json
{
"mcpServers": {
"jira": {
"command": "fastmcp-jira-server",
"env": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
}
}
}
}Restart Windsurf to load the new configuration.
Add to your Cursor MCP settings:
macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
Linux: ~/.config/Cursor/User/globalStorage/mcp.json
{
"mcpServers": {
"jira": {
"command": "fastmcp-jira-server",
"env": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
}
}
}
}Restart Cursor after updating the configuration.
Requirements: VS Code 1.99+ and GitHub Copilot with MCP policy enabled
Create .vscode/mcp.json in your project root:
{
"inputs": [
{
"type": "promptString"
}
],
"servers": {
"jira": {
"command": "fastmcp-jira-server"
}
}
}Environment Variables: Set these in your shell before starting VS Code:
export JIRA_MCP_URL="https://jira.yourcompany.com"
export JIRA_MCP_TOKEN="your-api-token-here"
code .Or add to your VS Code settings.json:
{
"terminal.integrated.env.osx": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
},
"terminal.integrated.env.linux": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
},
"terminal.integrated.env.windows": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here"
}
}After saving .vscode/mcp.json, click the "Start" button that appears at the top of the file. Access the Jira tools through Copilot Chat in Agent mode by clicking the tools icon.
After configuration, test the connection by asking your AI assistant:
"Use the jira_health_check tool to verify the Jira connection"
You should see a response confirming the connection status and server version.
# Verify connectivity and authentication
jira_health_check()
# Returns: {"connected": true, "server_version": "8.20.0", "base_url": "https://jira.yourcompany.com"}# Basic issue creation
jira_issue_create(
project="PROJ",
summary="Login page shows 404 error",
issue_type="Bug",
priority="High",
description="Users are seeing 404 errors when accessing /login"
)
# With custom fields (automatically validated against project schema)
jira_issue_create(
project="PROJ",
summary="Add user authentication",
issue_type="Story",
custom_fields={
"customfield_10001": 8, # Story Points
"customfield_10002": "Backend", # Component
}
)# Update specific fields
jira_issue_update(
issue_key="PROJ-123",
summary="Updated: Login page shows 404 error",
priority="Critical",
assignee="john.doe"
)
# Update custom fields
jira_issue_update(
issue_key="PROJ-123",
custom_fields={
"customfield_10001": 13 # Update story points
}
)# Retrieve full issue details including all custom fields
jira_issue_get(issue_key="PROJ-123")# Useful for finding custom field IDs and allowed values
jira_project_get_schema(
project="PROJ",
issue_type="Bug"
)
# Returns all available fields, their types, and validation rules# Search by project
jira_search_issues(project="PROJ")
# Search with multiple criteria
jira_search_issues(
project="PROJ",
status="Open",
assignee="currentUser()",
priority="High",
max_results=10
)
# Search by date range
jira_search_issues(
project="PROJ",
created_after="2025-01-01",
created_before="2025-12-31"
)
# Search by labels
jira_search_issues(
project="PROJ",
labels=["backend", "urgent"]
)# Simple JQL query
jira_search_jql(jql="project = PROJ AND status = Open")
# Complex JQL with date functions and ordering
jira_search_jql(
jql='project = PROJ AND created >= -7d AND assignee = currentUser() ORDER BY created DESC',
max_results=20
)
# JQL with multiple conditions
jira_search_jql(
jql='project = PROJ AND status IN ("Open", "In Progress") AND priority = High',
max_results=50,
start_at=0
)# Create a filter
filter_result = jira_filter_create(
name="My Open Issues",
jql="assignee = currentUser() AND status = Open",
description="All my open issues"
)
filter_id = filter_result["id"]
# List all accessible filters
filters = jira_filter_list()
# Get filter details
filter_details = jira_filter_get(filter_id="10000")
# Execute a saved filter
results = jira_filter_execute(filter_id="10000", max_results=20)
# Update filter
jira_filter_update(
filter_id="10000",
jql="assignee = currentUser() AND status IN (Open, 'In Progress')"
)
# Delete filter
jira_filter_delete(filter_id="10000")# Get available transitions for an issue
transitions = jira_workflow_get_transitions(issue_key="PROJ-123")
# Returns: {
# "issue_key": "PROJ-123",
# "transitions": [
# {"id": "21", "name": "In Progress", "to_status": "In Progress", "has_screen": False, "fields": []},
# {"id": "31", "name": "Done", "to_status": "Done", "has_screen": True, "fields": ["resolution"]}
# ]
# }
# Simple transition (no fields required)
jira_workflow_transition(issue_key="PROJ-123", transition_id="21")
# Transition with required fields (e.g., resolution when closing)
jira_workflow_transition(
issue_key="PROJ-123",
transition_id="31",
fields={"resolution": {"name": "Done"}}
)
# Transition with comment
jira_workflow_transition(
issue_key="PROJ-123",
transition_id="21",
fields={"comment": [{"add": {"body": "Moving to in progress"}}]}
)# Add a comment to an issue
comment = jira_comment_add(
issue_key="PROJ-123",
body="This issue is ready for review"
)
# Returns: {
# "id": "10001",
# "body": "This issue is ready for review",
# "author": {"displayName": "John Doe", "emailAddress": "john@example.com"},
# "created": "2025-01-15T10:00:00.000+0000"
# }
# Add comment with Jira markup
jira_comment_add(
issue_key="PROJ-123",
body="Status update:\n* Task 1: *Done*\n* Task 2: _In progress_\n* Task 3: {{Not started}}"
)
# List all comments on an issue
comments = jira_comment_list(issue_key="PROJ-123")
# Returns: {
# "comments": [
# {
# "id": "10001",
# "body": "First comment",
# "author": {"displayName": "John Doe"},
# "created": "2025-01-15T10:00:00.000+0000"
# },
# {
# "id": "10002",
# "body": "Second comment",
# "author": {"displayName": "Jane Smith"},
# "created": "2025-01-15T11:00:00.000+0000"
# }
# ],
# "total": 2
# }
# Update an existing comment
updated = jira_comment_update(
issue_key="PROJ-123",
comment_id="10001",
body="Updated comment text"
)
# Returns: {
# "id": "10001",
# "body": "Updated comment text",
# "author": {"displayName": "John Doe"},
# "updated": "2025-01-15T12:00:00.000+0000"
# }
# Delete a comment
result = jira_comment_delete(issue_key="PROJ-123", comment_id="10001")
# Returns: {
# "success": true,
# "message": "Comment 10001 deleted successfully",
# "issue_key": "PROJ-123",
# "comment_id": "10001"
# }Environment variables:
JIRA_MCP_URL (required): Your Jira instance URL
JIRA_MCP_TOKEN (required): API authentication token
JIRA_MCP_CACHE_TTL (optional, default: 3600): Schema cache TTL in seconds
JIRA_MCP_TIMEOUT (optional, default: 30): HTTP request timeout in seconds
JIRA_MCP_VERIFY_SSL (optional, default: true): Verify SSL certificates
By default, the server verifies SSL certificates. For testing with self-signed certificates, you can disable SSL verification:
export JIRA_MCP_VERIFY_SSL="false"Or in your AI assistant configuration:
{
"mcpServers": {
"jira": {
"command": "fastmcp-jira-server",
"env": {
"JIRA_MCP_URL": "https://jira.yourcompany.com",
"JIRA_MCP_TOKEN": "your-api-token-here",
"JIRA_MCP_VERIFY_SSL": "false"
}
}
}
}Security Warning: Disabling SSL verification should only be used for testing with self-signed certificates or internal development. Never use this in production environments as it makes your connection vulnerable to man-in-the-middle attacks.
git clone https://github.com/yourusername/jira-mcp-server.git
cd jira-mcp-server
pip install -e ".[dev]"pytestWith coverage report:
pytest --cov=src/jira_mcp_server --cov-report=htmlmypy src/# Check and auto-fix
ruff check src/ tests/ --fix
# Format code
ruff format src/ tests/FastMCP: MCP server framework
httpx: HTTP client for Jira REST API
Pydantic: Data validation and settings management
In-memory caching: TTL-based schema caching (1-hour default)
jira_issue_create - Create new issues with automatic custom field validation
jira_issue_update - Update existing issues (only provided fields are updated)
jira_issue_get - Get full issue details including all custom fields
jira_health_check - Verify connection and authentication status
jira_project_get_schema - Get project schema for debugging (shows all available fields, types, and validation rules)
jira_search_issues - Search with multiple criteria (project, assignee, status, priority, labels, date ranges)
jira_search_jql - Execute JQL queries directly with full Jira Query Language support
jira_filter_create - Create custom filter with name and JQL query
jira_filter_list - List all accessible filters
jira_filter_get - Get filter details by ID
jira_filter_execute - Run a saved filter with pagination support
jira_filter_update - Update filter criteria (name, JQL, description)
jira_filter_delete - Delete a filter (owner only)
jira_workflow_get_transitions - Get available transitions for an issue
jira_workflow_transition - Transition issue through workflow
jira_comment_add - Add comment to an issue (supports Jira markup)
jira_comment_list - List all comments on an issue with author and timestamp info
jira_comment_update - Update an existing comment (author or admin only)
jira_comment_delete - Delete a comment (author or admin only)
See the troubleshooting section in quickstart.md for common issues and solutions.
Contributions are welcome! Please read CONTRIBUTING.md for development guidelines.
MIT License - see LICENSE for details.
Issues: GitHub Issues
Documentation: Full Documentation
Add a comment to an issue.
Comments support Jira markup for formatting (bold, italic, lists, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") | |
| body | Yes | Comment text (supports Jira markup) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 mentions Jira markup support but fails to disclose behavioral traits such as error handling, permissions, or side effects like issue modification. Minimal safety context is given.
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 extremely concise with two sentences. The first sentence states the primary purpose, and the second adds a useful detail. No unnecessary 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?
The tool is simple and has an output schema, so it does not need to explain return values. However, it lacks sibling differentiation and behavioral transparency, making it only minimally complete for a production tool.
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?
Both parameters are documented in the schema (100% coverage). The description adds value by noting that the body supports Jira markup, which elaborates on the schema's description. This helps the agent understand formatting capabilities beyond the schema's minimal description.
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 ('Add'), the resource ('comment'), and the target ('issue'). It distinguishes the tool from sibling tools like jira_comment_delete_tool, jira_comment_list_tool, etc.
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 does not provide guidance on when to use this tool versus alternatives like jira_comment_update_tool or jira_comment_delete_tool. The usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment.
Only the comment author or users with appropriate permissions can delete a comment.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") | |
| comment_id | Yes | Comment ID to delete |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permission constraints but lacks depth on irreversibility, cascading effects, or error conditions. No annotations provided so description carries full burden.
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, no fluff, perfectly concise. Every word adds 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?
Simple tool with output schema; minimal description covers core behavior. Lacks details on outcome or errors but adequate for a straightforward delete operation.
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 already describes both parameters fully (100% coverage). Description adds no extra 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?
Description clearly states 'Delete a comment.' Specific verb+resource, directly distinguishes from siblings like add, list, update.
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?
Mentions permission requirement (comment author or appropriate permissions) but does not explicitly guide when to use vs. alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all comments on an issue.
Retrieves all comments with author information and timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates read-only retrieval but lacks details on pagination, ordering, or limits. The presence of an output schema partially compensates, but behavioral traits remain vague.
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 concise sentences, front-loaded with the main action. Every sentence adds value without extraneous 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 a single required parameter, an existing output schema, and distinct sibling tools, the description is nearly complete. Minor omission regarding pagination or comment ordering prevents a perfect score.
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 a clear parameter description. The tool description does not add extra meaning beyond the schema's own documentation; thus baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all comments on an issue' and elaborates with 'Retrieves all comments with author information and timestamps.' This is a specific verb+resource (list comments) and distinguishes from sibling tools like add, delete, update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The context of sibling CRUD operations implies reading, but there are no when-not or exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing comment.
Only the comment author or users with appropriate permissions can update a comment.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") | |
| comment_id | Yes | Comment ID to update | |
| body | Yes | New comment text (supports Jira markup) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the permission requirement, but lacks details on side effects, error handling, or behavior when the comment doesn't exist.
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 very concise, using two short sentences that front-load the purpose. Every word is necessary; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and three simple parameters, the description is adequate but minimal. It omits information about return values, error conditions, and the need for the comment to exist, relying on the schema.
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 descriptions for all three parameters (issue_key, comment_id, body). The description adds no extra meaning beyond the schema, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing comment,' specifying the verb and resource. It distinguishes from sibling tools like add, delete, and list, but does not explicitly mention the parameter (body) being updated.
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 notes that only the comment author or users with appropriate permissions can update, providing a constraint. However, it does not give guidance on when to choose this tool over alternatives like jira_comment_add_tool or jira_comment_delete_tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new saved filter for reusing complex search queries.
Filters allow you to save JQL queries for quick access to frequently-needed issue sets.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Filter name (required) | |
| jql | Yes | JQL query string (required) | |
| description | No | Optional filter description | |
| favourite | No | Whether to mark as favorite (default: False) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It states it creates a filter but does not mention side effects, permissions, rate limits, uniqueness constraints, or response details. For a creation tool with no annotations, more behavioral context is needed.
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 two sentences and clearly states the purpose. It is concise with no superfluous words, though it could be slightly more efficient. Overall, it is well-structured.
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?
An output schema exists but is not shown; the description is brief. For a creation tool with siblings, it could mention what the response contains (e.g., filter ID) or that the filter is saved for later use. Adequate but leaves some context unspecified.
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 each parameter is described in the schema. The description adds general context about saving JQL queries but does not provide additional parameter-specific semantics beyond what the schema offers. 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 tool creates a new saved filter for reusing JQL queries. The verb 'create' and resource 'saved filter' are specific, and the tool is distinguished from sibling filter tools (delete, execute, get, list, update) and search tools.
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 explains the tool is for saving complex search queries for reuse, implying use when saving filters. However, it does not explicitly mention when not to use it or list alternatives like jira_search_jql_tool for ad-hoc queries, so guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a filter.
Only the filter owner can delete it.
| Name | Required | Description | Default |
|---|---|---|---|
| filter_id | Yes | Filter ID |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds the ownership requirement, which is a behavioral trait beyond the input schema. It does not mention permanence or success/failure behavior, but for a delete it's fairly transparent.
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 action, no wasted 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?
Given the output schema exists, the description sufficiently covers the action and a key constraint. Minimal but complete for a simple delete operation.
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% for the single parameter (filter_id). The description adds no extra meaning beyond 'Filter ID', so baseline score 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 clearly states the tool deletes a filter, using a specific verb and resource. It distinguishes from sibling tools like create, update, list, etc.
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?
Provides a clear usage constraint: only the filter owner can delete it. While it doesn't explicitly exclude other uses, the ownership note guides appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a saved filter and return matching issues.
Retrieves the filter's JQL and executes it with pagination support.
| Name | Required | Description | Default |
|---|---|---|---|
| filter_id | Yes | Filter ID | |
| max_results | No | Maximum results to return (default: 50) | |
| start_at | No | Starting offset for pagination (default: 0) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'pagination support' but does not explicitly state that the tool is read-only or non-destructive. The term 'execute' could imply action, but context suggests it's a query; however, lacking explicit safety declaration.
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, no unnecessary words. Front-loaded with the core action and followed by a concise explanation of how it works.
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 full schema coverage and an output schema, the description is fairly complete. It explains the tool's mechanism (retrieves JQL, executes with pagination). Slight gap in not hinting at error conditions or filter existence checks, but overall adequate.
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 parameters. The description adds context about JQL retrieval and pagination, but does not enhance understanding of individual parameter formats or constraints 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 verb 'Execute' and resource 'saved filter' are specific and clear. The description states it returns matching issues, distinguishing it from sibling tools like jira_filter_get_tool (retrieves filter definition) and jira_search_issues_tool (general JQL search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a saved filter ID) or when to prefer filter execution over direct JQL search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete filter details by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| filter_id | Yes | Filter ID |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 states 'get complete filter details' but does not disclose whether it is read-only (likely), required permissions, or any limitations. For a simple get operation, it is minimally adequate but lacks detail.
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 with no waste. It is front-loaded with the action and resource. Could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, output schema exists), the description is adequate but not complete. It does not explain return format, error conditions, or permission requirements, though the output schema may cover return values.
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% (filter_id described as 'Filter ID'). The tool description does not add any additional meaning beyond 'by ID'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and the resource (complete filter details) by ID. It is specific and distinguishes from sibling tools like jira_filter_list_tool (list filters) or jira_filter_execute_tool (execute filter).
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 jira_filter_list_tool should be used for listing filters, or that jira_filter_execute_tool is for executing a filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all accessible filters.
Returns all filters you have permission to view, including your own and shared filters.
Returns: List of filter metadata (ID, name, JQL, owner)
Example: jira_filter_list_tool()
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it returns only filters the user has permission to view, which is key behavioral info. For a read-only list tool with no side effects, this is sufficiently transparent.
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 for purpose, one line for returns, and a clear example. No unnecessary words, front-loaded with main action.
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 zero parameters and an output schema (exists, though not detailed), the description covers all necessary information: what it does, what it returns, and an example call. Fully complete for this simple tool.
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?
Input schema has zero parameters, so schema coverage is complete. The description does not need to add parameter details. Baseline for 0 params is 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 clearly states the tool lists all accessible filters, including own and shared. It distinguishes from siblings like jira_filter_get_tool (which gets a specific filter) and filter create/update/delete tools.
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 implies usage for listing filters but does not explicitly state when to use this tool vs alternatives (e.g., jira_filter_get_tool for a specific filter) or when not to use it. No exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing filter.
Only provided fields are updated. At least one field must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| filter_id | Yes | Filter ID | |
| name | No | New filter name | |
| jql | No | New JQL query | |
| description | No | New description | |
| favourite | No | Whether to mark as favorite |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses partial update behavior but omits details like authorization needs, error handling, or what happens on failure. Adequate but with 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 sentences with zero unnecessary words. The purpose is front-loaded, and the constraint is stated efficiently.
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, high schema coverage, and presence of output schema, the description provides enough context for an agent to use it correctly. Could mention return value or error scenarios, but not strictly needed.
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 all parameters described. The description adds no extra parameter detail beyond the 'at least one field' constraint, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'existing filter', distinguishing it from sibling tools like create, delete, get, list, and execute.
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 indicates that only provided fields are updated and at least one field must be provided, guiding partial update usage. It does not explicitly exclude cases, but sibling context makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify connectivity to Jira instance and validate authentication.
Returns: Connection status and server info including version and URL
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavior. It describes the tool's outcome (connectivity verification and authentication validation) and return info (status, server info, version, URL), which is sufficiently transparent.
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 two short sentences, front-loading the purpose and succinctly listing return values. No superfluous 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 no parameters and an output schema, the description fully explains the tool's operation and return values. It is complete for a health check tool.
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?
The tool has zero parameters, so schema coverage is 100%. The description adds no parameter info because none is needed. Baseline score of 4 applies as per guidelines.
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 tool verifies connectivity and validates authentication to a Jira instance. This distinguishes it from sibling tools that perform CRUD operations on issues, comments, filters, etc.
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 implies usage for checking connectivity and authentication, but does not explicitly state when not to use it or mention alternatives. However, the purpose is self-evident given the tool name and context.
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 issue with automatic custom field validation.
The system automatically discovers and validates custom fields based on the project schema.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project key (e.g., "PROJ", "DEV") | |
| summary | Yes | Issue title/summary (1-255 characters) | |
| issue_type | No | Type of issue (Task, Bug, Story, etc.) - default: Task | Task |
| description | No | Detailed issue description (supports Jira markup) | |
| priority | No | Issue priority (if not set, uses project default) | |
| assignee | No | Username or user ID to assign the issue to | |
| labels | No | List of labels to apply to the issue | |
| due_date | No | Due date in ISO format (YYYY-MM-DD) | |
| custom_fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are missing, so the description carries the burden. It discloses that the tool performs automatic custom field validation based on project schema, which is a key behavioral trait. However, it does not mention mutation side effects, required permissions, error conditions, or output behavior (output schema exists but unmentioned). The description provides some transparency but not comprehensive.
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 two sentences, front-loading the primary action. Every sentence adds value: the first states the core function, the second explains the automatic validation feature. No redundant or extraneous 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?
Given the tool's complexity (9 parameters, including custom_fields), and that annotations are absent, the description covers the custom field validation aspect but omits usage guidance, output description, and prerequisites. The output schema exists but is not referenced. A more complete description would include when to use and what the return value contains.
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 high (89%), so baseline is 3. The description adds value by explaining that custom_fields are automatically validated based on project schema, which goes beyond the schema's simple 'additionalProperties: true' definition. Other parameters are well-documented in the schema, so the description's extra context improves understanding of the custom_fields parameter.
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 'Create a new Jira issue' which specifies the verb and resource. It also mentions 'automatic custom field validation' distinguishing it from related tools like jira_issue_update_tool that modify existing issues. The verb 'create' and resource 'Jira issue' are 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?
The description implies usage when a new issue needs to be created, but it does not explicitly state when to use this tool versus alternatives. No guidance is given on when not to use it or what prerequisites exist (e.g., required permissions). Sibling tools like jira_issue_update_tool are not mentioned as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full details of a single issue including all custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies read-only behavior via 'retrieve' but does not explicitly state idempotency, authentication needs, 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?
The description is a single, concise sentence with no wasted words, efficiently conveying the tool's core function.
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 (one required parameter, output schema present), the description is largely sufficient. It mentions custom fields, but could add context about error handling or prerequisites.
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?
The parameter is already well-documented in the schema (100% coverage) with an example. The description adds no further parameter-level meaning beyond mentioning the result includes custom fields.
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 verb 'retrieve' and the resource 'single issue,' including the specific detail of 'all custom fields.' This distinguishes it from siblings like jira_issue_create_tool and jira_search_issues_tool.
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 implies when to use this tool (retrieving a single issue) but does not explicitly state when not to use it or mention alternatives like search tools for multiple issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Jira issue.
Only provided fields are updated. Custom fields are validated against the project schema.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") | |
| summary | No | New issue summary | |
| description | No | New issue description | |
| priority | No | New priority | |
| assignee | No | New assignee (username or ID) | |
| labels | No | Replace existing labels | |
| due_date | No | New due date | |
| custom_fields | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears the full burden. It discloses that only provided fields are updated (partial update behavior) and that custom fields are validated against the project schema. This is good, but it omits potential side-effects like required permissions or immutability of certain 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?
Two sentences: the first states the purpose, the second adds two key behavioral notes. Every word earns its place, no 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?
Given the complexity (8 parameters, output schema exists), the description is reasonably complete. It covers partial update behavior and custom field validation. The output schema covers return values, so no need to describe them. It could mention label behavior (replace vs append) but that is in the schema. Overall adequate.
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?
The input schema covers 88% of parameters with individual descriptions. The description adds no parameter-specific meaning beyond the schema, except the implicit behavioral note that only provided fields are updated. The custom_fields parameter lacks a description in both schema and description, but the description mentions validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing Jira issue', which is a specific verb+resource combination. It distinguishes from sibling tools like jira_issue_create_tool and jira_issue_get_tool.
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 provides clear context for when to use the tool (update existing issues) and includes the note 'Only provided fields are updated', which implies partial updates. However, it does not explicitly exclude alternatives or mention when not to use it (e.g., for status changes, which would use jira_workflow_transition_tool).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get field schema for a project and issue type for debugging.
This tool helps you understand what fields are available for a project and issue type, including custom fields and their validation rules.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project key (e.g., "PROJ") | |
| issue_type | No | Issue type name (default: "Task") | Task |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates the tool returns field schema including custom fields and validation rules, which implies a read-only operation. No annotations are provided, so the description carries full burden; it is clear and sufficient for this type of 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?
The description is two short sentences, front-loaded with the purpose and adding key details in the second sentence. No unnecessary 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 presence of an output schema, the description adequately covers the tool's behavior. It could be slightly more specific about the output's structure, but the output schema handles that.
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?
The input schema already provides clear descriptions for both parameters (100% coverage). The description adds value by mentioning 'custom fields and their validation rules', which goes 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 clearly states the tool retrieves the field schema for a project and issue type, with a specific verb ('Get') and resource ('field schema'). It distinguishes from sibling tools like issue creation or comment tools.
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 mentions 'for debugging' but does not provide explicit guidance on when to use this tool versus alternatives. No when-not-to-use or sibling differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Jira issues using multiple criteria.
Build a JQL query from the provided criteria and execute it. At least one search criterion must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project key (e.g., "PROJ") | |
| assignee | No | Assignee username or "currentUser()" for current user | |
| status | No | Status name (e.g., "Open", "In Progress", "Closed") | |
| priority | No | Priority name (e.g., "High", "Critical", "Low") | |
| labels | No | List of label names to filter by | |
| created_after | No | Created after date in YYYY-MM-DD format | |
| created_before | No | Created before date in YYYY-MM-DD format | |
| updated_after | No | Updated after date in YYYY-MM-DD format | |
| updated_before | No | Updated before date in YYYY-MM-DD format | |
| max_results | No | Maximum results to return (default: 50) | |
| start_at | No | Starting offset for pagination (default: 0) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states that the tool builds and executes a JQL query, implying a read operation. However, it does not mention pagination behavior, rate limits, or authentication requirements. The existence of an output schema partially mitigates the need to describe return values.
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 consists of two concise sentences. The first sentence is front-loaded with the core purpose. Every sentence adds value without unnecessary words. It is optimally sized for quick understanding.
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 11 parameters, 100% schema coverage, and an existing output schema, the description adequately covers the core functionality. It could mention default ordering or the automatic JQL generation, but it is still complete enough for an agent to use 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 100%, so the input schema already documents each parameter well. The description adds a crucial constraint ('At least one search criterion must be provided') that is not in the schema, but does not provide additional meaning per parameter beyond what the schema already offers.
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 'Search for Jira issues using multiple criteria' and explains that it builds a JQL query. This distinguishes it from sibling tools like jira_issue_get_tool (single issue) and jira_search_jql_tool (raw JQL). The verb 'search' and resource 'issues' are specific and 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?
The description explicitly requires 'At least one search criterion must be provided,' which guides usage. It does not explicitly contrast with alternative search tools, but the siblings list implies a distinction from jira_search_jql_tool. Clear context for use is provided, though exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a JQL (Jira Query Language) query directly.
Use this for complex queries that can't be expressed through search_issues criteria. Supports all JQL operators and functions including ORDER BY clauses.
| Name | Required | Description | Default |
|---|---|---|---|
| jql | Yes | JQL query string (e.g., 'project = PROJ AND created >= -7d ORDER BY created DESC') | |
| max_results | No | Maximum results to return (default: 50) | |
| start_at | No | Starting offset for pagination (default: 0) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states it executes a query, which is read-only, but does not explicitly confirm no side effects, permissions needed, or rate limits. The mention of supporting ORDER BY adds some behavioral detail, but more transparency about the operation's nature would be beneficial.
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 concise with two sentences. The first states the core purpose, and the second provides usage guidance. No unnecessary 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?
With an output schema present, the description does not need to detail return values. It covers the tool's purpose, when to use, and basic behavior. For a tool of this complexity (JQL query execution), the description is complete enough, though it could mention pagination behavior (though schema covers parameters).
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 itself documents all three parameters clearly with descriptions and defaults. The description adds that the tool supports ORDER BY clauses (already part of JQL) and implies full JQL capability, but does not provide additional semantic context beyond what the schema offers. 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 tool executes a JQL query directly, with a specific verb ('Execute') and resource ('JQL query'). It also distinguishes from the sibling tool 'jira_search_issues_tool' by noting it's for complex queries not expressible through search_issues criteria.
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?
Explicitly tells when to use this tool: 'for complex queries that can't be expressed through search_issues criteria.' This provides clear guidance on selecting between this and the sibling tool, and mentions support for all JQL operators and ORDER BY clauses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available workflow transitions for an issue.
Returns all transitions available for the issue in its current state, including transition IDs, names, destination statuses, and required fields.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool is read-only and returns transition IDs, names, destination statuses, and required fields. It does not disclose potential authorization needs, rate limits, or other behavioral traits beyond the basic 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?
The description is two sentences, front-loaded with the primary purpose. Every sentence adds value, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values. It adequately covers what the tool does and the typical output. It does not mention error handling or prerequisites, but for a simple retrieval tool this is acceptable.
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 a single parameter 'issue_key' described in the schema. The description does not add additional meaning beyond the schema's example, so it meets the baseline for high coverage.
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 'Get available workflow transitions for an issue', specifying the action (get) and resource (issue transitions). It effectively distinguishes from sibling tools like jira_workflow_transition_tool.
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 implies usage for viewing transitions before applying one, but does not explicitly state when to use this tool versus alternatives or provide any exclusions. The context of 'available transitions' suggests it is for pre-transition checks, but the guidance is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transition an issue through workflow.
Executes a workflow transition, moving the issue to a new status. Some transitions may require additional fields (e.g., resolution when closing an issue).
| Name | Required | Description | Default |
|---|---|---|---|
| issue_key | Yes | Issue key (e.g., "PROJ-123") | |
| transition_id | Yes | Transition ID to execute (use get_transitions to find valid IDs) | |
| fields | No | Optional fields required by the transition (e.g., {"resolution": {"name": "Done"}}) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It acknowledges that transitions can require fields, but does not disclose other behavioral aspects such as permission requirements, irreversibility, or impact on issue history. This is minimal disclosure 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?
The description is concise at two sentences, with the main action stated first. It is efficient and avoids unnecessary detail, though could benefit from a brief note on prerequisites.
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 description covers the basic function, but lacks context on prerequisites (get_transitions), error handling, and behavioral details. An output schema exists, so return values are covered elsewhere, but overall completeness is adequate with gaps.
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?
The input schema has 100% coverage for all three parameters, providing complete descriptions. The tool's description adds no additional parameter details beyond the general note that fields may be required. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool transitions an issue to a new status using a workflow transition. The verb 'Transition' and 'Executes' are specific. It distinguishes from siblings like get_transitions by implying this tool performs the actual transition, but does not explicitly differentiate.
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 mentions that transitions may require additional fields, giving some guidance. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention the prerequisite of fetching transitions using get_transitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool targets a distinct resource and action; comments, filters, issues, search, and workflow are clearly separated with no overlapping functionality.
All tools follow a consistent pattern: jira_{resource}_{action}_tool (e.g., jira_comment_add_tool, jira_filter_create_tool), making it easy to predict behavior from the name.
19 tools cover major Jira operations (issues, comments, filters, workflow, search, health check) without being overwhelming; a few more could be added but the count is reasonable.
Covers CRUD for comments and filters well, but missing issue delete is a notable gap; workflow and search are adequately covered for common scenarios.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect to Atlassian Jira, Confluence, and Compass to search, create, and manage your work.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Give your AI agents the tools to build, manage, and run automation workflows.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/troylar/jira-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
