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

# Tools

> The twelve Dexi MCP tools, their parameters, and return shapes

Seven read tools (scope `notes:read`), three write tools (`notes:write`), and two spaced-repetition tools. Errors come back as MCP tool errors with a plain-language message (`Note not found`, `Folder not found: X`, …).

## Access restrictions

A connection may be [restricted](/mcp/oauth#access-restrictions) to notes in one folder, notes with one tag, or both. Inside a boundary:

* Every read tool sees only the user's **own** in-boundary notes (teammates' shared notes are excluded); out-of-boundary notes behave exactly like nonexistent ones (`Note not found`, `Folder not found`).
* `list_tags` and `list_folders` cover only in-boundary content — folder names and tags outside the boundary never appear.
* `create_note` keeps writes inside the boundary automatically: notes are filed into the restricted folder, and the restricted tag is appended to the text when missing.
* `update_note` refuses edits that would remove the restricted tag from a note (the error names the tag); deletes work only on in-boundary notes.
* Review tools cover only in-boundary cards.

## The note item

List and search tools return items in one shared shape:

```json Note item theme={null}
{
  "id": "2982e9b4-19fe-40fd-9a69-e23d45e53b13",
  "title": "Attention is all you need",
  "snippet": "Reading notes on the transformer paper — the key insight is…",
  "tags": ["@vaswani", "#ml", "#papers"],
  "source": "bookmark",
  "source_url": "https://arxiv.org/abs/1706.03762",
  "created": "2026-07-14T09:12:00+00:00",
  "updated": "2026-08-02T18:40:11+00:00"
}
```

* `snippet` is the first 300 characters of the body (`…` appended when truncated).
* `source` is `note`, `bookmark`, `email`, or `feed`; `source_url` is set for bookmarks and feed articles.
* Conditional keys: `folder` (name, only on your own filed notes), `shared: true` + `owner` (only on a teammate's team-shared note — read-only for you), and `similarity` (0–1, only from `semantic_search` and `find_similar`).

`get_note`, `create_note`, and `update_note` return the same shape with `snippet` replaced by `text` — the full plain-text body.

## Read tools

### search\_notes

Full-text search over titles and body text, ranked by relevance. Covers bookmarks, saved emails, and feed articles too — every item in Dexi is backed by a note. Use `semantic_search` instead when looking for concepts rather than exact words.

| Parameter | Type   | Constraints | Default  |
| --------- | ------ | ----------- | -------- |
| `query`   | string | 1–200 chars | required |
| `page`    | int    | ≥ 1         | 1        |
| `size`    | int    | 1–50        | 10       |

Returns `{items, total, page}`.

### semantic\_search

Find notes by meaning using vector embeddings — surfaces conceptually related content even when no words are shared with the query (e.g. "machine learning" matches notes about neural networks). Each result carries a `similarity` score; results below \~0.6 are usually only loosely related.

| Parameter | Type   | Constraints | Default  |
| --------- | ------ | ----------- | -------- |
| `query`   | string | 1–500 chars | required |
| `size`    | int    | 1–50        | 10       |

Returns `{items}` (no total/pagination — it's a ranked window).

### list\_notes

Browse newest-first with filters. The right tool for "what did I save this week?"-style questions.

| Parameter | Type   | Constraints                                                                                    | Default   |
| --------- | ------ | ---------------------------------------------------------------------------------------------- | --------- |
| `page`    | int    | ≥ 1                                                                                            | 1         |
| `size`    | int    | 1–50                                                                                           | 10        |
| `source`  | enum   | `all` `bookmark` `email` `feed` `note`                                                         | `all`     |
| `tag`     | string | `"#hashtag"`, `"@mention"`, or a bare word matching either                                     | —         |
| `folder`  | string | folder name (case-insensitive) or `"unfiled"`; unknown name errors — call `list_folders` first | —         |
| `period`  | enum   | `today` `yesterday` `week`                                                                     | —         |
| `sort`    | enum   | `created` `updated`                                                                            | `created` |

Returns `{items, total, page}`.

### get\_note

Fetch one note in full: complete body text, title, tags, source kind, and source URL.

| Parameter | Type   | Constraints                             |
| --------- | ------ | --------------------------------------- |
| `note_id` | string | note UUID (from search or list results) |

Returns a full note object (with `text`). Invisible or unknown ids error with `Note not found`.

### find\_similar

The notes most semantically similar to a given note — related reading, duplicates, connected ideas. Each result carries `similarity`.

| Parameter | Type   | Constraints | Default  |
| --------- | ------ | ----------- | -------- |
| `note_id` | string | note UUID   | required |
| `size`    | int    | 1–50        | 10       |

Returns `{items}`.

### list\_tags

The user's tags with usage counts, most-used first. Hashtags (`#topic`) categorize subjects; mentions (`@name`) reference people or entities. Tags are parsed automatically from note text — they are not set directly.

| Parameter | Type | Constraints         | Default   |
| --------- | ---- | ------------------- | --------- |
| `kind`    | enum | `hashtag` `mention` | `hashtag` |
| `limit`   | int  | 1–200               | 50        |

Returns `{tags: [{tag, count}]}`.

### list\_folders

The user's folders with note counts, plus how many notes are unfiled. Folders are personal organization — a note lives in at most one folder (tags handle cross-cutting topics). Pass a folder's name to `list_notes` to browse its contents.

No parameters. Returns `{folders: [{name, note_count}], unfiled_count}`.

## Write tools

### create\_note

Create a new note from plain text. Include `#hashtags` and `@mentions` inline — Dexi turns them into tags automatically.

| Parameter | Type   | Constraints     | Default |
| --------- | ------ | --------------- | ------- |
| `title`   | string | ≤ 500 chars     | `""`    |
| `text`    | string | plain text body | `""`    |

Returns the created note (full shape with `text`). On a free plan at the note cap, errors with the limit message instead of creating.

### update\_note

Update a note's title and/or body. `mode: "append"` adds text to the end of the existing body — safe for adding thoughts to an existing note. `mode: "replace"` overwrites the entire body, and any rich formatting (headings, links, lists) is lost — read the note first and prefer append unless a rewrite was asked for.

| Parameter | Type   | Constraints                      | Default   |
| --------- | ------ | -------------------------------- | --------- |
| `note_id` | string | note UUID; must be your own note | required  |
| `title`   | string | ≤ 500 chars; omit to keep        | —         |
| `text`    | string | omit to keep                     | —         |
| `mode`    | enum   | `replace` `append`               | `replace` |

Returns the updated note. Omitting both `title` and `text` in replace mode errors with `Nothing to update`.

### delete\_note

Permanently delete a note. Cannot be undone, and also removes the attached bookmark, saved email, or feed-article record if the note came from one. The tool is flagged destructive; assistants should confirm with the user before deleting anything not explicitly asked for.

| Parameter | Type   | Constraints                      |
| --------- | ------ | -------------------------------- |
| `note_id` | string | note UUID; must be your own note |

Returns `{deleted: true, id, title}`.

## Spaced repetition

Notes tagged with the user's review deck tags (Settings → Review) enroll in an SM-2 review schedule. These tools let an assistant run a review session in conversation.

### get\_due\_reviews

Cards due for review. Quiz the user on the title/topic before revealing the body, then call `grade_review`.

| Parameter | Type | Constraints | Default |
| --------- | ---- | ----------- | ------- |
| `limit`   | int  | 1–50        | 10      |

Returns `{items: [{id, title, text, due_at, interval_days, repetitions, is_new}], due_count}` — `is_new` means never graded.

### grade\_review

Record recall quality and reschedule the card. Requires scope `notes:write`.

| Parameter | Type   | Constraints                                                 |
| --------- | ------ | ----------------------------------------------------------- |
| `note_id` | string | note UUID                                                   |
| `grade`   | int    | 1=Again (forgot — back in \~10 min), 2=Hard, 3=Good, 4=Easy |

Returns `{id, grade, due_at, interval_days, ease_factor, repetitions}`. A note not enrolled in review errors with `Note is not in review`.