Tools

Tools are the primary mechanism through which agents interact with the environment. Each tool implements a common trait and is registered in a central registry that the backend session uses for tool calls.

Tool Trait

The Tool trait defines the interface every tool must implement:

#![allow(unused)]
fn main() {
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> serde_json::Value;
    fn execution_mode(&self) -> ExecutionMode { ExecutionMode::Native }
    fn execute(&self, input: Value, ctx: ToolContext)
        -> Pin<Box<dyn Future<Output = ToolResult> + Send + '_>>;
}
}

Method	Description
`name()`	Unique identifier for the tool (e.g., `"bash"`, `"read"`)
`description()`	Human-readable description shown to the LLM
`input_schema()`	JSON Schema defining the expected input parameters
`execution_mode()`	`Native` (in-process) or `Sandboxed` (WASM) — defaults to Native
`execute()`	Async execution function taking input JSON and a `ToolContext`

ToolResult

Every tool execution returns a ToolResult:

Field	Type	Description
`content`	`Vec<ToolResultContent>`	One or more content blocks
`is_error`	`bool`	Whether this result represents an error (signals retry to the LLM)

Content blocks can be:

Text — String content
Image — Base64-encoded image with media type

Helper constructors:

ToolResult::text(s) — Creates a successful text result
ToolResult::error(s) — Creates an error text result with is_error = true

ExecutionMode

Mode	Description
`Native`	Runs in-process with full system access
`Sandboxed`	Runs in a WASM sandbox with resource limits and capability restrictions

ToolContext

The ToolContext struct provides execution context to tools:

Field	Description
`working_dir`	The agent's worktree directory
`agent_name`	Name of the executing agent
`session_id`	Current session ID
`env_vars`	Environment variables to inject
`cancellation_token`	Token to check if the session has been cancelled
`permissions`	Optional `PermissionEvaluator` for permission checks

The context supports fluent building with with_env() and with_permissions().

ToolRegistry

The ToolRegistry manages tool registration and lookup:

Method	Description
`register(tool)`	Add a tool to the registry (insertion-order preserved)
`get(name)`	Look up a tool by name
`names()`	List all registered tool names
`definitions()`	Return tool definitions (name, description, schema) for the LLM
`execute(name, input, ctx)`	Execute a tool by name
`retain(predicate)`	Remove tools that don't match a predicate
`register_mcp_tools(tools)`	Register tools from MCP servers
`register_wasm_tools(tools)`	Register WASM sandboxed tools (feature-gated)

Default Registry

default_registry() creates a registry pre-populated with all built-in tools.

Built-in Tools

Swarm ships with these native tools:

Tool	Description
`bash`	Execute shell commands
`read`	Read file contents
`write`	Write/create files
`edit`	Edit files with search-and-replace
`glob`	Find files by pattern
`grep`	Search file contents with regex
`notebook`	Edit Jupyter notebook cells
`web_fetch`	Fetch and process web content
`web_search`	Search the web
`ask_user`	Ask the operator a question
`mailbox`	Send messages to other agents
`sub_agent`	Delegate tasks to sub-agents
`task`	Interact with the task system
`skill`	Execute a skill by name
`mcp_proxy`	Proxy tool calls to MCP servers
`workflow_output`	Report outputs from workflow stages

WASM Tools

When the wasm-sandbox feature is enabled, additional tools can be loaded from compiled WebAssembly components. These run in a sandboxed environment with configurable resource limits and capabilities. See WASM Tools for details.

Adding Tools — How to implement a new tool
Permissions — How tool access is controlled
MCP Integration — External tool servers
WASM Tools — Sandboxed tool execution

swarm