Tools System

Tools are the executable capabilities that agents use to interact with the outside world. Each tool provides a set of actions with defined parameter schemas and permission levels.

Built-in Tools

Built-in tools are registered from the explicit module list in src/tools/discovery.ts, alongside plugin extensions. The sections below describe common tool groups; use GET /api/tools/all and GET /api/tools/role-map for the running inventory and role exposure. Tool handlers and permission action names are related but are not always identical.

Filesystem

Read, write, and manage files and directories within the workspace.

Action	Description
`read_file`	Read file contents
`write_file`	Write content to a file
`append_file`	Append content to a file
`list_directory`	List directory contents
`file_info`	Get file metadata
`create_directory`	Create a directory
`delete_file`	Delete a file
`copy_file`	Copy a file
`move_file`	Move or rename a file
`search_files`	Search for files by pattern

Permissions: read: ALLOW, write: ASK, delete: ASK

Shell

Execute commands and manage processes.

Action	Description
`run`	Execute a shell command
`run_background`	Run a command in the background
`which`	Find a command’s path
`env`	Get environment variables

Permissions: execute: ASK, elevated: DENY

Git

Full Git operations for version control.

Action	Description
`status`	Show working tree status
`log`	View commit history
`diff`	Show changes
`add`	Stage files
`commit`	Create a commit
`branch`	List or create branches
`checkout`	Switch branches
`pull`	Pull from remote
`push`	Push to remote
`stash`	Stash changes
`reset`	Reset changes
`clone`	Clone a repository

Permissions: read: ALLOW, write: ASK, push: ASK

Browser

Playwright-based browser automation for web interaction.

Action	Description
`open`	Open a new browser
`navigate`	Navigate to a URL
`click`	Click an element
`type`	Type text into an element
`screenshot`	Take a screenshot
`get_text`	Extract text from the page
`get_html`	Get page HTML
`evaluate`	Execute JavaScript
`wait_for`	Wait for an element
`close`	Close the browser
`select`	Select from a dropdown
`scroll`	Scroll the page
`hover`	Hover over an element
`press_key`	Press a keyboard key
`drag`	Drag an element to a target
`pdf`	Export the current page as PDF

Permissions: navigate: ASK, screenshot: ALLOW, execute: ASK

Browser Extension

Control the user’s real browser via Octipus Chrome extension. Uses existing cookies, sessions, and authentication — no bot detection, no sandboxed environment.

Navigation & Tabs

Action	Description
`navigate`	Navigate the active tab to a URL
`new_tab`	Open a new browser tab
`close_tab`	Close a tab by ID
`select_tab`	Switch to a tab by ID
`get_tabs`	List all open browser tabs

Screenshots & Content

Action	Description
`screenshot`	Take a screenshot of the active tab
`extract_content`	Extract text, links, and forms from the page

Interactions

Action	Description
`click`	Click an element by CSS selector
`fill`	Fill an input field with a value
`select`	Select an option from a dropdown
`hover`	Hover over an element
`press_key`	Press a keyboard key
`scroll`	Scroll the page or an element
`drag`	Drag an element to a target

Waiting & Debugging

Action	Description
`wait_for`	Wait for an element or condition
`highlight`	Highlight an element on the page

JavaScript & State

Action	Description
`evaluate`	Execute JavaScript in the page context
`get_cookies`	Get cookies for a domain
`set_cookies`	Set cookies for a domain
`get_storage`	Read localStorage or sessionStorage
`set_storage`	Write localStorage or sessionStorage

Monitoring

Action	Description
`get_console`	Retrieve captured console log messages
`get_network`	Retrieve captured network requests

Dialogs

Action	Description
`handle_dialog`	Accept or dismiss a browser dialog

Permissions: navigate: ASK, screenshot: ALLOW, extract: ALLOW, interact: ASK, evaluate: ASK (dangerous), cookies: ASK (dangerous), tabs: ASK

Web Search

Search the web and fetch page content.

Action	Description
`search`	Search the web via SearXNG
`fetch_page`	Fetch and extract text from a URL

Permissions: search: ALLOW, fetch: ALLOW

The web search tool uses a multi-tier fallback:

SearXNG — primary meta-search engine (no bot blocking)
Google (Playwright) — browser-rendered Google search
DuckDuckGo (Playwright) — browser-rendered DuckDuckGo search

Docker

Manage Docker containers and images.

Action	Description
`list_containers`	List running containers
`start_container`	Start a container
`stop_container`	Stop a container
`container_logs`	View container logs
`build_image`	Build a Docker image
`exec_command`	Execute a command in a container

Permissions: read: ALLOW, manage: ASK

GitHub

Interact with GitHub repositories, issues, and pull requests.

Action	Description
`list_repos`	List repositories
`get_repo`	Get repository details
`issue_list`	List issues
`issue_create`	Create an issue
`pr_list`	List pull requests
`get_pr`	Get PR details with diff
`create_pr`	Create a pull request
`pr_review`	Add a review to a PR

Permissions: read: ALLOW, write: ASK

GitLab

Interact with GitLab projects, issues, and merge requests.

Action	Description
`project_list`	List projects
`project_view`	Get project details
`issue_list`	List issues
`issue_create`	Create an issue
`mr_list`	List merge requests
`mr_view`	Get merge request details
`mr_create`	Create a merge request

Permissions: read: ALLOW, write: ASK

Google Workspace

Interact with Gmail, Calendar, Drive, Docs, Sheets, Contacts, and Tasks.

Service	Actions
Gmail	`gmail_list`, `gmail_search`, `gmail_read`, `gmail_send`, `gmail_reply`, `gmail_labels`, `gmail_label`, `gmail_delete`
Calendar	`calendar_list`, `calendar_events`, `calendar_event_get`, `calendar_event_create`, `calendar_event_update`, `calendar_event_delete`
Drive	`drive_list`, `drive_search`, `drive_download`, `drive_upload`, `drive_delete`
Sheets	`sheets_read`, `sheets_write`, `sheets_create`, `sheets_info`
Docs	`docs_read`, `docs_create`, `docs_update`
Contacts	`contacts_list`, `contacts_search`, `contacts_get`, `contacts_create`
Tasks	`tasks_lists`, `tasks_list`, `tasks_get`, `tasks_create`, `tasks_complete`

Permissions: read: ALLOW, send: ASK, delete: ASK

Microsoft 365

Interact with Outlook Mail, Calendar, OneDrive, To Do, and Contacts.

Service	Actions
Mail	`mail_list`, `mail_search`, `mail_read`, `mail_send`, `mail_reply`, `mail_folders`, `mail_delete`
Calendar	`calendar_list`, `calendar_events`, `calendar_event_get`, `calendar_event_create`, `calendar_event_update`, `calendar_event_delete`
OneDrive	`drive_list`, `drive_search`, `drive_download`, `drive_upload`, `drive_delete`
To Do	`todo_lists`, `todo_tasks`, `todo_task_get`, `todo_task_create`, `todo_task_complete`
Contacts	`contacts_list`, `contacts_search`, `contacts_get`, `contacts_create`

Permissions: read: ALLOW, send: ASK, delete: ASK

Messaging

Send messages to connected channels (Telegram, Slack, Teams).

Action	Description
`send`	Send a message to a channel
`list_channels`	List connected channels

Permissions: send: ASK

Knowledge Base

Hybrid search and indexing over eligible knowledge content (raw source code is excluded). Supports multiple search modes: hybrid (BM25 + vector, default), fts (full-text only), and vector (semantic only).

Action	Description
`search_knowledge`	Hybrid search across indexed documents (BM25 + vector)
`read_knowledge`	Load full content for a specific entry
`index_file`	Index a file for search
`index_directory`	Index a directory recursively

Permissions: read: ALLOW, index: ALLOW

Documents

Process, categorize, and manage uploaded documents with OCR.

Action	Description
`upload`	Upload and queue documents for processing
`list`	List processed documents with filters
`get`	Get document details including OCR text

Permissions: read: ALLOW, upload: ASK

Scheduling

Create and manage hooks and scheduled tasks.

Action	Description
`list_hooks`	List automation hooks
`create_hook`	Create a new hook or scheduled task
`update_hook`	Update an existing hook
`delete_hook`	Delete a hook
`toggle_hook`	Enable or disable a hook

Permissions: read: ALLOW, manage: ASK

Tasks

Personal to-do items with completion tracking.

Action	Description
`list_tasks`	List all tasks with status
`create_task`	Create a new task
`complete_task`	Mark a task as complete
`update_task`	Update a task

Permissions: read: ALLOW, write: ASK

Voice

Voice I/O and phone call integration.

Action	Description
`make_call`	Start an outbound call (notify or conversation mode)
`end_call`	Hang up an active call

Permissions: initiate: ASK, manage: ALLOW

Artifacts

Create, view, and manage artifacts (code snippets, documents, outputs).

Action	Description
`create_live_artifact`	Create a new artifact
`list_live_artifacts`	List artifacts
`get_live_artifact`	Get artifact details
`update_live_artifact`	Update an artifact
`delete_live_artifact`	Delete an artifact

Permissions: read: ALLOW, write: ASK, delete: ASK

Artifacts Toolbox

Discover and validate artifact specifications. Handlers are list, search, describe, design, and validate; the manifest permission action is discover.

Visual

Capture web pages and inspect their appearance with a vision model. The current handlers are analyze_page and compare_pages, under the analyze permission (default ALLOW). This tool is not an image-generation API.

Task State

Read-only inter-agent workflow state tracking. Different from the Tasks tool — used for tracking agent-to-agent work status, not user to-do items.

Action	Description
`read_task_state`	Read workflow state for a task
`list_recent_session_tasks`	List all workflow states

Permissions: read: ALLOW

Permission Levels

Each tool action has one of three permission levels:

Level	Behavior
ALLOW	Tool executes immediately without user intervention
ASK	Attended execution requests approval; unattended execution rejects the action without a live approval channel
DENY	Tool call is blocked entirely

Permissions can be customized per-user via the web UI Settings page or the API.

Tool Configuration

Built-in registration uses a static module list so bundled builds retain the tools. ENABLED_TOOLS is not a supported runtime allowlist. Use role exposure and permission rules to control availability and authorization; adding a built-in module requires registering it in src/tools/discovery.ts.

The inventory also includes groups such as Atlassian, data, notes, planning, repository registry, skill distillation, and MCP administration. The running API and generated repository catalog provide their current schemas.

New Tools

Email Processor

Provider-agnostic batch email processing. Iterates emails one-by-one with per-email classification and actions instead of dumping all into context.

Action	Description
`process_emails`	Fetch and return emails in batches with continuation tokens
`get_email_summary`	Get detailed summary of a single email

Supports both Gmail and Outlook. Includes pagination via page_token (Gmail) or skip (Outlook).

People & Profiles

Store and recall information about people, organizations, and relationships.

Action	Description
`list_profiles`	List all known people/entities
`get_profile`	Get profile by ID or name
`create_profile`	Create a new profile
`add_fact`	Add a fact (location, birthday, preference)
`search_profiles`	Search by name or fact values

The user’s own profile (isUserProfile: true) is included in supported agent prompt construction.

Plugin System

Extend Octipus with drop-in plugins. Create a directory in extensions/ with a plugin.json manifest and an index.ts entry file. Plugins are loaded at startup and their tools are registered automatically.

extensions/
  my-plugin/
    plugin.json    # name, version, tools
    index.ts       # tool implementations

API: GET /api/plugins, POST /api/plugins/:name/reload

See the Plugins documentation for details.

Direct unattended tool API calls that resolve to ASK return HTTP 409. Preconfigure narrowly scoped ALLOW rules where appropriate; discovery does not grant authorization. External CLI-native actions are outside this middleware; see CLI Providers.