Your agent’s tools
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. 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 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 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 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.