MCP tools reference

This article documents the tools exposed by the LiveAgent MCP server, including the exact parameters each tool accepts and the exact fields it returns. A personal MCP connection offers every tool the agent's role has the privileges for, while an AI agent MCP connection offers only the tools selected for that AI agent.

Every tool returns a single JSON object. A call that succeeds returns the documented response, while a tool that has nothing to return answers with {"success": true}. A call that fails or is refused returns an error object, e.g. {"success": false, "error": "Not authorized to read this ticket"} or {"code": -32602, "message": "Tool is not available on this account: reply_via_whatsapp"}. That usually happens when the tool is not enabled for the AI agent, the agent's role lacks a privilege the tool needs, the tool is not available on the account, a usage limit is reached, etc.

Read-only tools

These tools look up tickets, account data and knowledge base content without changing anything.

Search tickets (search_tickets)

Retrieves the tickets that match the given filters, most recently changed first. Each call returns up to 10 tickets by default, or up to 50 with limit — page through the rest with nextCursor.

Parameters

Parameter	Required	Description
status	No	Return only tickets in the selected statuses: `new`, `open`, `answered`, `resolved`, `postponed`, `chatting` or `calling`. Several statuses can be combined. When omitted, every ticket except deleted, closed and spam tickets is returned.
departmentId	No	Return only tickets in the selected department, as returned by `list_departments`. When omitted, tickets of every department are returned.
agentId	No	Return only tickets assigned to the selected agent, as returned by `list_agents`. When omitted, tickets of every agent are returned, assigned or not.
query	No	Return only tickets whose content matches this full-text phrase. When omitted, no text matching is applied.
limit	No	Maximum number of tickets to return, `10` by default, up to a maximum of `50`. A higher value is quietly reduced to `50` rather than rejected.
cursor	No	Continue from a previous call by passing the `nextCursor` it returned. When omitted, the first page is returned.

Returns

Field	Description
tickets[].id	Internal ticket ID — this is what the other ticket tools expect as `ticketId`.
tickets[].code	Short human-readable ticket code, e.g. ABC-DEFGH-123, commonly shown in the agent panel.
tickets[].subject	Ticket subject.
tickets[].status	Current ticket status, one of the values the `status` filter accepts, or `init` when no `status` filter is given. Tickets in `closed`, `deleted` or `spam` status are never returned.
tickets[].departmentId	ID of the department the ticket belongs to.
tickets[].assignedAgentId	ID of the agent the ticket is assigned to. `null` when the ticket is unassigned.
totalCount	Total number of matching tickets, not just those on this page.
nextCursor	Cursor referring to the next page — pass it as `cursor` to retrieve that page. `null` when there are no more tickets.

Notes:

There is no date, tag, customer or channel filter, and the sort order cannot be changed. To narrow the results by tag, channel or date, check each ticket with get_ticket_metadata, which returns its tags, channel, createdAt and lastActivityAt.
The department and the assigned agent come back as IDs only — look up their names with list_departments and list_agents.

Get ticket metadata (get_ticket_metadata)

Retrieves a ticket's properties: status, channel, department, assignment, tags and timestamps.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns

Field	Description
id	Internal ticket ID.
code	Short human-readable ticket code, e.g. ABC-DEFGH-123, commonly shown in the agent panel.
subject	Ticket subject.
status	Current ticket status: `new`, `open`, `answered`, `resolved`, `postponed`, `chatting`, `calling`, `closed`, `deleted`, `spam` or `init`.
channel	Channel the ticket was created from: `email`, `contact_button`, `contact_form`, `invitation`, `call`, `call_button`, `facebook`, `facebook_message`, `twitter`, `forum`, `suggestion`, `instagram`, `instagram_mention`, `viber`, `whatsapp` or `telegram`. `null` when the channel was not recorded.
departmentId	ID of the department the ticket belongs to.
departmentName	Name of the department the ticket belongs to.
assignedAgentId	ID of the agent the ticket is assigned to. `null` when the ticket is unassigned.
assignedAgentName	Assigned agent's display name. `null` when the ticket is unassigned.
tags	Names of the tags currently attributed to the ticket.
createdAt	Datetime when the ticket was created, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.
lastActivityAt	Datetime when the ticket last changed, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.

Get ticket messages (get_ticket_messages)

Retrieves the messages of a ticket, including internal notes by default. Each call returns up to 20 messages — page through the rest with nextCursor.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
since	No	Continue from a previous call by passing the `nextCursor` it returned. When omitted, the first page is returned: the newest messages, or the oldest ones when `order` is `asc`.
types	No	Return only messages of the selected types: `email`, `chat`, `whatsapp`, `instant_message`, `note` or `legacy_message`. When omitted, messages of every type are returned, notes included.
dateFrom	No	Return only messages added at or after this time, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00Z`. When omitted, there is no lower time limit.
dateTo	No	Return only messages added at or before this time, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00Z`. When omitted, there is no upper time limit. A `dateTo` earlier than `dateFrom` is rejected.
order	No	Sort the messages by when they were added: `desc` lists the newest first and `asc` the oldest first. `desc` by default. When `since` is used, the cursor keeps its own order, and a conflicting `order` is rejected.

Returns

Field	Description
messages[].id	Message ID.
messages[].text	Message body as plain text.
messages[].author	Who added the message: `agent`, `customer`, `ai_agent`, `rule` or `external_app`.
messages[].authorId	ID of the author.
messages[].type	Message type: `email`, `chat`, `whatsapp`, `instant_message`, `note` or `legacy_message`.
messages[].createdAt	Datetime when the message was added, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.
messages[].attachments[]	Attachments of the message, each with `id`, `fileName`, `contentType`, `size` (bytes) and `downloadUrl`. The file content itself is never included in the result. `downloadUrl` is a single-use link that stops working after the first successful download or after 3 hours — call the tool again to get a fresh one.
messages[].recipients	Email addressing of the message: an object with `from`, `to`, `cc` and `replyTo`, where `from` is a single address and the others are lists of addresses, each with `name` and `email`. `null` for message types other than `email`. A `null` `from` or an empty list means the address was not recorded on the message, not that there was none. Bcc addresses are never returned.
nextCursor	Cursor referring to the last returned message — pass it as `since` to retrieve the next page. It is set whenever the page holds any message, the last page included, so the end is reached when a call returns an empty `messages` list and `null` here.

Get ticket notes (get_ticket_notes)

Retrieves the internal notes of a ticket, newest first. Each call returns up to 20 notes — page through the rest with nextCursor.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
since	No	Continue from a previous call by passing the `nextCursor` it returned. When omitted, the first page is returned: the newest notes.

Returns

Field	Description
notes[].noteId	Note ID.
notes[].text	Note body as plain text.
notes[].author.id	ID of the author.
notes[].author.name	Author display name.
notes[].author.type	Who added the note: `agent`, `ai_agent`, `rule` or `external_app`.
notes[].createdAt	Datetime when the note was added, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.
nextCursor	Cursor referring to the last returned note — pass it as `since` to retrieve the next page. It is set whenever the page holds any note, the last page included, so the end is reached when a call returns an empty `notes` list and `null` here.

Get ticket summary (get_ticket_summary)

Retrieves the AI-generated summary of a ticket. This tool cannot be selected for an AI agent, so it is available through personal MCP connections only.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns

Field	Description
summary	Summary as plain text. `null` when the ticket has no summary yet.
generatedAt	Datetime when the summary was last generated, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`. `null` when the ticket has no summary yet.

Get tags (get_tags)

Lists every tag in the account.

Parameters: none.

Returns

Field	Description
tags[].id	Tag ID, a 4-character alphanumeric code — this is what `add_tags_to_ticket` and `remove_tags_from_ticket` expect in `tags`, along with tag names.
tags[].name	Tag name as shown in the agent panel.
tags[].isPublic	Denotes whether the tag is visible outside the agent panel: `true` for public tags, `false` for internal ones.

Get ticket field definitions (get_ticket_field_definitions)

Lists the custom ticket fields configured for the account, with the metadata needed to fill them in correctly. Archived definitions are left out.

Parameters: none.

Returns

Field	Description
definitions[].definitionId	Numeric definition ID — this is what `set_ticket_field_value` expects as `definitionId`.
definitions[].code	Stable string code of the field — this is what `set_ticket_field_value` expects as `definitionCode`, instead of the numeric ID.
definitions[].name	Field label as shown in the agent panel.
definitions[].type	Field type, which decides the value parameter you use when writing: `BOOLEAN`, `STRING`, `POSTAL_ADDRESS`, `LIST_SINGLE_VALUED` or `LIST_MULTI_VALUED`.
definitions[].description	Help text configured for the field, as shown beside it in the agent panel. An empty string when none is set.
definitions[].checkboxDescription	Label shown next to the checkbox. Present on `BOOLEAN` definitions only.
definitions[].validation	Rule a value has to satisfy, present on `STRING` definitions only. Either `{"kind": "PREDEFINED", "format": …}` with one of `ALPHANUMERIC`, `ALPHANUMERIC_SPACE`, `DATE`, `DATE_REVERSE`, `DECIMAL`, `EMAIL`, `WHOLE_NUMBER`, `NUMERIC_STRING`, `INTERNATIONAL_PHONE`, `US_PHONE`, `IP_ADDRESS`, `TEXT`, `TIME` or `URL`; or `{"kind": "CUSTOM", "regex": …}` carrying a regular expression of your own.
definitions[].availableValues	Option labels a value can be chosen from. Present on `LIST_SINGLE_VALUED` and `LIST_MULTI_VALUED` definitions only.

Get ticket field values (get_ticket_field_values)

Retrieves all custom field values stored on one ticket, each returned together with its definition metadata. Values whose definition has since been archived are still returned.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns

Field	Description
values[].fieldId	ID of this stored value — this is what `delete_ticket_field_value` expects as `fieldId`.
values[].definitionId	Numeric ID of the definition this value belongs to.
values[].code	String code of the definition this value belongs to.
values[].name	Field label as shown in the agent panel.
values[].type	Field type, using the same values as `get_ticket_field_definitions`.
values[].value	The stored value, typed after the field: boolean for `BOOLEAN`; string for `STRING` and `LIST_SINGLE_VALUED`; array of strings for `LIST_MULTI_VALUED`; object with `street`, `district`, `city`, `state`, `postalCode` and `country` for `POSTAL_ADDRESS`.

List agents (list_agents)

Lists the agents in the account. Use it to find the agent ID for assign_ticket, or to turn an assignedAgentId into a name and email address.

Parameters

Parameter	Required	Description
search	No	Return only agents whose name or email address contains this text. When omitted, all agents are returned.

Returns

Field	Description
agents[].id	Agent ID — this is what `assign_ticket` expects as `agentId`.
agents[].name	Agent display name.
agents[].email	Agent email address. `null` when the agent has none.

List departments (list_departments)

Lists the departments in the account. Use it to find the department ID for transfer_ticket, or to turn a departmentId into a name.

Parameters

Parameter	Required	Description
search	No	Return only departments whose name contains this text. When omitted, all departments are returned.

Returns

Field	Description
departments[].id	Department ID — this is what `transfer_ticket` expects as `departmentId`.
departments[].name	Department name.

List knowledge bases (list_knowledge_bases)

Lists the knowledge bases in the account. None of the knowledge base tools assume a default knowledge base, so start here and pass the knowledgeBaseId you get from it.

Parameters: none.

Returns

Field	Description
knowledgeBases[].id	Knowledge base ID — this is what the other knowledge base tools expect as `knowledgeBaseId`.
knowledgeBases[].name	Knowledge base name.
knowledgeBases[].isActive	Denotes whether the knowledge base is switched on: `true` for an active one, `false` for a disabled one.

List knowledge base categories (list_kb_categories)

Lists the categories of a knowledge base as a nested tree — the full subtree under a parent category, or the whole knowledge base when no parent is given.

Parameters

Parameter	Required	Description
knowledgeBaseId	Yes	ID of the knowledge base to read, as returned by `list_knowledge_bases`.
parentCategoryId	No	Return only the subtree under this category, as returned by `list_kb_categories`. When omitted or `0`, the whole tree is returned.

Returns

Field	Description
categories[].id	Category ID — this is what the other knowledge base tools expect as `categoryId` or `parentCategoryId`.
categories[].name	Category name.
categories[].parentCategoryId	ID of the parent category. `0` for a root-level category.
categories[].visibility	Who can see the category: `public` or `internal`.
categories[].position	0-based position among its siblings.
categories[].children[]	Child categories, each with the same fields.
count	Total number of categories returned, children included.

Search knowledge base articles (search_kb_articles)

Searches a knowledge base for articles matching a keyword or phrase — to find an article that answers a customer's question, or to check whether one already exists. Each call returns up to 10 articles by default, or up to 50 with limit, with no way to page further.

Parameters

Parameter	Required	Description
query	Yes	Return only articles whose title or content matches this keyword or phrase.
knowledgeBaseId	Yes	ID of the knowledge base to search, as returned by `list_knowledge_bases`.
categoryId	No	Return only articles in this category and its sub-categories, as returned by `list_kb_categories`. When omitted, the whole knowledge base is searched.
limit	No	Maximum number of articles to return, `10` by default, up to a maximum of `50`. A higher value is quietly reduced to `50` rather than rejected.

Returns

Field	Description
articles[].id	Article ID — this is what `get_kb_article` and `update_kb_article` expect as `articleId`.
articles[].title	Article title.
articles[].url	Public article URL.
articles[].summary	Start of the article as plain text, cut to at most 300 characters on a word boundary and ended with an ellipsis when longer.
articles[].description	Meta description, as shown in search engine results.
articles[].categoryId	ID of the category the article sits in.
articles[].knowledgeBaseId	ID of the knowledge base the article belongs to.
articles[].status	Publication state: `published` or `draft`.
articles[].visibility	Who can see the article: `public` or `internal`.

Note: the full article body is not returned — fetch it with get_kb_article.

Get knowledge base article (get_kb_article)

Retrieves an article's full content, by its ID or by the 6-digit code in its URL.

Parameters

Parameter	Required	Description
articleId	One of the two	ID of the article to read, as returned by `search_kb_articles`. Supply either this or `urlCode`. When both are given, `articleId` is used.
urlCode	One of the two	The 6-digit code in the article URL, e.g. `397021` in `.../397021-article-title`.

Returns

Field	Description
id	Article ID — this is what `update_kb_article` expects as `articleId`.
title	Article title.
url	Public article URL.
body	Full article body as HTML.
plainText	The same body content as plain text.
description	Meta description, as shown in search engine results.
keywords	Meta keywords set on the article.
categoryId	ID of the category the article sits in.
knowledgeBaseId	ID of the knowledge base the article belongs to.
status	Publication state: `published` or `draft`.
visibility	Who can see the article: `public` or `internal`.
position	0-based position within its category.
createdAt	Datetime when the article was created, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.
changedAt	Datetime when the article was last changed, as an RFC 3339 timestamp, e.g. `2026-07-08T10:00:00+00:00`.
attachments[]	Attachments of the article, each with `id`, `fileName`, `contentType`, `size` (bytes), `isInline` and `downloadUrl`, where `isInline` is `true` for an image embedded in the body. The file content itself is never included in the result. `downloadUrl` is a single-use link that stops working after the first successful download or after 3 hours — call the tool again to get a fresh one.

Write/manage tools

These tools change tickets or the knowledge base, or send the customer a reply.

Reply via email (reply_via_email)

Sends an email reply to the customer on a ticket that is answered over email.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d. The ticket's `channel` must be `email`, `contact_button`, `contact_form`, `invitation`, `call` or `call_button` — the channels the agent panel answers from its email reply box. A ticket on any other channel, or with no recorded channel, is rejected.
text	Yes	Reply body sent to the customer, as plain text unless `format` is `html`.
format	No	Send `text` in the selected format: `plain` as plain text or `html` as an HTML body. `plain` by default. Use `html` only when `text` really is HTML markup. A body that cannot be parsed is rejected before anything is queued.
subject	No	Subject to send the reply under, up to 255 characters. A longer subject is quietly shortened to 255 characters rather than rejected. When omitted, the reply uses the subject the agent panel's reply box pre-fills for the ticket.
to	No	Send the reply to these email addresses, used exactly as given. When omitted, the reply goes to the same recipients the agent panel's Reply button would use.
cc	No	Copy the reply to these email addresses, used exactly as given, also when `to` is omitted. An address that is already in `to` is dropped from Cc. When omitted, the reply has no Cc.

Returns

Field	Description
answerId	ID of the reply that was queued for delivery.

Notes:

Deleted and closed tickets are rejected. A resolved ticket is accepted unless the account does not allow a new reply to reopen a resolved ticket.
When to is omitted, the ticket needs an email thread or an author email address to reply to. A ticket with neither — typically a call — is rejected until you supply to.
Every address has to be a valid email address, and the total number of recipients is capped by the account's recipient limit.
Attachments are not supported, and neither are Bcc or a different sender — the reply is sent from the outgoing email account LiveAgent selects for the ticket.
A successful result means the reply was stored and queued. Actual delivery happens afterwards and its outcome is not reported by this tool.
For an AI agent the tool is locked to the ticket the run was started for, so it cannot reply on a different ticket found via search_tickets. Sending the reply does not end the run.

Reply via WhatsApp (reply_via_whatsapp)

Sends a text reply to the customer on a WhatsApp ticket. The tool is available only on accounts with the WhatsApp add-on — on other accounts it is neither offered nor callable.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d. The ticket's `channel` must be `whatsapp`. Any other channel is rejected.
text	Yes	Reply text sent to the customer. WhatsApp enforces a maximum message length; an over-length reply is rejected with an error stating the limit.

Returns

Field	Description
messageId	ID of the reply that was queued for delivery.

Notes:

The reply must fall inside the 24-hour WhatsApp customer service window — that is, within 24 hours of the customer's last message. Outside it, the call fails and the fallback is an approved WhatsApp template sent by a human agent, or an internal note.
Attachments are not supported — the reply is text only.
A successful result means the reply was stored and queued. Actual delivery to WhatsApp happens afterwards and its outcome is not reported by this tool.
For an AI agent the tool is locked to the ticket the run was started for, so it cannot reply on a different ticket found via search_tickets. Sending the reply does not end the run.

Add note (add_note)

Adds an internal note to a ticket. Notes are visible to agents only, never to the customer.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
text	Yes	Note body to store, as plain text.
reopenTicket	No	Reopen the ticket when it is already resolved. `false` by default, so a resolved ticket stays resolved.

Returns

Field	Description
noteId	ID of the created note.

Note: attachments cannot be added through this tool.

Add tags to ticket (add_tags_to_ticket)

Adds one or more existing tags to a ticket.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
tags	Yes	One or more tag IDs (4-character alphanumeric) or tag names, as returned by `get_tags`. Unknown tags are rejected — the tool does not create them.

Returns: {"success": true}.

Remove tags from ticket (remove_tags_from_ticket)

Removes one or more tags from a ticket.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
tags	Yes	One or more tag IDs or tag names to remove, in the same form `add_tags_to_ticket` accepts. Unknown tags are rejected.

Returns: {"success": true}.

Set ticket field value (set_ticket_field_value)

Sets one custom field value on a ticket: creates the value when it is missing, updates it when it differs, and leaves it unchanged when it already matches.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
definitionId	One of the two	Numeric definition ID, as returned by `get_ticket_field_definitions`. Supply either this or `definitionCode` — never both, never neither.
definitionCode	One of the two	Stable string code of the field, as returned by `get_ticket_field_definitions`.
booleanValue	Exactly one	Value to store on a `BOOLEAN` field: `true` or `false`.
stringValue		Value to store on a `STRING` field, up to 255 characters. A longer value is rejected. It also has to satisfy the definition's `validation` rule.
singleValue		Value to store on a `LIST_SINGLE_VALUED` field: one label from the definition's `availableValues`.
multiValue		Values to store on a `LIST_MULTI_VALUED` field: any number of labels from the definition's `availableValues`.
postalAddress		Value to store on a `POSTAL_ADDRESS` field: an object with the keys `street`, `district`, `city`, `state`, `postalCode` and `country`.

Returns

Field	Description
fieldId	ID of the stored value — this is what `delete_ticket_field_value` expects as `fieldId`.
action	What the call did: `created`, `updated` or `unchanged`.

Notes:

The value parameter must match the field's type — a value parameter for any other type is rejected.
Archived definitions are rejected.
If a ticket holds more than one value for the same definition, the call fails and asks you to delete the extra values with delete_ticket_field_value first.

Delete ticket field value (delete_ticket_field_value)

Removes one stored custom field value from a ticket. Works even when the field's definition has been archived.

Parameters

Parameter	Required	Description
fieldId	Yes	ID of the stored value to delete, as returned by `get_ticket_field_values`. This is the value's own ID, not the definition ID.

Returns

Field	Description
fieldId	ID of the value that was deleted.

Assign ticket (assign_ticket)

Assigns a ticket to an agent, or clears the assignment.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
agentId	Yes	ID of the agent to assign the ticket to, as returned by `list_agents`. Must be present, but may be `null` to unassign.

Returns: {"success": true}.

Transfer ticket (transfer_ticket)

Moves a ticket to a different department. The ticket keeps its assigned agent unless reopenTicket is true.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.
departmentId	Yes	ID of the department to move the ticket to, as returned by `list_departments`.
reopenTicket	No	Reopen the ticket after the transfer and clear its assigned agent. `false` by default, so a resolved ticket stays resolved and keeps its assigned agent. The agent is cleared even when the ticket is in a status that cannot be reopened, and the transfer still succeeds.

Returns: {"success": true}.

Note: for an AI agent this is a final action — the run ends once the transfer succeeds, so add any tags or notes first.

Resolve ticket (resolve_ticket)

Marks a ticket as resolved.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns: {"success": true}.

Note: for an AI agent this is a final action — the run ends once the ticket is resolved, so add any tags or notes first.

Reopen ticket (reopen_ticket)

Reopens a resolved ticket.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns: {"success": true}, or {"success": false, "error": "Ticket is already open"} when there is nothing to reopen.

Mark as spam (mark_as_spam)

Marks a ticket as spam.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns: {"success": true}, or {"note": "Ticket was already marked as spam"} when the ticket already was spam.

Note: for an AI agent this is a final action — the run ends once the ticket is marked as spam, also when it already was, so add any tags or notes first.

Mark as not spam (mark_as_not_spam)

Clears the spam mark from a ticket and returns the ticket to the queue.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket ID, e.g. 1a2b3c4d.

Returns: {"success": true}, or {"note": "Ticket was already not marked as spam"} when the ticket was not spam.

Note: unlike mark_as_spam, this is not a final action — an AI agent's run continues after it.

Create knowledge base article (create_kb_article)

Creates an article in a knowledge base category.

Parameters

Parameter	Required	Description
title	Yes	Title of the new article, up to 255 characters. A longer title is rejected.
body	Yes	Body of the new article, as HTML.
categoryId	Yes	ID of the category to place the article in, as returned by `list_kb_categories`.
knowledgeBaseId	Yes	ID of the knowledge base to create the article in, as returned by `list_knowledge_bases`.
status	Yes	Publication state of the new article: `published` or `draft`.
visibility	Yes	Who can see the new article: `public` or `internal`.
description	No	Meta description of the new article, as shown in search engine results. When omitted, the article has no meta description.
keywords	No	Meta keywords of the new article. When omitted, the article has no meta keywords.
position	No	0-based position of the new article within its category. When omitted, the article is placed first.

Returns

Field	Description
articleId	ID of the article that was created — this is what `get_kb_article` and `update_kb_article` expect as `articleId`.
message	Confirmation text naming the article's title and status.

Note: attachments cannot be uploaded through this tool. Images referenced inline in the HTML body are picked up from the body itself.

Update knowledge base article (update_kb_article)

Changes an existing article. Only the parameters you supply are changed; everything else keeps its current value.

Parameters

Parameter	Required	Description
articleId	Yes	ID of the article to update, as returned by `search_kb_articles`.
title	No	Replace the title, up to 255 characters. A longer title is rejected.
body	No	Replace the body with this HTML.
status	No	Change the publication state: `published` or `draft`.
visibility	No	Change who can see the article: `public` or `internal`.
description	No	Replace the meta description. Pass an empty string to clear it.
keywords	No	Replace the meta keywords. Pass an empty string to clear them.
categoryId	No	Move the article to this category, as returned by `list_kb_categories`. The article is placed first in that category unless `position` is also given. When omitted, the article stays where it is.
knowledgeBaseId	No	If supplied, must match the article's current knowledge base — moving an article between knowledge bases is not supported.
position	No	Move the article to this 0-based position within its category.

Returns

Field	Description
message	Confirmation text naming the ID of the updated article.

Create knowledge base category (create_kb_category)

Creates a category in a knowledge base, at root level or under a parent category.

Parameters

Parameter	Required	Description
name	Yes	Name of the new category, up to 255 characters. A longer name is rejected.
knowledgeBaseId	Yes	ID of the knowledge base to create the category in, as returned by `list_knowledge_bases`.
visibility	Yes	Who can see the new category: `public` or `internal`.
parentCategoryId	No	ID of the parent category, as returned by `list_kb_categories`. When omitted, the category is created at root level.
keywords	No	Meta keywords of the new category. When omitted, the category has no meta keywords.
position	No	0-based position of the new category among its siblings. When omitted, the category is placed first.

Returns

Field	Description
categoryId	ID of the category that was created — this is what the other knowledge base tools expect as `categoryId` or `parentCategoryId`.
message	Confirmation text naming the created category.

Update knowledge base category (update_kb_category)

Renames, moves or reorders a category, or changes its visibility or keywords. Only the parameters you supply are changed; everything else keeps its current value.

Parameters

Parameter	Required	Description
categoryId	Yes	ID of the category to update, as returned by `list_kb_categories`.
name	No	Rename the category, up to 255 characters. A longer name is rejected.
visibility	No	Change who can see the category: `public` or `internal`.
keywords	No	Replace the meta keywords. Pass an empty string to clear them.
parentCategoryId	No	Move the category under this parent, as returned by `list_kb_categories`, or to root level with `0`. The category is placed first among its new siblings unless `position` is also given. Moving a category under itself or one of its own descendants is rejected.
knowledgeBaseId	No	If supplied, must match the category's current knowledge base — moving a category between knowledge bases is not supported.
position	No	Move the category to this 0-based position among its siblings.

Returns

Field	Description
message	Confirmation text naming the updated category.

MCP tools reference

Read-only tools

Search tickets (search_tickets)

Get ticket metadata (get_ticket_metadata)

Get ticket messages (get_ticket_messages)

Get ticket notes (get_ticket_notes)

Get ticket summary (get_ticket_summary)

Get tags (get_tags)

Get ticket field definitions (get_ticket_field_definitions)

Get ticket field values (get_ticket_field_values)

List agents (list_agents)

List departments (list_departments)

List knowledge bases (list_knowledge_bases)

List knowledge base categories (list_kb_categories)

Search knowledge base articles (search_kb_articles)

Get knowledge base article (get_kb_article)

Write/manage tools

Reply via email (reply_via_email)

Reply via WhatsApp (reply_via_whatsapp)

Add note (add_note)

Add tags to ticket (add_tags_to_ticket)

Remove tags from ticket (remove_tags_from_ticket)

Set ticket field value (set_ticket_field_value)

Delete ticket field value (delete_ticket_field_value)

Assign ticket (assign_ticket)

Transfer ticket (transfer_ticket)

Resolve ticket (resolve_ticket)

Reopen ticket (reopen_ticket)

Mark as spam (mark_as_spam)

Mark as not spam (mark_as_not_spam)

Create knowledge base article (create_kb_article)

Update knowledge base article (update_kb_article)

Create knowledge base category (create_kb_category)

Update knowledge base category (update_kb_category)

Related articles

Other Articles