Tools

Thirteen tools. Nine read, four write. Clients discover them through the standard tools/list, so nothing here needs a custom integration. Every summary carries as_of. A queue changes while an agent is reading a recap of it, and a figure with no timestamp is a figure someone quotes in a meeting an hour later.

get_support_summary

How the queue looks right now. Input: none.

{
  "as_of": "2026-08-28T14:22:10Z",
  "open_conversations": 59,
  "by_status": { "new": 12, "open": 38, "pending": 9, "resolved": 104 },
  "oldest_waiting_hours": 32,
  "first_reply": { "median_minutes": 42.5, "window_days": 30 }
}

open_conversations counts new, open, and pending together. resolved and closed have left the queue, so they appear in by_status but not in the total. first_reply is the median time between a conversation opening and its first public reply, over conversations opened in the last 30 days. It is the same figure behind the widget’s “usually replies in” line. Two things to know when you quote it:

The AI’s automatic replies count as first replies. A workspace that sends them reads as fast here even if people answer slowly.
median_minutes is null when fewer than five conversations in the window got a reply. One slow night would otherwise set the number.

list_oldest_unanswered

Conversations with no reply since the customer’s last message, oldest first. Input: limit, 1 to 50, default 10.

{
  "as_of": "2026-08-28T14:22:10Z",
  "data": [
    {
      "id": "0195e2c1-...",
      "reference": "ACME-1042",
      "preview": "Clicking export does nothing.",
      "priority": "high",
      "waiting_since": "2026-08-27T06:12:00Z",
      "requester": "sam@customer.com"
    }
  ]
}

“Unanswered” is not the same as status = "new". A ticket someone opened, read, and left is unanswered in every sense a customer cares about, and its status is open. This checks whether there has been a public reply since the requester’s last message.

search_tickets

Find conversations by what was written in them, by when they were opened, or both. Everything that matched is counted beside the rows. Use it to find one ticket (“the customer who mentioned order 4512”) or to look at a period (“what customers have been reporting this month”, “how August compared with July”). Input: all optional.

Field	Meaning
`query`	Words to find: what the customer wrote, a ticket reference, a name, or an email address.
`days`	How far back from today, 1 to 365. Default 30, or 365 with a `query`.
`from`	First day counted, as `2026-08-01`.
`to`	Last day counted, included, as `2026-08-31`.
`topic`	One category label, such as `billing`.
`limit`	Rows per page, 1 to 50. Default 25.
`cursor`	`next_cursor` from a previous call.

Give days on its own for a rolling window, or from and to for a fixed one. If either date is present it wins over days. from on its own runs up to today; to on its own counts days back from that date. With a query and no dates, the window is the last year rather than the last 30 days. A search is usually after one particular conversation, and that one is rarely from this month.

{
  "as_of": "2026-09-08T14:22:10Z",
  "period": { "from": "2025-09-09", "to": "2026-09-08", "timezone": "UTC" },
  "query": "charged twice",
  "total": 3,
  "by_status": { "new": 0, "open": 1, "pending": 0, "resolved": 2, "closed": 0 },
  "by_topic": [
    { "topic": "billing", "count": 3 }
  ],
  "tickets": [
    {
      "id": "0195e2c1-...",
      "reference": "ACME-1043",
      "status": "open",
      "priority": "high",
      "topic": "billing",
      "created_at": "2026-09-07T08:41:00Z",
      "preview": "I was charged twice for the September plan."
    }
  ],
  "next_cursor": null
}

total, by_status, and by_topic describe everything that matched. tickets is one page of it. Read the counts for the shape of the period and the rows for the wording customers used, and do not treat a page as the period.

A topic of null in by_topic is the untriaged bucket: conversations the classifier had no confident label for. It is counted rather than dropped, so the topics add up to total. The window selects on when the conversation was opened. The rows come back in the queue’s own order, most recently active first, which is not the same thing: a conversation from the first of the month that someone replied to this morning sorts near the top. Every row carries its own created_at. There is no status filter, because by_status is the status breakdown. Ask for the window and read the split. Internal notes play no part. A query only matches text the customer could see, and preview is the latest public message. Otherwise a search for a word in a note would tell your agent the note exists, and what it is about. Possible errors:

`error`	Meaning
`query must be text...`	`query` was not a string
`days must be a number of days, such as 30.`	`days` was not a number
`from must be a date like 2026-08-01.`	Unparseable or impossible date
`from is after to. Give the earlier date as from.`	The range runs backwards

get_agent_workload

How many open conversations each active member is assigned. Input: none.

{
  "as_of": "2026-08-28T14:22:10Z",
  "data": [
    { "name": "Priya", "open_assigned": 14 },
    { "name": "Sam", "open_assigned": 3 }
  ]
}

Active members only. A deactivated colleague keeps their message history but does not count as capacity.

get_ticket

One conversation and its public messages. Input: ticket_id, required.

{
  "as_of": "2026-08-28T14:22:10Z",
  "id": "0195e2c1-...",
  "reference": "ACME-1042",
  "status": "open",
  "priority": "high",
  "category": "billing",
  "language": "en",
  "messages": [
    {
      "author_type": "requester",
      "body": "Clicking export does nothing.",
      "created_at": "2026-08-27T06:12:00Z"
    }
  ]
}

Internal notes are not filtered out of the result; they are never fetched in the first place. An MCP client is an AI agent whose output a person may paste anywhere, and an internal note reaching one is the same leak as it reaching a customer, one step removed. An unknown or cross-workspace id returns { "error": "not_found" }.

get_customer

One customer: who they are, how long they have been writing in, and their ten most recent conversations. Input: one of email or ticket_id. With a ticket_id, you get the customer who opened that conversation.

{
  "as_of": "2026-08-28T14:22:10Z",
  "name": "Sam Lee",
  "email": "sam@customer.com",
  "external_id": "user_8812",
  "verified": true,
  "customer_since": "2026-02-03T09:15:00Z",
  "last_seen": "2026-08-27T06:12:00Z",
  "conversations": 6,
  "open_conversations": 1,
  "channels": ["email", "widget"],
  "recent_tickets": [
    {
      "id": "0195e2c1-...",
      "reference": "ACME-1042",
      "status": "open",
      "created_at": "2026-08-27T06:12:00Z",
      "preview": "Clicking export does nothing."
    }
  ]
}

external_id is the id your own app knows them by, when your widget or API sent one. preview is the first public message of each conversation, which is usually what it was about. Your team’s private note on the customer is never included, for the same reason get_ticket leaves out internal notes. Neither are their browser and device details. A customer who asked to be erased comes back with "erased": true and no name or email. A customer merged into another one returns the customer they were merged into. An unknown email, or a ticket from another workspace, returns { "error": "not_found" }.

list_pending_drafts

AI drafts waiting for a person to review, oldest first. Only conversations that are still open: a resolved ticket’s leftover draft is not waiting on anyone. Input: limit, 1 to 25, default 10.

{
  "as_of": "2026-08-28T14:22:10Z",
  "total": 4,
  "drafts": [
    {
      "draft_id": "0195e3a0-...",
      "ticket_id": "0195e2c1-...",
      "reference": "ACME-1042",
      "ticket_status": "open",
      "body": "Thanks for flagging this. It was a permissions bug and it is now fixed.",
      "confidence": 0.82,
      "grounding_score": 0.91,
      "created_at": "2026-08-27T06:14:00Z"
    }
  ],
  "note": "Drafts reach nobody until a person sends them from the inbox."
}

total counts every pending draft, so you can tell a page from the whole list. This includes drafts made with create_draft_reply.

search_knowledge

Find the workspace’s own reference documents by topic. Input: query (an empty query lists everything), limit 1 to 25, default 10.

{
  "query": "refund policy",
  "documents": [
    {
      "document_id": "0195dd40-...",
      "title": "Refunds and cancellations",
      "language": "en",
      "tokens": 1840
    }
  ]
}

Titles and sizes only, not the text. A search that returned full documents would spend the context window on the four the model did not want. tokens is there so it can tell a one-line rule from a handbook before asking for it.

read_document

The full text of one reference document. Input: document_id, required. Get it from search_knowledge first.

{
  "document_id": "0195dd40-...",
  "title": "Refunds and cancellations",
  "language": "en",
  "complete": true,
  "content": "Refunds are available within 14 days..."
}

Documents are read whole, up to 80,000 characters. Past that, complete is false and a note says how much was returned:

{
  "complete": false,
  "content": "...",
  "note": "This document is 240000 characters and you are reading the first 80000. Say what you could not check rather than assuming the rest agrees."
}

The cut is announced rather than silent, because a silent cut reads as the complete text and the reply then states a policy that the unread half qualifies. Passing something that is not a document id returns a message telling the model to search first, rather than a database error. Models otherwise tend to guess a filename from a title.

create_draft_reply

Ask miniDesk’s own model to compose a reply from your documents, for a person to review. Use reply_ticket below when you want to send your own words. Input: ticket_id, required.

{
  "draft_id": "0195e3a0-...",
  "body": "Thanks for flagging this. It was a permissions bug and it is now fixed.",
  "confidence": 0.82,
  "grounding_score": 0.91,
  "delivered": false,
  "note": "This is a draft. It reaches nobody until a person sends it."
}

delivered: false and the note are returned every single time, on purpose, so a connected agent cannot tell its user that a reply was sent. The draft is stored for review in the dashboard, with the calling model recorded and an audit log row written in the same transaction. It replaces any draft already waiting on that conversation, which is why clients are told this tool is destructive. Possible errors:

`error`	Meaning
`not_found`	Unknown ticket, or another workspace’s
`ai_disabled`	AI is switched off for this workspace
`no_draft_available`	The model produced nothing usable

reply_ticket

Send your own text to the customer.

This reaches a real person and cannot be unsent. Show the wording to whoever you are working for and get their agreement before calling it.

Input: ticket_id and body, both required. body is the text the customer reads, up to 10,000 characters.

{
  "message_id": "0195e3b7-...",
  "delivered": true,
  "note": "This was sent to the customer. It cannot be unsent."
}

delivered is false when the reply was written but did not reach the customer. Their channel refused it, like Instagram after its 24-hour window, or your workspace hit its sending limits. The reply stays on the conversation, and an internal note there says why.

{
  "message_id": "0195e3b7-...",
  "delivered": false,
  "note": "The reply is on the conversation, but it did not reach the customer. An internal note on the conversation says why."
}

One message, one conversation. There is no way to send to a list of tickets, and that is deliberate: the reasoning is here. The message is attributed to the credential that sent it, not to a person, so the thread records which integration wrote it. For the same reason these replies are excluded from the pool of past answers our drafting model learns from: nobody on your team put their name to them. Possible errors:

`error`	Meaning
`not_found`	Unknown ticket, or another workspace’s
`body is required...`	Empty body, or not a string
`body is N characters...`	Over the 10,000 limit

write_knowledge

Propose a reference document: a policy, a rule, a product note. Input: title and content, both required. content is the document text, up to 80,000 characters.

{
  "document_id": "0195e3c2-...",
  "active": false,
  "note": "Saved as a proposal. An owner has to switch it on from the knowledge screen before the AI can read it."
}

This does not add anything to your knowledge base. The document is stored switched off and appears on the knowledge screen as Waiting for you. Until an Owner approves it, no query in the product will hand its text to a model.

The text goes through the same redaction as every other document, so a card number an agent copied out of a ticket thread does not get stored. Possible errors:

`error`	Meaning
`title is required.`	Empty or missing title
`content is required...`	Empty or missing content
`content is N characters...`	Over the 80,000 limit; split it up

add_internal_note

Leave a note on one conversation for your team. Input: ticket_id and body, both required. body is up to 10,000 characters.

{
  "message_id": "0195e3d4-...",
  "visible_to_customer": false,
  "note": "Saved as an internal note. Only your team can see it."
}

The customer never sees it. It sends no email, does not change the conversation’s status, and does not count toward your plan. miniDesk’s AI does not read it either. The drafting model only reads public messages, so a note cannot change what it writes to a customer. The note is attributed to the credential that wrote it, not to a person, so your team can tell an integration’s notes from a colleague’s. Possible errors:

`error`	Meaning
`not_found`	Unknown ticket, or another workspace’s
`body is required...`	Empty body, or not a string
`body is N characters...`	Over the 10,000 limit

Tools that do not exist

There is no update_ticket, assign_ticket, or resolve_ticket, and nothing takes a list of tickets. Their absence is the security model, not an oversight. The reasoning is here.

Overview

Connect a client

get_support_summary

list_oldest_unanswered

search_tickets

get_agent_workload

get_ticket

get_customer

list_pending_drafts

search_knowledge

read_document

create_draft_reply

reply_ticket

write_knowledge

add_internal_note

Tools that do not exist

​get_support_summary

​list_oldest_unanswered

​search_tickets

​get_agent_workload

​get_ticket

​get_customer

​list_pending_drafts

​search_knowledge

​read_document

​create_draft_reply

​reply_ticket

​write_knowledge

​add_internal_note

​Tools that do not exist

get_support_summary

list_oldest_unanswered

search_tickets

get_agent_workload

get_ticket

get_customer

list_pending_drafts

search_knowledge

read_document

create_draft_reply

reply_ticket

write_knowledge

add_internal_note

Tools that do not exist