# Your agent’s tools

> The MCP tools kelve gives it. Every page of kelve's docs is listed at https://kelve.ai/llms.txt.

`kelve mcp` gives your agent eleven tools over the Model Context Protocol, and instructions on when to use them. It speaks MCP versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

## open

`open` opens kelve for you on what you asked to see, in a new browser tab. It starts kelve if it isn't running. It says how many files there are, and how many need reading. It also gives your agent the number of what it opened, to take its jobs by.

| Input | What it is |
|---|---|
| `what` | Needed. `change`: what isn't committed, a branch against a base, or one commit. `worktree`: everything in its worktree since it left its base, committed or not. `folder`: a folder, or the whole repository. `files`: some files. `file`: one file. |
| `path` | The folder or file, from the root. For a change or a worktree, the folder your agent is working in. |
| `paths` | For `files`: each file, from the root. |
| `base` | For a change or a worktree: the branch it's read against, such as `main`. Left out for what isn't committed. |
| `commit` | For a change: one commit. |
| `title` | What it is, in a few words, at most 80 characters. |
| `said` | What it is, or what changed and why, at most 200 characters. |
| `model` | The model your agent runs on, as it names it. |

When you ask what it did, your agent shows only what's new since it last showed you. When it hands work over, by committing, pushing or opening a pull request, it shows you that too, without being asked.

## next_job

`next_job` takes the next piece of kelve's work. A job is one of these:

- finding a way in
- reading files
- tracing an idea down
- writing or fixing an entry
- saying plainly what part of your work does
- doing a note
- writing a lesson

Each job has its instructions, its material, and the shape its answer must fit. `next_job` says so when there's no more.

| Input | What it is |
|---|---|
| `for` | The number of something open in kelve. Only its jobs come. `open` gives the number, and so does what kelve gives you to say for one tab, "(number 12)". Left out, any job. |
| `have` | The instructions and answer shapes your agent already has in full in this conversation, by name, such as `read@10` and `shape:1a2b3c4d`. A job following one of those comes with its name alone. |
| `model` | The model your agent runs on. It goes to the shared graph with what it writes. |

## hand_in

`hand_in` hands in an answer to a job. kelve checks the answer's shape at once. An answer that doesn't fit comes back with why, to hand in again. When kelve takes the answer, the next job comes with it.

| Input | What it is |
|---|---|
| `job` | Needed. The job's number, as `next_job` gave it. |
| `answer` | Needed. The answer, in the job's shape. |
| `more` | `false` for the last job your agent will take. No next job comes, and your agent is told how many are left. |
| `for`, `have`, `model` | As for `next_job`. |

## kept

`kept` lists kelve's work waiting for your agent, the most wanted first, as you see it on [its list](/docs/agents-list/). No inputs.

## notes

`notes` gives the notes you left your agent in kelve that are waiting, for the project it's working in. Each note comes with:

- its id and version
- what it asks
- the file and lines it's on, as they are now
- other notes on the same lines
- the ideas on those lines

For a note done before, `notes` also gives what it said then, what was done, and what's been added since. No inputs.

## note_done

`note_done` marks a note done, with a line on what your agent did. Then your agent opens what it changed, so you see it beside your note.

| Input | What it is |
|---|---|
| `note` | Needed. The note's id, as `notes` gave it. |
| `version` | Needed. The note's version, as `notes` gave it. A note changed since isn't marked done. |
| `did` | Needed. What your agent did, at most 300 characters. |

## lessons

`lessons` gives what other people's agents learned using the same ideas, from the shared graph. Each lesson comes with how far it's confirmed, and a check to make first when it isn't. [Lessons](/docs/lessons/) says more.

| Input | What it is |
|---|---|
| `problem` | What failed, as the tool said it. kelve takes your work's own names out before it looks. |
| `ideas` | The ideas, libraries or tools your agent is using, by name, such as `pytest`. Left out, what this work uses: the libraries its files import and the tools run here. |
| `write` | `true` keeps a job for what your agent learned itself, to take with `next_job`. |

## held

`held` says what came of a lesson kelve gave your agent. A lesson that doesn't apply is kelve's miss, and never counts against the lesson. Only the lesson and what came of it go to the shared graph.

| Input | What it is |
|---|---|
| `lesson` | Needed. The lesson's id, as kelve gave it. |
| `held` | Whether it held, where it applied. |
| `applies` | `false` when it doesn't apply here at all. |
| `why` | Why it didn't hold or apply, in a line, at most 200 characters, with nothing from the work. |

## marks

`marks` reads [what kelve marks](/docs/marks/) for you:

- how much overall
- how well you know each area
- ideas always and never marked
- anything in your words
- whether files read as code or plainly

No inputs.

## set_marks

`set_marks` writes what kelve marks for you, in place of what was there. Your agent uses it only when you ask it to. Then your agent tells you what it wrote.

| Input | What it is |
|---|---|
| `mark` | Needed. How much to mark anywhere not named in `areas`: `new` (every idea), `learning` (all but the basics), `working` (advanced and specialist ideas) or `deep` (specialist ideas only). |
| `read` | How code files read: `code` or `plainly`. |
| `areas` | Needed. How well you know each area. Each has an `area`, such as `rust`, and a `level`. A language also has its own `read`. |
| `always` | Needed. Ideas to always mark, by name. |
| `never` | Needed. Ideas never to mark, by name. |
| `words` | Needed. Anything else, in your words. |

## update

`update` updates kelve to its newest version, as [`kelve update`](/docs/update-uninstall/) does. It restarts kelve if it's running, and says what it did in a sentence. Its description tells your agent to call it only once you've said yes. No inputs.

## When your agent uses them

kelve's instructions tell your agent to use these tools:

- when you ask to see something in kelve
- when you ask it to do kelve's work
- when you've left it notes

Your agent checks notes before it starts anything you ask. When you ask it to do what's waiting for you in kelve, it takes jobs with the number you give. Without a number, it takes any job. When something fails and it doesn't know why, it asks `lessons`. It says with `held` whether a lesson it was given held. With a dozen files or more to read, it shares the jobs among subagents, if it can. Each subagent uses the same `for`.

When a newer kelve is out, kelve tells your agent once, with your next message or at the end of a tool's answer. Your agent asks you whether to update, and calls `update` only if you say yes.
