---
title: Tools Reference
description: Overview of the Corvus Agent tool system, security model, and registration.
owner: team-runtime
status: canonical
lastReviewed: 2026-05-06
appliesTo: main
docType: reference
---

# Tools Reference

Corvus Agents interact with the world through **Tools**. Each tool is a specialized function that the agent can invoke with structured parameters to perform actions, retrieve data, or manage its internal state.

The tool system is built on a "deny-by-default" security model, ensuring that every operation is subject to the configured [Security Policy](../architecture.md#security-model).

## Categories

Built-in tools are organized into six primary categories:

- [**Core Tools**](core.md) — System command execution (`shell`), persistent tasks (`TaskCreate`), native workspace search (`code_search`, `Grep`), file discovery parity (`Glob`), and workspace filesystem access (`file_read`, `file_write`).
- [**Web Tools**](web.md) — Web browsing (`browser`), search (`web_search_tool`), structured API calls (`http_request`), and read-only fetch parity (`WebFetch`).
- [**Memory Tools**](memory.md) — Long-term persistence and retrieval of facts and preferences (`memory_store`, `memory_recall`).
- [**Automation Tools**](automation.md) — Multi-agent delegation (`delegate`), managed app integrations (`composio`), Git repository management, scheduled tasks (Cron/Schedule), and notifications (`pushover`).
- [**Media Tools**](media.md) — Vision-related capabilities including screen capture and image metadata extraction.
- [**Hardware Tools**](hardware.md) — Board discovery (`hardware_board_info`), memory introspection (`hardware_memory_read`), and peripheral control (`gpio_write`, `arduino_upload`).

## Security Model

Every tool execution passes through the `SecurityPolicy` layer. Tools are classified into two operational tiers:

### Read-Only (Safe)
These tools do not modify the system or external state. They are generally allowed even in low-autonomy modes.
- *Examples:* `file_read`, `Glob`, `Grep`, `WebFetch`, `memory_recall`, `web_search_tool`, `image_info`, `hardware_board_info`.

## Claude-style parity mapping

This slice adds first-class parity tools without removing existing Corvus-native names.

| Parity name | Backing runtime piece | Slice status | Notes |
| :--- | :--- | :--- | :--- |
| `Glob` | Workspace discovery metadata helpers | Additive + canonical for parity-facing docs | New native tool for file-pattern discovery. |
| `Grep` | Shared search backend aligned with `code_search` | Additive + canonical for parity-facing docs | `code_search` remains available for the native contract. |
| `WebFetch` | Shared outbound HTTP policy derived from `http_request` | Additive + canonical for parity-facing docs | Read-only fetch-and-extract surface. |
| `TaskCreate` / `TaskGet` / `TaskList` / `TaskUpdate` / `TaskStop` | Persistent runtime task lifecycle in `brain.db` | Additive + canonical for parity-facing docs | Supported only with the `sqlite` memory backend. `schedule` and `cron_*` remain separate scheduler semantics, not task-lifecycle replacements. |

This slice does **not** require broad renames or removal of existing internal tool names.

Persistent task parity stays intentionally narrow in this slice: global tasks with optional
`session_id`, UUID IDs, statuses `pending | in_progress | completed | cancelled`, priorities
`low | medium | high`, and no reopen semantics, subtasks, or dependencies.

### Action-Bearing (Risk-bearing)
These tools can modify files, execute code, or interact with external services. They may require explicit user approval in supervised modes.
- *Examples:* `shell`, `file_write`, `git_operations`, `cron_add`, `delegate`, `composio`, `gpio_write`, `memory_forget`.

## MCP Integration

In addition to built-in tools, Corvus supports the **Model Context Protocol (MCP)**. This allows you to extend the agent's capabilities by connecting to external MCP servers.

MCP tools are automatically namespaced as `mcp.<server_name>.<tool_name>`. For detailed configuration, see the [MCP Guide](mcp.md).

## Registration & Discovery

Tools are registered during the runtime bootstrap process. The agent discovers available tools by inspecting the `ToolSpec` emitted by each implementation, which includes the tool's name, description, and JSON Schema for parameters.

:::tip[Custom Tools]
To add custom tools, you must implement the `Tool` trait in Rust and register it in the `all_tools` factory in `clients/agent-runtime/src/tools/mod.rs`.
:::
