WolfSuite Workspace · Documentation

# MCP tools reference

A Wolf Workspace room gives an agent eight MCP tools for reading, searching, creating and editing its Word, Excel, PowerPoint and PDF files. An edit is a proposal for a person to approve unless the agent saves directly. [1](#evidence-1) [2](#evidence-2) [3](#evidence-3)

## The tools

The tool list is `workspace_list`, `doc_read`, `doc_search`, `doc_create`, `doc_edit`, `doc_inspect_visual`, `pack_link_refresh` and `comment_reply`, in that order. The whole list serializes to under 14,000 bytes, about 3,500 tokens. [1](#evidence-1) [4](#evidence-4)

| Tool | Arguments | What it does | Evidence |
| --- | --- | --- | --- |
| `workspace_list` | `format`, `limit` | Lists the room's documents with their current revision and the proposals and threads open on each, filtered by format and cut at the limit. | [5](#evidence-5) [6](#evidence-6) |
| `doc_read` | `doc` (required), `view`, `target`, `max_nodes` | Reads a document as `structure` with addresses, as `text` or `markdown`, whole or at an address, or a workbook as `cells`. | [7](#evidence-7) [8](#evidence-8) [9](#evidence-9) |
| `doc_search` | `query` (required), `doc`, `regex`, `limit` | Finds text ignoring case and returns addresses `doc_read` accepts. The query is a literal unless `regex` is true. | [10](#evidence-10) [11](#evidence-11) |
| `doc_create` | `name` and `format` (required), `template`, `ops` | Creates a blank document or a copy of a template, and saves any first operations as its first change. | [12](#evidence-12) [13](#evidence-13) [14](#evidence-14) |
| `doc_edit` | `doc`, `base_revision`, `mode`, `ops` (all required), `message` | With `mode: "propose"` holds the operations for a person; with `mode: "commit"` saves them at once and reports the new revision. | [2](#evidence-2) [3](#evidence-3) |
| `doc_inspect_visual` | `doc` (required), `pages`, `dpi`, `preflight`, `proposal_id` | Renders pages for a visual check. A server started without a renderer refuses with `BAD_REQUEST` and the reason `no-renderer`. | [15](#evidence-15) |
| `pack_link_refresh` | `pack` (required), `bindings`, `mode` | Refreshes linked figures from a pack. A server started without packs refuses with `BAD_REQUEST` and the reason `no-pack-refresher`. | [15](#evidence-15) |
| `comment_reply` | `thread_id` and `body` (required), `resolve` | Replies in a comment thread as the agent, and resolves the thread when `resolve` is true. | [16](#evidence-16) [17](#evidence-17) |

## The edit loop

1. Read the document with `doc_read` and note its revision. [18](#evidence-18)
2. Call `doc_edit` with that revision as `base_revision` and `mode: "propose"`. Nothing changes yet. [2](#evidence-2)
3. A person approves in the web app, which saves the change as the next revision. [19](#evidence-19)
4. Read the result, then reply in the thread with `comment_reply` and resolve it. [18](#evidence-18)

Proposing the same change twice returns the proposal already open instead of opening another. [20](#evidence-20)

## Errors

| Code | Meaning | Evidence |
| --- | --- | --- |
| `REVISION_MISMATCH` | `base_revision` is older than the document. The error carries the current revision to read and start again from. | [21](#evidence-21) |
| `UNKNOWN_DOCUMENT` | No document in the room has that name. | [22](#evidence-22) |
| `UNKNOWN_THREAD` | No comment thread has that id. | [23](#evidence-23) |
| `LICENSE_LIMIT` | The workspace is read-only. The message gives the reason and the way to upgrade. | [24](#evidence-24) |

An argument a tool does not define is refused, and the error lists the arguments that tool does define. [25](#evidence-25)

When the workspace has no seat for the agent, `doc_read` and `workspace_list` are refused and the agent takes no seat. [26](#evidence-26)

## Transports

Over HTTP, `initialize` opens a session and returns its id, and every later request must carry a session id that server holds. [27](#evidence-27) [28](#evidence-28)

Over stdio, a call before `initialize` is refused, and invalid arguments are JSON-RPC error `-32602`. [29](#evidence-29)

## Evidence

Each numbered reference above points to the test that exercises the statement or to a recorded observation of the hosted service at workspace.wolfsdk.com. Test paths are relative to the WolfSuite repository.

1. Test `sdk/web/packages/protocol/test/workspace.test.ts`: “eight tools, in order”
2. Test `sdk/web/packages/mcp/test/tools.test.ts`: “propose holds the ops for a person and changes nothing”
3. Test `sdk/web/packages/mcp/test/tools.test.ts`: “commit applies the ops at once and reports the new head and the log entry”
4. Test `sdk/web/packages/protocol/test/workspace.test.ts`: “the serialized tool list is under 14000 UTF-8 bytes and 3500 tokens”
5. Test `sdk/web/packages/mcp/test/tools.test.ts`: “lists the documents with their heads and what is open on them”
6. Test `sdk/web/packages/mcp/test/tools.test.ts`: “filters by format and cuts at the limit”
7. Test `sdk/web/packages/mcp/test/tools.test.ts`: “reads the structure with addresses, kinds and text previews”
8. Test `sdk/web/packages/mcp/test/tools.test.ts`: “reads text and markdown, whole or at an address”
9. Test `sdk/web/packages/mcp/test/tools.test.ts`: “reads the cells of a workbook, and refuses the cells of a document”
10. Test `sdk/web/packages/mcp/test/tools.test.ts`: “finds a literal ignoring case, with an address that doc_read accepts”
11. Test `sdk/web/packages/mcp/test/tools.test.ts`: “a literal is not a pattern”
12. Test `sdk/web/packages/mcp/test/tools.test.ts`: “creates a blank document that can be read at once”
13. Test `sdk/web/packages/mcp/test/tools.test.ts`: “copies a template”
14. Test `sdk/web/packages/mcp/test/tools.test.ts`: “applies the first ops as a commit and reports its entry”
15. Test `sdk/web/packages/mcp/test/tools.test.ts`: “doc_inspect_visual and pack_link_refresh say so instead of pretending”
16. Test `sdk/web/packages/mcp/test/tools.test.ts`: “replies in the thread as the agent”
17. Test `sdk/web/packages/mcp/test/tools.test.ts`: “resolves the thread with the reply”
18. Test `sdk/web/packages/mcp/test/workflow.test.ts`: “the agent proposes, the person approves, the agent reads the result and settles the thread”
19. Test `sdk/web/packages/mcp/test/tools.test.ts`: “a person approving the proposal commits it, and the agent then reads the result”
20. Test `sdk/web/packages/mcp/test/tools.test.ts`: “a repeated propose answers with the proposal already open, says existed, and opens nothing”
21. Test `sdk/web/packages/mcp/test/tools.test.ts`: “a stale base_revision is REVISION_MISMATCH carrying the head to rebase on”
22. Test `sdk/web/packages/mcp/test/tools.test.ts`: “an unknown document is UNKNOWN_DOCUMENT”
23. Test `sdk/web/packages/mcp/test/tools.test.ts`: “an unknown thread is UNKNOWN_THREAD”
24. Test `sdk/web/packages/server/test/read-only.test.ts`: “is LICENSE_LIMIT with a stable reason, and a message with the reason and the upgrade path verbatim”
25. Test `sdk/web/packages/mcp/test/tools.test.ts`: “an undefined argument is refused with the defined arguments for every tool”
26. Test `sdk/web/packages/mcp/test/tools.test.ts`: “an agent without a seat is refused doc_read and workspace_list, and takes none”
27. Test `sdk/web/packages/mcp/test/http.test.ts`: “initialize opens a session and returns its id”
28. Test `sdk/web/packages/mcp/test/http.test.ts`: “the session is required, and must be one this server holds”
29. Test `sdk/web/packages/mcp/test/stdio.test.ts`: “a call before initialize is refused, and invalid arguments are -32602”
