Redflag/system/tools_reference.md

---
description: Built-in tools reference - available without skill invocation
limit: 2000
---
# Built-In Tools Reference

## Core Tools (Always Available)

These tools are built into Letta Code and available without invoking any skill.

### 1. Bash
**Purpose:** Execute shell commands
**Use for:** Git operations, file system commands, npm/pip installs, docker, curl, etc.
**Key params:**
- `command` (required) - The command to execute
- `description` - What the command does
- `timeout` - Optional, in ms (default 120000)
- `run_in_background` - Run without blocking

**Examples:**
```typescript
Bash({ command: "git status", description: "Check git status" })
Bash({ command: "npm install", description: "Install dependencies", timeout: 300000 })
```

---

### 2. Glob
**Purpose:** File pattern matching
**Use for:** Finding files by pattern, exploring directory structures
**Key params:**
- `pattern` (required) - Glob pattern like "**/*.ts"
- `path` - Directory to search (defaults to current)

**Examples:**
```typescript
Glob({ pattern: "**/*.ts", path: "/home/ani/Projects" })
Glob({ pattern: "**/README.md" })
```

---

### 3. Grep
**Purpose:** Content search with ripgrep
**Use for:** Finding text in files, searching codebases
**Key params:**
- `pattern` (required) - Regex pattern to search
- `path` - Directory or file to search
- `glob` - Filter by file pattern
- `output_mode` - "content" (show matches) or "files_with_matches" (default)
- `-C` - Context lines to show

**Examples:**
```typescript
Grep({ pattern: "class.*Agent", path: "/home/ani/Projects", glob: "*.ts" })
Grep({ pattern: "TODO|FIXME", output_mode: "content" })
```

---

### 4. Read
**Purpose:** Read file contents
**Use for:** Reading source files, configs, documentation
**Key params:**
- `file_path` (required) - Absolute path to file
- `offset` - Start reading from line number
- `limit` - Max lines to read

**Examples:**
```typescript
Read({ file_path: "/home/ani/Projects/lettabot/package.json" })
Read({ file_path: "/home/ani/file.ts", offset: 100, limit: 50 })
```

---

### 5. Edit
**Purpose:** Edit files with exact string replacement
**Use for:** Modifying code, updating configs
**Key params:**
- `file_path` (required)
- `old_string` (required) - Text to replace (must be unique)
- `new_string` (required) - Replacement text
- `replace_all` - Replace all occurrences

**Examples:**
```typescript
Edit({ 
  file_path: "/home/ani/file.ts",
  old_string: "const x = 1;",
  new_string: "const x = 2;"
})
```

---

### 6. Write
**Purpose:** Write new files
**Use for:** Creating new files (only when needed)
**Key params:**
- `file_path` (required) - Must be absolute path
- `content` (required) - File contents

**Examples:**
```typescript
Write({
  file_path: "/home/ani/new-file.md",
  content: "# Hello\n\nContent here"
})
```

---

## Task Tool (Subagents)

### 7. Task
**Purpose:** Spawn specialized subagents
**Use for:** Delegating work, parallel exploration, complex tasks
**Key params:**
- `description` - Short task name
- `prompt` - Detailed instructions
- `subagent_type` - "explore", "coder", "verifier", etc.
- `model` - Which model to use (kimi-k2.5, nemotron-3-super, etc.)
- `run_in_background` - Continue without waiting

**Examples:**
```typescript
Task({
  description: "Explore Matrix formatting",
  prompt: "Find all files related to...",
  subagent_type: "explore",
  model: "kimi-k2.5"
})
```

---

## Memory Tools

### 8. memory
**Purpose:** CRUD operations on memory files
**Use for:** Creating, reading, updating memory blocks
**Commands:** `create`, `str_replace`, `delete`, `rename`, `update_description`
**Key params:**
- `command` (required)
- `path` - Memory file path (relative to memory dir)
- `description` - For create/update_description
- `file_text` - Content for create
- `old_string` / `new_string` - For str_replace
- `reason` - Commit message

**Examples:**
```typescript
memory({ 
  command: "create",
  path: "system/new-doc.md",
  description: "Documentation",
  file_text: "Content",
  reason: "Add documentation"
})
```

---

## LettaBot-Specific Tools

### 9. manage_todo
**Purpose:** CRUD operations on todos
**Commands:** `add`, `list`, `complete`, `reopen`, `remove`, `snooze`

**Examples:**
```typescript
manage_todo({ action: "add", text: "Do thing" })
manage_todo({ action: "complete", id: "todo-abc123" })
```

---

### 10. conversation_search
**Purpose:** Search message history
**Use for:** Finding past conversations

**Examples:**
```typescript
conversation_search({ query: "Matrix bridge" })
```

---

### 11. archival_memory_search
**Purpose:** Search long-term memory
**Use for:** Recalling stored facts

---

## When to Use What

| Task | Tool |
|------|------|
| Run shell command | `Bash` |
| Find files | `Glob` |
| Search code | `Grep` |
| Read file | `Read` |
| Modify file | `Edit` |
| Create file | `Write` |
| Delegate work | `Task` |
| Update memory | `memory` |
| Manage todos | `manage_todo` |

---

## Important Notes

1. **Always use absolute paths** - `/home/ani/...` not relative paths
2. **Read before editing** - Must read file before using Edit
3. **Prefer editing existing files** - Over creating new ones
4. **Specify model for subagents** - Use kimi-k2.5, nemotron-3-super, etc.
5. **Bash commands need description** - Always include what they do

---

Last updated: 2026-03-21