---
title: "Tool reference"
description: "Every tool the MySpec MCP servers offer, which ones change data, and the rules for editing, paging, sessions, artifacts and comments."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool reference

The two MySpec MCP servers share 43 tools in nine groups, with the same names
wherever they do the same thing. Two more tools exist on only one server:

- `download_spec_file` is **local server only**, because it saves files to your disk.
- `list_trashed_spec_files` is **remote server only** and deprecated.

In the tables, **Changes data** marks the tools that create, change or delete
something in MySpec. They need a [read and write API token](/mcp/api-tokens/) or a
connection with write access (except stream tokens; see
[Stream tokens](#stream-tokens)). Every other tool only reads. Every tool also
works within your role on the project; see [Project roles](#project-roles).

## Projects

| Tool | What it does | Changes data |
|---|---|---|
| `list_projects` | List or search the projects you can see, most recent activity first, with your role on each as `viewer_role`. | No |
| `get_project` | Get one project with its active sessions, spec files and attachments, and your role on it as `viewer_role`. | No |
| `create_project` | Create a project with a name and an optional description. | Yes |
| `update_project` | Change a project's name, description or project type (`greenfield`, `brownfield` or `auto`). | Yes |
| `archive_project` | Archive a project. Archiving an archived project does nothing. | Yes |
| `unarchive_project` | Return an archived project to the active list. | Yes |
| `delete_project` | Delete an archived project. It refuses an active project and never archives it for you. Needs the `admin` role on the project. | Yes |

## Spec files

| Tool | What it does | Changes data |
|---|---|---|
| `list_spec_file` | List a project's spec files with path, type, size, revision count and last update. Filter to a folder with `path`. Set `trashed: true` to list the Trash Bin instead. | No |
| `get_spec_file` | Get a file's metadata, including the `content_version` you need to update it. On the local server, `include_download_url` also returns a time-limited download link for a revision. | No |
| `read_spec_file` | Read a file's text, up to 2,000 lines per call. Pass `revision` to read an older revision. | No |
| `download_spec_file` | **Local server only.** Save a file to disk, by default under `.specs/` in the server's working folder. Handles binary files and files up to 50 MiB. Returns where it saved the file, not the content. It refuses to replace an existing file unless you pass `overwrite: true`. | No |
| `upload_spec_file` | Add a new spec file at a path that has no file yet. On the local server, the body can come from a local file (`local_file_path`) instead of `content`. | Yes |
| `update_spec_file` | Save a new revision of an existing file. Pass `expected_version` (see [Edit safely](#edit-safely-with-content_version)). | Yes |

## Trash

| Tool | What it does | Changes data |
|---|---|---|
| `move_spec_file_to_trash` | Move a spec file to the Trash Bin. It disappears from file lists and from the AI's tools, but stays restorable. This is not a permanent delete. | Yes |
| `restore_spec_file_from_trash` | Move a file from the Trash Bin back to the project's files. | Yes |
| `list_trashed_spec_files` | **Remote server only, deprecated.** Lists the Trash Bin. Use `list_spec_file` with `trashed: true` instead; this tool will be removed. | No |

## Attachments

| Tool | What it does | Changes data |
|---|---|---|
| `list_attachments` | List a project's attachments with name, type and size. | No |
| `get_attachment` | Get one attachment's metadata. On the local server, `include_download_url` also returns a time-limited download link. | No |
| `read_attachment` | Read an attachment. Text comes back in pages of lines. PNG, JPEG, GIF and WebP images come back whole. PDF, DOCX, XLSX and other binary files cannot be read here; open them in the web app. | No |
| `upload_attachment` | Add an attachment of up to 10 MB: PDF, DOCX, XLSX, PNG, JPEG, GIF, WebP or any UTF-8 text file. The local server reads a file path on your machine; the remote server takes the content as base64. With `override: true`, an existing attachment with the same name is replaced. | Yes |

## Sessions

| Tool | What it does | Changes data |
|---|---|---|
| `list_spec_sessions` | List a project's sessions with their title and status. Filter by `archive_filter` (`active`, `archived` or `all`), `status` or a search `query`. | No |
| `get_spec_session` | Get one session's status, counters, dates and title. `include_context: true` also returns the session's working context, up to 1 MiB. | No |
| `start_spec_session` | Start a new Generate or Edit session with an opening message, wait for MySpec's first reply, and return a link to continue in the web app. See [Start a session](#start-a-session-from-your-agent). | Yes |
| `rename_spec_session` | Rename a session (up to 500 characters). Works on archived sessions too. | Yes |
| `archive_spec_session` | Archive a session. You must archive a session before you can delete it. | Yes |
| `unarchive_spec_session` | Return an archived session to the active list. | Yes |
| `delete_spec_session` | Delete an archived session. It refuses an active session and never archives it for you. | Yes |

No session tool returns the chat conversation itself.

## Artifacts

| Tool | What it does | Changes data |
|---|---|---|
| `list_artifacts` | List a project's artifacts with their revision count. | No |
| `get_artifact` | Get an artifact's metadata and its list of files (path, type, size, checksum) for the latest revision, or for `revision`. | No |
| `read_artifact_file` | Read one text file from an artifact, in pages of lines. Binary files such as images and fonts cannot be read. | No |
| `create_artifact` | Create an artifact from a set of files, as revision 1. | Yes |
| `write_artifact_revision` | Add a new revision, either with every file or with only the changed files. | Yes |
| `rollback_artifact` | Restore an earlier revision by adding a new revision with its files. | Yes |

## Stream tokens

| Tool | What it does | Changes data |
|---|---|---|
| `create_stream_token` | Create a short-lived token that lets a client follow a project's live events. | Yes |
| `list_stream_tokens` | List your organization's stream tokens with their scope, expiry and whether each still works. Never returns the secret. | No |
| `revoke_stream_token` | Stop a stream token at once. | Yes |

A **Read only** API token can also create and revoke stream tokens, because a
stream token only reads. A connector connected without write access cannot.
See [Stream tokens](/mcp/stream-tokens/) for how to use them.

## Comments

| Tool | What it does | Changes data |
|---|---|---|
| `list_spec_file_comments` | List the comment threads on a spec file, with the passage each one is about, whether it is resolved and its comments. Filter with `status`: `open`, `resolved` or `orphaned`. | No |
| `create_spec_file_comment_thread` | Start a comment thread on a passage of a spec file. | Yes |
| `reply_spec_file_comment_thread` | Reply to a thread. | Yes |
| `update_spec_file_comment` | Edit one of your own comments. | Yes |
| `delete_spec_file_comment` | Delete one of your own comments. | Yes |

## Tasks

The task tools work on a project's task board: the checkbox tasks in its
`tasks.md` files. See [Tasks](/guides/projects/#tasks).

| Tool | What it does | Changes data |
|---|---|---|
| `list_tasks` | List a project's tasks in file order. Each has a `task_id`, a status (`pending`, `in_progress` or `done`), an assignee, a priority, story points, a cycle, start and due dates, labels, and relationships with other tasks. Filter by status, assignee (`me` for yourself, `none` for unassigned), cycle, label or file. Add `include_details` to get each task's sub-bullets. | No |
| `list_task_assignees` | List the people a project's tasks can be assigned to, and your own user id as `self_user_id`. | No |
| `update_tasks` | Change the planning fields of one or more tasks: assignee, priority, story points, cycle, start and due dates, labels, and relationships with other tasks. It doesn't change a task's status or text. | Yes |
| `set_task_status` | Change the status of one or more tasks by rewriting their checkbox in `tasks.md`: `[ ]` pending, `[-]` in progress, `[x]` done. Each changed file gets one new revision. | Yes |

- `update_tasks` applies the same change to every task you pass. A field you
  leave out stays as it is, and `null` clears it. Labels are added and removed,
  not replaced. One unknown task id fails the whole call.
- A relationship says how a task stands to another: it `blocks` the other
  task, it is `blocked_by` the other task, or the two are `related`. Each
  `list_tasks` task lists them as `{type, task_id}`. In `update_tasks`,
  `add_relationships` sets them and `remove_relationships` takes task ids to
  unlink. Two tasks have one relationship at most, so setting one replaces the
  old one, and the other task shows the inverse.
- `set_task_status` can partly succeed: a file it can't write fails only its own
  tasks, and the result gives an outcome for each task. Pass
  `expected_versions` with the `content_version` values from `list_tasks`, so a
  file that changed since you listed it is not written.
- The task tools work only where the task board is available. Elsewhere they
  fail with "the task board is turned off in this MySpec environment".

## Project roles

Each tool works within your [project role](/guides/teams-and-project-access/),
and never does more than you can do in the web app:

| Your role | What the tools can do |
|---|---|
| `read` | Every tool that only reads, and the [stream token](#stream-tokens) tools. |
| `write` | Also the tools that change spec files, the Trash Bin, attachments, sessions, artifacts, comments and tasks, including `start_spec_session`. |
| `admin` | Also `update_project`, `archive_project`, `unarchive_project` and `delete_project`. |

- `list_projects` and `get_project` show your role on each project as
  `viewer_role`: `read`, `write` or `admin`.
- `list_projects` leaves out projects you have no role on, and other tools
  answer as if those projects do not exist.
- `create_project` works whatever your role, and gives you `admin` on the new
  project.
- A **Read only** API token, or a connection without write access, acts as
  `read` on every project. Its tools that change data fail with the
  [read-only error](/mcp/troubleshooting/#read-only-errors).

A tool that needs more than your role fails with a message like this one:

```text
update_spec_file failed: permission denied — this action needs the write role on the project; you have read. Ask a project admin for access.
```

A new token will not help. Ask someone with `admin` on the project to raise
your role. See [Troubleshooting](/mcp/troubleshooting/#permission-denied-for-your-project-role).

## Edit safely with content_version

Several people and AI sessions can work on the same project at once. To avoid
overwriting someone else's work:

1. Read the file with `get_spec_file` or `read_spec_file`. Both return a
   `content_version`.
2. Pass that value as `expected_version` to `update_spec_file`.
3. If someone saved the file in the meantime, the update is rejected and their
   version is kept. The error says who changed it and when. Read the file again,
   combine the changes, and update with the new `content_version`.

Do not resend the same content after a conflict: that would undo the other
person's work. `content_version` is not the same as the revision count.

The remote server always requires `expected_version`. The local server accepts an
update without it, but a project can be set up to reject such updates, so
always pass it.

## Pagination

### Lists

List tools take `limit` and `offset`. They return `total` and, while more
records remain, `next_offset`: pass it as `offset` to get the next page. The
local server's `list_projects` returns no `next_offset`; page on with
`offset` until you have `total` projects. A `limit` above the maximum is reduced
to the maximum, except on the local server's `list_projects`, which refuses it.

| Tool | Default page size | Maximum |
|---|---|---|
| `list_projects` | 20 on the local server, 50 on the remote server | 100 on the local server, 200 on the remote server |
| `list_spec_file`, `list_attachments`, `list_stream_tokens` | 50 | 200 |
| `list_artifacts` | 50 | 100 |
| `list_spec_sessions` | 10 | 20 |
| `list_tasks` | 100 | 500 |

`list_tasks` returns `total_tasks` instead of `total`, and refuses a `limit`
above 500.

`list_spec_file_comments` returns at most 100 threads and shortens each comment
to 1,000 characters. Filter by `status` to see fewer threads in full.

### Reading files by line

`read_spec_file`, `read_attachment` (for text) and `read_artifact_file` read a
window of lines:

- `offset` is the first line to read, starting at 1.
- `limit` is the number of lines, at most 2,000 (the default). One response
  holds at most 1 MiB.
- The result includes `total_lines`, `truncated` and, when more lines remain,
  `next_offset`.

`read_spec_file` refuses binary files and files over 8 MiB. On the local server,
use `download_spec_file` for those. On the remote server, open them in the web
app.

## Start a session from your agent

`start_spec_session` lets your coding agent start a MySpec session for you, with
an opening message it writes from what it knows about your code and your goal.

- **One call starts one real session**, and that session uses AI, just like one
  you start in the web app. Call it once per goal. If the call times out, check
  `list_spec_sessions` before trying again, or you may create a duplicate.
- **It waits for the first reply**, for up to 75 seconds, then returns. If the
  first reply is not finished by then, it returns anyway and the reply finishes
  in the background.
- **It needs write access**: a read and write API token, or a connection with
  write access, and the `write` role on the project. With read-only access, no
  session is created.
- **For Brownfield workflows**, start the local server's `reverse` command first
  and keep it running, so the session can read your code. See
  [Work on an existing codebase](/guides/brownfield/).
- **A Generate session runs at Full spec depth.** The tool has no spec depth
  argument. When you continue the session in the web app, the level picked
  there applies from your next message. See
  [Spec depth](/guides/generate-sessions/#spec-depth).

### Arguments

| Argument | Required | Meaning |
|---|---|---|
| `project_id` | Yes | The project to start the session in. |
| `mode` | Yes | `generate` writes new spec files; `edit` changes existing ones. |
| `prompt` | Yes | The opening message. |
| `workflow_id` | No | Which workflow to follow (see below). Must match `mode`. Omit it to use the default. |
| `language` | No | The language the session writes in: `en` (English, the default), `zh` (Simplified Chinese), `ja` (Japanese) or `vi` (Vietnamese). It cannot change once the session starts. |
| `model_id` | No | Run the session with a specific model. Omit it to let MySpec choose. |
| `attachment_ids` | No | Up to 25 of the project's attachments to reference in the opening message. |
| `spec_file_ids` | No | Up to 25 existing spec files to reference. In practice, Edit sessions need these. |
| `session_title` | No | A title of up to 500 characters. Some workflows rename the session during the interview. |

| `workflow_id` | Mode | Workflow |
|---|---|---|
| `myspec-greenfield-v1` | `generate` | MySpec (the default for `generate`) |
| `speckit-greenfield-v1` | `generate` | SpecKit |
| `openspec-brownfield-v1` | `generate` | OpenSpec, for an existing codebase |
| `myspec-brownfield-v1` | `generate` | MySpec, for an existing codebase |
| `myspec-edit-v1` | `edit` | MySpec edit (the default for `edit`) |
| `myspec-edit-brownfield-v1` | `edit` | MySpec edit, for an existing codebase |

An unknown `workflow_id`, or one that does not match `mode`, is rejected before
anything is created. So is an attachment or spec file id that does not belong to
the project.

### Result

| Field | Meaning |
|---|---|
| `session_url` | The link to open the session in MySpec. Give it to the person you are working with. |
| `session_id`, `project_id` | Identifiers of the new session and its project. |
| `assistant_text` | MySpec's first reply, or as much of it as was ready. |
| `pending_action` | What MySpec is waiting for (see below). |
| `next_step_instruction` | Guidance for the calling agent. |
| `first_turn_error` | Present only when the session was created but its first reply could not run. The person can send the message again from the session page. |
| `warnings` | Local server only. For example, a warning that no `reverse` bridge is running for a Brownfield session. |

| `pending_action` | Meaning |
|---|---|
| `mcq_form_pending` | MySpec asked interview questions. |
| `spec_file_pending_decision` | A spec file is waiting to be approved or changed. |
| `review_feedback_pending` | Review feedback is waiting for a decision. |
| `user_choice_pending` | MySpec asked the person to pick an option. |
| `turn_still_running` | The first reply was still being written after 75 seconds. It finishes in the background; opening `session_url` shows it. |
| `none` | Nothing is waiting. |

The agent's job ends with handing over `session_url`. The person continues the
session in MySpec; the agent should not try to answer MySpec's questions itself.

## How artifacts work

An artifact is a set of files that MySpec stores and versions as one unit, such
as an HTML mockup made of `index.html`, `styles.css` and `app.js`.

- `create_artifact` creates revision 1. An artifact can hold at most 50 files,
  2 MiB per file and 10 MiB per revision. Its `slug` must be unique in the project.
- `write_artifact_revision` adds a revision. Without `base_revision`, the files
  you send become the whole artifact. With `base_revision`, you send only the
  changed files, plus the paths to drop in `remove`.
- Revisions never change once written. By default, only the 50 newest are kept;
  rolling back to an older one that is no longer kept fails with "not found".
- `rollback_artifact` restores an earlier revision by **adding** a new revision
  with its files. History is never rewritten.
- To avoid overwriting someone else's revision, pass the current `revision_count`
  from `get_artifact` or `list_artifacts` as `expected_version`. If the artifact
  has moved on, the write is rejected; read it again and retry.

## Rules for comments

- **No tool can resolve, reopen or re-attach a thread.** Agents can read, add,
  reply, and edit or delete their own comments. Deciding that a discussion is
  finished stays with people. See [Comments](/guides/comments/).
- To start a thread, pass the passage as `anchor_quote`, copied exactly from the
  file. MySpec finds it in the current text. Do not send character positions.
  If the passage appears more than once, add a few words before or after it in
  `anchor_prefix` or `anchor_suffix`.
- `update_spec_file_comment` takes the **comment's** own `content_version` as
  `expected_version`, not the file's.
- `delete_spec_file_comment` has three outcomes. A reply disappears. A first
  comment that has replies is replaced by a "deleted" placeholder, so the replies
  still make sense. A first comment with no replies deletes the whole thread.
- On a file in the Trash Bin you can read, edit and delete comments, but you
  cannot start threads or reply.
- MySpec records comments and spec file changes made through these tools as
  AI work. In the web app, comments written by an agent show as **MySpec AI**.

## Limit the tools an agent sees

On the remote server, the optional `X-MCP-Tools` header limits the tools your
agent sees. See [Remote MCP server](/mcp/remote-server/).

Source: https://docs.myspec.dev/mcp/tools/index.mdx