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. Exactly one of the 32 tools here requires JIRA_ADMIN_TOKEN — list_workflows, the instance-wide workflow catalogue, marked [ADMIN] in the table below; a real Jira DC refuses it to a plain licensed user. Nothing else on this page is admin-gated, and none of these tools require a confirm:true argument.

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."
  • "What do I need to fill in to create a Bug in PROJ?"
  • "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.
get_issue_creation_guide Look up an issue type by name or ID and get everything you can set when creating one — which fields are required and what values they accept — in a single call, before create_issue.
create_issue Create a new Jira issue. Anything beyond project, summary, issue type and description — required custom fields, assignee, priority, labels, components, a sub-task's parent — goes in the fields argument, keyed by field ID.
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; ask to also see each transition's required/optional fields and their allowed values (includeFields) if you want to know what a move will ask for before making it.
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 [ADMIN] 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.
  • Some calls are now refused before they reach Jira. transition_issue and update_issue look the relevant screen up first and stop if what you asked for can't work. This is a change in behaviour: a call that used to be sent to Jira may now come back as a refusal instead.
  • transition_issue refuses if the transition isn't one the issue currently offers (the message lists the ones that are), and refuses if the transition's screen has a required field you didn't supply and the issue doesn't already have a value for — naming the field and listing its allowed values. Previously Jira accepted that case and left the issue half-finished, with the required field still empty. A required field the issue already carries is left alone: Jira keeps the existing value, so nothing ends up half-finished and there's nothing to re-supply. Three fields are always asked for, because they request a new entry rather than a value: a comment, a worklog, or an attachment. A comment you can give the agent directly; a transition screen that demands a worklog or an attachment can only be pushed through with skipFieldValidation: true, after which you'd log the work or attach the file separately.
  • update_issue refuses if a field you're setting isn't on the issue's Edit screen, and tells you what to do instead: resolution is never on an Edit screen by design (set it with transition_issue on a resolving transition), and any other missing field has to be added to the Edit screen by a Jira administrator first. Previously this came back as a confusing Jira
    1. If Jira reports that nothing on the issue is editable, the refusal says so instead — that means the account lacks the Edit Issues permission, or the issue's status is non-editable (closed issues usually are), and no screen change would help.

If you'd rather skip the check, ask the agent to pass skipFieldValidation: true — that drops the pre-check (and the extra lookup or two it costs: update_issue makes one, transition_issue one plus a second read of the issue when a required screen field wasn't supplied) and sends the request straight to Jira, exactly as before. If the pre-check's own lookup fails, the error says so explicitly and points at that same option. - 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.