Appearance
Built-in Tools
Iris comes with tools for truths, memory management, calendar operations, follow-up scheduling, image generation, and web access. This reference documents each tool's parameters and typical usage.
Truth Tools
Truths are stable, core facts about the user - more permanent than memories. These tools let Iris manage Truths during conversation.
store_truth
Store a core truth about the user - fundamental facts that define who they are.
| Parameter | Type | Required | Description |
|---|---|---|---|
truthContent | string | Yes | Complete, self-contained statement about the user |
category | string | No | personal, professional, hobbies, health, relationships, preferences, goals |
isPinned | boolean | No | Pin to always include regardless of conversation topic (default: false) |
Usage example:
"My name is TJ and I'm a software engineer in NYC - that's important to remember"
Iris calls:
store_truth(
truthContent: "TJ is a software engineer based in New York City",
category: "professional",
isPinned: false
)Returns: Confirmation with truth ID and pin status.
TIP
Use Truths for stable identity facts (name, career, location, core relationships). Use memories for contextual or time-bound information.
search_truths
Search existing truths semantically.
| Parameter | Type | Required | Description |
|---|---|---|---|
searchQuery | string | Yes | Question or topic to search for |
limit | number | No | Max results 1-10 (default: 5) |
Usage example:
"What core facts do you know about me?"
search_truths(searchQuery: "identity career location relationships")Returns: List of matching truths with content, source, and pin status.
update_truth
Modify an existing truth when core facts change.
| Parameter | Type | Required | Description |
|---|---|---|---|
truthId | number | Yes | ID of truth to update |
updatedContent | string | Yes | New content (replaces old) |
Usage example:
"I got promoted to tech lead - update my job title"
update_truth(
truthId: 5,
updatedContent: "TJ is a tech lead at a fintech company in New York City"
)Returns: Confirmation of the update.
delete_truth
Remove a truth permanently.
| Parameter | Type | Required | Description |
|---|---|---|---|
truthId | number | Yes | ID of truth to delete |
Usage example:
"Forget that fact about my old job"
Returns: Confirmation of deletion.
NOTE
When you delete a truth, similar memories won't be promoted to replace it - the system respects your explicit deletion.
Memory Tools
These tools let Iris manage persistent memories during conversation. They complement automatic extraction - use them for contextual information, events, and situational details.
store_memory
Store a new memory about the user.
| Parameter | Type | Required | Description |
|---|---|---|---|
memoryContent | string | Yes | Complete, self-contained fact with context |
memoryType | string | No | fact, preference, goal, event, skill, relationship, habit, context |
tags | array | No | Organization tags |
category | string | No | personal, professional, hobbies, health, etc. |
Usage example:
"Remember that I'm allergic to shellfish"
Iris calls:
store_memory(
memoryContent: "User is allergic to shellfish",
memoryType: "fact",
category: "health"
)Returns: Confirmation message with memory ID.
TIP
The memoryContent should be self-contained -it should make sense without the conversation context. "Allergic to shellfish" is better than "Has the allergy we discussed."
search_memory
Search stored memories semantically.
| Parameter | Type | Required | Description |
|---|---|---|---|
searchQuery | string | Yes | Question or topic to search for |
memoryType | string | No | Filter by type |
tags | array | No | Filter by tags |
category | string | No | Filter by category |
limit | number | No | Max results 1-20 (default: 5) |
Usage example:
"What do you know about my dietary restrictions?"
Iris calls:
search_memory(
searchQuery: "dietary restrictions food allergies",
memoryType: "fact",
limit: 5
)Returns: List of matching memories with content and metadata.
update_memory
Modify an existing memory. Useful when information changes or was recorded incorrectly.
| Parameter | Type | Required | Description |
|---|---|---|---|
memoryId | number | Yes | ID of memory to update |
updatedContent | string | Yes | New content (replaces old) |
Usage example:
"Actually, I moved to Chicago last month. Update my location."
Iris first searches for the location memory, then calls:
update_memory(
memoryId: 42,
updatedContent: "User lives in Chicago (moved from Seattle in December 2025)"
)Returns: Confirmation of the update.
NOTE
Updating regenerates the memory's embedding, so semantic search will find it with the new content.
delete_memory
Remove a memory permanently.
| Parameter | Type | Required | Description |
|---|---|---|---|
memoryId | number | Yes | ID of memory to delete |
Usage example:
"Forget that I like pineapple on pizza -I changed my mind."
Returns: Confirmation of deletion.
Calendar Tools
These tools interact with Google Calendar. They require a connected Google account.
list_calendar_events
Fetch upcoming events.
| Parameter | Type | Required | Description |
|---|---|---|---|
days | number | No | Days ahead, 1-30 (default: 7) |
calendarId | string | No | Specific calendar to filter by |
Usage example:
"What's on my calendar next week?"
list_calendar_events(days: 7)Returns: List of events with title, time, location, and calendar name.
Error responses:
- "Google Calendar is not connected" - User needs to connect in Settings
- "No events found" - Calendar is empty for the requested period
create_calendar_event
Create a new calendar event.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Event title |
startDateTime | string | Yes | ISO 8601 format with timezone |
endDateTime | string | Yes | ISO 8601 format with timezone |
description | string | No | Event notes |
location | string | No | Address or meeting link |
addMeetLink | boolean | No | Add Google Meet link |
Usage example:
"Schedule a team sync tomorrow at 10am for 30 minutes"
create_calendar_event(
title: "Team Sync",
startDateTime: "2026-01-29T10:00:00-05:00",
endDateTime: "2026-01-29T10:30:00-05:00",
addMeetLink: true
)Returns: Event ID and confirmation with Meet link if requested.
IMPORTANT
DateTime must be ISO 8601 format with timezone. Iris handles the conversion from natural language.
update_calendar_event
Modify an existing event.
| Parameter | Type | Required | Description |
|---|---|---|---|
eventId | string | Yes | Event to update |
title | string | No | New title |
startDateTime | string | No | New start time |
endDateTime | string | No | New end time |
description | string | No | New description |
location | string | No | New location |
Usage example:
"Move my dentist appointment to 3pm"
Iris finds the event, then calls:
update_calendar_event(
eventId: "abc123",
startDateTime: "2026-01-29T15:00:00-05:00",
endDateTime: "2026-01-29T16:00:00-05:00"
)delete_calendar_event
Remove an event from the calendar.
| Parameter | Type | Required | Description |
|---|---|---|---|
eventId | string | Yes | Event to delete |
Returns: Confirmation of deletion.
Follow-up Tools
These tools let Iris schedule and manage future check-ins during conversation. When Iris says "I'll check in on that later," these tools make it real.
schedule_followup
Schedule a future check-in with the user.
| Parameter | Type | Required | Description |
|---|---|---|---|
context | string | Yes | What to follow up about - be specific for future context |
minutes_from_now | number | Yes | How many minutes from now to follow up |
Usage example:
"I have a job interview in an hour, wish me luck!"
Iris calls:
schedule_followup(
context: "Check in after job interview to see how it went",
minutes_from_now: 90
)Returns: Confirmation with follow-up ID and scheduled time.
TIP
Follow-ups are processed by the proactive messages system. The user must have proactive messages enabled in Settings for follow-ups to trigger.
list_followups
List scheduled follow-ups.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | pending (default), completed, or all |
limit | number | No | Max results 1-50 (default: 10) |
Usage example:
"What follow-ups do you have scheduled?"
list_followups(status: "pending")Returns: List of follow-ups with ID, context, scheduled time, and status.
update_followup
Update the context or reschedule a pending follow-up.
| Parameter | Type | Required | Description |
|---|---|---|---|
followup_id | number | Yes | ID of follow-up to update |
context | string | No | New context (replaces old) |
minutes_from_now | number | No | Reschedule to this many minutes from now |
At least one of context or minutes_from_now must be provided.
Usage example:
"Actually, push that check-in back another hour"
update_followup(
followup_id: 12,
minutes_from_now: 120
)Returns: Confirmation with updated details.
Error responses:
- "not found" - Follow-up doesn't exist or belongs to another user
- "already completed" - Can't update a completed follow-up
cancel_followup
Cancel a pending follow-up.
| Parameter | Type | Required | Description |
|---|---|---|---|
followup_id | number | Yes | ID of follow-up to cancel |
reason | string | No | Reason for cancellation |
Usage example:
"Never mind about that check-in, it's resolved"
cancel_followup(
followup_id: 12,
reason: "Issue resolved during conversation"
)Returns: Confirmation of cancellation.
Image Generation
generate_image
Generate an image from a text description using OpenAI's GPT Image model.
| Parameter | Type | Required | Description |
|---|---|---|---|
description | string | Yes | Detailed image description |
size | string | No | 1024x1024, 1536x1024, or 1024x1536 (default: 1024x1024) |
Usage example:
"Create an image of a cozy coffee shop"
generate_image(
description: "A cozy coffee shop with warm lighting, wooden tables,
plants on windowsills, and a cat sleeping on a cushioned chair",
size: "1536x1024"
)Returns: The generated image displayed inline in chat, plus storage path.
Error responses:
- "OpenAI API key not configured" - Add
OPENAI_API_KEYto.env - "Content policy violation" - The prompt was rejected by OpenAI's safety filters
See Image Generation for more details on prompt strategies and limitations.
Provider Tools
Provider tools are built into Anthropic's API and run on their infrastructure:
php
// config/iris.php
'provider_tools' => [
['type' => 'web_fetch_20250910', 'name' => 'web_fetch'],
['type' => 'web_search_20250305', 'name' => 'web_search'],
],web_search
Search the web for current information. Anthropic handles the search on their servers.
Usage example:
"What's the latest news about Laravel?"
Iris calls web_search internally, receives results, and synthesizes a response.
Best for:
- Recent news and events
- Current documentation
- Fact-checking information
- Researching topics
web_fetch
Retrieve content from a specific URL.
Usage example:
"Read this article: https://example.com/blog/post"
Best for:
- Reading specific articles or documentation
- Fetching content from URLs the user provides
- Accessing public APIs
Limitations:
- Some sites block automated access
- Very large pages may be truncated
- JavaScript-rendered content may not be accessible
TIP
To disable provider tools entirely, set provider_tools to an empty array in config/iris-custom.php.
Shell Commands (Beta)
WARNING
Shell command execution is disabled by default. Set IRIS_SHELL_ENABLED=true in your .env to enable.
Execute shell commands for file operations, system queries, and CLI tasks. This is an initial implementation - the API may change or be removed in future releases. See the Shell Commands guide for full details.
run_shell_command
Execute a shell command on the host operating system.
| Parameter | Type | Required | Description |
|---|---|---|---|
command | string | Yes | The shell command to execute |
workingDirectory | string | No | Directory for command execution |
timeout | number | No | Timeout in seconds (default: 30, max: 300) |
Usage example:
"Show me the git log for my project at ~/code/myapp"
Iris calls:
run_shell_command(
command: "git log --oneline -10",
workingDirectory: "/Users/you/code/myapp"
)Returns: Command output with exit code, stdout, and stderr.
NOTE
Privilege escalation commands (sudo, su) and dangerous patterns are blocked. Commands run in a clean environment without access to sensitive variables.
Task Delegation (Beta)
WARNING
Task delegation is disabled by default. Requires both IRIS_SUBAGENT_ENABLED=true and IRIS_SHELL_ENABLED=true in your .env.
Delegate complex, multi-step tasks to an autonomous sub-agent. This is an initial implementation - the API may change or be removed in future releases. See the Task Delegation guide for full details.
delegate_task
Delegate a complex task to a sub-agent for autonomous execution.
| Parameter | Type | Required | Description |
|---|---|---|---|
description | string | Yes | Clear description of what needs to be done |
successCriteria | array | No | Verifiable conditions that define completion |
contextFiles | array | No | File paths relevant to the task |
workingDirectory | string | No | Directory for task execution |
timeout | number | No | Timeout in seconds (default: 300, max: 600) |
Usage example:
"Set up a new Laravel project with Breeze authentication"
Iris calls:
delegate_task(
description: "Create Laravel project with Breeze auth scaffolding",
successCriteria: [
"Laravel project created",
"Breeze installed and configured",
"Migrations run successfully"
],
workingDirectory: "/home/user/projects"
)Returns: Task completion status with output, duration, and modified files.
NOTE
Each user can only have one active delegated task at a time. The sub-agent inherits all shell security settings.