Document all built-in tools available without skill invocation

system/tools_reference.md

@@ -0,0 +1,222 @@
+---
+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