Tools

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 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. 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.