System Tools

​

read — Read File

​

Parameters

​

Returns

​

Example

{
  path: "src/index.ts",
  offset: 10,
  limit: 50
}

​

Notes

• Maximum 500 lines per read by default
• Use offset and limit for large files
• Returns truncation notice if file has more lines

​

write — Write File

​

Parameters

​

Returns

​

Example

{
  path: "src/utils/helper.ts",
  content: "export function add(a: number, b: number) { return a + b; }"
}

​

Notes

• Parent directories are created automatically
• Overwrites existing files without confirmation
• Use for creating new files or full rewrites

​

edit — Edit File

​

Parameters

​

Returns

​

Errors

• not_found: old_text not found in file
• not_unique: old_text appears multiple times (ambiguous)

​

Example

{
  path: "src/config.ts",
  old_text: "port: 3000",
  new_text: "port: 8080"
}

​

Notes

• old_text must appear exactly once in the file
• Use read first to verify exact text to replace
• For multiple replacements, call edit multiple times

​

bash — Execute Shell

​

Parameters

​

Returns

​

Example

{
  command: "npm test",
  timeout: 300000  // 5 minutes
}

​

Notes

• Default timeout: 2 minutes
• Runs in the working directory (cwd)
• Use for: tests, git operations, package installs, builds
• Output limited to 30KB (truncated if larger)
• Command killed with SIGTERM on timeout, then SIGKILL after 3s

​

glob — Find Files

​

Parameters

​

Returns

​

Example

{
  pattern: "**/*.test.ts",
  path: "src"
}

​

Notes

• Maximum 200 results
• Uses find command under the hood
• Paths returned relative to working directory

​

grep — Search Code

​

Parameters

​

Returns

​

Example

{
  pattern: "function.*async",
  include: "*.ts",
  path: "src"
}

​

Notes

• Maximum 100 results
• Uses grep -rn -E under the hood
• Regex is extended regex (ERE) format
• Returns “No matches found” if pattern not found

​

ls — List Directory

​

Parameters

​

Returns

​

Example

{
  path: "src/components"
}

​

Notes

• Directories marked with trailing /
• Returns all entries (no filtering or pagination)
• Use glob for pattern-based file finding

​

Tool Filtering

{
  "agents": [
    {
      "name": "readonly-agent",
      "allowedTools": ["read", "glob", "grep", "ls"]
    }
  ]
}

​

Security Considerations

​

bash Tool

• Runs commands with full shell access
• No sandboxing or command filtering
• Use with trusted agents only
• Consider restricting via allowedTools for untrusted workloads

​

File Operations

• write and edit can modify any file in the working directory
• No write protection or backup
• Agents can delete files via bash tool
• Consider version control (git) for protection

​

Best Practices

​

Reading Large Files

// Bad: Read entire 10k line file
{ path: "large.txt" }

// Good: Read in chunks
{ path: "large.txt", offset: 1, limit: 500 }
{ path: "large.txt", offset: 501, limit: 500 }

​

Editing Files

// Step 1: Read to find exact text
{ path: "config.ts", offset: 1, limit: 50 }

// Step 2: Edit with exact match
{
  path: "config.ts",
  old_text: "const PORT = 3000;",
  new_text: "const PORT = 8080;"
}

​

Searching Code

// Bad: Broad search
{ pattern: "function" }  // 1000s of results

// Good: Specific search
{ pattern: "async function handle.*Request", include: "*.ts" }

​

Extended Tool Categories

{
  "name": "outreach-agent",
  "allowedTools": ["read", "write", "edit", "bash", "glob", "grep", "ls", "browser_*", "email_*", "vault_*", "image_*", "video_*", "audio_*", "search_*"]
}

​

Implementation

interface AgentTool<TSchema> {
  name: string;
  label: string;
  description: string;
  parameters: TSchema;
  execute(toolCallId: string, params: ParamsType, signal?: AbortSignal): Promise<AgentToolResult>;
}