Overview When an agent uses agent reasoning mode, it has access to 22 built-in tools. These tools are automatically available — no configuration required.
File tools (write, read, edit, grep, delete, ls) and the command 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 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_memoryKnowledge Auto Vector search through knowledge base screenshotKnowledge Auto Capture web page screenshot web_fetchKnowledge Auto Extract page content as markdown rememberMemory Auto Save to user long-term memory recallMemory Auto Search user memories list_memoriesMemory Auto List all user memories forgetMemory Auto Remove a user memory writeFiles Conditional Create or overwrite a file readFiles Auto Read file content editFiles Conditional Exact string replacement grepFiles Auto Regex search across files deleteFiles Conditional Soft-delete a file create_planPlanning Auto Register a plan update_planPlanning Auto Modify plan or advance todos read_planPlanning Auto Read current plan state accept_planPlanning Always Submit plan for user approval ask_userCommunication Always Ask structured questions notify_userCommunication Auto Send proactive notification message_agentCommunication Auto Message another agent schedule_taskAutomation Auto Create recurring task commandExecution Conditional Run code/commands in sandbox thinkUtility Auto Internal reasoning
Knowledge & Search search_memory Search through the bot’s knowledge base and uploaded documents using vector similarity.
Parameter Type Required Description querystring Yes The search query to find relevant information topinteger 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 urlstring Yes URL of the web page to screenshot widthinteger No Viewport width in pixels (default: 1920) heightinteger No Viewport height in pixels (default: 1080) fullPageboolean No Capture full scrollable page (default: false) devicestring No Device preset (e.g., iphone-15, ipad-pro-12.9, pixel-7, desktop-1080p) themestring No Color scheme: light or dark (default: light) qualityinteger No JPEG quality 1-100 (default: 80) formatstring No Output format: jpg or png (default: jpg) blockCookieBannersboolean No Block cookie consent banners (default: false) blockAdsboolean No Block advertisements (default: false) blockChatWidgetsboolean No Block chat widgets (default: false) blockPopupsboolean No Block popups and modals (default: false) hideSelectorsarray No CSS selectors to hide before capture clickSelectorsarray No CSS selectors to click before capture timeoutinteger 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 urlstring Yes URL of the web page to extract content from
User Memory User Memory must be enabled on the agent. Enable it in Settings → Features & Options → Access to Memory , or set memory: true via the Bot Management API . remember Save or update information in long-term memory for the current user. Automatically detects whether to create a new memory or update an existing one.
Parameter Type Required Description contentstring Yes The information to remember typestring No Memory type: semantic, episodic, or procedural (default: semantic) tagsarray No Tags for categorization
recall Search through saved memories for the current user.
Parameter Type Required Description querystring Yes What to search for in memories typestring No Filter by type: semantic, episodic, procedural, or all (default: all) topinteger No Number of results to return (default: 5)
list_memories List all saved memories for the current user, ordered by most recent.
Parameter Type Required Description typestring No Filter by type: semantic, episodic, procedural, or all (default: all) limitinteger No Max memories to return (default: 10)
forget Remove a specific memory about the current user.
Parameter Type Required Description querystring Yes Description of the memory to forget
File Operations File tools operate on the agent’s sandbox Workspace . See the Workspaces documentation for full details including REST API endpoints.
Tool Approval Description writeConditional Create or overwrite a file — params: file_path, content, language readAuto Read file content — params: file_path, start_line, end_line editConditional Exact string replacement — params: file_path, old_string, new_string grepAuto Regex search across files — params: pattern, file_path, include deleteConditional 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 titlestring Yes A concise title for the plan plan_file_pathstring Yes Path to the plan .md file (e.g., /.plans/add-dark-mode.md) todosarray 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 titlestring No New title for the plan todosarray No Replacement todos array (replaces all todos, resets status to pending) statusstring No Set status: cancelled or completed advance_todoboolean No Mark current todo complete and advance to next todo_resultstring No Summary of what was accomplished (used with advance_todo)
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.
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 questionsarray Yes Array of 1-4 question objects
Each question object:
Field Type Required Description questionstring Yes The question to ask optionsarray Yes 2-4 answer options (strings)
notify_user Send a proactive notification to the user when something needs their attention.
Parameter Type Required Description titlestring Yes Short notification title messagestring Yes Detailed notification message prioritystring No Priority: low, normal, or urgent (default: normal) action_urlstring No URL the user can click to take action
message_agent Send a message to another agent in the same project. Delivered asynchronously.
Parameter Type Required Description target_agentstring Yes Name or UUID of the target agent messagestring Yes The message to send contextstring No Additional context to include
Automation schedule_task Create a recurring scheduled task that runs automatically.
Parameter Type Required Description namestring Yes Short descriptive name for the task promptstring Yes The instruction to execute on each run schedule_typestring No Frequency: interval, daily, weekly, or once (default: interval) schedule_configobject No Schedule details (varies by schedule_type) descriptionstring No Longer description of the task timezonestring No Timezone for schedule (default: UTC) max_executionsinteger No Maximum number of runs (null = unlimited)
Code Execution command 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 commandstring Yes The shell command to run (e.g., python main.py, npm install express, node server.js, curl https://example.com)
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 thoughtstring Yes Reasoning, analysis, or planning thoughts
Next Steps
Workspaces File tools details and REST API
User Memory Memory management REST API
Chat API Send messages and receive AI responses
Heartbeat API Autonomous agent schedules
