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