Redflag/system/tools_reference.md

description, limit

description	limit
Built-in tools reference - available without skill invocation	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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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