Skip to content

Core issues & search

These tools let your agent find, read, and manage Jira issues on your behalf, plus look up reference data — valid statuses, priorities, fields, and so on — that's useful when searching or filling in a request. Everything here runs under your configured Jira Personal Access Token, so the agent can only do what your own Jira permissions allow. None of these tools require admin access.

Example prompts

  • "What's the status of PROJ-456?"
  • "Find all open bugs assigned to me in the PROJ project."
  • "Show me every issue in PROJ that's still In Progress and was updated in the last week."
  • "Create a bug in PROJ titled 'Login page throws 500' with the steps to reproduce in the description."
  • "Add a comment to PROJ-456 saying the fix is deployed to staging."
  • "What's the comment history on PROJ-456?"
  • "What are the next steps available on PROJ-456?"
  • "Move PROJ-456 to Done."
  • "Assign PROJ-456 to jsmith." / "Unassign PROJ-456."
  • "Change the priority on PROJ-456 to High."
  • "What projects can I see?"
  • "What priorities are available on this instance?"
  • "What custom fields does this Jira instance have, and what's the field ID for 'Story Points'?"
  • "What does 'epic' get called on this instance?"
  • "Help me build a query for issues in PROJ that are unresolved and due this week."

What's available

Issues

Tool What it does
get_issue Look up a single issue by key.
search_issues Search issues using JQL (Jira's query language) — the preferred way to search.
search_issues_get Search issues using JQL via a URL-friendly alternative to search_issues.
create_issue Create a new Jira issue.
add_comment Add a comment to an issue.
get_issue_comments Get comments on an issue (paginated; use startAt/maxResults to page through all of them).
get_transitions List the workflow moves available on an issue right now.
transition_issue Move an issue to a new status.
update_issue Update fields on an issue.
assign_issue Assign an issue to a user by username, or unassign it.
list_projects List all Jira projects visible to you.
get_search_error_lookup Look up a leftover search error message from earlier in the session, if one exists.

Reference data & JQL helpers

Tool What it does
get_jql_autocomplete_data Get valid JQL field names, function names, and reserved words for building queries.
get_jql_suggestions Get valid values for a specific JQL field (e.g. priority), optionally filtered.
get_search_limits Get this instance's JQL search limits (max result window, etc.).
list_priorities List issue priorities available on this instance.
get_priority Look up a single issue priority by ID.
list_resolutions List issue resolutions available on this instance.
get_resolution Look up a single issue resolution by ID.
list_statuses List issue statuses available on this instance, each with its status category.
get_status Look up a single issue status by ID or name.
list_status_categories List the To Do / In Progress / Done groupings that statuses belong to.
get_status_category Look up a single status category by ID or key.
get_security_level Look up a single issue-level security level by ID.
list_fields List all system and custom fields, including custom field IDs for update_issue.
get_projects_picker Search for projects by partial name — a quick typeahead-style lookup.
list_workflows List all workflows defined on this instance.
list_terminology_entries List this instance's custom terminology renamings, if any are configured.
get_terminology_entry Look up a single custom terminology renaming (e.g. for "epic") by its original name.
update_terminology_entries Rename "Epic"/"Sprint" instance-wide (e.g. to "Theme"/"Iteration").

API documentation lookup

Tool What it does
get_api_references Look up which Jira API endpoints Alces has implemented. Mostly used internally by the agent, not something you'd typically ask for by name.

Things to know

  • Search always uses JQL, Jira's query language. If you don't know JQL, just describe what you want in plain language and the agent builds the query for you.
  • Before moving an issue to a new status, the agent looks up available transitions first with get_transitions — transition IDs aren't fixed across projects and workflows, so it can't guess one and calls transition_issue only once it knows a valid ID.
  • Responses are trimmed to the fields that matter (status, assignee, summary, and so on), not Jira's full raw payload. If you need a field that's missing, ask for it and the agent can widen the request.
  • A few tools, like get_search_error_lookup and get_api_references, are internal helpers the agent calls automatically as needed — you generally don't need to ask for them by name.

See docs/api-catalog.md for the complete technical reference (every field, every parameter). For errors, see Troubleshooting.