---
title: MCP tool reference
description: Every tool the RAAD MCP server exposes, generated from source.
order: 3
---

# MCP tool reference

Generated from `MCPToolCatalog.swift` by `raad mcp tools --markdown` — do not edit by hand. CI regenerates this file and fails if it differs from what's committed.

## `search_clips`

Full-text search over the user's Raad clipboard history, by exact words — use this when you know the wording (an error string, a URL, an identifier). Sensitive, deleted, and sealed-pinboard clips are never returned.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `app_bundle_id` | string | no | Restrict to clips copied from this app's bundle id. |
| `clip_type` | string | no | Restrict to one clip type: text, richText, image, url, color, file. |
| `favorites_only` | boolean | no | Restrict to clips the user has favorited. |
| `limit` | integer | no | Maximum results (default 20, max 200). |
| `query` | string | yes | Search text. |
| `since` | string | no | ISO8601 timestamp; only clips copied after this. |
| `until` | string | no | ISO8601 timestamp; only clips copied at or before this. |

**Returns** an object with: `clips`

## `recent_clips`

The user's most recent clipboard history, newest first.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `favorites_only` | boolean | no | Restrict to clips the user has favorited. |
| `limit` | integer | no | Maximum results (default 20, max 200). |
| `since` | string | no | ISO8601 timestamp; only clips copied after this. |

**Returns** an object with: `clips`

## `get_clip`

A single clip by id.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |

**Returns** an object with: `clip`

## `list_pinboards`

The user's pinboards (folders). Sealed pinboards are never included, not even by name.

**Returns** an object with: `pinboards`

## `get_session_context`

Recently clustered work sessions from the user's Raad clipboard history — what they were working on and when, grouped by app/site and time gap. Answered from capture metadata already on disk (Phase 21), not a search, so it never needs Raad running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Maximum sessions to return, newest first (default 5, max 200). |

**Returns** an object with: `sessions`

## `semantic_search`

Search the user's clipboard history by meaning, when you don't know the exact wording. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Maximum results (default 20, max 200). |
| `pinboard_id` | string | no | Restrict results to one pinboard. |
| `query` | string | yes | What to search for, in natural language. |

**Returns** an object with: `clips`

## `get_pinboard`

The clips filed in one of the user's pinboards (folders). A sealed pinboard's contents are never returned, and asking for a sealed pinboard's id fails the same way as asking for one that doesn't exist. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Maximum results (default 20, max 200). |
| `pinboard_id` | string | yes |  |

**Returns** an object with: `clips`

## `save_clip`

Save text as a new clip in the user's Raad history. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `pinboard_id` | string | no | Optionally file it into a pinboard. |
| `text` | string | yes | The text to save (up to 100 KB). |

**Returns** an object with: `id`

## `create_pinboard`

Create a new pinboard (folder) in the user's Raad history. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `color` | string | no | A #RRGGBB hex color. |
| `icon` | string | no | An SF Symbol name. |
| `name` | string | yes |  |

**Returns** an object with: `id`

## `add_to_pinboard`

File an existing clip into a pinboard. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `clip_id` | string | yes |  |
| `pinboard_id` | string | yes |  |

## `set_clipboard`

Put an existing clip onto the system clipboard, so the user's next ⌘V pastes it. Raad shows the user a notification every time this runs. Requires Raad to be running.

**Arguments**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `clip_id` | string | yes |  |