---
title: "Built-in tools reference"
description: "Comprehensive reference for all built-in tools available in Meerkat, including parameters, types, and defaults."
icon: "wrench"
---

## Overview

| Tool | Category | Default | Gate | Description |
|------|----------|---------|------|-------------|
| `task_create` | Task | Yes | -- | Create a new task |
| `task_get` | Task | Yes | -- | Get a task by ID |
| `task_list` | Task | Yes | -- | List tasks with optional filters |
| `task_update` | Task | Yes | -- | Update an existing task |
| `shell` | Shell | No | -- | Execute a shell command |
| `shell_jobs` | Shell | No | -- | List background shell jobs |
| `shell_job_status` | Shell | No | -- | Check background job status |
| `shell_job_cancel` | Shell | No | -- | Cancel a background job |
| `memory_search` | Memory | N/A | `memory-store-session` | Search semantic memory |
| `datetime` | Utility | Yes | -- | Get current date/time |
| `apply_patch` | Utility | Yes | -- | Apply structured file patches inside the project root |
| `view_image` | Utility | Yes | `image_tool_results` | Read an image file and return base64 content |
| `generate_image` | Image generation | Runtime-backed | image provider profile | Generate or edit assistant images and commit blob-backed image blocks |
| `blob_save_file` | Blob files | Runtime-backed | blob store | Save decoded blob bytes to a project-root-contained file |
| `blob_load_file` | Blob files | Runtime-backed | blob store | Load a project-root-contained file into the realm blob store |
| `blob_inspect` | Blob files | Runtime-backed | blob store | Inspect blob media type and decoded byte size without returning bytes |
| `send_message` | Comms | Yes | `comms` | Send a collaboration message to a peer |
| `send_request` | Comms | Yes | `comms` | Send a structured request to a peer |
| `send_response` | Comms | Yes | `comms` | Send a response to a peer request |
| `peers` | Comms | Yes | `comms` | List discoverable peers (trusted + inproc) |
| `browse_skills` | Skills | Yes | `skills` | Browse skill collections and search skills |
| `load_skill` | Skills | Yes | `skills` | Load a skill's full instructions into the conversation |
| `skill_list_resources` | Skills | Yes | `skills` | List skill-owned resources |
| `skill_read_resource` | Skills | Yes | `skills` | Read a specific skill-owned resource |
| `skill_invoke_function` | Skills | Yes | `skills` | Invoke a skill-defined function |
| `tool_catalog_search` | Control plane | Yes | `builtins` | Search deferred tool-catalog entries |
| `tool_catalog_load` | Control plane | Yes | `builtins` | Load deferred tool-catalog entries into visibility |
| `meerkat_schedule_create` | Schedule | Yes | `schedule` | Create a new schedule |
| `meerkat_schedule_get` | Schedule | Yes | `schedule` | Read one schedule |
| `meerkat_schedule_list` | Schedule | Yes | `schedule` | List schedules |
| `meerkat_schedule_update` | Schedule | Yes | `schedule` | Update trigger, target, or policies |
| `meerkat_schedule_pause` | Schedule | Yes | `schedule` | Pause a schedule |
| `meerkat_schedule_resume` | Schedule | Yes | `schedule` | Resume a paused schedule |
| `meerkat_schedule_delete` | Schedule | Yes | `schedule` | Delete a schedule |
| `meerkat_schedule_occurrences` | Schedule | Yes | `schedule` | List occurrences for a schedule |
| `workgraph_create` | WorkGraph | No | `work_graph` | Create a work item |
| `workgraph_get` | WorkGraph | No | `work_graph` | Read one item |
| `workgraph_list` | WorkGraph | No | `work_graph` | List items |
| `workgraph_ready` | WorkGraph | No | `work_graph` | List ready items |
| `workgraph_snapshot` | WorkGraph | No | `work_graph` | Read an observability snapshot |
| `workgraph_events` | WorkGraph | No | `work_graph` | Read event history |
| `workgraph_claim` | WorkGraph | No | `work_graph` | Claim an item |
| `workgraph_release` | WorkGraph | No | `work_graph` | Release a claim |
| `workgraph_update` | WorkGraph | No | `work_graph` | Update item fields |
| `workgraph_block` | WorkGraph | No | `work_graph` | Mark an item blocked |
| `workgraph_close` | WorkGraph | No | `work_graph` | Close an item terminally |
| `workgraph_link` | WorkGraph | No | `work_graph` | Add an edge |
| `workgraph_add_evidence` | WorkGraph | No | `work_graph` | Add evidence |

## Enabling and disabling tools

<Accordion title="Factory-level flags">
`AgentFactory` controls which tool categories are available via builder methods:

| Flag | Builder Method | Default | Controls |
|------|---------------|---------|----------|
| `enable_builtins` | `.builtins(bool)` | `false` | Task tools, utility tools (`datetime`, `apply_patch`, `view_image`), runtime-backed `generate_image`, and blob file tools when a blob store is wired |
| `enable_shell` | `.shell(bool)` | `false` | All shell tools (`shell`, `shell_jobs`, `shell_job_status`, `shell_job_cancel`) |
| `enable_memory` | `.memory(bool)` | `false` | `memory_search` (requires `memory-store-session` feature) |
| `enable_schedule` | `.schedule(bool)` | `false` | Scheduler tools (`meerkat_schedule_*`) |
| `enable_workgraph` | `.workgraph(bool)` | `false` | WorkGraph tools (`workgraph_*`) |
| `enable_comms` | `.comms(bool)` | `false` | All comms tools (requires `comms` feature) |
| `enable_mob` | `.mob(bool)` | `false` | Mob orchestration tools (`mob_*`, `meerkat_*`) |

`AgentFactory` is the only place tool categories are composed. The public `meerkat::AgentBuilder` delegates to the factory path with explicit client/tool/store overrides. The lower-level `meerkat_core::AgentBuilder` is not re-exported by the facade and is not a public standalone embedding API. See [AgentBuilder vs AgentFactory](/rust/advanced#agentbuilder-vs-agentfactory).

**Source:** `meerkat/src/factory.rs` -- `AgentFactory` struct and builder methods.
</Accordion>

<Accordion title="Per-build overrides">
Each `AgentBuildConfig` can override factory-level flags for a single agent build:

| Override Field | Type | Effect |
|---------------|------|--------|
| `override_builtins` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |
| `override_shell` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |
| `override_memory` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |
| `override_schedule` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |
| `override_workgraph` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |
| `override_mob` | `ToolCategoryOverride` | Explicit `enable`, `disable`, or `inherit` |

All default to `inherit` (use the factory-level setting).

**Source:** `meerkat/src/factory.rs` -- `AgentBuildConfig` struct.
</Accordion>

<Accordion title="ToolPolicyLayer">
Individual tools can be enabled or disabled via `ToolPolicyLayer` in `BuiltinToolConfig`. When shell is enabled, a `ToolPolicyLayer` is applied that activates the four shell tools (which have `default_enabled: false`).
</Accordion>

<Accordion title="Capability registrations">
Capabilities are registered via the `inventory` crate in `meerkat-tools/src/lib.rs`:

- **Builtins** (`CapabilityId::Builtins`): `task_list`, `task_create`, `task_get`, `task_update`, `datetime`, `apply_patch`, `view_image`, runtime-backed `generate_image`, and runtime-backed `blob_save_file`/`blob_load_file`/`blob_inspect` when a blob store is available. Controlled by `config.tools.builtins_enabled`.
- **Shell** (`CapabilityId::Shell`): `shell`, `shell_jobs`, `shell_job_status`, `shell_job_cancel`. Controlled by `config.tools.shell_enabled`.
- **Schedule** (`CapabilityId::Schedule`): `meerkat_schedule_*`. Controlled by `config.tools.schedule_enabled`.
- **WorkGraph** (`CapabilityId::WorkGraph`): `workgraph_*`. Controlled by `config.tools.workgraph_enabled`.
</Accordion>

## Runtime tool scoping

Beyond static factory flags and per-build overrides, tool visibility can be changed at runtime during a live session. See [Tool scoping](/concepts/tools#tool-scoping) for the conceptual overview.

<Accordion title="ToolScope lifecycle">
`ToolScope` (in `meerkat-core`) manages runtime tool visibility. It holds the base tool set from the dispatcher, an active external filter, and an optional per-turn overlay.

**Staging:** External callers stage filter updates via `ToolScopeHandle::stage_external_filter(filter)`. The staged filter is NOT applied immediately — the current turn is unaffected.

**Boundary apply:** At the start of each `CallingLlm` loop iteration, `tool_scope.apply_staged(dispatcher_tools)` atomically promotes the staged filter to active, prunes stale tool names, and returns the visible tool set. A `ToolConfigChanged` event is emitted and a typed `tool_config` system notice is recorded in the conversation.

**Filter types:**
- `ToolFilter::All` — no restriction (default)
- `ToolFilter::Allow(set)` — only listed tools are visible
- `ToolFilter::Deny(set)` — listed tools are hidden

**Composition:** Most-restrictive wins. Multiple allow-lists intersect, multiple deny-lists union, deny beats allow.

**Persistence:** The active external filter is stored in session metadata under `tool_scope_external_filter` and restored on session resume.

**Source:** `meerkat-core/src/tool_scope.rs`
</Accordion>

<Accordion title="Live MCP server mutation">
MCP servers can be added or removed from a running session. Operations are staged on the `McpRouter` and applied at the next turn boundary.

| Surface | Method | Status |
|---------|--------|--------|
| JSON-RPC | `mcp/add`, `mcp/remove`, `mcp/reload` | Fully wired (staged) |
| REST | `POST /sessions/{id}/mcp/add\|remove\|reload` | Fully wired |
| CLI | `rkat mcp add/remove/list/get` | Config surface; start or resume a session to load config |
| MCP server | `meerkat_mcp_add`, `meerkat_mcp_remove`, `meerkat_mcp_reload` | Fully wired |

Servers being removed transition through `Active → Removing (draining) → Removed` to allow in-flight tool calls to complete before finalization.

**Source:** `meerkat-mcp/src/router.rs`, `meerkat-rpc/src/handlers/mcp.rs`
</Accordion>

<Accordion title="Per-turn flow tool overlay">
Mob flow steps can restrict tools for a single turn via `TurnToolOverlay`:

```rust
TurnToolOverlay {
    allowed_tools: Option<Vec<String>>,  // allow-list for this turn
    blocked_tools: Option<Vec<String>>,  // deny-list for this turn
}
```

Set on `StartTurnRequest.flow_tool_overlay` by the flow engine. Ephemeral — cleared after the turn completes. Composes with the external filter using most-restrictive semantics.

**Source:** `meerkat-core/src/service/mod.rs`, `meerkat-mob/src/runtime/flow.rs`
</Accordion>

## Schedule tools

Schedule tools are the agent-facing scheduler surface. They are distinct from the host APIs (`schedule/*` over RPC and `/schedules/*` over REST).

<Accordion title="Schedule tool inventory">
| Tool | Purpose |
|------|---------|
| `meerkat_schedule_create` | Create a durable schedule with trigger, target, and policies |
| `meerkat_schedule_get` | Read one schedule by `schedule_id` |
| `meerkat_schedule_list` | List schedules in the active realm |
| `meerkat_schedule_update` | Update trigger, target, policies, or labels |
| `meerkat_schedule_pause` | Pause a schedule |
| `meerkat_schedule_resume` | Resume a paused schedule |
| `meerkat_schedule_delete` | Delete a schedule |
| `meerkat_schedule_occurrences` | List occurrences for a schedule |

These tools are provided by `ScheduleToolDispatcher` in `meerkat-schedule` and are gated by the scheduler capability.
</Accordion>

## WorkGraph tools

WorkGraph tools are the agent-facing write path for durable work. Host RPC,
REST, and CLI expose read-only observability only.

<Accordion title="WorkGraph tool inventory">
| Tool | Purpose |
|------|---------|
| `workgraph_create` | Create a durable work item |
| `workgraph_get` | Read one item |
| `workgraph_list` | List items with filters |
| `workgraph_ready` | List machine-derived ready items |
| `workgraph_snapshot` | Read items, edges, ready ids, timestamp, and event high-water mark |
| `workgraph_events` | Read event history |
| `workgraph_claim` | Claim an item with expected revision and typed owner |
| `workgraph_release` | Release an active claim |
| `workgraph_update` | Update mutable fields |
| `workgraph_block` | Mark an item blocked |
| `workgraph_close` | Close as `completed`, `cancelled`, or `failed` |
| `workgraph_link` | Add an edge |
| `workgraph_add_evidence` | Add an evidence reference |

For operating guidance, load the `workgraph-workflow` companion skill when it
is available. For the data model and host observability surfaces, see
[WorkGraph reference](/reference/workgraph-reference).
</Accordion>

## Task tools

Task tools provide structured work tracking. They are enabled by default when builtins are on. Tasks are persisted via `TaskStore` (either `FileTaskStore` on disk or `MemoryTaskStore` in-memory).

<Accordion title="Task data model">
A `Task` object returned by task tools has these fields:

| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Unique task identifier |
| `subject` | `String` | Short subject/title |
| `description` | `String` | Detailed description |
| `status` | `String` | `"pending"`, `"in_progress"`, or `"completed"` |
| `priority` | `String` | `"low"`, `"medium"`, or `"high"` |
| `labels` | `String[]` | Labels/tags for categorization |
| `blocks` | `String[]` | IDs of tasks that this task blocks |
| `blocked_by` | `String[]` | IDs of tasks that block this task |
| `created_at` | `String` | ISO 8601 creation timestamp |
| `updated_at` | `String` | ISO 8601 last-updated timestamp |
| `created_by_session` | `String?` | Session ID that created this task |
| `updated_by_session` | `String?` | Session ID that last updated this task |
| `owner` | `String?` | Owner/assignee (agent name or user identifier) |
| `metadata` | `Object` | Arbitrary key-value metadata |

**Source:** `meerkat-tools/src/builtin/types.rs` -- `Task` struct.
</Accordion>

<Accordion title="task_create">
Create a new task in the project task list.

**Default enabled:** Yes

<ParamField body="subject" type="String" required>
  Short subject/title of the task.
</ParamField>

<ParamField body="description" type="String" required>
  Detailed description of what needs to be done.
</ParamField>

<ParamField body="priority" type="String" default="medium">
  `"low"`, `"medium"`, or `"high"`.
</ParamField>

<ParamField body="labels" type="String[]" default="[]">
  Labels/tags for categorization.
</ParamField>

<ParamField body="blocks" type="String[]" default="[]">
  Task IDs that this task blocks.
</ParamField>

<ParamField body="blocked_by" type="String[]" default="[]">
  Task IDs that block this task.
</ParamField>

<ParamField body="owner" type="String" default="null">
  Owner/assignee.
</ParamField>

<ParamField body="metadata" type="Object" default="{}">
  Arbitrary key-value metadata.
</ParamField>

**Returns:** The created `Task` object (see task data model above).

**Source:** `meerkat-tools/src/builtin/tasks/task_create.rs`
</Accordion>

<Accordion title="task_get">
Get a task by its ID.

**Default enabled:** Yes

<ParamField body="id" type="String" required>
  The task ID to retrieve.
</ParamField>

**Returns:** The `Task` object matching the given ID.

**Error:** `ExecutionFailed` if the task ID is not found.

**Source:** `meerkat-tools/src/builtin/tasks/task_get.rs`
</Accordion>

<Accordion title="task_list">
List tasks in the project, optionally filtered by status or labels.

**Default enabled:** Yes

<ParamField body="status" type="String" default="null (all)">
  Filter by status: `"pending"`, `"in_progress"`, or `"completed"`.
</ParamField>

<ParamField body="labels" type="String[]" default="null (all)">
  Filter by labels (tasks matching any label).
</ParamField>

**Returns:** Array of `Task` objects matching the filters.

**Source:** `meerkat-tools/src/builtin/tasks/task_list.rs`
</Accordion>

<Accordion title="task_update">
Update an existing task. Only provided fields are modified; omitted fields remain unchanged.

**Default enabled:** Yes

<ParamField body="id" type="String" required>
  The task ID to update.
</ParamField>

<ParamField body="subject" type="String" default="unchanged">
  New subject/title.
</ParamField>

<ParamField body="description" type="String" default="unchanged">
  New description.
</ParamField>

<ParamField body="status" type="String" default="unchanged">
  New status: `"pending"`, `"in_progress"`, or `"completed"`.
</ParamField>

<ParamField body="priority" type="String" default="unchanged">
  New priority: `"low"`, `"medium"`, or `"high"`.
</ParamField>

<ParamField body="labels" type="String[]" default="unchanged">
  Replace all labels.
</ParamField>

<ParamField body="owner" type="String" default="unchanged">
  New owner/assignee.
</ParamField>

<ParamField body="metadata" type="Object" default="unchanged">
  Merge metadata (set key to `null` to remove).
</ParamField>

<ParamField body="add_blocks" type="String[]" default="[]">
  Task IDs to add to the `blocks` list.
</ParamField>

<ParamField body="remove_blocks" type="String[]" default="[]">
  Task IDs to remove from the `blocks` list.
</ParamField>

<ParamField body="add_blocked_by" type="String[]" default="[]">
  Task IDs to add to the `blocked_by` list.
</ParamField>

<ParamField body="remove_blocked_by" type="String[]" default="[]">
  Task IDs to remove from the `blocked_by` list.
</ParamField>

**Returns:** The updated `Task` object.

**Error:** `ExecutionFailed` if the task ID is not found.

**Source:** `meerkat-tools/src/builtin/tasks/task_update.rs`
</Accordion>

## Shell tools

Shell tools execute commands and manage background jobs. They are all `default_enabled: false` and require the factory-level `enable_shell` flag (or a `ToolPolicyLayer` override) to be active.

<Accordion title="Shell configuration">
Shell behavior is controlled by `ShellConfig`:

| Config Field | Type | Default | Description |
|-------------|------|---------|-------------|
| `enabled` | `bool` | `false` | Master switch for shell tools |
| `default_timeout_secs` | `u64` | `30` | Default command timeout |
| `restrict_to_project` | `bool` | `true` | Restrict working dirs to project root |
| `shell` | `String` | `"nu"` | Shell binary name (Nushell by default; falls back to bash/zsh/sh) |
| `shell_path` | `PathBuf?` | `None` | Explicit shell binary path |
| `project_root` | `PathBuf` | CWD | Project root for path restriction |
| `max_completed_jobs` | `usize` | `100` | Maximum completed jobs retained |
| `completed_job_ttl_secs` | `u64` | `300` | TTL for completed job records (seconds) |
| `max_concurrent_processes` | `usize` | `10` | Maximum concurrent background processes |
| `security_mode` | `SecurityMode` | `Unrestricted` | Command security policy |
| `security_patterns` | `Vec<String>` | `[]` | Glob patterns for allow/deny lists |

**Source:** `meerkat-tools/src/builtin/shell/config.rs`
</Accordion>

<Accordion title="Shell security modes">
The `SecurityEngine` validates commands before execution using POSIX-compliant word splitting (`shlex`) and glob pattern matching (`globset`).

| Mode | Behavior |
|------|----------|
| `Unrestricted` | All commands allowed (default) |
| `AllowList` | Only commands matching `security_patterns` globs are allowed |
| `DenyList` | Commands matching `security_patterns` globs are rejected |

Patterns are matched against the canonicalized command invocation. The engine parses the full command string into individual words, then validates the executable (first word) and the full command string against the pattern set.

**Source:** `meerkat-tools/src/builtin/shell/security.rs`
</Accordion>

<Accordion title="shell">
Execute a shell command. Uses POSIX-style parsing for policy checks; runs via Nushell or fallback shell.

**Default enabled:** No (requires shell to be enabled)

<ParamField body="command" type="String" required>
  The command to execute (POSIX-style parsing for policy checks).
</ParamField>

<ParamField body="working_dir" type="String" default="Project root">
  Working directory (relative to project root).
</ParamField>

<ParamField body="timeout_secs" type="u64" default="Config default (30)">
  Timeout in seconds.
</ParamField>

<ParamField body="background" type="bool" default="false">
  If `true`, run in background and return job ID immediately.
</ParamField>

<CodeGroup>
```json Returns (foreground)
{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "timed_out": false,
  "duration_secs": 1.23
}
```

```json Returns (background)
{
  "job_id": "job_<uuid-v7>",
  "status": "running",
  "message": "Background job started"
}
```
</CodeGroup>

<Note>
Output is truncated to the last 100,000 characters if it exceeds that limit. Fields `stdout_lossy` and `stderr_lossy` indicate whether output was lossy-decoded from non-UTF-8 bytes.
</Note>

**Source:** `meerkat-tools/src/builtin/shell/tool.rs`
</Accordion>

<Accordion title="shell_jobs">
List all background shell jobs.

**Default enabled:** No (requires shell to be enabled)

**Parameters:** None (empty object).

```json
[
  {
    "id": "job_<uuid-v7>",
    "command": "echo hello",
    "status": "running",
    "started_at_unix": 1700000000
  }
]
```

The `status` field is one of: `"running"`, `"completed"`, `"failed"`, `"timed_out"`, `"cancelled"`.

**Source:** `meerkat-tools/src/builtin/shell/jobs_list_tool.rs`
</Accordion>

<Accordion title="shell_job_status">
Check status of a background shell job. Returns full job details including output when complete.

**Default enabled:** No (requires shell to be enabled)

<ParamField body="job_id" type="String" required>
  The job ID to check.
</ParamField>

```json
{
  "id": "job_<uuid-v7>",
  "command": "echo test",
  "working_dir": "/path/to/project",
  "timeout_secs": 30,
  "started_at_unix": 1700000000,
  "status": "completed"
}
```

**Error:** `ExecutionFailed` if the job ID is not found.

**Source:** `meerkat-tools/src/builtin/shell/job_status_tool.rs`
</Accordion>

<Accordion title="shell_job_cancel">
Cancel a running background shell job.

**Default enabled:** No (requires shell to be enabled)

<ParamField body="job_id" type="String" required>
  The job ID to cancel.
</ParamField>

```json
{
  "job_id": "job_<uuid-v7>",
  "status": "cancelled"
}
```

**Error:** `ExecutionFailed` if the job ID is not found.

**Source:** `meerkat-tools/src/builtin/shell/job_cancel_tool.rs`
</Accordion>

<Accordion title="Shell types">
**JobId format:** `"job_"` followed by a UUID v7 string.

**JobStatus variants:** `Running`, `Completed`, `Failed`, `TimedOut`, `Cancelled` (serialized as lowercase snake_case strings).

**Source:** `meerkat-tools/src/builtin/shell/types.rs`
</Accordion>

## Memory tool

The memory search tool lives in the `meerkat-memory` crate and is composed into the tool dispatcher as a separate `MemorySearchDispatcher` (implementing `AgentToolDispatcher`). It is NOT part of `CompositeDispatcher` -- it is wired via `ToolGateway` when the `memory-store-session` feature is enabled and `enable_memory` is `true`.

<Accordion title="memory_search">
Search semantic memory for past conversation content. Memory contains text from earlier conversation turns that were compacted away to save context space.

<ParamField body="query" type="String" required>
  Natural language search query describing what you want to recall.
</ParamField>

<ParamField body="limit" type="usize" default="5">
  Maximum number of results to return (max: 20).
</ParamField>

The `limit` is capped at 20 regardless of the requested value.

```json
[
  {
    "content": "The project codename is AURORA-7",
    "score": 0.87,
    "session_id": "<uuid>",
    "turn": 3
  }
]
```

Returns an empty array if no matches are found.

**Source:** `meerkat-memory/src/tool.rs`
</Accordion>

## Utility tools

Utility tools are general-purpose helpers enabled by default when builtins are on.

<Accordion title="datetime">
Get the current date and time. Returns ISO 8601 formatted datetime and Unix timestamp.

**Default enabled:** Yes

**Parameters:** None (empty object).

```json
{
  "iso8601": "2025-01-15T14:30:00+01:00",
  "date": "2025-01-15",
  "time": "14:30:00",
  "timezone": "+01:00",
  "unix_timestamp": 1736949000,
  "year": 2025,
  "month": 1,
  "day": 15,
  "weekday": "Wednesday"
}
```

**Source:** `meerkat-tools/src/builtin/utility/datetime.rs`
</Accordion>

<Accordion title="view_image">
Read an image file from the project directory and return its contents as a base64-encoded `ContentBlock::Image`. This enables vision-capable models to analyze images from disk during tool use.

**Default enabled:** Yes (when builtins are on and the model supports image tool results)

<ParamField body="path" type="String" required>
  Path to the image file, relative to the project root.
</ParamField>

**Supported formats:** PNG, JPEG, GIF, WebP, SVG.

**Size limit:** 5 MB. Files exceeding this limit return an error.

**Capability gating:** `view_image` is currently hidden via `ToolScope` when the active model does not support image content in tool results (`ModelProfile.image_tool_results == false`).

**Returns:** A content-block result containing a single `ContentBlock::Image` with the base64-encoded image data and detected media type.

**Source:** `meerkat-tools/src/builtin/utility/view_image.rs`
</Accordion>

<Accordion title="blob_save_file">
Save decoded bytes from the session blob store to a file inside the project root. This is the model-facing equivalent of materializing a blob with `rkat blob get`, but it remains sandboxed to the active project.

**Default enabled:** Yes when builtins are on and the runtime-backed session has a blob store.

<ParamField body="blob_id" type="String" required>
  Blob ID to save.
</ParamField>

<ParamField body="path" type="String" required>
  Destination path, relative to the project root or absolute within the project root.
</ParamField>

<ParamField body="overwrite" type="Boolean" default="false">
  Whether to replace an existing file.
</ParamField>

**Returns:** JSON metadata: `blob_id`, `media_type`, `path`, and `bytes_written`. Raw bytes are never returned in the tool result.

**Source:** `meerkat-tools/src/builtin/utility/blob_file.rs`
</Accordion>

<Accordion title="blob_load_file">
Read a file inside the project root and store its bytes in the realm blob store.

**Default enabled:** Yes when builtins are on and the runtime-backed session has a blob store.

<ParamField body="path" type="String" required>
  Source path, relative to the project root or absolute within the project root.
</ParamField>

<ParamField body="media_type" type="String" default="inferred from extension">
  Optional media type. When omitted, Meerkat infers common image, text, JSON, CSV, SVG, and PDF media types from the file extension.
</ParamField>

**Size limit:** 25 MB.

**Returns:** JSON metadata: `blob_id`, `media_type`, `path`, and `bytes_read`. Raw bytes are never returned in the tool result.

**Source:** `meerkat-tools/src/builtin/utility/blob_file.rs`
</Accordion>

<Accordion title="blob_inspect">
Inspect a blob without returning its raw payload.

**Default enabled:** Yes when builtins are on and the runtime-backed session has a blob store.

<ParamField body="blob_id" type="String" required>
  Blob ID to inspect.
</ParamField>

**Returns:** JSON metadata: `blob_id`, `media_type`, and decoded `size_bytes`.

**Source:** `meerkat-tools/src/builtin/utility/blob_file.rs`
</Accordion>

<Accordion title="generate_image">
Generate or edit an assistant-owned image through the session image-generation substrate. Generated bytes are committed to the realm blob store and returned as durable `AssistantImageRef` values.

**Default enabled:** Yes when builtins are on and the runtime-backed session has image-generation machine, executor, planner, and blob-store wiring.

<ParamField body="request" type="Object" required>
  Image generation request. The simple shape supports `intent`, `prompt`, `instruction`, `source_images`, `reference_images`, `size`, `quality`, `format`, `count`/`n`, `target`, `provider`, `model`, and `provider_params`.
</ParamField>

**Common request:**

```json
{
  "request": {
    "intent": "generate",
    "prompt": "a cozy tabby cat by a sunlit window",
    "size": "1024x1024",
    "quality": "auto",
    "format": "png",
    "count": 1,
    "provider": "openai"
  }
}
```

**Targets:** `auto` uses the current provider's image profile when available. Use `provider: "openai"` or `provider: "gemini"` to force a provider default. Use `provider` plus `model` to force a provider-owned image model.

**Supported universal options:** `size` accepts `auto`, `1024x1024`, `1024x1536`, `1536x1024`, or `WIDTHxHEIGHT`; `quality` accepts `auto`, `low`, `medium`, `high`; `format` accepts `auto`, `png`, `jpeg`, `jpg`, `webp`; `count` is currently limited to `1`.

**Provider params:** Use top-level `size`, `quality`, `format`, and `intent` for normal requests; these are Meerkat fields, not raw provider params. For the current `gpt-image-2` default, OpenAI `provider_params` should normally be limited to `background`, `output_compression`, `moderation`, hosted-tool-only `action`, hosted-tool-only `reasoning_effort`, and hosted-tool-only `web_search`; `background` is `auto` or `opaque` only, `output_compression` applies when `format` is `jpeg`/`webp`, `moderation` is `auto` or `low`, `action` is usually omitted in favor of top-level `intent`, and `input_fidelity` is not accepted by Meerkat 0.6.19. Gemini accepts `aspect_ratio` and `image_size`.

**Returns:** `ImageGenerationToolResult` JSON containing `operation_id`, `terminal`, `images`, `provider_text`, `revised_prompt`, `native_metadata`, and `warnings`. Each generated image includes `blob_ref.blob_id`, which can be saved from inside the session with `blob_save_file` or fetched externally with `rkat blob get <blob_id> --output image.png`.

**Source:** `meerkat-tools/src/builtin/image_generation.rs`

See [Image generation](/guides/image-generation) for provider behavior, examples, and troubleshooting.
</Accordion>

## Comms tools

Comms tools enable inter-agent communication. They require the `comms` Cargo feature (`dep:meerkat-comms`) and the factory-level `enable_comms` flag. Unlike other tool categories, comms tools are provided as a separate `CommsToolSurface` dispatcher (implementing `AgentToolDispatcher`) and composed via `ToolGateway`, NOT bundled into `CompositeDispatcher`.

Comms tools are only shown to the agent when at least one peer is discoverable
(controlled by `CommsToolSurface::peer_availability()`). The check passes when
`TrustedPeers` has entries.

Tool definitions (name, description, input schema) are dynamically loaded from `meerkat_comms::tools_list()`.

<Accordion title="send_message">
Send a collaboration message to a trusted peer.

**Default enabled:** Yes (when comms is active)

<ParamField body="to" type="String" required>
  Peer name to send to.
</ParamField>

<ParamField body="body" type="String" required>
  Message content.
</ParamField>

<ParamField body="handling_mode" type="String" required>
  Use `"queue"` for ordinary delivery or `"steer"` for immediate steer processing on runtime-backed sessions.
</ParamField>

```json
{ "status": "sent" }
```

**Source:** `meerkat-comms/src/mcp/tools.rs`
</Accordion>

<Accordion title="send_request">
Send a structured request to a trusted peer. Use when you want explicit `intent + params` and a correlated response via `send_response`.

**Default enabled:** Yes (when comms is active)

<ParamField body="to" type="String" required>
  Peer name to send to.
</ParamField>

<ParamField body="intent" type="String" required>
  Request intent/action identifier (e.g., `"review"`, `"delegate"`).
</ParamField>

<ParamField body="params" type="any" default="null">
  Request parameters.
</ParamField>

<ParamField body="handling_mode" type="String" required>
  Use `"queue"` for ordinary delivery or `"steer"` for immediate steer processing on runtime-backed sessions.
</ParamField>

<Note>
Use `send_message` for normal agent collaboration. Use `send_request` only when you want an explicit structured ask and later `send_response` correlated by `in_reply_to`.
</Note>

```json
{ "status": "sent" }
```

**Source:** `meerkat-comms/src/mcp/tools.rs`
</Accordion>

<Accordion title="send_response">
Send a response to a previously received request from a trusted peer.

**Default enabled:** Yes (when comms is active)

<ParamField body="to" type="String" required>
  Peer name to send to.
</ParamField>

<ParamField body="in_reply_to" type="String (UUID)" required>
  ID of the request being responded to.
</ParamField>

<ParamField body="status" type="String" required>
  Response status: `"accepted"`, `"completed"`, or `"failed"`.
</ParamField>

<ParamField body="result" type="any" default="null">
  Response result data.
</ParamField>

```json
{ "status": "sent" }
```

**Source:** `meerkat-comms/src/mcp/tools.rs`
</Accordion>

<Accordion title="peers">
List all discoverable peers and their connection status.

Returns configured trusted peers (`TrustedPeers`), excluding the current agent ("self") by public key.

**Default enabled:** Yes (when comms is active)

**Parameters:** None (empty object).

```json
{
  "peers": [
    {
      "name": "agent-beta",
      "peer_id": "<derived-peer-id>",
      "address": "tcp://127.0.0.1:4200"
    }
  ]
}
```

**Source:** `meerkat-comms/src/mcp/tools.rs` -- `PeersInput`
</Accordion>

## Cargo feature gates

Tool availability depends on compile-time features in the `meerkat-tools` crate:

| Feature | Default | Dependencies | Tools unlocked |
|---------|---------|-------------|----------------|
| `comms` | Yes | `dep:meerkat-comms` | `send_message`, `send_request`, `send_response`, `peers` |
| `mcp` | Yes | `dep:meerkat-mcp` | External MCP tool routing (not builtin tools) |

The `memory_search` tool is gated by the `memory-store-session` feature on the `meerkat` facade crate (not `meerkat-tools`), since `MemorySearchDispatcher` lives in `meerkat-memory`.

**Source:** `meerkat-tools/Cargo.toml`
