Give the assistant a tool
Summary
Section titled “Summary”A tool lets your KonversAI assistant do something, not only write an answer. You manage tools on the Assistant tools screen in the KonversAI console. Select Settings in the left sidebar, then select AI tools. The screen heading is Assistant tools. Four figures at the top show how many tools you have, how many are active, and the calls and errors in the last 7 days. The list groups your tools by what they do, such as Shop and orders, CRM and Handover, and shows a logo beside each tool. Tools are tenant-wide. Every tool you enable is available to the assistant in every conversation in the tenant.
For a short list of what each Tool type does, see See available integrations. This page is the shared add, edit, validate, disable and delete flow.
Who can do this
Section titled “Who can do this”A team member with the View tools permission opens the Assistant tools screen in the KonversAI console. A team member with the Modify tools permission adds, edits, validates, deletes and discovers. A Tenant Admin holds both permissions, always. Without View tools, the item AI tools does not appear under Settings in the left sidebar. With View tools only, you can open the add form, but KonversAI refuses the save with a permission error. Ask a Tenant Admin to grant Modify tools on the User permissions screen.
Before you start
Section titled “Before you start”Sign in to the KonversAI console and select your tenant. Select Settings in the left sidebar, then select AI tools. The screen heading is Assistant tools.
The Assistant tools screen is not behind a feature flag. Some individual tools need one. Calendar Booking (built-in) works only when your tenant has the Calendar feature. That tool answers Calendar is not enabled for this workspace. when the feature is off.
Collect what the tool needs before you start the form. A webhook URL, an API key or a server URL is easier to paste than to find halfway through.
KonversAI includes three tools in every workspace: Knowledge Base Search, Email Verification and Read attachments. They are always on. They do not appear in the Tool type list or on the Assistant tools screen, and you cannot edit, switch off or delete them. KonversAI writes their usage guidance for you. Knowledge Base Search searches your published knowledge base and returns the matching text. Email Verification sends a code to the customer email address and checks the reply. Read attachments reads an image, a PDF, a Word document, an Excel workbook, a PowerPoint presentation or a text or CSV file that the customer attaches to the conversation. For a long file it reads the start only: the first 8 pages of a PDF, the first 8,000 characters of a document, presentation or text file, and the first 100 rows and 10 columns of the first sheet of a workbook or CSV file. It cannot read the older .doc, .xls and .ppt formats.
These are the tool types you can add today. The Tool type list shows them in this order. For a short description of each type, see See available integrations.
| Tool type | Tool set type | What it does |
|---|---|---|
| Phone Verification | phone_verification |
Sends a code to the customer phone number and checks the reply. |
| Handover | handover |
Passes the conversation to a person, and emails the contacts you list. |
| Calendar Booking | ical_booking |
Reads free slots from an external iCal URL and emails an invitation. See Set up the Calendar Booking tool. |
| Calendar Booking (built-in) | calendar_booking |
Books, finds and cancels in the KonversAI Calendar. Needs the Calendar feature. |
| Slack | slack |
Posts a message to a Slack incoming webhook. |
| SkyDyn | skykontoret_crm |
Looks up a contact, checks membership, and creates a support case. |
| Shopify | shopify |
Searches the product catalog, and looks up an order and its shipping status in a Shopify shop. See Connect Shopify. |
| Posten / Bring | bring_tracking |
Looks up the delivery status of a parcel sent with Posten or Bring. |
| Yayloh | yayloh |
Lists the returns registered in Yayloh for a customer, and shares a return shipping label. See Connect Yayloh returns. |
| Klarna | klarna |
Tells a verified customer whether the Klarna payment for their Shopify order is charged or refunded. Needs the Shopify tool. See Connect Klarna. |
| HubSpot | hubspot |
Looks up a HubSpot contact and creates a support ticket. See Connect HubSpot. |
| Tripletex | tripletex |
Answers a verified customer’s questions about their invoices, and shows the invoices on the contact card. See Connect Tripletex. |
| Yr | yr_weather |
Returns a yr.no forecast for a location you configure. See Set up the Yr Weather tool. |
| BookVisit | bookvisit |
Looks up a BookVisit booking and adds or removes its add-ons. |
| TheFork | thefork |
Checks free tables at a restaurant for a date and party size, and tells a verified guest the status of their reservation. See Connect TheFork. |
| Mews | mews |
Quotes free hotel rooms and prices with a booking link, answers a verified guest about their booking, and passes guest requests to hotel staff. Turned on per workspace on request. See Connect Mews. |
| MCP Server | mcp_server |
Connects to an MCP server (optionally via OAuth Connect) and uses the functions it publishes. |
-
Select Settings in the left sidebar of the KonversAI console, then select AI tools. The screen opens with the heading Assistant tools.

Assistant tools. Each row is one tool the assistant can call.
-
Read the page. Four figures at the top show tools added, active now, calls in the last 7 days and errors in the last 7 days. Each kind of tool, such as Shop and orders or CRM, has a card of its own below them. A row shows the logo and the kind of tool, such as Shopify or Slack, which links to the tool. When you have more than one tool of the same kind, the label you gave each tool appears in small text beneath its title, so you can tell them apart. A kind you have only once shows no label, and the page never shows the slug. Pills show what the tool lets the assistant do, such as Order status or Contact lookup, in a grid of up to four. When a tool does more than four things, the fourth pill, such as +2, holds the rest. calls / 7 d counts how often the assistant used the tool in the last 7 days. Under it you see when the tool was last used, Not used, or a link such as 1 error · see activity that opens Tool activity on those failed calls. A switch turns the tool on or off, and a chip beside it reads Active or Off. A tool that is off appears greyed. Select the ⋯ button to open Edit and Delete, and Discover on an MCP server. An empty tenant shows No tool configurations yet. Add one to get started.
-
Select + Add tool at the top right. The form opens with the heading Add tool.
-
Select the type in Tool type. The list starts with the placeholder — Select a tool —. You cannot change the type later: the edit screen disables the list and says Tool type cannot be changed when editing.
-
Type a label in Display name. The list shows each tool by its kind, so the label appears beneath the title only when you have more than one tool of the same kind. KonversAI fills Slug from Display name while you type.
-
Check Slug. The assistant calls the tool by this slug, so keep it short and readable. The help text says: Unique ID used by the assistant to call this tool. Letters, numbers, underscores, hyphens only (1–64 chars). The slug must be unique inside your tenant. KonversAI refuses a double underscore with Slug must not contain double underscores (‘__’); this delimiter is reserved for multi-function tool naming.
-
Type your instruction in Usage guidance for the AI assistant. The placeholder says: When to use this tool, and how eagerly to use it. KonversAI puts this text in the assistant prompt, next to the tool name. Say when to use the tool, and when not to.
-
Keep the Enabled checkbox selected. Clear it to save the tool without giving it to the assistant.
-
Fill in the Configuration card. This card appears only for a type that needs settings, and each field carries its own label and help text. A sensitive field, such as a webhook URL, shows dots instead of the text.
-
Fill in the Secrets card, when the type has one. The card lists each secret with Name, Status and Actions. Status is Not set or Configured. Select Add secret to open the small window, type the value in Value, then select Apply. On a saved tool the button is Update, and the window saves with Save secret.
-
Select Add tool at the bottom. KonversAI saves the tool and opens it again with the heading Edit tool.
-
Select Validate and save. KonversAI checks the settings against the real service and shows the result in a banner. Only the edit screen has this button.
Worked example: notify your team on Slack
Section titled “Worked example: notify your team on Slack”This example adds one Slack tool in the KonversAI console. The assistant then posts a message into a Slack channel when a conversation needs a person. Select Settings in the left sidebar, then select AI tools, to start.
- Create an incoming webhook in Slack first, and copy its URL. Slack gives you a
URL that starts with
https://hooks.slack.com/. - Select Settings in the left sidebar of the KonversAI console, then select AI tools. Select + Add tool.
- Select Slack in Tool type.
- Type
Slack Notificationsin Display name. KonversAI fills Slug withslack_notifications. - Type your instruction in Usage guidance for the AI assistant. For example: Use this when the customer asks for a person, or when I cannot answer and the customer is unhappy.
- Leave the Enabled checkbox selected.
- Paste the webhook URL into Slack webhook URL in the Configuration card. The box hides the text, because the URL is a secret.
- Check Message template in the Configuration card. The default text is
A conversation needs attention: {conversation_link}. Keep{conversation_link}in the text. KonversAI replaces it with a link to the conversation. - Select Add tool. The screen reopens with the heading Edit tool.
- Select Validate and save. A green banner with Slack settings are valid. means Slack accepted your settings.
- Open a test conversation in your widget and ask for a person. The message arrives in your Slack channel with a link back to the conversation.
The assistant calls this tool at most once per conversation, so a customer cannot flood your channel.
Three errors can appear in the banner. webhook_url is required. means the
Slack webhook URL box is empty. webhook_url must be a valid HTTP(S) URL.
means the text is not an http:// or https:// address. slack_message_content
must include {conversation_link}. means you removed {conversation_link} from
Message template.
What is an assistant tool, and why does my assistant need one?
Section titled “What is an assistant tool, and why does my assistant need one?”A tool lets your KonversAI assistant act, not only write. You manage tools on the Assistant tools screen in the KonversAI console: select Settings in the left sidebar, then select AI tools. Without a tool, the assistant can only write text from its instructions and its knowledge base. With a tool, it can search your knowledge base, verify an email address, book a slot, look up an order, or post to Slack. Each tool you add is one configured instance of a tool type. The assistant sees the tool by its Slug, and reads your Usage guidance for the AI assistant to decide when to call it.
Which tool types can I add?
Section titled “Which tool types can I add?”The Tool type list on the add form in the KonversAI console holds every type in the table above. Select Settings in the left sidebar, then select AI tools, then select + Add tool, to see it. For short descriptions and which types have a dedicated how-to, see See available integrations. For HubSpot, see Connect HubSpot. For Calendar Booking, see Set up the Calendar Booking tool. For Yr, see Set up the Yr Weather tool. For Shopify, see Connect Shopify. For Tripletex, see Connect Tripletex. For Yayloh, see Connect Yayloh returns. For Klarna, see Connect Klarna. For TheFork, see Connect TheFork. For Mews, see Connect Mews. You can add the same type more than once, with a different Slug each time. For example, you can add two Yr tools for two different sets of locations.
KonversAI refuses my slug. What is allowed?
Section titled “KonversAI refuses my slug. What is allowed?”Slug on the add form in the KonversAI console has three rules. Select
Settings in the left sidebar, then select AI tools, then select + Add
tool, to reach the field. The help text under the box says: Unique ID used by
the assistant to call this tool. Letters, numbers, underscores, hyphens only
(1–64 chars). KonversAI shows Slug must be 1-64 characters and contain only
letters, digits, underscores, or hyphens. for a bad character. It shows Slug
must not contain double underscores (‘__’); this delimiter is reserved for
multi-function tool naming. for a __ inside the slug. The slug must also be
unique inside your tenant. KonversAI fills the slug from Display name while
you add a tool, and stops filling it after the first save.
What do I write in Usage guidance for the AI assistant?
Section titled “What do I write in Usage guidance for the AI assistant?”Usage guidance for the AI assistant is a free text box on the add form in the KonversAI console. Select Settings in the left sidebar, then select AI tools, then open a tool, to find it. KonversAI copies your text into the assistant prompt, beside the tool name. Write when to call the tool and when to leave it alone. The placeholder gives the shape: When to use this tool, and how eagerly to use it. Two good sentences beat one long paragraph. Leave the box empty, and the assistant uses only the built-in description of the tool.
How do I turn a tool off without deleting it?
Section titled “How do I turn a tool off without deleting it?”Use the switch on the tool’s row. Select Settings in the left sidebar of the KonversAI console, select AI tools, then select the switch beside the tool. The switch saves at once, and the word beside it changes from Active to Off. The assistant stops seeing that tool at once. Your settings and your secrets stay in place. Select the switch again to bring the tool back. You need the Modify tools permission. With View tools only, you see the state but the switch is greyed out. You can also clear Enabled on the tool’s own screen and select Save changes, which does the same thing.
Where do I put an API key or a password?
Section titled “Where do I put an API key or a password?”It depends on the tool type. Select Settings in the left sidebar of the KonversAI console, then select AI tools, then open the tool. Shopify, Posten / Bring, Yayloh, Klarna, BookVisit, SkyDyn and HubSpot have a Secrets card. TheFork needs no API key from you; see Connect TheFork. See Connect Shopify and Connect Yayloh returns for what to put in those two. Each row there shows Name, Status and Actions, with Not set or Configured. Select Add secret, type the value in Value, then select Apply on a new tool or Save secret on a saved tool. On a saved tool the secret saves immediately, because the card says Changes are saved immediately. Other types, such as Slack, keep the sensitive value in the Configuration card in a box that hides the text. KonversAI never shows a stored secret again — you can only replace it.
How do I connect an MCP server with OAuth?
Section titled “How do I connect an MCP server with OAuth?”Many remote MCP servers (for example consumer or SaaS MCP endpoints) use the standard MCP OAuth flow. On the MCP Server edit screen, enter the MCP server URL, save the tool, then select Connect. KonversAI opens the provider’s login page in your browser. After you approve access, you return to the tool screen with a success message and KonversAI stores tokens for the tenant and discovers the server’s tools.
Use Reconnect if the connection expires, or Disconnect to clear stored tokens. Servers that do not support OAuth can still use Static authentication (JSON) under configuration (bearer token, custom header, and similar).
The MCP Server tool points outwards: your KonversAI assistant calls somebody else’s MCP server while it answers a customer. KonversAI also publishes an MCP server of its own, which points the other way — your MCP client manages your KonversAI workspace. See Connect an MCP client.
What does the Discover button do?
Section titled “What does the Discover button do?”Discover appears in the ⋯ menu on the tool’s row of the Assistant tools screen in the KonversAI console, on MCP Server rows only. Select Settings in the left sidebar, then select AI tools, to see the list. An MCP server publishes its own list of functions, so KonversAI has to ask the server what it can do. Discover asks again and stores the fresh list. Use it after somebody changes the MCP server. KonversAI also discovers once by itself, right after you add the MCP Server tool (when the server allows unauthenticated discovery or you already connected with OAuth). A failure shows Failed to discover tools or the message from the server. If the server requires OAuth, connect first, then run Discover.
What happens when I delete a tool?
Section titled “What happens when I delete a tool?”Select the ⋯ button on the tool’s row of the Assistant tools screen in the KonversAI console, then select Delete. Select Settings in the left sidebar, then select AI tools, to reach the list. A window opens with the heading Delete tool configuration? and the text This cannot be undone. The assistant will no longer be able to use this tool. Select Delete to confirm, or Cancel to keep the tool. The delete removes the settings and the secrets with the tool. To stop a tool for a short time instead, open the tool, clear the Enabled checkbox, and select Save changes.
What is the difference between Calendar Booking and Calendar Booking (built-in)?
Section titled “What is the difference between Calendar Booking and Calendar Booking (built-in)?”Both appear in the Tool type list on the add form in the KonversAI console. Select Settings in the left sidebar, then select AI tools, then select + Add tool, to compare them. Calendar Booking (built-in) uses the KonversAI Calendar: it reads your calendars, creates a booking, finds a booking by reference, and cancels one. It needs the Calendar feature on your tenant, and answers Calendar is not enabled for this workspace. without it. Calendar Booking is the simpler external option: you give it a Calendar URL, an Invite email, a Timezone, a Booking start hour, a Booking end hour and a Meeting duration (minutes), and it emails an invitation for a free slot it reads from that URL.
Last reviewed . Tell us when a step no longer matches the product.