Jira tools: Extension or legacy?

Glean offers two Jira tools, each differing in capabilities, deployment support, and payload formats.

While you can enable both tools for a single Jira instance, doing so can cause inconsistent behavior. The Jira Extension Tools use Atlassian Document Format (ADF) for rich text, while the legacy Jira Tools use plain text. Enabling both may result in duplicate, overlapping tools such as duplicate Create Issue or Comment options.

tip

For the most consistent user experience, use only one Jira tool per Jira instance. Only enable both if you are actively migrating or strictly require unique capabilities from each tool.

Comparison: Jira tools

Feature	Jira Extension Tools	Legacy Jira Tools
Admin console path	Admin console → Tools → Jira Extension Tools	Admin console → Tools → Jira
Status	Beta	GA (General Availability)
Supported deployments	Jira Cloud only	Jira Cloud, Server, and Data Center
Payload format	ADF (Atlassian Document Format)	Plain text (rest/api/2)
Rich text support	Bold, italic, code blocks, tables, @mentions	Plain text only
User mentions	Native Atlassian account ID @mentions	Not supported
Tool count	15+ tools (Create, Edit, Search, Comment, JSM)	4 core tools
Multi-instance support	One set of tools per Jira instance	One set of tools per Jira instance

Atlassian Document Format (ADF)

ADF is a structured JSON schema that Jira Cloud uses internally to represent rich text in fields like description, comment, and other rich-text custom fields. Instead of sending a plain string, the tool sends a JSON object:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This is a " },
        { "type": "text", "text": "bold", "marks": [{ "type": "strong" }] },
        { "type": "text", "text": " comment." }
      ]
    }
  ]
}

Why ADF matters (API v3 vs. API v2)

Jira Cloud's REST API v3 used by the Jira Extension Tools strictly requires ADF for all rich text fields. If you send a plain text string to an API v3 description or comment field, the request will either:

• Fail silently: The field saves as entirely empty.
• Throw a 400 Bad Request error: The API rejects the payload completely.

The legacy Jira Tools rely on REST API v2. Because API v2 accepts raw strings, they remain compatible with Jira Server and Data Center, but they cannot render rich formatting or native elements on Jira Cloud.

Choose the right Jira tools

To determine which Jira tools fit your environment, evaluate your deployment type and functional requirements:

Use Jira Extension Tools if:

• Your Jira deployment is Jira Cloud.
• You require rich text formatting like code blocks, tables, lists in tickets.
• You are building AI agents that must generate structured content.
• You need native @mention support to notify specific team members.

Use legacy Jira Tools if:

• Your Jira deployment is a server or data center.
• Your organization requires GA-stable integrations with zero beta risk.
• Your workflows only require plain text descriptions and comments.

note

Enabling both tools for the same Jira instance will expose duplicate tools to users and agents. While this will not break the integration, it introduces inconsistent behavior and user confusion depending on which tool is triggered. Stick to a single tool per Jira instance unless you are actively migrating.

ADF in practice: How the LLM processes payloads

When a user instructs Glean to create a Jira ticket with a code block in the description, the LLM automatically constructs the complex ADF JSON payload behind the scenes. Administrators and users do not need to write ADF manually.

However, the LLM will only successfully generate and render ADF if the following prerequisites are met:

1. Tool authorization: The Jira Extension Tools must be enabled.
2. Surface availability: The specific tool must be enabled for the target surface like Agents, Assistant, or both.
3. Field compatibility: The target field in Jira must be configured as a rich text field (data type: doc).

note

For standard Jira plain text fields (data type: string), ADF is bypassed. The Jira Extension Tools automatically detect the field type and safely transmit standard strings instead.

Setting up Jira Extension Tools

1. Navigate to Glean Admin console.
2. Click Platform → Tools.
3. Click Add tools and search for Jira Extension Tools.
4. Complete OAuth authentication using a Jira Cloud admin account.
5. Under Edit settings, enable the specific tools you need for Agents and/or Assistant.

For multi-instance setups (more than one Jira Cloud org), add a separate Jira Extension Tools instance for each Jira instance and name them clearly, for example, "Jira Extension — Engineering" and "Jira Extension — Support".

Troubleshooting

For example, @john.doe shows as text instead of a real mention.

Cause: The legacy Jira Tools don't support ADF mentions. The Jira Extension Tools resolve @mentions to Atlassian account IDs automatically.

Fix: Use the Jira Extension Tools.

Cause: A plain text string was sent to a REST API v3 rich text field.

Fix: Confirm the Jira Extension Tools are enabled. If the error persists, check whether the target field is a custom field of type string — those require plain text and reject ADF.

Cause: The Jira Extension Tools are Cloud only.

Fix: Use the legacy Jira Tools for Server/DC deployments. Rich formatting isn't available on Server/DC.

For any further questions or issues, reach out to the Glean support team.