atlas/docs/TOOL_CALLING_POLICY.md

# Tool-Calling Policy

This document defines the policy for when and how LLM agents should call tools in the Atlas voice agent system.

## Overview

The tool-calling policy ensures that:
- Tools are used appropriately and safely
- High-risk actions require confirmation
- Agents understand when to use tools vs. respond directly
- Tool permissions are clearly defined

## Tool Risk Categories

### Low-Risk Tools (Always Allowed)

These tools provide information or perform safe operations that don't modify data or have external effects:

- `get_current_time` - Read-only time information
- `get_date` - Read-only date information
- `get_timezone_info` - Read-only timezone information
- `convert_timezone` - Read-only timezone conversion
- `weather` - Read-only weather information (external API, but read-only)
- `list_tasks` - Read-only task listing
- `list_timers` - Read-only timer listing
- `list_notes` - Read-only note listing
- `read_note` - Read-only note reading
- `search_notes` - Read-only note searching

**Policy**: These tools can be called automatically without user confirmation.

### Medium-Risk Tools (Require Context Confirmation)

These tools modify local data but don't have external effects:

- `add_task` - Creates a new task
- `update_task_status` - Moves tasks between columns
- `create_timer` - Creates a timer
- `create_reminder` - Creates a reminder
- `cancel_timer` - Cancels a timer/reminder
- `create_note` - Creates a new note
- `append_to_note` - Modifies an existing note

**Policy**: 
- Can be called when the user explicitly requests the action
- Should confirm what will be done before execution (e.g., "I'll add 'buy milk' to your todo list")
- No explicit user approval token required, but agent should be confident about user intent

### High-Risk Tools (Require Explicit Confirmation)

These tools have external effects or significant consequences:

- **Future tools** (not yet implemented):
  - `send_email` - Sends email to external recipients
  - `create_calendar_event` - Creates calendar events
  - `modify_calendar_event` - Modifies existing events
  - `set_smart_home_device` - Controls smart home devices
  - `purchase_item` - Makes purchases
  - `execute_shell_command` - Executes system commands

**Policy**:
- **MUST** require explicit user confirmation token
- Agent should explain what will happen
- User must approve via client interface (not just LLM decision)
- Confirmation token must be signed/validated

## Tool Permission Matrix

| Tool | Family Agent | Work Agent | Confirmation Required |
|------|--------------|------------|----------------------|
| `get_current_time` | ✅ | ✅ | No |
| `get_date` | ✅ | ✅ | No |
| `get_timezone_info` | ✅ | ✅ | No |
| `convert_timezone` | ✅ | ✅ | No |
| `weather` | ✅ | ✅ | No |
| `add_task` | ✅ (home only) | ✅ (work only) | Context |
| `update_task_status` | ✅ (home only) | ✅ (work only) | Context |
| `list_tasks` | ✅ (home only) | ✅ (work only) | No |
| `create_timer` | ✅ | ✅ | Context |
| `create_reminder` | ✅ | ✅ | Context |
| `list_timers` | ✅ | ✅ | No |
| `cancel_timer` | ✅ | ✅ | Context |
| `create_note` | ✅ (home only) | ✅ (work only) | Context |
| `read_note` | ✅ (home only) | ✅ (work only) | No |
| `append_to_note` | ✅ (home only) | ✅ (work only) | Context |
| `search_notes` | ✅ (home only) | ✅ (work only) | No |
| `list_notes` | ✅ (home only) | ✅ (work only) | No |

## Tool-Calling Guidelines

### When to Call Tools

**Always call tools when:**
1. User explicitly requests information that requires a tool (e.g., "What time is it?")
2. User explicitly requests an action that requires a tool (e.g., "Add a task")
3. Tool would provide significantly better information than guessing
4. Tool is necessary to complete the user's request

**Don't call tools when:**
1. You can answer directly from context
2. User is asking a general question that doesn't require specific data
3. Tool call would be redundant (e.g., calling weather twice in quick succession)
4. User hasn't explicitly requested the action

### Tool Selection

**Choose the most specific tool:**
- If user asks "What time is it?", use `get_current_time` (not `get_date`)
- If user asks "Set a timer", use `create_timer` (not `create_reminder`)
- If user asks "What's on my todo list?", use `list_tasks` with status filter

**Combine tools when helpful:**
- If user asks "What's the weather and what time is it?", call both `weather` and `get_current_time`
- If user asks "What tasks do I have and what reminders?", call both `list_tasks` and `list_timers`

### Error Handling

**When a tool fails:**
1. Explain what went wrong in user-friendly terms
2. Suggest alternatives if available
3. Don't retry automatically unless it's a transient error
4. If it's a permission error, explain the limitation clearly

**Example**: "I couldn't access that file because it's outside my allowed directories. I can only access files in the home notes directory."

## Confirmation Flow

### For Medium-Risk Tools

1. **Agent explains action**: "I'll add 'buy groceries' to your todo list."
2. **Agent calls tool**: Execute the tool call
3. **Agent confirms completion**: "Done! I've added it to your todo list."

### For High-Risk Tools (Future)

1. **Agent explains action**: "I'm about to send an email to john@example.com with subject 'Meeting Notes'. Should I proceed?"
2. **Agent requests confirmation**: Wait for user approval token
3. **If approved**: Execute tool call
4. **If rejected**: Acknowledge and don't execute

## Tool Argument Validation

**Before calling a tool:**
- Validate required arguments are present
- Validate argument types match schema
- Validate argument values are reasonable (e.g., duration > 0)
- Sanitize user input if needed

**If validation fails:**
- Don't call the tool
- Explain what's missing or invalid
- Ask user to provide correct information

## Rate Limiting

Some tools have rate limits:
- `weather`: 60 requests/hour (enforced by tool)
- Other tools: No explicit limits, but use reasonably

**Guidelines:**
- Don't call the same tool repeatedly in quick succession
- Cache results when appropriate
- If rate limit is hit, explain and suggest waiting

## Tool Result Handling

**After tool execution:**
1. **Parse result**: Extract relevant information from tool response
2. **Format for user**: Present result in user-friendly format
3. **Provide context**: Add relevant context or suggestions
4. **Handle empty results**: If no results, explain clearly

**Example**:
- Tool returns: `{"tasks": []}`
- Agent says: "You don't have any tasks in your todo list right now. Would you like me to add one?"

## Escalation Rules

**If user requests something you cannot do:**
1. Explain the limitation clearly
2. Suggest alternatives if available
3. Don't attempt to bypass restrictions
4. Be helpful about what you CAN do

**Example**: "I can't access work files, but I can help you with home tasks and notes. Would you like me to create a note about what you need to do?"

## Version

**Version**: 1.0  
**Last Updated**: 2026-01-06  
**Applies To**: Both Family Agent and Work Agent