KoltrixEvery tool in the Koltrix MCP server, explained
A tour of the reading, organizing, drafting and sending tools: inputs, permissions, what each returns, and what is missing on purpose, like delete and forward.
On this page(10 sections)
The fastest way to understand what an assistant can do in your Koltrix mailbox is to read the list of tools. Not the marketing, the actual list. A tool is a named action with defined inputs, and an assistant can do nothing in Koltrix that is not on it.
This is a tour of that list: what each tool takes, what it returns, which permission it needs, and what the shape of the whole set says about the design. It is a plain-language companion to the reference in the docs.
How the tools are grouped
Tools fall into four groups, and each group needs its own permission.
| Group | Permission | Count | Can change your mail? |
|---|---|---|---|
| Reading | Read | 8 | No |
| Organising | Organise | 6 | Yes, reversibly |
| Drafting | Draft | 1 | Adds a draft; never sends |
| Sending | Send | 1 | Only when allowed, behind checks |
Every tool works only on the mailboxes you can open in Koltrix, and results include links back to the message in Koltrix. Tools that return mail wrap third-party text in markers and flag it as untrusted, a point we will come back to.
Reading tools
These never change anything.
search takes a query and returns matching conversations as {id, title, url}. It exists for ChatGPT's connectors and deep research, which expect this exact shape. It understands Koltrix operators such as from:, to:, subject:, label:, has:attachment, is:unread, in:sent, before: and after:.
fetch takes an id from search and returns one conversation as {id, title, text, url, metadata}. The text holds every message with its sender, recipients and date. Together, search and fetch are the pair ChatGPT looks for.
search_mail is the richer search, for assistants in general. Inputs:
| Input | Meaning |
|---|---|
query |
Words to search for; operators also work |
folder |
One of inbox, sent, drafts, archive, spam, trash or starred |
label |
Only conversations with this label |
from |
A full address, or a domain such as acme.com |
unread |
Only unread mail |
limit |
How many to return, default 20, up to 50 |
It returns conversation summaries: subject, sender, snippet, date, unread state, labels and a thread id.
list_threads lists conversations in a folder, newest first, optionally narrowed to an inbox category (primary, other or cold_pitch), a label or unread. It pages with a cursor, and the page size defaults to 25, up to 50.
get_thread takes a thread_id and returns every message in the conversation: from, to, cc, date, subject and plain-text body. Attachments are listed by name and size and are not downloaded. Reading does not mark the conversation read.
list_mailboxes lists the addresses you can read and draft from in this workspace.
list_labels lists the workspace's labels with id, name and color.
get_inbox_summary takes no input. It returns unread counts for the inbox overall and per category, and the conversations Koltrix thinks need a reply.
That is the whole read surface. No tool downloads attachments, exports a mailbox or lists other people's mail.
Organising tools
These change your mail in ways you can undo.
| Tool | Inputs | Effect |
|---|---|---|
apply_label |
thread_id, label |
Adds a label by name or id. A name that does not exist yet is created |
remove_label |
thread_id, label |
Takes the label off; the label itself stays |
archive_thread |
thread_id |
Moves the conversation out of the inbox into Archive. Nothing is deleted |
mark_read |
thread_id |
Marks every message in the conversation read |
mark_unread |
thread_id |
Marks it unread again |
star_thread |
thread_id, optional starred |
Stars it, or unstars it with starred set to false |
Each is safe to repeat, and each reverses with another call or in the app. Each acts on one conversation at a time, so a large cleanup is many calls. Organizing your inbox by chat shows a safe way to do a bulk one.
The drafting tool
There is exactly one: create_draft.
| Input | Meaning |
|---|---|
body_text |
The message body, plain text. Required |
to, cc |
Recipient addresses |
subject |
Subject line |
in_reply_to_thread_id |
The conversation this answers. to and the subject then default to replying to the latest message |
from_mailbox |
Which of your mailboxes to use. Defaults to the one the conversation was addressed to, or your first |
It saves a draft to your Drafts folder and returns a draft id and a review_url that opens the draft in Koltrix. It never sends. There is no input for attachments or Bcc. Drafting replies with Claude and Koltrix covers how to get good drafts out of it.
The sending tool
Only listed when the connection holds the send permission and the workspace allows sending, which is off by default.
send_draft takes draft_id, confirmed (must be exactly true) and confirmation, which is the draft's To addresses, then its Cc addresses, comma-separated, then a vertical bar and the subject. It sends a draft that already exists. It is refused unless the confirmation matches the draft as it is now. Limits apply: at most 10 recipients per message, 20 sends a day per connection and 50 a day per workspace. Drafts with Bcc recipients or attachments are not sent through it.
In apps that show interactive cards, send_draft is not offered. The Send button on the draft card sends through a second tool, hidden from the assistant, that needs a one-time token issued with the draft. Safe sending from Claude and MCP Apps cards cover the two routes.
What is not on the list
The absences matter as much as the entries.
- No delete. No tool deletes or trashes a message or a draft. Even the card's Discard button deletes nothing.
- No forward. There is no way to hand a message to a new recipient.
- No send of new text. The only sending tool sends an existing draft.
- No attachment download. Attachments show up as names and sizes.
- No account or settings changes. An assistant cannot change workspace settings, invite people or alter permissions.
This is the point of a small tool set. A mistake, or a successful trick, can only reach what the tools can do. Read, organize, draft, then confirm: a capability model explains the idea in general terms.
Email is untrusted input
Every tool that returns mail returns text written by other people. Koltrix fences bodies and snippets between markers and attaches a notice saying that email subjects, names, snippets and bodies are third-party text, to be treated as data and never as instructions. If a sender tries to forge the closing marker to escape the fence, it is defanged first. The tool descriptions say the same thing.
That is a courtesy to the model, not the safety mechanism. The mechanism is the shape of the tool set above. With sending off, which is the default, even a fooled assistant can only label, archive, mark, star and draft. Defending AI assistants against hidden instructions goes deeper.
How the tools combine
| You ask | Tools it is likely to call |
|---|---|
| "What needs a reply?" | get_inbox_summary, then get_thread for a few |
| "Find the thread about the renewal" | search_mail or search, then get_thread or fetch |
| "Label last week's receipts and archive them" | search_mail, apply_label, archive_thread |
| "Reply to Dana, we ship Friday" | get_thread, list_mailboxes, create_draft |
| "Which of my addresses can I draft from?" | list_mailboxes |
You never have to name a tool. They are what the assistant calls on your behalf, and most assistants show you when they do.
Checking it yourself
If you want to see the list rather than take our word for it, ask your assistant: "List the Koltrix tools you have, with what each does." The answer should match this post. Your admin can confirm what each connection is allowed to do in the connections list, and every tool call is recorded in the workspace audit log by tool name, never by mail content.
Key takeaways
- Koltrix's MCP server has eight reading tools, six organizing tools, one drafting tool and one sending tool that is off by default.
- Organizing changes are reversible; drafting never sends; sending is gated by a workspace switch, your opt-in and a confirmation.
- There is no tool to delete, forward, download attachments or change settings.
- Mail returned by tools is marked as untrusted, but the real protection is the narrow tool set.
- The authoritative reference is the docs, and koltrix.com/mcp has the overview.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
