Tools Overview

Tools are how Iris interacts with the world beyond conversation. They enable actions like storing memories, managing calendars, generating images, and searching the web.

What Are Tools?

Tools are functions that Iris can invoke during a conversation. When Iris determines an action is needed, it calls the appropriate tool, receives a result, and incorporates it into the response.

User: "Remember that I prefer dark mode"
        ↓
Iris calls: store_memory(content="User prefers dark mode", type="preference")
        ↓
Tool returns: "Memory stored successfully"
        ↓
Iris: "Got it! I'll remember you prefer dark mode."

This happens seamlessly -users just ask for things, and Iris decides when to use tools.

Tool Types

Iris uses three types of tools:

Custom Tools

Tools defined in app/Tools/, built using Prism's Tool class. These are application-specific tools that run server-side:

// config/iris.php
'tools' => [
    // Truth tools - stable, core facts
    StoreTruthTool::class,
    SearchTruthTool::class,
    UpdateTruthTool::class,
    DeleteTruthTool::class,
    // Memory tools - contextual information
    StoreMemoryTool::class,
    SearchMemoryTool::class,
    UpdateMemoryTool::class,
    DeleteMemoryTool::class,
    // Calendar tools
    ListCalendarEventsTool::class,
    CreateCalendarEventTool::class,
    UpdateCalendarEventTool::class,
    DeleteCalendarEventTool::class,
    // Image generation
    GenerateImageTool::class,
],

Custom tools have full access to Laravel's services -they can query databases, call APIs, write files, or perform any server-side operation.

Add your own tools via config/iris-custom.php -they'll be appended to the list. See Custom Tools for details.

Provider Tools

Built-in tools provided by Anthropic that run on their infrastructure:

// config/iris.php
'provider_tools' => [
    ['type' => 'web_fetch_20250910', 'name' => 'web_fetch'],
    ['type' => 'web_search_20250305', 'name' => 'web_search'],
],

Tool	Purpose
web_search	Search the web for current information
web_fetch	Fetch content from a specific URL

Provider tools are stored as arrays (rather than classes) for config caching compatibility.

System Tools (Beta)

Tools that interact with the host operating system or spawn autonomous agents. These are initial implementations and the API may change or be removed in future releases.

// config/iris.php
'tools' => [
    // ... other tools ...
    RunShellCommandTool::class,
    DelegateTaskTool::class,
],

Tool	Purpose
run_shell_command	Execute shell commands on the host system
delegate_task	Delegate complex tasks to a sub-agent
read_file	Read a file within the agent's workspace
write_file	Write or create a file within the agent's workspace
edit_file	Replace a string within a previously-read workspace file
grep	Search file contents by regex pattern within the workspace
glob	List files matching a glob pattern within the workspace

NOTE

run_shell_command has full host access — it can read and write anywhere the process user can reach. The five filesystem tools (read_file, write_file, edit_file, grep, glob) are workspace-scoped: every path is resolved and validated against the agent's workspace root, so they can never access files outside it.

All system tools are disabled by default and require explicit enablement via environment variables. See Shell Commands, Task Delegation, and Filesystem Tools for details.

Agent Skills

Agent Skills extend Iris with specialized knowledge and workflows. Skills are loaded from .agents/skills/ and can be activated on-demand or pinned to threads for always-on expertise:

// config/iris.php
'tools' => [
    // ... other tools ...
    ActivateSkillTool::class,
],

Pinned skills inject their full content into the system prompt for every message in the thread, so you don't need to wait for Iris to activate them. See Agent Skills for details.

When to Use Which

Use case	Tool type
Access your data (memories, calendar)	Custom tool
Call your APIs or services	Custom tool
Store or modify application state	Custom tool
Search the web for current information	Provider tool
Fetch public web pages	Provider tool
Execute CLI commands or scripts	System tool
Complex multi-step file operations	System tool (delegate_task)

The Agentic Loop

Iris operates as an agent, meaning it can use multiple tools in sequence before providing a final response. This happens automatically -Iris decides what tools to use based on the request.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                      User Message                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Iris evaluates: "Does this require tools?"                 │
│                                                             │
│  If yes → call tool(s)                                      │
│  If no → generate response                                  │
└─────────────────────────────────────────────────────────────┘
                              │
                  ┌───────────┴───────────┐
                  │                       │
                  ▼                       ▼
          ┌─────────────┐        ┌─────────────────┐
          │ Tool Call   │        │ Generate        │
          │             │        │ Response        │
          └─────────────┘        └─────────────────┘
                  │
                  ▼
          ┌─────────────┐
          │ Tool Result │
          └─────────────┘
                  │
                  ▼
          ┌─────────────────────────────────────────┐
          │  Evaluate again: "More tools needed?"   │
          │                                         │
          │  If yes → call more tools (loop)        │
          │  If no → generate final response        │
          └─────────────────────────────────────────┘

Example: Multi-Step Task

You: "Schedule a meeting with John tomorrow at 2pm and remind me to prepare the quarterly report"

Iris might:

1. Call create_calendar_event(title: "Meeting with John", ...) → Event created
2. Call store_memory(content: "Prepare quarterly report before meeting with John", ...) → Memory stored
3. Generate response: "Done! I've scheduled your meeting with John for 2pm tomorrow and I'll remember you need to prepare the quarterly report."

Step Limits

The agent.max_steps configuration (default: 60) limits iterations to prevent runaway loops. Each tool call counts as one step. Most requests use 1-5 steps.

Building Tools

Iris tools are built using Prism's Tool class. For complete documentation on tool anatomy, parameter types, and return values, see the Prism Tools Documentation.

For Iris-specific patterns and examples, see Custom Tools.

Stream Events

Tool activity appears in the response stream in real-time, allowing the frontend to show what Iris is doing:

Event	When	Example
ToolCallEvent	Tool invocation started	"Storing memory..."
ToolResultEvent	Tool execution completed	"Memory stored"
ProviderToolEvent	Provider tool activity	"Searching the web..."

The frontend uses these events to show tool activity chips and status indicators during streaming.

NOTE

Events stream via WebSockets for real-time delivery. If a connection drops briefly, events are stored and replayed when the client reconnects.

Disabling Tools

To disable specific tools without modifying core config:

// config/iris-custom.php
return [
    'disabled_tools' => [
        App\Tools\GenerateImageTool::class,  // Disable image generation
    ],
];

To disable all provider tools:

// config/iris-custom.php
return [
    'provider_tools' => [],
];