# Tools

> Every tool the Tirver MCP server offers, with inputs and the scope each needs.

Assistants discover these tools on their own. This page tells you what each does, so you know what to ask for and what to expect. The server only lists the tools your key's [scopes](https://tirver.com/help/mcp/permissions.md) allow, and refuses any other call with the missing scope named. Arguments are checked against each tool's published schema, and unknown arguments are rejected.

| Tool | What it does | Scope |
|---|---|---|
| `search_articles` | Keyword search over published help articles. | `help-center:read` |
| `list_articles` | Lists articles, drafts included. | `help-center:read` |
| `get_article` | Returns one article with its Markdown text. | `help-center:read` |
| `list_collections` | Lists help center collections. | `help-center:read` |
| `list_conversations` | Lists conversations by status, assignee, tag or customer. | `conversations:read` |
| `get_conversation` | Returns one conversation with its messages. | `conversations:read` |
| `list_customers` | Looks up customers by name, email or your own id. | `customers:read` |
| `list_feedback_posts` | Lists feedback posts. | `feedback:read` |
| `get_feedback_post` | Returns one post with its comments. | `feedback:read` |
| `list_changelog` | Lists changelog entries. | `changelog:read` |
| `list_knowledge_sources` | Lists what the AI agent learns from. | `knowledge:read` |
| `get_credits` | Returns the AI credit balance. | `credits:read` |
| `ask` | Asks the AI agent a question and returns an answer with citations. | `ai:ask` |
| `draft_reply` | Saves a suggested reply as an internal note. | `conversations:write` |
| `create_feedback_post` | Files a feedback post, linked to a conversation if given. | `feedback:write` |
| `create_article_draft` | Starts a help center article as a draft. | `help-center:write` |

Arguments and limits are the same as for the matching [REST endpoint](https://tirver.com/help/api.md). Lists accept `limit` (1 to 100) and `cursor` and return `data`, `next_cursor` and `has_more`.

## search_articles

Finds published articles by keyword. It matches words, not meaning, with titles ranking first. For a natural language answer use `ask`.

| Input | Type | Meaning |
|---|---|---|
| `q` | string | Required. The words to look for. |
| `limit` | integer | How many results, 1 to 50. |

## list_articles and get_article

`list_articles` takes `status` (`draft` or `published`), `collection_id`, `q`, `limit` and `cursor`. `get_article` takes `id`, which can be the article id or its slug, and returns the Markdown body.

## list_conversations

| Input | Type | Meaning |
|---|---|---|
| `status` | string | `open`, `snoozed` or `closed`. |
| `assignee_id` | string | Only conversations assigned to this team member. |
| `handled_by` | string | `ai` or `team`. |
| `tag` | string | Only conversations with this tag. |
| `customer_id` | string | Only this customer's conversations. |
| `limit`, `cursor` | | Paging. |

## get_conversation

| Input | Type | Meaning |
|---|---|---|
| `id` | string | Required. The conversation to read. |

Returns the customer, a short plain extract of the thread called `summary` (not an AI summary) and up to the first 500 messages, oldest first. Internal notes are included so the assistant has full context, so be careful where you route the output.

## list_customers

Takes `q` (name or email contains), `email` (exact), `external_id`, `limit` and `cursor`. Needs `customers:read`, which includes email addresses.

## ask

| Input | Type | Meaning |
|---|---|---|
| `question` | string | Required. Up to 2000 characters. |
| `history` | array | Earlier turns, up to 19, each with `role` (`user` or `assistant`) and `text`. |

Uses the same AI agent, tone and instructions as **Test the agent**. It stores nothing and uses no credits. It is limited to 10 calls a minute per key, shared with `POST /api/v1/ask`.

## draft_reply

| Input | Type | Meaning |
|---|---|---|
| `conversation_id` | string | Required. The conversation to draft for. |
| `body` | string | Required. The suggested reply, up to 3,900 characters. |
| `author_id` | string | The team member to show as the note's author. Defaults to the person who created the key. |

Saves an internal note that starts with "Draft reply (from an AI assistant, not sent):". There is no separate draft message type, so the draft appears in the conversation as a note. A team member reads it and sends the reply themselves. Nothing reaches the customer.

## create_feedback_post

| Input | Type | Meaning |
|---|---|---|
| `title` | string | Required. The idea in a line. |
| `body` | string | More detail. |
| `board_id` | string | The board to file it on. |
| `conversation_id` | string | Link the post to the conversation it came from. The customer gets the first vote. A conversation can have one post. |

## create_article_draft

| Input | Type | Meaning |
|---|---|---|
| `title` | string | Required. The article title. |
| `body` | string | The text, as Markdown. |
| `collection_id` | string | The collection to file it under. |
| `slug` | string | The address. Made from the title when left out. |
| `description` | string | The search description. |

The article is always a draft until a person publishes it.

## Resources

Besides tools, the server offers readable resources: `tirver://articles/{id}` (Markdown), `tirver://conversations/{id}` and `tirver://feedback/{id}` (JSON). Each needs the same scope as the matching tool.

## An example exchange

You ask: "Which open conversations are about billing?"

1. The assistant calls `list_conversations` with `status` set to `open` and `tag` set to `billing`.
2. It calls `get_conversation` for the ones that look relevant.
3. It tells you what it found and offers to `draft_reply` to any of them.

New tools are announced in the [changelog](https://tirver.com/changelog.md).

Source: https://tirver.com/help/mcp/tools