# Scratchpad MCP tools

Scratchpad tools expose project-scoped [Markdown notes](../scratchpads/using-scratchpads.md) to MCP clients. Turn on **Enabled in MCP** in **Settings > Features > Scratchpads** to expose them. Turning off the Scratchpads feature itself also removes these tools and the scratchpad resources; see [Turned-off features](./overview.md#turned-off-features).

## Tools

- `scratchpad_list` — List scratchpads in a project, optionally filtered by keyword query or tags and paginated with offset/limit.
- `scratchpad_tags_list` — List distinct scratchpad tags in a project.
- `scratchpad_read` — Read a scratchpad, including revision and metadata. Supports automatic headings fallback for large omitted-mode reads, full content, headings-only outlines, and section reads.
- `scratchpad_find` — Search one scratchpad for a literal substring. Optional `scope` limits matching to `headings` or `content` lines (default `all`), `case_sensitive` enables exact-case matching, `limit` bounds the matches returned, and `context_lines` includes surrounding lines with each match.
- `scratchpad_tail` — Return the last N lines of a scratchpad with line-count metadata. `lines` defaults to 10; use 0 for metadata only.
- `scratchpad_write` — Create a scratchpad or replace its content and tags at an expected revision. A leading H1 in the content is treated as the scratchpad title.
- `scratchpad_rename` — Rename a scratchpad at an expected revision without rewriting its content.
- `scratchpad_add_tags` — Add multiple tags to a scratchpad in one revision bump without returning its full content.
- `scratchpad_remove_tags` — Remove multiple tags from a scratchpad in one revision bump without returning its full content.
- `scratchpad_append` — Append to the end of a scratchpad. Optionally pass an expected revision guard.
- `scratchpad_append_section` — Append content under an existing non-title Markdown heading. Heading matching is whitespace-normalized and case-insensitive; an expected revision guard is optional. Use `scratchpad_rename` to rename the title or `scratchpad_write` for full-document changes that include a title.
- `scratchpad_edit` — Replace one non-title Markdown section or a zero-based line range at an expected revision. Pass `target` as `{"type": "section", "section_heading": "..."}` or `{"type": "line_range", "offset": 0, "limit": 1}`. Section edits replace the whole section when the replacement starts with a Markdown heading; otherwise they preserve the matched heading and replace that section's body. Use `scratchpad_rename` to rename the title or `scratchpad_write` for full-document changes that include a title.
- `scratchpad_clear` — Clear a scratchpad at an expected revision.
- `scratchpad_delete` — Delete a scratchpad at an expected revision.
- `scratchpad_archive` — Hide a scratchpad from lists without deleting it.
- `scratchpad_transfer` — Move a scratchpad to another project at an expected revision.
- `scratchpad_save_to_file` — Write a scratchpad to a filesystem path as UTF-8 text, including its title as a leading H1.
- `scratchpad_load_from_file` — Load UTF-8 text from a file into a scratchpad. A leading H1 in the file is treated as the scratchpad title.

## Notes

Scratchpad revisions protect against overwriting newer edits. Use read-before-write patterns when an agent is updating shared working notes: call `scratchpad_read` to get the current revision, then use `scratchpad_edit`, `scratchpad_append_section`, or `scratchpad_append` for targeted changes. Reserve `scratchpad_write` for full-document creates and overwrites.

For file import/export tools, project-relative paths are resolved inside the project and rejected if they escape through `..` or symlinks. Absolute paths are honored directly when Solo can read or write them.

When scratchpad tools are enabled, scratchpads are also readable as MCP resources; see [MCP prompts and resources](./prompts-and-resources.md).

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/mcp-tools/scratchpads