> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in Tools

> Complete reference for all agent built-in tools

## Overview

When an agent uses `agent` reasoning mode, it has access to BoostGPT built-in tools for knowledge, memory, files, planning, communication, automation, workspace delivery, and platform operations.

> [!NOTE]
>
> File tools (`write`, `read`, `edit`, `grep`, `glob`, `delete`, `ls`) and the `bash` tool require the agent's **Workspace** setting to be enabled. Planning tools (`create_plan`, `update_plan`, `read_plan`, `accept_plan`) require plan mode (`chat_mode: 'plan'`), which also requires workspace.

### Approval Levels

| Level | Behavior | Description |
| - | - | - |
| **Auto** | Executes without user interaction | Read-only and low-risk operations |
| **Input** | Waits for visitor interaction | User-facing tools such as booking cards |
| **Conditional** | Configurable per agent | Write operations that modify workspace files |
| **Always** | Always requires user approval | Actions that need explicit user consent |

## Summary

| Tool | Category | Approval | Description |
| - | - | - | - |
| `search_memory` | Knowledge | Auto | Vector search through knowledge base |
| `screenshot` | Knowledge | Auto | Capture web page screenshot |
| `web_fetch` | Knowledge | Auto | Extract page content as markdown |
| `write` | Files | Conditional | Create or overwrite a file |
| `read` | Files | Auto | Read file content |
| `edit` | Files | Conditional | Exact string replacement |
| `grep` | Files | Auto | Search file contents — regex, inverted match, multiline, context |
| `glob` | Files | Auto | Find files by path pattern |
| `delete` | Files | Conditional | Soft-delete a file |
| `create_plan` | Planning | Auto | Register a plan |
| `update_plan` | Planning | Auto | Modify plan or advance todos |
| `read_plan` | Planning | Auto | Read current plan state |
| `accept_plan` | Planning | Always | Submit plan for user approval |
| `ask_user` | Communication | Always | Ask structured questions |
| `notify_user` | Communication | Auto | Send proactive notification |
| `schedule_task` | Automation | Auto | Create recurring task |
| `bash` | Execution | Conditional | Run shell commands in the sandbox |
| `think` | Utility | Auto | Internal reasoning |

***

## Knowledge & Search

### search\_memory

Search through the bot's knowledge base and uploaded documents using vector similarity.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | Yes | The search query to find relevant information |
| `top` | integer | No | Number of results to return (default: 10) |

### screenshot

Capture a visual screenshot of a web page. Returns an image URL for vision-capable AI analysis.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | URL of the web page to screenshot |
| `width` | integer | No | Viewport width in pixels (default: 1920) |
| `height` | integer | No | Viewport height in pixels (default: 1080) |
| `fullPage` | boolean | No | Capture full scrollable page (default: false) |
| `device` | string | No | Device preset (e.g., `iphone-15`, `ipad-pro-12.9`, `pixel-7`, `desktop-1080p`) |
| `theme` | string | No | Color scheme: `light` or `dark` (default: light) |
| `quality` | integer | No | JPEG quality 1-100 (default: 80) |
| `format` | string | No | Output format: `jpg` or `png` (default: jpg) |
| `blockCookieBanners` | boolean | No | Block cookie consent banners (default: false) |
| `blockAds` | boolean | No | Block advertisements (default: false) |
| `blockChatWidgets` | boolean | No | Block chat widgets (default: false) |
| `blockPopups` | boolean | No | Block popups and modals (default: false) |
| `hideSelectors` | array | No | CSS selectors to hide before capture |
| `clickSelectors` | array | No | CSS selectors to click before capture |
| `timeout` | integer | No | Page load timeout in ms (default: 30000) |

### web\_fetch

Extract the content of a web page as structured markdown with metadata (title, description, word count). Unlike `screenshot` which captures a visual image, `web_fetch` returns the page's text content.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | URL of the web page to extract content from |

***

## File Operations

File tools operate on the agent's sandbox [Workspace](/docs/sdk/core/workspaces.md). See the [Workspaces documentation](/docs/sdk/core/workspaces.md) for full details including REST API endpoints.

| Tool | Approval | Description |
| - | - | - |
| `write` | Conditional | Create or overwrite a file — params: `file_path`, `content`, `language` |
| `read` | Auto | Read file content — params: `file_path`, `start_line`, `end_line` |
| `edit` | Conditional | Exact string replacement — params: `file_path`, `old_string`, `new_string` |
| `grep` | Auto | Search file contents — params: `pattern`, `file_path`, `include`, `exclude`, `files_without_match`, `invert_match`, `multiline`, `case_sensitive`, `context` |
| `glob` | Auto | Find files by path pattern — params: `pattern` |
| `delete` | Conditional | Soft-delete a file — params: `file_path` |

***

## Planning

Planning tools enable agents to create structured plans, track progress through todos, and get user approval before executing.

### create\_plan

Register a plan after writing the plan document to a workspace file. First use `write` to create the plan file at `/.plans/{title}.md`, then call this tool.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | A concise title for the plan |
| `plan_file_path` | string | Yes | Path to the plan `.md` file (e.g., `/.plans/add-dark-mode.md`) |
| `todos` | array | No | Todo descriptions (in plan mode, typically added after acceptance) |

### update\_plan

Update the active plan. Can modify title, replace todos, change status, or advance to the next todo.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | No | New title for the plan |
| `todos` | array | No | Replacement todos array (replaces all todos, resets status to pending) |
| `status` | string | No | Set status: `cancelled` or `completed` |
| `advance_todo` | boolean | No | Mark current todo complete and advance to next |
| `todo_result` | string | No | Summary of what was accomplished (used with `advance_todo`) |

> [!WARNING]
>
> Setting `todos` replaces the entire todo list and resets all statuses to pending. Use `advance_todo: true` to mark individual todos as completed.

### read\_plan

Read the current active plan. Returns title, status, todos with completion state, and current todo index. No parameters.

### accept\_plan

Submit the current draft plan for user approval. No parameters. Always requires user approval before proceeding.

> [!NOTE]
>
> After a plan is accepted, the agent typically adds execution todos via `update_plan` and then works through them step by step.

***

## Communication

### ask\_user

Ask the user 1-4 structured questions with selectable options. Always requires approval — the user sees the questions and picks answers.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `questions` | array | Yes | Array of 1-4 question objects |

Each question object:

| Field | Type | Required | Description |
| - | - | - | - |
| `question` | string | Yes | The question to ask |
| `options` | array | Yes | 2-4 answer options (strings) |

### notify\_user

Send a proactive notification to the user when something needs their attention.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | Short notification title |
| `message` | string | Yes | Detailed notification message |
| `priority` | string | No | Priority: `low`, `normal`, or `urgent` (default: normal) |
| `action_url` | string | No | URL the user can click to take action |

## Automation

### schedule\_task

Create a recurring scheduled task that runs automatically.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Short descriptive name for the task |
| `prompt` | string | Yes | The instruction to execute on each run |
| `schedule_type` | string | No | Frequency: `interval`, `daily`, `weekly`, or `once` (default: interval) |
| `schedule_config` | object | No | Schedule details (varies by `schedule_type`) |
| `description` | string | No | Longer description of the task |
| `timezone` | string | No | Timezone for schedule (default: UTC) |
| `max_executions` | integer | No | Maximum number of runs (null = unlimited) |

***

## Code Execution

### bash

Run code or shell commands in an isolated sandbox environment. The sandbox has access to all workspace files under `/workspace` and has network access. Requires both **Workspace** and **Code Sandbox** to be enabled on the agent.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `command` | string | Yes | The shell command to run (e.g., `python main.py`, `npm install express`, `node server.js`, `curl https://example.com`) |

> [!NOTE]
>
> The sandbox auto-detects the runtime (Python or Node.js) based on workspace file extensions. Files modified by the command are automatically synced back to the workspace. Each execution has a 30-second timeout.

***

## Utility

### think

Reason aloud and plan next steps without producing any user-visible output. Useful for the agent to organize its thoughts before acting.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `thought` | string | Yes | Reasoning, analysis, or planning thoughts |

***

## Next Steps

> [card] [Workspaces](/docs/sdk/core/workspaces.md)
>
> File tools details and REST API

> [card] [Chat API](/docs/sdk/core/chat-api.md)
>
> Send messages and receive AI responses

> [card] [Tasks API](/docs/sdk/core/tasks.md)
>
> Autonomous agent schedules


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.