Built-in Tools

Overview

Every agent spawned in armament has access to a standard toolkit. These tools enable file manipulation, shell access, web fetching, and user interaction without any additional configuration.

File Tools

Tool	Description
`read_file`	Read file contents with optional line offset and limit
`write_file`	Write content to a file (creates or overwrites)
`edit_file`	Apply a targeted edit (old_string → new_string replacement)
`append_file`	Append content to an existing file
`list_files`	List files with recursive traversal and glob filtering
`grep`	Search files with regex patterns

read_file

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

Returns file content with line numbers. Supports offset/limit for large files.

edit_file

{
  "path": "src/auth.ts",
  "old_string": "const timeout = 30;",
  "new_string": "const timeout = 60;"
}

Finds and replaces an exact string match. Fails if the string isn’t found or isn’t unique.

Shell Tools

Tool	Description
`bash`	Execute shell commands with timeout and output cap

bash

{ "command": "npm test", "timeout": 30000 }

Runs a shell command and returns stdout/stderr. Default timeout is 120 seconds. Output is capped to prevent context overflow.

Web Tools

Tool	Description
`web_fetch`	Fetch a URL and return its content

web_fetch

{ "url": "https://api.example.com/status", "headers": { "Authorization": "Bearer ..." } }

30-second timeout, 100KB response cap. Supports custom headers.

Interaction Tools

Tool	Description
`ask_user`	Prompt the user for input or approval

ask_user

{
  "question": "Deploy to production?",
  "type": "confirm",
  "options": ["Yes", "No", "Dry-run first"]
}

Supports types: confirm, radio, multi-select, freeform, picklist.

Task Management Tools

Tool	Description
`todo_write`	Create/update a todo list
`task_create`	Create a trackable task
`task_get`	Get task status
`task_list`	List all tasks
`task_update`	Update task progress

Scheduling Tools

Tool	Description
`schedule_create`	Schedule a future action
`schedule_delete`	Remove a scheduled action
`schedule_list`	List scheduled actions
`schedule_wakeup`	Trigger a scheduled wakeup

Plan Mode Tools

Tool	Description
`enter_plan_mode`	Enter planning mode (no actions executed)
`exit_plan_mode`	Exit planning mode and optionally execute plan

MCP Tools

In addition to built-in tools, agents can access tools from connected MCP servers. These are registered dynamically when an MCP server connects:

/mcp add github
# Agent now has: create_pull_request, search_code, list_issues, ...

Tool Permissions

Tool execution goes through the permission system. By default, read-only tools (read_file, grep, list_files) are auto-approved. Write tools (bash, write_file, edit_file) require user approval unless configured otherwise.

permissions:
  auto_approve:
    - read_file
    - grep
    - list_files
    - web_fetch
  require_approval:
    - bash
    - write_file
    - edit_file