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

# Tools

> Built-in tools available to agents: shell, file I/O, web, memory, and soul

## Overview

Tools are functions the LLM can call during the agent loop. MeepaGateway registers a set of built-in tools for every agent, filtered by the agent's allow/deny configuration. MCP servers add additional tools from external processes.

All tools are exposed to the LLM with a name, description, and JSON Schema for their parameters.

***

## Built-in Tools

### `shell`

Execute a shell command in the agent's workspace directory.

**Parameters:**

| Parameter | Type    | Required | Description                                              |
| --------- | ------- | -------- | -------------------------------------------------------- |
| `command` | string  | yes      | Shell command to execute                                 |
| `timeout` | integer | no       | Timeout in seconds (default: agent's configured timeout) |

**Returns:** stdout, stderr, and exit code.

When `isolation.enabled = true`, shell commands run inside the Docker container. When `isolation.enabled = false` and `container_mode.runtime = "none"`, commands run on the host subject to `allowed_commands` filtering.

***

### `read_file`

Read a file from disk.

**Parameters:**

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `path`    | string | yes      | Absolute or relative path to the file |

Access is validated against `allowed_dirs`. Reads outside allowed directories are rejected.

***

### `write_file`

Write content to a file.

**Parameters:**

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `path`    | string | yes      | Path to write |
| `content` | string | yes      | File contents |

Access is validated against `allowed_dirs` before writing.

***

### `web_fetch`

Fetch a URL and return its content.

**Parameters:**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `url`     | string | yes      | URL to fetch |

Returns the response body as text. HTML is returned as-is; the LLM handles parsing.

***

### `web_search`

Search the web using the Brave Search API.

**Parameters:**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `query`   | string | yes      | Search query |

Requires `web_search_enabled = true` on the agent and a valid Brave API key configured via `BRAVE_API_KEY`.

***

### `memory_store`

Store a fact in the long-term SQLite fact store.

**Parameters:**

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `content` | string | yes      | Fact text to store                                  |
| `source`  | string | yes      | Origin of the fact (e.g. `"user"`, `"observation"`) |

***

### `memory_search`

Search stored facts using full-text search (FTS5).

**Parameters:**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `query`   | string | yes      | Search terms |

Returns a ranked list of matching facts with IDs, content, source, and timestamps.

***

### `memory_delete`

Delete a stored fact by ID.

**Parameters:**

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `id`      | string | yes      | UUID of the fact to delete |

***

### `memory_note`

Append a note to `MEMORY.md` or `USER.md`.

**Parameters:**

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `content` | string | yes      | Markdown content to append   |
| `file`    | string | yes      | `"MEMORY.md"` or `"USER.md"` |

***

### `memory_read`

Read the full contents of `MEMORY.md` or `USER.md`.

**Parameters:**

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `file`    | string | yes      | `"MEMORY.md"` or `"USER.md"` |

***

### `soul_read`

Read the agent's current `SOUL.md` persona file.

**Parameters:** none

***

### `soul_edit`

Replace the entire `SOUL.md` content.

**Parameters:**

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `content` | string | yes      | New SOUL.md content |

***

## Tool Access Control

Tools are filtered per-agent using allow and deny lists. The registry applies them at startup:

* If `allow` is non-empty, only listed tools are available (allowlist wins)
* If `deny` is non-empty, listed tools are excluded
* If both are empty, all registered tools are available

```yaml theme={null}
agents:
  - id: coder
    tools:
      allow: [shell, read_file, write_file, memory_store, memory_search]
      # deny: [web_search]  # alternative: block specific tools
```

***

## File Access Control

`read_file` and `write_file` validate paths against `file_access`, enforced regardless of container mode settings:

```yaml theme={null}
agents:
  - id: coder
    file_access:
      unrestricted: false
      allow_read: []
      allow_read_write: [/tmp/meepa-workspace]
      deny: []
```

An empty `allow_read_write` list means unrestricted access (default). Add directories to restrict file tool access to specific paths.

***

## Custom Tools via MCP

Agents can access tools from external MCP (Model Context Protocol) servers. MCP tools appear alongside built-in tools — the LLM cannot distinguish them. See [MCP](/gateway/mcp) for configuration.

***

## Configuration Reference

```yaml theme={null}
agents:
  - id: meepa
    default: true
    file_access:
      unrestricted: false  # File tool path restrictions. true = unrestricted.
      allow_read: []
      allow_read_write: []
      deny: []
    container_mode:
      enabled: false         # Enable Docker isolation for shell execution
      runtime: docker        # "docker" | "none"
      timeout: 120s
      image: alpine:3.20
      memory_limit: 256m
      network_disabled: true
      allowed_commands: []   # "none" runtime only — empty = all allowed
    tools:
      # allow: [shell, read_file]   # allowlist
      # deny: [write_file]          # or denylist
```