> ## Documentation Index
> Fetch the complete documentation index at: https://comis-feature-skill-archive-import.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Built-in Tools
> Every built-in tool your Comis agents can use for files, shell commands, web access, and browser automation
Built-in tools are the core capabilities that come with every Comis agent.
They handle file operations, shell commands, web access, and browser
automation. These tools are always available unless you restrict them with a
[tool policy](/skills/tool-policy).
**Where these fit.** Comis ships **70 tools** in total. The 13 documented in
this page (plus the context tools and terminal driver tools below) are the
framework-level "built-ins" that any coding-agent host would have. The
remaining tools -- messaging, scheduling, sessions, media, fleet admin, etc. --
are [platform tools](/skills/platform-tools) layered on top. For per-tool guides
with deeper examples, see the [Agent Tools](/agent-tools/index) tab.
## All Built-in Tools
| Tool | What It Does | Config Toggle |
| --------------- | ------------------------------------------------------------------- | --------------------------- |
| `read` | Read file contents | `builtinTools.read` |
| `write` | Create or overwrite files | `builtinTools.write` |
| `edit` | Search-and-replace edits in files | `builtinTools.edit` |
| `notebook_edit` | Cell-level Jupyter notebook editing (insert, replace, delete cells) | `builtinTools.notebookEdit` |
| `grep` | Search file contents with patterns | `builtinTools.grep` |
| `find` | Find files by name pattern | `builtinTools.find` |
| `ls` | List directory contents | `builtinTools.ls` |
| `exec` | Run shell commands | `builtinTools.exec` |
| `process` | Manage background processes | `builtinTools.process` |
| `web_search` | Search the web (8 providers) | `builtinTools.webSearch` |
| `web_fetch` | Fetch and read web pages | `builtinTools.webFetch` |
| `apply_patch` | Apply multi-file patches | Enabled with `edit` |
| `browser` | Control a headless browser | `builtinTools.browser` |
## Tool Details
Reads the contents of a file with line numbers. Useful for inspecting source
code, configuration files, logs, or any text file in the workspace.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ----------------------------------- |
| `path` | `string` | Yes | Path to the file to read |
| `offset` | `number` | No | Start reading from this line number |
| `limit` | `number` | No | Maximum number of lines to return |
**Example usage:**
```yaml theme={null}
# Read the first 50 lines of a config file
tool: read
path: config.yaml
limit: 50
```
**Notes:**
* Respects safe path rules -- agents cannot read files outside the workspace
directory
* Automatically detects binary files and returns a warning instead of garbled
content
* Line numbers are included in the output for easy reference
Creates a new file or completely overwrites an existing file. Use this for
creating new files from scratch. For surgical edits to existing files, use
the `edit` tool instead.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------- |
| `path` | `string` | Yes | Path where the file should be created |
| `content` | `string` | Yes | The full content to write to the file |
**Example usage:**
```yaml theme={null}
# Create a new configuration file
tool: write
path: settings.json
content: |
{
"theme": "dark",
"language": "en"
}
```
**Notes:**
* Automatically creates parent directories if they do not exist
* Respects safe path rules -- agents cannot write files outside the workspace
* Overwrites the entire file -- there is no append mode
Makes precise text replacements in an existing file. The agent specifies the
exact text to find and the text to replace it with. This is safer than
rewriting entire files because it only changes the targeted section.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | -------- | -------- | --------------------------------------- |
| `path` | `string` | Yes | Path to the file to edit |
| `old_string` | `string` | Yes | Exact text to find (must match exactly) |
| `new_string` | `string` | Yes | Replacement text |
**Example usage:**
```yaml theme={null}
# Change a configuration value
tool: edit
path: config.yaml
old_string: "port: 3000"
new_string: "port: 8080"
```
**Notes:**
* Requires an exact match -- this is not a regular expression search
* Fails if `old_string` is not found in the file
* Fails if `old_string` appears more than once (ambiguous edit)
* Respects safe path rules
Edits Jupyter notebook (`.ipynb`) files at the cell level. Supports inserting
new cells, replacing cell content, and deleting cells by index. This is safer
than rewriting an entire notebook because it preserves cell metadata and outputs
for unchanged cells.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | ------------------ | --------------------------------------------------- |
| `path` | `string` | Yes | Path to the `.ipynb` notebook file |
| `action` | `string` | Yes | Action to perform: `insert`, `replace`, or `delete` |
| `index` | `number` | Yes | Cell index (0-based) to operate on |
| `content` | `string` | For insert/replace | Cell source content |
| `cell_type` | `string` | No | Cell type: `code` (default) or `markdown` |
**Example usage:**
```yaml theme={null}
# Insert a new code cell at position 2
tool: notebook_edit
path: analysis.ipynb
action: insert
index: 2
content: "import pandas as pd\ndf = pd.read_csv('data.csv')"
# Replace cell content
tool: notebook_edit
path: analysis.ipynb
action: replace
index: 0
content: "# Updated Analysis\nThis notebook analyzes the Q4 results."
cell_type: markdown
```
**Notes:**
* Respects safe path rules -- agents cannot edit notebooks outside the workspace
* Preserves cell outputs and metadata for unchanged cells
* Enabled via `builtinTools.notebookEdit` config toggle (default: `true`)
Searches through files using regular expression patterns, similar to the
`grep` command-line tool. Returns matching lines with file paths and line
numbers.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------------------------- |
| `pattern` | `string` | Yes | Regular expression pattern to search for |
| `path` | `string` | No | Directory to search in (defaults to workspace root) |
| `include` | `string` | No | File glob filter (e.g., `*.ts`, `*.md`) |
**Example usage:**
```yaml theme={null}
# Find all TODO comments in TypeScript files
tool: grep
pattern: "TODO"
include: "*.ts"
```
**Notes:**
* Uses ripgrep under the hood for fast searching
* Respects `.gitignore` rules by default
* Safe path rules apply to the search directory
Finds files matching a glob pattern. Returns a list of file paths. Useful for
locating files when you know part of the name but not the exact directory.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------------------------------ |
| `pattern` | `string` | Yes | Glob pattern to match file names (e.g., `*.config.ts`) |
| `path` | `string` | No | Directory to search in (defaults to workspace root) |
**Example usage:**
```yaml theme={null}
# Find all test files
tool: find
pattern: "*.test.ts"
```
**Notes:**
* Uses fd under the hood for fast file discovery
* Respects `.gitignore` and `.fdignore` rules
* Returns full paths relative to the workspace root
Lists the contents of a directory, including hidden files (dotfiles). Returns
file and directory names in alphabetical order.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ----------------------------- |
| `path` | `string` | Yes | Path to the directory to list |
**Example usage:**
```yaml theme={null}
# List workspace root
tool: ls
path: "."
```
**Notes:**
* Shows dotfiles (files starting with `.`)
* Results are sorted alphabetically
* Respects safe path rules
Applies a set of file operations (add, update, delete, move) in a single
atomic operation. All changes succeed together or none are applied. This is
useful when an agent needs to make coordinated changes across multiple files.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------------------- |
| `patch` | `string` | Yes | Patch content in the `*** Begin Patch` format |
The patch format supports four operations per file:
* **Add** -- create a new file with specified content
* **Update** -- modify specific sections of an existing file
* **Delete** -- remove a file
* **Move** -- rename or relocate a file
**Notes:**
* Atomic -- all patches apply or none do, preventing partial updates
* Enabled when the `edit` config toggle is on
* Respects safe path rules for all file operations
Runs a shell command and returns the output (stdout, stderr, and exit code).
Supports foreground mode (waits for completion) and background mode (returns
immediately).
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | --------- | -------- | --------------------------------------------------- |
| `command` | `string` | Yes | The shell command to execute |
| `cwd` | `string` | No | Working directory (defaults to workspace root) |
| `timeoutMs` | `number` | No | Timeout in milliseconds (default 30000, max 300000) |
| `env` | `object` | No | Environment variable overrides |
| `background` | `boolean` | No | Run in background and return immediately |
| `input` | `string` | No | String to write to the process stdin |
**Example usage:**
```yaml theme={null}
# Run a build command
tool: exec
command: "npm run build"
timeoutMs: 60000
# Run a server in the background
tool: exec
command: "node server.js"
background: true
```
**Notes:**
* **OS-level sandbox** (enabled by default) -- on Linux, commands run inside a
[bubblewrap](https://github.com/containers/bubblewrap) namespace where only the
workspace, graph shared directory, and system binaries are visible. On macOS
(dev only), `sandbox-exec` provides equivalent file-access restrictions. The
agent cannot read other workspaces, home directory secrets, or system files --
they simply do not exist inside the sandbox. Set `execSandbox.enabled: "never"`
to disable (falls back to denylist-only protection).
* Blocks dangerous commands like `rm -rf /`, filesystem format commands,
and piped script execution as an additional defense-in-depth measure
* Working directory is validated to prevent execution outside workspace bounds
* Dangerous environment variables (`LD_PRELOAD`, `DYLD_*`, etc.) are blocked
* Large outputs are automatically truncated with a notice showing the original
size
Manages background processes that were started by the `exec` tool. Provides
four actions for process lifecycle management.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | ------------------- | ----------------------------------------------------- |
| `action` | `string` | Yes | Action to perform: `list`, `kill`, `status`, or `log` |
| `sessionId` | `string` | For kill/status/log | The session ID of the target process |
| `offset` | `number` | No | Line offset for log pagination |
| `limit` | `number` | No | Maximum lines to return for log (default 200) |
**Actions:**
* **list** -- show all background process sessions with status and command
* **kill** -- terminate a running process (sends SIGTERM then SIGKILL)
* **status** -- inspect a single process session
* **log** -- read paginated output from a process
**Notes:**
* Only manages processes started by the agent via `exec` with `background: true`
* Each background process gets a unique session ID returned at creation time
Searches the web using one of 8 configurable search providers with automatic
fallback. Returns a list of search results with titles, URLs, and descriptions.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------- |
| `query` | `string` | Yes | Search query string |
| `count` | `number` | No | Number of results to return (1-10, default 5) |
| `deepFetch` | `number` | No | Auto-fetch full content for top N results (0-5, default 0) |
| `country` | `string` | No | 2-letter country code for regional results (e.g., `US`, `DE`) |
| `search_lang` | `string` | No | ISO language code for results (e.g., `en`, `fr`) |
| `freshness` | `string` | No | Filter by time (Brave only): `pd` (past day), `pw` (past week), `pm` (past month), `py` (past year) |
| `provider` | `string` | No | Override search provider for this call |
**Available providers:** Brave, Perplexity, Grok, DuckDuckGo, SearXNG, Tavily,
Exa, Jina. DuckDuckGo requires no API key. Other providers need API keys
configured in your Comis settings.
**Example usage:**
```yaml theme={null}
# Basic search
tool: web_search
query: "latest Node.js release"
# Search with full page content for top 3 results
tool: web_search
query: "TypeScript best practices"
deepFetch: 3
count: 5
```
**Notes:**
* Results are cached for 15 minutes by default to reduce API calls
* When `deepFetch` is greater than 0, the tool automatically fetches full page
content for the top results, saving separate `web_fetch` calls
* If the primary provider fails, the tool automatically tries fallback providers
* See [Web Tools Guide](/agent-tools/web-tools) for provider setup details
Fetches a URL and extracts the readable content. Converts HTML pages into
clean Markdown or plain text using the Readability algorithm (the same
technology behind browser reading modes).
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------------------------- |
| `url` | `string` | Yes | HTTP or HTTPS URL to fetch |
| `extractMode` | `string` | No | Extraction mode: `markdown` (default) or `text` |
| `maxChars` | `number` | No | Maximum characters to return (default 50000) |
**Example usage:**
```yaml theme={null}
# Fetch a documentation page
tool: web_fetch
url: "https://docs.example.com/guide"
# Get plain text with a smaller limit
tool: web_fetch
url: "https://news.example.com/article"
extractMode: "text"
maxChars: 10000
```
**Notes:**
* Uses SSRF (Server-Side Request Forgery) validation to prevent access to
internal network addresses -- agents cannot fetch `localhost` or private IPs
* Uses Chrome TLS fingerprinting to avoid bot detection on most websites
* Results are cached to reduce duplicate fetches
* JSON responses are automatically pretty-printed
Controls a headless Chromium browser for web research, form filling, and page
interaction. Supports 16 different actions for full browser automation.
**Key actions:**
* **navigate** -- go to a URL
* **screenshot** -- capture the current page as an image
* **snapshot** -- get the accessibility tree (a structured representation of
page elements)
* **act** -- interact with the page (click, type, fill, press keys, hover,
scroll, select)
* **start** / **stop** -- launch or close the browser
* **tabs** / **open** / **close** / **focus** -- manage browser tabs
* **console** -- read browser console logs
* **pdf** -- save the current page as a PDF
* **upload** -- upload files to file input elements
* **dialog** -- handle browser dialogs (alerts, confirms, prompts)
* **profiles** -- list available browser profiles
* **status** -- check if the browser is running
**Example usage:**
```yaml theme={null}
# Navigate to a page and take a screenshot
tool: browser
action: navigate
targetUrl: "https://example.com"
tool: browser
action: screenshot
```
**Notes:**
* URLs are validated through the SSRF guard before navigation -- agents cannot
browse to internal network addresses
* The browser runs headless (no visible window) on the server
* Screenshots are returned as images that the agent can analyze
* See [Browser Guide](/agent-tools/browser) for the complete action reference
with all parameters
## Context Tools
Context tools help your agent search and recall information from the current conversation session. In the default **DAG** (LCD) mode the available tools are three **in-session** expansion tools -- `ctx_search`, `ctx_inspect`, and `ctx_expand` -- that recover detail the summary hierarchy compressed away within the current conversation. They are active only in DAG mode (`contextEngine.version` defaults to `"dag"`), `never-export`, and distinct from cross-session recall (`memory_search`, `session_search`). In the opt-in **pipeline** mode the available tool is `session_search` instead. See [Context expansion tools](/agent-tools/sessions#context-expansion-tools) and [Compaction](/agents/compaction) for how the engines work.
`ctx_expand` performs a bounded in-process **multi-hop walk**: starting from a summary, it descends the summary-parent hierarchy (condensed summary -> child summaries -> leaf summaries -> the underlying messages) and -- when the knowledge graph is populated -- fuses bounded KG hops, returning a **ranked, cited evidence bundle**. The walk is **depth-capped per model tier** (nano 1 / small 2 / mid 3 / frontier 4 hops), token-capped (`maxExpandTokens`), and node-visit capped, so it can never run away on a deep or cyclic hierarchy. It is **read-only**, runs inside the per-conversation single-flight serializer, secret-scrubs and taint-wraps every recovered region on re-entry, and spills oversized output to a session file. It is **not** a sub-agent -- the walk is deterministic and in-process. When the knowledge graph is empty (the default), the walk degrades cleanly to summary-parent edges only.
### Availability
| Tool | Pipeline Mode | DAG Mode | Description |
| ---------------- | :-----------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------ |
| `session_search` | Yes | Yes | Search current session history |
| `ctx_search` | No | Yes | Full-text search over this conversation's compressed history |
| `ctx_inspect` | No | Yes | Inspect a compressed summary's metadata and children |
| `ctx_expand` | No | Yes | Bounded multi-hop walk that recovers a compressed region's underlying detail (depth-capped per model tier) as a ranked, cited bundle |
Searches through the current conversation session history using case-insensitive substring matching. Available in pipeline mode.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `query` | `string` | Yes | Search pattern (case-insensitive substring match) |
| `scope` | `string` | No | Filter by message role: `"all"` (default), `"user"`, `"assistant"`, `"tool"` |
| `limit` | `number` | No | Maximum results to return (1-30, default 10) |
**Notes:**
* Search results are protected from observation masking, so recovered content remains visible
* This tool is registered as a protected tool name -- its results survive compaction
Recovers the underlying detail of a compressed summary region of the current conversation via a **bounded in-process multi-hop walk**. Given a summary id (from `ctx_search` / `ctx_inspect`), it descends the summary-parent hierarchy -- a condensed summary's child summaries, then their leaf summaries, then the underlying messages -- and returns a **ranked, cited evidence bundle**. Available in DAG mode only.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------- |
| `summaryId` | `string` | Yes | The summary id (from `ctx_search` / `ctx_inspect`) whose compressed region to recover |
**Caps (the walk is always bounded):**
| Cap | Bound |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| Depth | Tier-gated per the agent's model: nano 1, small 2, mid 3, frontier 4 hops |
| Tokens | `contextEngine.maxExpandTokens` (default 4000) -- oversized output spills to a session file with a handle |
| Node visits | Capped so a wide or cyclic hierarchy can never run away (a visited-set makes it cycle-safe) |
**Notes:**
* **Read-only** and runs inside the per-conversation single-flight serializer, so it never interleaves with a concurrent compaction write.
* Every recovered region is **secret-scrubbed** and **taint-wrapped** on re-entry (untrusted content), and large bundles spill to a session file you can read with the file tools.
* The knowledge-graph (KG) hop is optional: when the KG is empty or disabled (the default), the walk degrades cleanly to **summary-parent edges only** -- the KG is never a precondition.
* It is **not** a sub-agent: the walk is deterministic and in-process. A drifted (missing) message id is skipped, never fatal -- the result reports a partial-coverage count.
## Terminal Driver
Nine tools for driving interactive terminal sessions. Each tool
requires an operator-configured allowlist (`allowEntries`) -- without a
matching allowlist entry the tool rejects. Designed for use with the
bubblewrap sandbox on Linux. See [exec sandbox](/security/exec-sandbox) for
the bubblewrap sandbox that terminal tools require.
| Tool | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `terminal_session_create` | Start an interactive terminal session driving an allowlisted binary. Fail-closed without a sandbox provider. |
| `terminal_session_read` | Read buffered output from an active terminal session (accumulated bytes since last read). |
| `terminal_session_list` | List all active terminal sessions for the current agent. |
| `terminal_session_kill` | Terminate an active terminal session and free its resources. |
| `terminal_session_send_text` | Write text to a terminal session's stdin. |
| `terminal_session_send_key` | Send a named keypress (e.g., Enter, Ctrl-C) to a terminal session. |
| `terminal_session_resize` | Resize a terminal session's pseudo-TTY (cols x rows). |
| `terminal_session_wait` | Wait for a terminal session to produce matching output or a timeout. |
| `terminal_session_status` | Registered with its final schema; execute rejects with `[not_implemented]` until the implementation lands. |
`terminal_session_status` is a registered stub -- its schema is final but the
execute handler immediately returns `[not_implemented]`. All other eight
terminal tools are fully implemented.
## Disabling Tools
Each built-in tool can be individually toggled off through configuration. This
is useful when you want to restrict what an agent can do at the config level,
independent of the tool policy:
```yaml theme={null}
skills:
builtinTools:
exec: false # Disable shell commands
browser: false # Disable browser automation
write: false # Disable file creation
webSearch: false # Disable web search
```
When a tool is disabled via config, it is completely removed from the agent's
available tools -- the agent will not even know it exists. This is different
from the tool policy, which can deny access to a tool but still lets the agent
see it.
See [Configuration Reference](/reference/config-yaml) for the full list of
config options.
## Related
Comis-specific tools for messaging, scheduling, and administration
Control which tools each agent can use
Web search providers and URL content fetching
Headless browser automation with 16 actions