# MCP tools

The eleven tools an agent sees over MCP, with the inputs each one needs.

Seven tools write and four read. Every writing tool needs a request id, a branch and the version you expect, so no write is anonymous, unguarded or unsafe to retry. Every reading tool takes a branch selection and a page bound in rows and bytes.

## Shapes you will see everywhere

**A version**

```json
{ "generation": "3", "sequence": "41" }
```


**A selection**

```json
{ "branch": "main", "version": null }
```


**Page limits**

```json
{ "rows": 100, "bytes": 65536 }
```


**A record reference**

```json
{ "collection": "patients", "document_id": "p0" }
```


## Writing

- `define_collection` (request_id, branch, expected, collection, schema): Define a collection and its shape on a branch. schema is null, a boolean or an object.
- `put_records` (request_id, branch, expected, collection, records): Put one or more records on a branch atomically. Each record is a document_id and a document.
- `delete_record` (request_id, branch, expected, record): Delete a record and its incident edges and vectors.
- `link_records` (request_id, branch, expected, relation, from, to, properties): Link two records on a branch.
- `unlink_records` (request_id, branch, expected, relation, from, to): Remove a link between two records on a branch.
- `create_branch` (request_id, branch, expected, name, from): Fork a branch from a retained version. branch is the source; its expected head guards the fork.
- `merge_branch` (request_id, branch, expected, from, reviewed): Merge a reviewed branch, at the version its review read, into the branch it was forked from. reviewed must equal the current source head; the target must still match the source fork base. Read the review before supplying its version.


## Reading

- `run_query` (selection, query, page, parameters?, after?): Read one bounded page from a query.
- `describe_store` (selection, page, after): Describe one captured store version in bounded pages: branches, collections, relations and vector fields.
- `read_history` (selection, page, record?, after?): Read retained branch snapshots, or a record at a captured version.
- `review_branch` (selection, page, after): Read bounded branch differences, preparation states and dangling findings. after is an object of review cursors, initially {}. Read every page before merging.


## A write, as an agent sends it

**put_records**

```json
{
  "request_id": "admit-p2-2026-10-13",
  "branch": "ward-4b-intake",
  "expected": { "generation": "1", "sequence": "9" },
  "collection": "patients",
  "records": [
    { "document_id": "p2", "document": { "name": "Cai", "ward": "4B", "admitted": 20261013 } }
  ]
}
```


> Why a Lys pass on every call
> When a pass source is configured, the stdio server presents it before each tool's store work. Without one, a protected store refuses the call as pass_missing. What the agent may read and write is the pass's grant, decided by Lys, not by the agent's own claim.