Tools Reference

Complete reference for all AgentGate tools. Tools in the Read category work immediately. Tools in the Write category create pending changes that require human approval before they're applied to Jira.

Session

prime

Get project status: in-progress issues, pending changes, failed changes, and contextual tips.

Parameter	Type	Required	Description
project_key	string	No	Override default project

Example:

prime()
prime(project_key: "OTHER")

---

Reading Issues

issues_list

Search issues with filters or raw JQL. Returns a paginated list of matching issues.

Parameter	Type	Required	Description
project_key	string	No	Override default project
status	string	No	Filter: "open", "in_progress", "done", or an exact status name
assignee	string	No	Filter: "me", "unassigned", or a display name
labels	string[]	No	Filter by labels (OR logic)
parent	string	No	Filter by parent issue key
type	string	No	Filter by issue type: "Bug", "Task", "Story", "Epic"
priority	string	No	Filter: "Highest", "High", "Medium", "Low", "Lowest"
jql	string	No	Raw JQL query (overrides all other filters)
limit	number	No	Max results (default 50)
next_page_token	string	No	Cursor for next page

Examples:

issues_list(status: "in_progress")
issues_list(assignee: "me", priority: "High")
issues_list(jql: "project = PROJ AND text ~ 'marketplace' ORDER BY updated DESC")
issues_list(parent: "PROJ-100")
issues_list(labels: ["backend", "urgent"])

issues_show

Get full details of a single issue including description, status, comments, links, and attachments.

Parameter	Type	Required	Description
key	string	Yes	Issue key (e.g., "PROJ-123")

issues_children

Get child issues of a parent. Optionally recurse the full tree.

Parameter	Type	Required	Description
key	string	Yes	Parent issue key
recursive	boolean	No	Fetch full descendant tree (default: false)

issues_context

Get complete context for an issue: parent chain, siblings, children, links, and recent comments. Useful for understanding an issue in its full project context.

Parameter	Type	Required	Description
key	string	Yes	Issue key
children_depth	number	No	Depth of children to fetch (default: 1)

issues_transitions

Get available workflow transitions for an issue. Use this before issues_transition to see what status changes are valid.

Parameter	Type	Required	Description
key	string	Yes	Issue key

workflow_describe

Describe the project's workflow: issue types and their status transitions.

Parameter	Type	Required	Description
project_key	string	No	Override default project

issues_attachments_download

Download attachments from an issue.

Parameter	Type	Required	Description
key	string	Yes	Issue key
attachment_id	string	No	Specific attachment ID (downloads all if omitted)

---

Writing (Pending Approval)

All write operations create pending changes. Nothing is applied to Jira until a human approves.

changes_create

Propose creating, updating, transitioning, or deleting an issue.

Parameter	Type	Required	Description
type	string	Yes	"create", "update", "transition", or "delete"
issue_key	string	For update/transition/delete	Target issue key
project_key	string	No	Override default project (for create)
proposed	object	Yes	Proposed field values (see below)
reason	string	No	Human-readable reason for the change

Proposed fields for create:

Field	Type	Description
summary	string	Issue title
issueType	string	"Bug", "Task", "Story", "Epic", etc.
description	string	Issue description
priority	string	"Highest", "High", "Medium", "Low", "Lowest"
labels	string[]	Labels to set
parent	string	Parent issue key
assignee	string	Display name, or null to unassign
children	object[]	Child issues to create atomically (each has summary, issueType, etc.)
links	object[]	Issue links (type, direction, targetKey)

Proposed fields for update: Same as create — only include fields you want to change.

Examples:

// Create a simple task
changes_create(
  type: "create",
  proposed: {
    summary: "Fix login timeout",
    issueType: "Bug",
    priority: "High"
  },
  reason: "Reported by 3 users this week"
)

// Create Epic with children
changes_create(
  type: "create",
  proposed: {
    summary: "Auth Overhaul",
    issueType: "Epic",
    children: [
      { summary: "Implement OAuth 2.0", issueType: "Story" },
      { summary: "Add password reset", issueType: "Story" },
      { summary: "Write auth tests", issueType: "Task" }
    ]
  },
  reason: "Q2 security initiative"
)

// Update an issue
changes_create(
  type: "update",
  issue_key: "PROJ-123",
  proposed: { priority: "Highest", labels: ["urgent"] },
  reason: "Customer escalation"
)

// Delete an issue
changes_create(
  type: "delete",
  issue_key: "PROJ-999",
  reason: "Duplicate of PROJ-123"
)

comment

Add a comment to an issue.

Parameter	Type	Required	Description
key	string	Yes	Issue key
body	string	Yes	Comment text

issues_transition

Move an issue to a new status.

Parameter	Type	Required	Description
key	string	Yes	Issue key
status	string	Yes	Target status name (e.g., "In Progress", "Done")
reason	string	No	Reason for the transition

issues_assign

Assign an issue to a user.

Parameter	Type	Required	Description
key	string	Yes	Issue key
assignee	string	Yes	Display name, "me", or null to unassign

issues_attachments_upload

Upload a file attachment to an issue (max 2MB).

Parameter	Type	Required	Description
key	string	Yes	Issue key
file_path	string	Yes	Path to the file to upload

---

Managing Changes

changes_list

List changes filtered by status.

Parameter	Type	Required	Description
status	string	No	"pending", "approved", "rejected", "failed"

changes_show

View details of a specific change, including the proposed diff against current Jira state.

Parameter	Type	Required	Description
id	string	Yes	Change ID (e.g., "chg-abc123")

changes_update

Modify a pending change before it's reviewed. Useful for correcting mistakes without cancelling and re-proposing.

Parameter	Type	Required	Description
id	string	Yes	Change ID
proposed	object	No	Updated proposed fields
comment	object	No	Updated comment ({ body: "..." })
reason	string	No	Updated reason

Updating comments

For pending comment changes, use the comment parameter (not proposed):

changes_update(id: "chg-xxx", comment: { body: "Corrected text" })

changes_cancel

Cancel a pending change. The change is discarded and never applied.

Parameter	Type	Required	Description
id	string	Yes	Change ID