<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.2-built-in-tools-reference -->

# Built-in Tools Reference

- docs/claude/configuration.md
- src/agent/context_monitor.rs
- src/channels/acp.rs
- src/channels/acp_http.rs
- src/tools/cron.rs
- src/tools/docx_read.rs
- src/tools/filesystem.rs
- src/tools/gsheets.rs
- src/tools/http_request.rs
- src/tools/memory.rs
- src/tools/message.rs
- src/tools/pdf_read.rs
- src/tools/r8r.rs
- src/tools/reminder.rs
- src/tools/shell.rs
- src/tools/spawn.rs
- src/tools/transcribe.rs
- src/tools/whatsapp.rs
- tests/acp_acpx.rs

This page provides a comprehensive reference for all 32+ built-in tools available in ZeptoClaw. Each tool implements the `Tool` async trait and is registered in the `ToolRegistry` for LLM function calling.

For architectural details about the tool system, see [Tool System Architecture](/qhkm/zeptoclaw/3.4-tool-system-architecture). For implementation details of specific tool categories, see [Web Tools](/qhkm/zeptoclaw/8.3-web-tools), [Filesystem and Shell Tools](/qhkm/zeptoclaw/8.4-filesystem-and-shell-tools), [Custom Tools](/qhkm/zeptoclaw/8.5-custom-tools), [Binary Plugin System](/qhkm/zeptoclaw/8.6-binary-plugin-system), [MCP Integration](/qhkm/zeptoclaw/8.7-mcp-integration), and [Tool Composition](/qhkm/zeptoclaw/8.8-tool-composition).

**Sources:** [src/tools/mod.rs1-138](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L138) [src/tools/message.rs47-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/message.rs#L47-L66)

## Tool Categories and Registration

ZeptoClaw categorizes tools to manage permissions and security boundaries. The `ToolRegistry` acts as the central hub for dispatching execution.

### Code-to-System Mapping: Tool Registry

```

```

**Sources:** [src/tools/mod.rs1-138](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L138) [src/tools/shell.rs15-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L15-L17) [src/tools/message.rs64-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/message.rs#L64-L66)

### Global Tool Map

```

```

**Sources:** [src/tools/mod.rs1-138](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L138) [src/tools/shell.rs111-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L111-L125) [src/tools/memory.rs69-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/memory.rs#L69-L71) [src/tools/cron.rs41-43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/cron.rs#L41-L43) [src/tools/reminder.rs4-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/reminder.rs#L4-L5)

## Core Filesystem Tools

### read_file / write_file / list_dir / edit_file

These tools provide the primary interface for an agent to interact with the workspace. They utilize `validate_path_in_workspace` to ensure no path traversal occurs [src/tools/filesystem.rs39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L39-L39) Filesystem tools require a configured workspace for safety [src/tools/filesystem.rs34-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L34-L37)

**Implementation Details:**

- read_file : Reads entire content and applies truncate_tool_output src/tools/filesystem.rs 189-196
- write_file : Uses write_file_secure_blocking which ensures the directory chain is secure and checks for hard links to prevent aliasing content outside the workspace src/tools/filesystem.rs 47-83

**Sources:** [src/tools/filesystem.rs1-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L1-L203)

### grep

Search for a pattern in files using the system `grep -rn` for performance. Supports regex patterns and glob filters.

**Parameters:**

- pattern (string, required): Regex or literal pattern to search for.
- path (string, optional): Directory or file to search (default: workspace root).
- glob (string, optional): Glob pattern filter (e.g. *.rs ).

## Shell and Command Execution Tools

### shell

Executes shell commands with configurable runtime isolation.

**Parameters:**

- command (string, required): The shell command to execute src/tools/shell.rs 132-135
- timeout (integer, optional): Timeout in seconds (default: 60) src/tools/shell.rs 136-139

**Security:**

- Validates commands against ShellSecurityConfig src/tools/shell.rs 152
- Supports ContainerRuntime backends (Landlock, Firejail, Docker, etc.) for isolation src/tools/shell.rs 168-172

**Sources:** [src/tools/shell.rs111-178](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L111-L178)

## Memory Tools

### memory_search

Searches workspace markdown memory files using a ranked scoring algorithm.

**Scoring Logic:**
The `BuiltinSearcher` calculates scores based on term coverage and density within memory snippets [src/tools/memory.rs143-153](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/memory.rs#L143-L153)

**Sources:** [src/tools/memory.rs55-157](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/memory.rs#L55-L157)

### memory_get

Retrieves a specific memory file from the workspace memory paths, supporting line-range windows [src/tools/memory.rs185-192](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/memory.rs#L185-L192)

**Sources:** [src/tools/memory.rs160-231](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/memory.rs#L160-L231)

## Agent Coordination and Messaging

### message

The primary tool for proactive outbound communication. It bridges the `AgentLoop` to the `MessageBus` [src/tools/message.rs14-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/message.rs#L14-L16)

**Supported Actions:**

- send : Standard text message (all channels) src/tools/message.rs 102
- react : Emoji reactions (Discord) src/tools/message.rs 102
- rich_message : Block Kit messages (Slack) src/tools/message.rs 102
- inline_keyboard : Interactive buttons (Telegram) src/tools/message.rs 102

**Implementation Flow:**

```

```

**Sources:** [src/tools/message.rs47-184](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/message.rs#L47-L184) [src/tools/message.rs20-28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/message.rs#L20-L28)

### spawn

Allows an agent to delegate a task to a background sub-agent [src/tools/spawn.rs34-36](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/spawn.rs#L34-L36)

**Recursion Protection:**
To prevent "fork bombs," `SpawnTool` rejects requests if the current channel is already `subagent` [src/tools/spawn.rs65-69](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/spawn.rs#L65-L69)

**Sources:** [src/tools/spawn.rs29-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/spawn.rs#L29-L133)

### cron

Manages scheduled tasks and reminders via the `CronService` [src/tools/cron.rs16-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/cron.rs#L16-L18)

**Actions:**

- add : Schedules a new job via every_seconds , cron_expr , or at (ISO datetime) src/tools/cron.rs 98
- list : Shows all active jobs src/tools/cron.rs 99
- remove : Deletes a job by job_id src/tools/cron.rs 100

**Constraints:**

- Maximum of 50 active jobs src/tools/cron.rs 111
- Minimum interval of 60 seconds src/tools/cron.rs 163

**Sources:** [src/tools/cron.rs28-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/cron.rs#L28-L105)

### reminder

Persistent scheduled reminders with a dedicated `ReminderStore` [src/tools/reminder.rs3-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/reminder.rs#L3-L5) Supports status tracking (Pending, Done, Snoozed) and categories [src/tools/reminder.rs80-107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/reminder.rs#L80-L107)

**Sources:** [src/tools/reminder.rs1-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/reminder.rs#L1-L120)

## Document Processing Tools

### docx_read

Extracts plain text from Microsoft Word files within the workspace [src/tools/docx_read.rs190-192](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/docx_read.rs#L190-L192)

**Technical Details:**

- Engine : Uses zip and quick-xml src/tools/docx_read.rs 101-122
- Extraction : Collects text from <w:t> elements and handles paragraph breaks ( </w:p> ), tabs ( <w:tab/> ), and line breaks ( <w:br/> ) src/tools/docx_read.rs 95-100
- Limits : 50 MB file size limit src/tools/docx_read.rs 18

**Sources:** [src/tools/docx_read.rs30-181](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/docx_read.rs#L30-L181)

### pdf_read

Extracts plain text from PDF documents using the `lopdf` engine.

**Limits:**

- Max file size: 50 MB.
- Max output: 200,000 characters (hard limit).

### transcribe

Converts audio files to text using the Groq Whisper API.

**Technical Details:**

- Supported Formats: mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg.
- Max File Size: 25 MB.

## External Integration Tools

### r8r

Symbiotic integration with the R8r workflow engine for deterministic automation [src/tools/r8r.rs8-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L8-L11)

**Key Actions:**

- run : Executes a workflow (default action) src/tools/r8r.rs 193
- list : Shows available workflows src/tools/r8r.rs 191
- status : Checks execution status by execution_id src/tools/r8r.rs 191
- emit : Publishes an event to the engine src/tools/r8r.rs 191
- create : Creates a new workflow from a YAML definition src/tools/r8r.rs 191

**Sources:** [src/tools/r8r.rs151-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L151-L215)

### http_request

Make HTTP requests to external APIs.

**Security Features:**

- SSRF Protection: Private/local IPs are blocked.
- DNS Pinning: Resolves hostname and pins the IP to prevent DNS rebinding attacks.
- Header Stripping: Dangerous headers like Authorization or Cookie are stripped from inputs.

## Output Management

Tools that produce large volumes of data utilize the `truncate_tool_output` utility to prevent context window exhaustion [src/tools/filesystem.rs192-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L192-L196)

**Default Limits:**

- Max Lines: 2,000.
- Max Bytes: 50,000.

**Sources:** [src/tools/filesystem.rs23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L23-L23) [src/tools/shell.rs15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L15-L15)
