Tools Overview

Tools are how Iris interacts with the world beyond conversation. They enable actions like storing memories, managing calendars, creating tasks, 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")
        ↓
Iris: "Got it! I'll remember you prefer dark mode."

Tool Types

Custom Tools

Tools defined in app/Tools/, built using Prism's Tool class:

• Memory tools (store, search, update, delete)
• Calendar tools (list, create, update, delete events)
• Todoist tools (manage tasks)
• Image generation tool

Provider Tools

Built-in tools provided by Anthropic:

• web_search - Search the web
• web_fetch - Fetch web content

Agentic Loop

Iris operates as an agent, using multiple tools in sequence before responding (up to 30 iterations):

You: "Schedule a meeting with John tomorrow and remind me to prepare"

Iris might:

1. Call create_calendar_event to schedule the meeting
2. Call create_todoist_task to create a preparation task
3. Call store_memory to remember the meeting context
4. Respond with confirmation

Tool Anatomy

Every Prism tool follows this structure:

class MyTool extends Tool
{
    public function __construct()
    {
        $this
            ->as('tool_name')                    // Unique identifier
            ->for('Description of what it does') // Helps LLM decide when to use
            ->withStringParameter('param1', 'Description')
            ->using($this);                      // Handler
    }

    public function __invoke(string $param1): string
    {
        return 'Result message';
    }
}

Parameter Types

->withStringParameter('name', 'A text value')
->withNumberParameter('count', 'A numeric value')
->withBooleanParameter('enabled', 'A true/false value')
->withArrayParameter('items', 'A list of values')
->withEnumParameter('status', 'One of allowed values', ['pending', 'done'])

Tool Output

Tools can return a simple string or a ToolOutput with artifacts (images, files):

return new ToolOutput(
    result: json_encode(['status' => 'success']),
    artifacts: [$artifact],
);

Stream Events

Tool activity appears in the response stream:

Event	When
ToolCallEvent	Tool invocation started
ToolResultEvent	Tool execution completed
ProviderToolEvent	Provider tool activity

This enables the frontend to show tool activity in real-time.