# MCP tools

## Introduction

These tools are listed on a connector only when **Track work and memories**
was ticked when it was approved. See [Work](/docs/work) to turn it on. Every
tool acts as the person who approved the connector, so it sees exactly the
projects they can see.

Most tools take a project the same way: pass `project` (its key) or
`repository` (the output of `git remote get-url origin`), or neither when
there is only one project. See [Repositories](/docs/work/projects#repositories)
for how a project is found.

## Session start and end

| Tool | What it does |
|------|--------------|
| `get_work_context` | Call at session start and after compaction. Returns the last handoff, issues this person holds, answers to their questions, the top ready issues, and the project's memories (shortened). |
| `write_handoff` | Leave a `summary`, `next_steps` and `open_questions` for the next session, with the issues touched. `release_claims` gives back every issue held in the project. |

## Projects

| Tool | What it does |
|------|--------------|
| `create_project` | Create a project with a `key`, a `name`, and optionally a `description` and the `repository` remote. The key cannot change later. |

## Issues

| Tool | What it does |
|------|--------------|
| `list_issues` | Short rows for one `view`: `ready` (default), `mine`, `in_progress`, `waiting`, `open`, `stale` (claims that lapsed), `closed`, `all`. Filters by `type`, `priority`, `labels` (all of), `labels_any`, `parent` and `query`. Returns up to 50 rows. |
| `show_issue` | One issue in full: text fields, dependencies both ways, children's progress, questions, latest comments. |
| `create_issues` | 1 to 25 issues in one call. Items can name each other with `ref` and point at those names from `parent`, `blocked_by` and `discovered_from`. |
| `update_issue` | Change text fields, type, priority, labels, parent or metadata (merged, `null` removes a key), or status `open`, `blocked`, or `deferred` with `defer_until`. `append_notes` adds a dated line. |
| `claim_issue` | Take an issue by `id`, or the top ready issue matching filters. Returns the full issue. |
| `release_issue` | Give a claim back, with a `note` for whoever picks it up. |
| `close_issue` | Close with a `reason`, or set `duplicate_of` or `superseded_by`. Returns the issues that just became ready and whether the parent epic is finished. |
| `link_issues` | Add or `remove` a dependency of `type` `blocks` (default), `discovered-from` or `related`. Cycles are refused. |
| `comment_on_issue` | A durable note on the issue. |
| `ask_human` | Ask you a `question` on an issue. The issue waits until it is answered. |

## Memories

| Tool | What it does |
|------|--------------|
| `remember` | Store a fact under a `key`, up to 2,000 characters. The same key replaces it; `forget` deletes it. Without a key, one is made from the content. |
| `recall` | Read memories in full: one by `key`, those matching a `query`, or every key with a preview. |

## Board

| Tool | What it does |
|------|--------------|
| `show_work_board` | Shows you the project's board: questions for you, ready work, who holds what, what is blocked, what just closed. Assistants that support MCP Apps render it in the chat with buttons to answer, change priority, comment, close, and release a lapsed claim. Others get the same data as JSON. |

The board uses two more tools, `work_board_data` and `work_board_act`, to
refresh itself and carry out your clicks. Agents are told never to call them.

## Example

A session in a repository with an existing project:

```text
get_work_context  { "repository": "git@github.com:acme/api.git" }
claim_issue       { "repository": "git@github.com:acme/api.git" }
comment_on_issue  { "id": "API-12", "body": "Reproduced on main." }
create_issues     { "project": "API", "issues": [
                    { "title": "Orders page runs 40 queries", "type": "bug",
                      "discovered_from": "API-12" } ] }
close_issue       { "id": "API-12", "reason": "Fixed in PR #123" }
write_handoff     { "project": "API", "summary": "Fixed API-12.",
                    "next_steps": "Start on API-13 (the N+1 found today)." }
```

## Limits

- 25 issues per `create_issues` call and 50 rows per `list_issues` call.
- Metadata up to 8 KB per issue.
- Memories up to 2,000 characters each.
- A claim lapses after 30 minutes without a tool call from the connector.