# Zendesk tools

> Every Zendesk tool in the developer API, with arguments and examples: search, read, reply to, update and create tickets.

**Needs:** A Zendesk connection. 13 tools.

These tools appear in `GET /v1/tools` only when the API key's MCP server includes a connection of this kind. Call each one with `POST /v1/tools/\<name>`, sending its arguments as a JSON object. See [Calling tools](https://docs.plugsight.app/developers/calling-tools.md) for the request and response format.

| Tool                                                                | What it does                       | Kind   |
| ------------------------------------------------------------------- | ---------------------------------- | ------ |
| [`zendesk_search_tickets`](#zendesk_search_tickets)                 | Search Zendesk tickets             | Read   |
| [`zendesk_get_ticket`](#zendesk_get_ticket)                         | Read a Zendesk ticket              | Read   |
| [`zendesk_get_attachment`](#zendesk_get_attachment)                 | Read a Zendesk attachment          | Read   |
| [`zendesk_find_users`](#zendesk_find_users)                         | Find Zendesk users                 | Read   |
| [`zendesk_list_support_addresses`](#zendesk_list_support_addresses) | List Zendesk support addresses     | Read   |
| [`zendesk_list_ticket_statuses`](#zendesk_list_ticket_statuses)     | List Zendesk ticket statuses       | Read   |
| [`zendesk_get_side_conversations`](#zendesk_get_side_conversations) | Read a ticket's side conversations | Read   |
| [`zendesk_add_comment`](#zendesk_add_comment)                       | Reply or add a note                | Change |
| [`zendesk_update_ticket`](#zendesk_update_ticket)                   | Update a Zendesk ticket            | Change |
| [`zendesk_ticket_stats`](#zendesk_ticket_stats)                     | Zendesk ticket counts              | Read   |
| [`zendesk_list_macros`](#zendesk_list_macros)                       | List Zendesk macros                | Read   |
| [`zendesk_apply_macro`](#zendesk_apply_macro)                       | Apply a Zendesk macro              | Change |
| [`zendesk_create_ticket`](#zendesk_create_ticket)                   | Create a Zendesk ticket            | Change |

Change tools in this group: `zendesk_add_comment`, `zendesk_update_ticket`, `zendesk_apply_macro`, `zendesk_create_ticket`. Check each tool's notes below for what it needs before it runs.

The example requests fill in only the required arguments, with placeholder values.

## zendesk_search_tickets

**Search Zendesk tickets** · Read

Searches tickets with Zendesk search syntax, e.g. "status:open", "requester:jane@acme.com", "assignee:me status\<solved", "tags:refund created>2026-01-01", "updated>24hours", or plain words. Newest updated first. status takes new, open, pending, hold, solved or closed; a custom status (e.g. "Waiting on customer") is custom_status_id:\<id> from zendesk_list_ticket_statuses (a custom status name after status: is translated for you). Dates are yyyy-mm-dd, an ISO time with offset, or relative such as updated>24hours (7d, today and yesterday are translated). Zendesk search returns at most the first 1,000 matches (pages past that fail); for larger sets narrow the query, e.g. by created or updated date, and use zendesk_ticket_stats for counts.

| Argument     | Type    | Required | What it is                                                                                          |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `account`    | string  | No       | Zendesk account id from list_accounts (optional when there's only one)                              |
| `query`      | string  | No       | Zendesk search query (type:ticket is added automatically)                                           |
| `sort_by`    | string  | No       | Field to sort by. One of: `updated_at`, `created_at`, `priority`, `status`. Default `"updated_at"`. |
| `sort_order` | string  | No       | asc or desc. One of: `desc`, `asc`. Default `"desc"`.                                               |
| `limit`      | integer | No       | Most results to return. Default `25`.                                                               |
| `page`       | integer | No       | Page of results, from 1. Default `1`.                                                               |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_search_tickets \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## zendesk_get_ticket

**Read a Zendesk ticket** · Read

Returns a ticket with requester, assignee, CCs and followers, organisation, group, brand, form, satisfaction rating, custom fields (by name, with drop-down option names), its custom status when the account has them (custom_status, e.g. "Waiting on customer"; status is its category) and the full conversation (public replies and internal notes, oldest first). For email, `source` shows which address wrote and which support address received it; `replies_from` is the support address public replies go out from. Side conversations (separate email/Slack threads started from the ticket) aren't included; read them with zendesk_get_side_conversations. Each comment lists its files, numbered from 0, including images pasted into the reply (inline: true, marked in the text as [inline image #N]). Open any of them, e.g. a customer's screenshot or a PDF, with zendesk_get_attachment.

| Argument                | Type    | Required | What it is                                                             |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------- |
| `account`               | string  | No       | Zendesk account id from list_accounts (optional when there's only one) |
| `ticket_id`             | integer | Yes      | Ticket number                                                          |
| `include_comments`      | boolean | No       | Include the ticket's comments. Default `true`.                         |
| `max_chars_per_comment` | integer | No       | Longest comment text returned; longer ones are cut. Default `4000`.    |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_get_ticket \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1}'
```

## zendesk_get_attachment

**Read a Zendesk attachment** · Read

Opens a file from a ticket comment, including images pasted into the reply (screenshots). `comment_id` and `attachment` (the file's index) come from zendesk_get_ticket. Images are returned as images, so you can look at them; PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), HTML, CSV and other text files as text. For a file inside an attached email (.eml) use a path like "1.0". Use mode "base64" for the raw file.

| Argument     | Type              | Required | What it is                                                                                                      |
| ------------ | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `account`    | string            | No       | Zendesk account id from list_accounts (optional when there's only one)                                          |
| `ticket_id`  | integer           | Yes      | Ticket number                                                                                                   |
| `comment_id` | integer           | Yes      | Comment id from zendesk_get_ticket                                                                              |
| `attachment` | integer or string | Yes      | File index from zendesk_get_ticket (e.g. 0), or a path inside an attached email (e.g. "1.0")                    |
| `mode`       | string            | No       | auto: text when the file can be read as text; base64: the raw file. One of: `auto`, `base64`. Default `"auto"`. |
| `max_chars`  | integer           | No       | Truncate extracted text. Default `50000`.                                                                       |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_get_attachment \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1, "comment_id": 1, "attachment": 1}'
```

## zendesk_find_users

**Find Zendesk users** · Read

Finds people (customers or agents) by name, email or phone, with their phone and organisation. Shows up to 50; has_more says when more match, so narrow the search. Use the id for assignee changes.

| Argument  | Type   | Required | What it is                                                             |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `account` | string | No       | Zendesk account id from list_accounts (optional when there's only one) |
| `query`   | string | Yes      | Search text                                                            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_find_users \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "…"}'
```

## zendesk_list_support_addresses

**List Zendesk support addresses** · Read

The email addresses customers write to in this Zendesk account, each with its brand and whether it's the default. A ticket's replies go out from one of these; choose a different one with from_address on zendesk_create_ticket or zendesk_update_ticket.

| Argument  | Type   | Required | What it is                                                             |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `account` | string | No       | Zendesk account id from list_accounts (optional when there's only one) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_list_support_addresses \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## zendesk_list_ticket_statuses

**List Zendesk ticket statuses** · Read

The ticket statuses agents can choose in this Zendesk account, including custom ones such as "Waiting on customer" or "In progress", each with its id, its category (new, open, pending, hold or solved) and whether it's that category's default. Set one with custom_status on zendesk_update_ticket or zendesk_add_comment. Accounts without custom ticket statuses only have the built-in statuses (available: false); use status for those.

| Argument  | Type   | Required | What it is                                                             |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `account` | string | No       | Zendesk account id from list_accounts (optional when there's only one) |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_list_ticket_statuses \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## zendesk_get_side_conversations

**Read a ticket's side conversations** · Read

Side conversations on a ticket: separate email, Slack or child-ticket threads an agent started (e.g. asking a supplier or another team), with every message in each, oldest first. They aren't part of zendesk_get_ticket. Needs Zendesk's Collaboration add-on or Suite Professional or above.

| Argument                | Type    | Required | What it is                                                             |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------- |
| `account`               | string  | No       | Zendesk account id from list_accounts (optional when there's only one) |
| `ticket_id`             | integer | Yes      | Ticket number                                                          |
| `max_chars_per_message` | integer | No       | Longest message text returned; longer ones are cut. Default `4000`.    |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_get_side_conversations \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1}'
```

## zendesk_add_comment

**Reply or add a note** · Change

Adds a public reply (emailed to the requester) or an internal note to a ticket, optionally changing its status (status, or custom_status for one of the account's own statuses such as "Waiting on customer"). Internal notes are only seen by agents. Needs changes allowed for this Zendesk account and MCP server.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument        | Type              | Required | What it is                                                                                                                                                                                                               |
| --------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `account`       | string            | No       | Zendesk account id from list_accounts (optional when there's only one)                                                                                                                                                   |
| `ticket_id`     | integer           | Yes      | Ticket number                                                                                                                                                                                                            |
| `body`          | string            | Yes      | Text of the reply or note                                                                                                                                                                                                |
| `public`        | boolean           | Yes      | true = public reply to the customer, false = internal note                                                                                                                                                               |
| `status`        | string            | No       | Also set the ticket status. One of: `open`, `pending`, `hold`, `solved`.                                                                                                                                                 |
| `custom_status` | string or integer | No       | One of the account's ticket statuses (zendesk_list_ticket_statuses), by its name (any case, e.g. "Waiting on customer") or id. It also sets the ticket's status to that status's category, so don't pass status as well. |
| `confirm`       | boolean           | Yes      | Must be true: the user approved this exact text                                                                                                                                                                          |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_add_comment \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1, "body": "…", "public": true, "confirm": true}'
```

## zendesk_update_ticket

**Update a Zendesk ticket** · Change

Changes a ticket's status, priority, type, assignee, tags or the support address its replies go out from (from_address, which also moves it to that address's brand). For one of the account's own statuses, such as "Waiting on customer", use custom_status instead of status (zendesk_list_ticket_statuses). Needs changes allowed for this Zendesk account and MCP server.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument        | Type              | Required | What it is                                                                                                                                                                                                               |
| --------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `account`       | string            | No       | Zendesk account id from list_accounts (optional when there's only one)                                                                                                                                                   |
| `ticket_id`     | integer           | Yes      | Ticket number                                                                                                                                                                                                            |
| `status`        | string            | No       | Status. One of: `new`, `open`, `pending`, `hold`, `solved`, `closed`.                                                                                                                                                    |
| `custom_status` | string or integer | No       | One of the account's ticket statuses (zendesk_list_ticket_statuses), by its name (any case, e.g. "Waiting on customer") or id. It also sets the ticket's status to that status's category, so don't pass status as well. |
| `priority`      | string            | No       | Priority. One of: `low`, `normal`, `high`, `urgent`.                                                                                                                                                                     |
| `type`          | string            | No       | Type. One of: `question`, `incident`, `problem`, `task`.                                                                                                                                                                 |
| `assignee_id`   | integer           | No       | Agent user id (zendesk_find_users)                                                                                                                                                                                       |
| `add_tags`      | array of string   | No       | Tags to add                                                                                                                                                                                                              |
| `remove_tags`   | array of string   | No       | Tags to remove                                                                                                                                                                                                           |
| `from_address`  | string            | No       | Support address the ticket's emails go out from, e.g. help@brand-b.com (zendesk_list_support_addresses). When the account has several and the user didn't say which, ask them.                                           |
| `confirm`       | boolean           | Yes      | Must be true: the user approved these exact changes                                                                                                                                                                      |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_update_ticket \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1, "confirm": true}'
```

## zendesk_ticket_stats

**Zendesk ticket counts** · Read

Counts tickets for a quick overview: open, pending, on hold, new and unsolved right now, plus created and solved in a period. Narrow it with a Zendesk query, e.g. "tags:refund", "group:Billing" or "assignee:me". For trends, call it for each period.

| Argument  | Type   | Required | What it is                                                             |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `account` | string | No       | Zendesk account id from list_accounts (optional when there's only one) |
| `from`    | string | Yes      | Period start, YYYY-MM-DD                                               |
| `to`      | string | Yes      | Period end, YYYY-MM-DD (inclusive)                                     |
| `query`   | string | No       | Extra Zendesk search filter applied to every count                     |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_ticket_stats \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-11-01", "to": "2026-11-15"}'
```

## zendesk_list_macros

**List Zendesk macros** · Read

The saved replies and actions (macros) this agent can use, optionally filtered by words in the title. Use zendesk_apply_macro to use one.

| Argument  | Type   | Required | What it is                                                             |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `account` | string | No       | Zendesk account id from list_accounts (optional when there's only one) |
| `search`  | string | No       | Words in the macro title                                               |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_list_macros \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## zendesk_apply_macro

**Apply a Zendesk macro** · Change

Applies a macro to a ticket (its reply text, status, tags and other changes). Needs changes allowed for this Zendesk account and MCP server.

> [!IMPORTANT]
> Call it first with `preview` left at `true` to see what the macro would do. To apply it, call again with `"preview": false` and `"confirm": true`. Changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument    | Type    | Required | What it is                                                                       |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `account`   | string  | No       | Zendesk account id from list_accounts (optional when there's only one)           |
| `ticket_id` | integer | Yes      | Ticket number                                                                    |
| `macro_id`  | integer | Yes      | Macro id from zendesk_list_macros                                                |
| `preview`   | boolean | No       | true = only show what would change. Default `true`.                              |
| `confirm`   | boolean | No       | Must be true to apply: the user approved the previewed changes. Default `false`. |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_apply_macro \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1, "macro_id": 1, "preview": false, "confirm": true}'
```

## zendesk_create_ticket

**Create a Zendesk ticket** · Change

Opens a new ticket for a customer (by email; Zendesk creates the person if new), with a first message, priority, type and tags. By default the first message is an internal note, so the customer isn't emailed; set notify_requester: true to email them. It goes out from the account's default support address unless from_address names another (that address's brand is used too). Needs changes allowed for this Zendesk account and MCP server.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument           | Type            | Required | What it is                                                                                                                                                                     |
| ------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `account`          | string          | No       | Zendesk account id from list_accounts (optional when there's only one)                                                                                                         |
| `subject`          | string          | Yes      | Subject                                                                                                                                                                        |
| `body`             | string          | Yes      | The first message                                                                                                                                                              |
| `requester_email`  | string          | Yes      | Requester's email address                                                                                                                                                      |
| `requester_name`   | string          | No       | Requester's name                                                                                                                                                               |
| `notify_requester` | boolean         | No       | true = the first message is a public reply emailed to the requester. Default `false`.                                                                                          |
| `priority`         | string          | No       | Priority. One of: `low`, `normal`, `high`, `urgent`.                                                                                                                           |
| `type`             | string          | No       | Type. One of: `question`, `incident`, `problem`, `task`.                                                                                                                       |
| `tags`             | array of string | No       | Tags                                                                                                                                                                           |
| `assignee_id`      | integer         | No       | Agent user id (zendesk_find_users)                                                                                                                                             |
| `from_address`     | string          | No       | Support address the ticket's emails go out from, e.g. help@brand-b.com (zendesk_list_support_addresses). When the account has several and the user didn't say which, ask them. |
| `confirm`          | boolean         | Yes      | Must be true: the user approved these exact details                                                                                                                            |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/zendesk_create_ticket \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "…", "body": "…", "requester_email": "someone@example.com", "confirm": true}'
```

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)

---

Web version: https://docs.plugsight.app/developers/zendesk-tools
