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 sandbox.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

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 allowed_dirs, enforced regardless of sandbox settings:

agent_defaults:
  allowed_dirs: [/tmp/meepa-workspace]

agents:
  # Per-agent override
  - id: coder
    allowed_dirs: [/home/user/projects, /tmp]

An empty allowed_dirs 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 for configuration.

---

Configuration Reference

agent_defaults:
  # Directories file tools can access. Empty = unrestricted.
  allowed_dirs: []
  sandbox:
    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

agents:
  - id: meepa
    default: true
    tools:
      # allow: [shell, read_file]   # allowlist
      # deny: [write_file]          # or denylist