Tools

The server has 44 tools in seven toolsets. When an assistant connects, it sees every tool. There are no meta-tools that find or run other tools. To load fewer tools, add ?toolsets= to the MCP URL. Every tool acts as the connected employee, in the connection’s company. It returns only what that employee can see in Workchats, and it can do only what that employee can do there.

Conventions

Ids. Tools take and return prefixed ids, so an assistant can pass an id from one tool to another:

Prefix	Thing	Prefix	Thing
`usr_`	person	`tsk_`	task
`dm_`	direct message conversation	`mtg_`	meeting occurrence
`grp_`	group, and its Main chat	`call_`	call
`chn_`	named channel	`drf_`	message draft
`dmsg_`	direct message	`fil_`	file
`gmsg_`	group or channel message	`fcd_`	Filing Cabinet document
`poll_`	poll	`evt_`	company event
`ann_`	announcement	`ntf_`	notification

Comment, subtask and recording ids are plain UUIDs. A conversation is a dm_, grp_ or chn_ id. Results. Each tool returns structuredContent that matches its output schema, and the same object as JSON text, for clients that read only text. Pages. List tools take limit (default 20, at most 50 unless the tool says otherwise) and cursor, and return next_cursor. next_cursor is null on the last page. list_events and list_announcements take limit but no cursor. Effect. Each tool row says what the tool does to Workchats. Each tool declares matching MCP annotations, so a client knows when to ask you first:

Effect	`readOnlyHint`	`destructiveHint`	`idempotentHint`
Read	`true`	`false`	`true`
Changes only your own view: react, mark read, watch, RSVP, status	`false`	`false`	`true`
Creates or changes work others see: task, comment, meeting, poll, group, DM	`false`	`false`	`false`
Writes a draft (`draft_message`)	`false`	`false`	`false`
Sends a message (`send_draft`)	`false`	`true`	`true`
Replaces work others see (`update_task`, `pin_message`)	`false`	`true`	`false`

openWorldHint is false on every tool. send_draft is marked destructive on purpose: a sent message cannot be taken back, so clients ask before they call it. update_task is marked destructive because it overwrites a task others already see. pin_message is marked destructive because a pin is shared: everyone in the conversation sees it, and any member can remove it. Errors. A tool that fails returns isError: true and {"error": {"code", "message"}}:

`code`	Meaning
`not_found`	The item does not exist, or you may not see it. The two are never told apart.
`invalid_argument`	An input is wrong. `message` names it.
`not_allowed`	You can see the item, but you may not do this, for example post in a channel where only admins post.
`conflict`	The task changed since it was read. Read it again with `get_task`.
`draft_changed`	The draft changed since you approved it. The error carries the new text and revision.
`draft_not_pending`	The draft was already sent, discarded or expired.
`rate_limited`	Over a limit. `retry_after_seconds` says when to try again.
`unavailable`	Your company turned the feature off, or a service it needs failed.

A write tool called with a token that can only read gets an HTTP 403 with insufficient_scope, not a tool error. See OAuth for client developers.

Read-only URL and toolsets

/mcp/readonly lists and runs read tools only. A connection made through this URL can only read.
?toolsets= picks toolsets by URL, for example https://mcp.workchats.com/mcp?toolsets=tasks,meetings. Every tool of the named toolsets is listed, plus search and fetch. A tool of a toolset you did not name is not listed, and a call to it answers “Tool not found”. An unknown toolset name gets HTTP 400.

Toolset names: core, messaging, people, tasks, meetings, files, events. A call to discover_tools or execute answers “Tool not found”, as for any unknown name.

Search and fetch

search and fetch have the exact shapes that ChatGPT’s Deep Research and company knowledge expect.

Tool	What it does	Inputs	Effect
`search`	Searches your group and channel messages, your tasks, your meetings by title, and files shared in groups and channels. Returns up to 20 results, each an `id`, a `title` and a `url` that opens the item in Workchats Web.	`query` (required)	Read
`fetch`	Returns one item that `search` named, with its text: a message with the five messages before and after it, a task, a meeting with its AI summary and action items, or a file with its text.	`id` (required)	Read

search and fetch never return a direct message, or a file whose newest message you can read is in a direct message.
search lists no meeting more than 30 days ahead, and one result per meeting series.
People, events and polls are not in search.
A result title is plain text from a fixed pattern, such as Task: … or File: …, because ChatGPT shows it as a label. Text that other people wrote is cut to 80 characters, with line breaks, < and > removed. A message body is never in a title. fetch wraps the item’s text as usual.
A message link opens its conversation in Workchats Web, not the message itself.

Messaging

Tool	What it does	Key inputs	Effect
`search_messages`	Searches your group and channel messages. It reads direct messages only when `type` includes `dm` or `all`.	`query`, `type`, `in`, `from`, `before`, `after`, `has` (`file`, `link` or `task`)	Read
`search_dms`	Searches your one-to-one messages only.	`query`, `with`, `from`, `before`, `after`, `has`	Read
`catch_up`	Your unread messages and @mentions in direct messages, groups and channels, newest conversation first.	`since`, `include_dms`, `max_conversations`, `max_messages_per_conversation`	Read
`list_my_conversations`	Your direct messages, groups and channels with unread counts, most recent first.	`type`, `unread_only`, `query`	Read
`read_conversation`	The messages of one conversation, newest page first. Each page lists its messages oldest first. Up to 100 a page.	`conversation` (required), `before`, `limit`	Read
`draft_message`	Writes a draft into a conversation. The draft appears in your Workchats message box and is not sent.	`body` (required), `conversation` or `to`, `mentions`, `reply_to_id`	Writes a draft
`send_draft`	Sends a draft after you approve its text.	`draft_id` (required), `revision` (required)	Sends a message
`add_reaction`	Adds your emoji reaction to a message.	`message_id` (required), `emoji` (required)	Changes your own view
`pin_message`	Pins a message in its conversation, or unpins it.	`message_id` (required), `pinned` (required)	Replaces work others see
`mark_read`	Marks every message of a conversation read for you.	`conversation` (required)	Changes your own view
`create_dm`	Opens your direct message conversation with a person, or finds it.	`user_id` (required)	Creates work others see
`create_group_chat`	Creates a group with you as its admin.	`name` (required), `member_ids` (required), `description`, `visibility`	Creates work others see
`list_group_channels`	The channels of a group that you are in.	`group_id` (required)	Read

Notes:

Direct messages need their own tool. search_messages searches groups and channels by default. Searching direct messages needs search_dms, or type with dm or all. So you can see in the assistant when it reads your direct messages.
Results name their conversation. A message from a channel names the channel and its group. A direct message names the other person. A message that an assistant sent for its author carries via_client.
Reading never marks read. catch_up, read_conversation and the search tools leave your unread counts as they are. Only mark_read changes them, and it marks the whole conversation.
search_messages and search_dms take a query of 3 to 200 characters. The query is optional when in, with or from is given.
draft_message takes a body of 1 to 4,000 characters. To mention a person, write @ and their full name in the body, and give their usr_ id in mentions. See Drafts and the “via” label.

People

Tool	What it does	Key inputs	Effect
`search_users`	Finds colleagues by name, email or job title among the people you can see in the Workchats directory. Sorted by name.	`query` (required, at least 3 characters)	Read
`get_user_profile`	One colleague’s profile: job title, department, contact details, timezone, presence and status.	`user_id` (required)	Read
`set_my_status`	Sets or clears your custom status. A field you leave out keeps its value.	`text`, `emoji`, `clear_after`, `clear`	Changes your own view

search_users returns no email address or phone number.
get_user_profile returns null for a contact detail, job title or department that the person hides from you, and for the text of a status they hide. The assistant sees what a regular employee sees, also when you are an admin.

Tasks

Tool	What it does	Key inputs	Effect
`list_my_tasks`	Tasks assigned to you, created by you, or that you watch. Open tasks by default.	`scope` (`assigned`, `created` or `watching`), `status`, `stage`, `due_before`, `due_after`, `group_id`	Read
`search_tasks`	Tasks whose title or description contains the query, in every group you are in. Newest first.	`query` (required), `group_id`, `status`, `stage`, `assignee_id`	Read
`get_task`	One task with its description, subtasks, comments, recent activity and `lock_version`.	`task_id` (required)	Read
`create_task`	Creates a task in a group you are in, or in one of its channels.	`group_id` (required), `title` (required), `channel_id`, `description`, `assignee_ids`, `due_date`, `priority`, `stage`, `tags`	Creates work others see
`update_task`	Changes a task’s title, description, stage, priority, due date, assignees or tags.	`task_id` (required), `lock_version` (required), and the fields to change	Replaces work others see
`add_task_comment`	Adds your comment to a task.	`task_id` (required), `body` (required), `mentions`	Creates work others see
`convert_message_to_task`	Creates a task from a group or channel message, in that message’s group and channel.	`message_id` (required), `title`, `assignee_ids`, `due_date`, `priority`	Creates work others see
`create_subtask`	Adds a subtask to the end of a task’s checklist.	`task_id` (required), `title` (required), `assignee_id`	Creates work others see
`add_task_watcher`	Starts or stops watching a task, as you.	`task_id` (required), `watching` (required)	Changes your own view
`list_task_stages`	Your company’s task stages, the board columns, in order.	None	Read
`list_task_tags`	The tags used on a group’s tasks.	`group_id` (required)	Read

update_task needs the lock_version from the last read. If the task changed since, the answer is conflict. assignee_ids and tags replace the whole list.
Assignees must be members of the task’s group.
There is no overdue scope. For overdue tasks, use status: open with due_before.
A mention in a comment needs @ and the person’s full name in body. add_task_comment returns a warning for each mention it could not store.
convert_message_to_task works only on group and channel messages, not direct messages.

Meetings and calls

Tool	What it does	Key inputs	Effect
`list_meetings`	Meetings you organised or were invited to. Upcoming first by default. `past` lists the latest first.	`range`, `from`, `to`, `query`, `group_id`	Read
`get_meeting`	One meeting occurrence with its attendees, AI summary, action items, recording and, if asked, the start of its transcript.	`meeting_id` (required), `include_transcript`	Read
`create_meeting`	Schedules a meeting that you organise, and invites colleagues. They get the usual invitation.	`title` (required), `start` (required), `end`, `timezone`, `invitee_ids`, `group_id`, `description`, `video`	Creates work others see
`rsvp_meeting`	Accepts, declines or tentatively accepts one meeting occurrence.	`meeting_id` (required), `response` (required)	Changes your own view
`list_recent_calls`	Your 1:1 and group call history, latest first: calls you made and calls that rang you.	`type`, `status` (`answered` or `missed`), `with_user_id`, `from`, `to`	Read
`get_call`	One 1:1 or group call with its AI summary, action items, recording and, if asked, the start of its transcript.	`call_id` (required), `include_transcript`	Read

list_meetings leaves out cancelled occurrences.
A recurring meeting keeps one transcript, summary and recording, its latest. Every occurrence of the series reports that one.
create_meeting ends 30 minutes after start by default, uses your own timezone by default, and has a Workchats video link unless video is false.
An answer to the current occurrence of a series also answers the later occurrences, as in the app.

Files

Tool	What it does	Key inputs	Effect
`search_files`	Files shared in your direct messages, groups and channels, by file name. Newest first. Each file names the conversation it was shared in.	`query` (required), `in`, `type` (`document`, `image`, `video` or `audio`), `from`	Read
`ask_filing_cabinet`	Answers a question from the company Filing Cabinet, the official documents you may read, and cites its sources as `[n]`.	`question` (required)	Read
`read_file`	One file’s details and its text, for PDF, Word, PowerPoint, Excel, CSV, text and Markdown files.	`file_id` (required), `max_chars` (default 20,000, at most 50,000)	Read

A search_files page can hold fewer files than limit, or none, while next_cursor is set. Keep paging until next_cursor is null.
ask_filing_cabinet can take up to 45 seconds. It answers with unavailable when your company has the Filing Cabinet off, and it keeps no Filing Cabinet conversation.
read_file reads files up to 10 MB. text_status says whether text was extracted, or why not: unsupported, too_large or unavailable.

Events, polls and notifications

Tool	What it does	Key inputs	Effect
`list_events`	Company events you can see. Upcoming first by default.	`when` (`upcoming` or `past`), `my_rsvp`	Read
`get_event`	One company event, your RSVP and how many said yes.	`event_id` (required)	Read
`list_polls`	Polls you can see, newest first.	`group_id`, `status` (`active` or `closed`)	Read
`create_poll`	Posts a one-question poll in a group’s Main chat or one of its channels, where you can post.	`group_id` (required), `question` (required), `options` (required), `channel_id`, `multiple`, `anonymous`, `closes_at`	Creates work others see
`list_announcements`	Live announcements addressed to you, newest first.	`unread_only`	Read
`list_notifications`	Your notification feed, newest first.	`category` (`task`, `mention`, `call`, `meeting` or `all`), `unread_only`	Read

Reading announcements or notifications here does not mark them seen, read or acknowledged.
list_polls leaves out polls of a chat you locked, and polls of a channel you are not in. A poll names its group, not its channel.

Limits

Each employee has these limits, shared by all their connected assistants:

What	Limit
Tool calls	60 a minute
Drafts and sends (`draft_message` and `send_draft` together)	30 an hour
New sessions (`initialize`)	10 a minute

A tool over its limit returns the rate_limited tool error with retry_after_seconds. An initialize over its limit gets HTTP 429 with Retry-After.

Getting Started

Guides

AI assistants (MCP)

Reference

Changelog

Policies

Conventions

Read-only URL and toolsets

Search and fetch

Messaging

People

Tasks

Meetings and calls

Files

Events, polls and notifications

Limits

​Conventions

​Read-only URL and toolsets

​Search and fetch

​Messaging

​People

​Tasks

​Meetings and calls

​Files

​Events, polls and notifications

​Limits

Conventions

Read-only URL and toolsets

Search and fetch

Messaging

People

Tasks

Meetings and calls

Files

Events, polls and notifications

Limits