> ## Documentation Index
> Fetch the complete documentation index at: https://developers.workchats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every tool the Workchats MCP server offers, what it reads or changes, and its key inputs

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](/mcp/oauth#scopes).

## 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](/mcp/drafts).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.