SAM Tools Reference

12 core tools (13 with ALICE). Infinite possibilities.

This is how SAM gets things done. While most AI assistants just talk, SAM takes action: reading your files, searching the web, managing memory, generating images, and more.

You don't call tools directly. Just describe what you need in natural language, and SAM automatically invokes the right tools. Say "read that config file" and SAM uses file_operations. Ask "what did we discuss about auth?" and SAM searches memory.

This reference covers: - All 12 core tools (13 with ALICE) with their operations documented - When to use each tool (and when not to) - Security model and authorization

Who needs this: - Power users pushing SAM's limits - System prompt authors designing workflows - Anyone curious about what's possible

Overview

SAM provides a consolidated tool system that lets the AI take action instead of only replying with text. Tools are invoked automatically - you don't call them directly. You see tool activity through tool cards in the conversation UI.

Tool Categories:

  • Collaboration: user_collaboration, todo_operations
  • Memory: memory_operations
  • Files & Documents: file_operations, document_operations
  • Web & Research: web_operations
  • Computation: math_operations
  • macOS Integration: calendar_operations, contacts_operations, notes_operations, spotlight_search, weather_operations
  • Image Generation: image_generation (requires ALICE)
  • Terminal: terminal_operations

For an authoritative, up-to-date inventory, see the repository's docs/TOOLS.md. This document provides usage examples and workflows.

Security Note: All tools implement proper authorization. Operations outside the working directory require user approval. macOS integration tools require explicit macOS permission grants.

Core Tools

1. think

Purpose: Strategic planning and problem decomposition

Description:
Enables the AI to think through complex problems, plan multi-step solutions, and organize its approach before taking action. Implements the thinking pattern from VS Code Copilot.

When to use: - Planning complex multi-step workflows - Clarifying approach when uncertain - Breaking down large or ambiguous requests - Analyzing errors or unexpected results

When NOT to use: - Simple, single-step tasks - Repeated planning without action - Todo list management (use todo_operations instead)

Parameters: - thoughts (string, required): Planning, analysis, or reasoning process - requested_tools (array[string], optional): List of tool names for subsequent iterations

Example:

{
  "name": "think",
  "arguments": {
    "thoughts": "To refactor the authentication system: 1) Analyze current implementation 2) Design new architecture 3) Implement changes 4) Test thoroughly",
    "requested_tools": ["file_operations", "terminal_operations"]
  }
}

Critical Rule: Think once, then execute. Do NOT get stuck in thinking loops.

2. increase_max_iterations

Purpose: Request more iterations for complex tasks

Description:
Allows agents to request additional iterations when approaching the limit. Requires Dynamic Iterations to be enabled in conversation settings.

When to use: - Approaching iteration limit - Complex task requires more iterations than initially allocated - Making steady progress but need more time to complete

Requirements: - Dynamic Iterations must be ENABLED in conversation settings - Specify total iterations needed (not additional iterations) - Provide clear reason explaining the need

Parameters: - requested_iterations (integer, required): Total iterations needed (must be greater than current max) - reason (string, required): Clear explanation of why more iterations are needed

Example:

{
  "name": "increase_max_iterations",
  "arguments": {
    "requested_iterations": 500,
    "reason": "Need more iterations to complete refactoring of remaining files. Making steady progress."
  }
}

3. read_tool_result

Purpose: Retrieve large tool results in chunks

Description:
Large tool results are automatically saved to disk to avoid provider errors. This tool reads those saved results in manageable chunks.

When to use: - Tool response contains [TOOL_RESULT_STORED] marker - Tool response includes toolCallId and totalLength metadata - Need to access large web scraping or research results

Chunked Retrieval: - Configurable chunk sizes for efficient reading - Use offset + length to paginate through large results

Parameters: - toolCallId (string, required): Tool call ID from stored result message - offset (integer, optional): Character offset to start reading from (default: 0) - length (integer, optional): Number of characters to read

Example:

{
  "name": "read_tool_result",
  "arguments": {
    "toolCallId": "call_abc123",
    "offset": 0,
    "length": 8192
  }
}

Example Workflow: 1. Tool returns: "Preview: ... [TOOL_RESULT_STORED: toolCallId=abc123, totalLength=150000]" 2. Read first chunk: read_tool_result(toolCallId: "abc123", offset: 0, length: 8192) 3. Read next chunk: read_tool_result(toolCallId: "abc123", offset: 8192, length: 8192) 4. Continue until hasMore=false

4. user_collaboration

Purpose: Request user input during task execution

Description:
Enables SAM to request user input, clarification, or decisions mid-stream without breaking conversation flow. Blocks execution until user responds.

Critical Rule: Ask questions HERE, not in chat responses. If you have a question, call this tool.

When to use: - Ambiguous requests needing clarification - Multiple valid approaches - user should choose - Confirmation before destructive operations - Information only user knows (API keys, credentials, paths)

When NOT to use: - Questions answerable with other tools (use memory_operations, file_operations instead) - Optional confirmations (proceed unless operation is destructive) - Information already available in the conversation context

Parameters: - prompt (string, required): Question or request to show user - context (string, optional): Context explaining why you're asking - authorize_operation (string, optional): Tool operation to authorize if user approves (format: 'tool_name.operation')

Example:

{
  "name": "user_collaboration",
  "arguments": {
    "prompt": "Found 500 files matching pattern. Rename all with timestamp prefix?",
    "context": "This will modify all .log files in the directory permanently",
    "authorize_operation": "file_operations.rename_file"
  }
}

Security: Blocks execution indefinitely until user responds. User has full control.

File & Terminal Operations

5. file_operations

Purpose: Read, write, search, and manage files

Description:
Comprehensive file system operations including reading, writing, searching (glob, regex, semantic), and file management. 18 operations total.

Authorization: - Inside working directory: AUTO-APPROVED ✅ - Outside working directory: Requires user approval ⚠️ - Relative paths: Auto-resolve to working directory

READ Operations (4):

read_file

Read file contents with optional line range.

Parameters: - operation: "read_file" (required) - filePath (string, required): Absolute path to file - limit (number, optional): Max lines to read - offset (number, optional): Starting line (1-indexed)

Example:

{
  "name": "file_operations",
  "arguments": {
    "operation": "read_file",
    "filePath": "/Users/andrew/project/src/main.swift",
    "limit": 100,
    "offset": 1
  }
}

list_dir

List directory contents.

Parameters: - operation: "list_dir" (required) - path (string, required): Directory path

get_errors

Retrieve compilation or linting errors.

Parameters: - operation: "get_errors" (required) - filePaths (array, optional): Specific files to check

get_file_info

Get file metadata (size, type, modified time).

Parameters: - operation: "get_file_info" (required) - path (string, required): File path

read_tool_result

Retrieve large persisted tool results in chunks.

Parameters: - operation: "read_tool_result" (required) - toolCallId (string, required): Tool call ID from stored result message - offset (integer, optional): Character offset (default: 0) - length (integer, optional): Number of characters to read

SEARCH Operations (4):

Search for files by glob pattern.

Parameters: - operation: "file_search" (required) - query (string, required): Glob pattern (e.g., "**/*.swift") - maxResults (number, optional): Limit results

Example:

{
  "name": "file_operations",
  "arguments": {
    "operation": "file_search",
    "query": "**/*.{js,ts}",
    "maxResults": 50
  }
}

Search file contents using regex.

Parameters: - operation: "grep_search" (required) - query (string, required): Search pattern - isRegexp (boolean, required): true for regex - includePattern (string, optional): File pattern to search within - maxResults (number, optional): Limit results

Example:

{
  "name": "file_operations",
  "arguments": {
    "operation": "grep_search",
    "query": "class\\s+\\w+Controller",
    "isRegexp": true,
    "includePattern": "src/**/*.swift"
  }
}

AI-powered code/text search across workspace.

Parameters: - operation: "semantic_search" (required) - query (string, required): Natural language query

Example:

{
  "name": "file_operations",
  "arguments": {
    "operation": "semantic_search",
    "query": "function that validates email addresses"
  }
}

list_usages

Find all references to a symbol (variable, function, class).

Parameters: - operation: "list_usages" (required) - symbolName (string, required): Symbol to find - filePaths (array, optional): Files to search within

WRITE Operations (9):

create_file

Create new file with content.

Parameters: - operation: "create_file" (required) - filePath (string, required): Absolute path for new file - content (string, required): File content

Example:

{
  "name": "file_operations",
  "arguments": {
    "operation": "create_file",
    "filePath": "/Users/andrew/project/README.md",
    "content": "# My Project\n\nDescription here..."
  }
}

replace_string

Replace text in file (single occurrence).

Parameters: - operation: "replace_string" (required) - filePath (string, required): File to modify - oldString (string, required): Exact text to replace (include context lines!) - newString (string, required): Replacement text

Important: Include 3-5 lines of context before/after to ensure unique match.

multi_replace_string

Multiple string replacements in one operation.

Parameters: - operation: "multi_replace_string" (required) - filePath (string, required): File to modify - replacements (array, required): Array of {oldString, newString} objects

insert_at_line

Insert or replace text at specific line.

Parameters: - operation: "insert_at_line" (required) - filePath (string, required): File to modify - lineNumber (number, required): Line number (1-indexed) - newText (string, required): Text to insert/replace - insertOperation (string, required): "insert" or "replace"

rename_file

Rename or move file.

Parameters: - operation: "rename_file" (required) - oldPath (string, required): Current file path - newPath (string, required): New file path

delete_file

Delete file.

Parameters: - operation: "delete_file" (required) - filePath (string, required): File to delete

write_file

Write content to a file (overwrites if exists).

Parameters: - operation: "write_file" (required) - path (string, required): File path - content (string, required): File content

append_file

Append content to an existing file.

Parameters: - operation: "append_file" (required) - path (string, required): File path - content (string, required): Content to append

create_directory

Create a directory (with parents).

Parameters: - operation: "create_directory" (required) - path (string, required): Directory path to create

Note on Working Directories:

File operations use the conversation's effective working directory:

Without Shared Topic: - Working Directory: ~/SAM/{conversation-uuid}/ - Creates: ~/SAM/{conversation-uuid}/file.txt

With Shared Topic "myproject": - Working Directory: ~/SAM/myproject/ - Creates: ~/SAM/myproject/file.txt

Benefits: - Multiple conversations share same workspace - Human-readable directory names - Easy to find files in Finder

See Shared Topics Documentation for details.

6. terminal_operations

Purpose: Execute shell commands and manage terminal sessions

Description:
Execute shell commands with safety validation and timeout support. Commands are classified by intent (network access, credential reading, system destruction) and confirmed with the user based on risk level. 1 operation total.

Operations: - exec - Run command and capture output (aliases: shell, run_command, terminal_exec)

Key Features: - Commands run in captured mode by default (output to file, no PTY) - Use passthrough parameter for interactive TTY access - Idle timeout: 300s default, 600s hard ceiling - Shell-specific handling: Windows cmd /c wrappers, bash detection

Common Parameters: - operation (string, required): Tool operation to perform - command (string, required): Shell command to execute - passthrough (boolean, optional): Use interactive TTY mode - timeout (integer, optional): Idle timeout in seconds - working_directory (string, optional): Working directory

Memory & RAG Tools

7. memory_operations

Purpose: Store, search, and recall memories across sessions

Description:
Consolidated tool for semantic search across stored memories, persistent storage, and task management. 14 operations total.

Operations:

OperationDescription
searchSemantic search across stored memories
storeSave information to memory
retrieveRetrieve stored value by key
listList all memory keys
deleteDelete a memory entry
recall_historySearch archived YaRN-compressed context
add_discoveryAdd a discovery fact to LTM
add_solutionAdd an error+solution pair to LTM
add_patternAdd a reusable pattern to LTM
update_ltmUpdate an existing LTM entry
prune_ltmRemove old LTM entries
ltm_statsGet LTM statistics
recall_sessionsSearch previous sessions in LTM

Session Memory vs. LTM: Session memory (store, retrieve, search, list, delete) persists within conversation scope. LTM operations (add_discovery, add_solution, add_pattern, recall_sessions, ltm_stats) persist across sessions in .clio/ltm.json.

8. todo_operations

Purpose: Track progress and plan tasks through structured todo lists

Description:
Dedicated tool for managing todo lists during multi-step workflows. Use VERY frequently to ensure task visibility and proper planning. Separated from memory_operations for clearer usage.

When to Use: - Complex multi-step work requiring planning and tracking - User provides multiple tasks or requests (numbered/comma-separated) - After receiving new instructions requiring multiple steps - BEFORE starting work on any todo (mark as in-progress) - IMMEDIATELY after completing each todo (mark completed individually) - When user requests more work after completing initial tasks (use add operation)

When NOT to Use: - Single, trivial tasks completable in one step - Purely conversational/informational requests - Simple code samples or explanations

Operations (4): - read - Get current todo list - write - Create/replace todo list (requires todoList array) - update - Partial update (requires todoUpdates array) - add - Append new todos while preserving existing ones (requires newTodos array)

Parameters: - operation (string, required): 'read', 'write', 'update', or 'add' - todoList (array[object]): Complete todo array for write operation - todoUpdates (array[object]): Partial updates for update operation - newTodos (array[object]): New todos to add (for add operation)

Todo Item Structure:

{
  "id": 1,
  "title": "Implement authentication",
  "description": "Add JWT-based auth to API endpoints",
  "status": "in-progress",
  "priority": "high",
  "dependencies": [],
  "canRunParallel": false,
  "progress": "0.5"
}

Status Values: not-started | in-progress (max 1 at a time) | completed | blocked

Critical Workflow: 1. Plan tasks by writing todo list with specific, actionable items 2. Mark ONE todo as in-progress BEFORE starting work 3. Complete the work for that specific todo 4. Mark that todo as completed IMMEDIATELY after finishing 5. Move to next todo and repeat

Example - Create Todo List:

{
  "name": "todo_operations",
  "arguments": {
    "operation": "write",
    "todoList": [
      {
        "id": 1,
        "title": "Research options",
        "description": "Explore available authentication libraries",
        "status": "not-started"
      },
      {
        "id": 2,
        "title": "Implement solution",
        "description": "Add chosen auth library to the project",
        "status": "not-started"
      }
    ]
  }
}

Example - Update Status:

{
  "name": "todo_operations",
  "arguments": {
    "operation": "update",
    "todoUpdates": [
      {"id": 1, "status": "completed"},
      {"id": 2, "status": "in-progress"}
    ]
  }
}

Example - Add New Tasks (after completing initial list):

{
  "name": "todo_operations",
  "arguments": {
    "operation": "add",
    "newTodos": [
      {"title": "Additional task", "description": "New work requested by user"},
      {"title": "Another task", "description": "More details here"}
    ]
  }
}

The add operation automatically: - Preserves all existing todos (including completed ones) - Assigns IDs starting after the highest existing ID - Defaults to not-started status

Important: Describing progress in your response is NOT the same as updating - you MUST call this tool to update todo status.

Version Control

9. version_control

Purpose: Build tasks and version control operations

Description:
Git version control operations for repository management. 9 operations total.

Operations: - status - Show repository status - log - Show commit history - diff - Show file differences - commit - Stage and commit changes - push - Push to remote - pull - Pull from remote - branch - Branch operations - stash - Stash changes - tag - Tag operations

Common Parameters: - operation (string, required): Build/VCS operation to perform - task (object): Task definition for create_and_run_task - label (string): Task label for run_task - message (string): Commit message for git_commit - files (array[string]): Files to commit

Example:

{
  "name": "version_control",
  "arguments": {
    "operation": "create_and_run_task",
    "task": {
      "label": "Build Debug",
      "type": "shell",
      "command": "make build-debug"
    },
    "workspaceFolder": "/Users/andrew/project"
  }
}

{
  "name": "version_control",
  "arguments": {
    "operation": "git_commit",
    "message": "feat: Add authentication system",
    "files": ["Sources/Auth.swift", "Tests/AuthTests.swift"]
  }
}

{
  "name": "version_control",
  "arguments": {
    "operation": "get_changed_files",
    "sourceControlState": ["staged", "unstaged"]
  }
}

Security: Git operations require authorization. Task output captured and retrievable.

Web & Documents

10. web_operations

Purpose: Web research, search, scraping, and content retrieval

Description:
Comprehensive web operations tool combining research, search, scraping, and content extraction. Includes professional search via SerpAPI when configured.

Operations (3): - fetch_url - Fetch content from a URL (with WebKit rendering) - search_web - Web search (SerpAPI when configured, DuckDuckGo fallback) - research - Comprehensive multi-source research with memory storage

When to use: - Current events, news, live information - Documentation lookup - Multi-source research synthesis - Shopping/product research (serpapi with engine=amazon/ebay/walmart)

When NOT to use: - Information already in context - Questions answerable from conversation history - Local file content (use file_operations)

Parameters: - operation (string, required): Operation type (fetch_url, search_web, research) - query (string): Search query or research question - url (string): Target URL for scrape/fetch operations (MUST use HTTPS) - depth (string): Research depth - shallow/standard/comprehensive - engine (string): Search engine for serpapi - google/bing/amazon/ebay/walmart - location (string): Search location for serpapi (optional)

Examples:

{
  "name": "web_operations",
  "arguments": {
    "operation": "research",
    "query": "Latest developments in quantum computing",
    "depth": "comprehensive"
  }
}

{
  "name": "web_operations",
  "arguments": {
    "operation": "serpapi",
    "query": "best laptops 2025",
    "engine": "amazon"
  }
}

Important: All URLs must use HTTPS. Research operation stores results in memory for later retrieval via retrieve operation.

12. document_operations

Purpose: Import documents, create formatted files, and get document info

Description:
Comprehensive document handling for importing PDFs/DOCX/TXT/MD/XLSX into memory and creating formatted documents.

Supported Operations: - document_import - Import PDF/DOCX/TXT/MD/XLSX into conversation memory - document_create - Create formatted DOCX/PDF/TXT/Markdown files - get_doc_info - List imported documents in current conversation

Supported Import Formats: - PDF files (text extraction) - Word documents (.docx) - Excel spreadsheets (.xlsx) - New in December 2025 - Text files (.txt, .md, .rtf) - Code files (all programming languages)

When to use: - Extract content from PDFs, Word docs, Excel spreadsheets, text files - Generate formatted reports or documents - Track what documents were imported

When NOT to use: - Plain text file reading (use file_operations) - Web content (use web_operations) - Simple text creation (use file_operations write)

Parameters: - operation (string, required): Operation type (document_import, document_create, get_doc_info) - path (string): File path to import (for document_import) - must be valid file:// URL or absolute path - tags (array[string]): Tags to associate with imported document - content (string): Document content (for document_create) - format (string): Output format - docx/pdf/txt/markdown - output_path (string): Path where to save created document

File URL Handling: - Malformed file:// URLs are automatically recovered using working directory - Both absolute paths and file:// URLs accepted - URLs validated before import attempt

Examples:

{
  "name": "document_operations",
  "arguments": {
    "operation": "document_import",
    "path": "/Users/andrew/Documents/report.pdf",
    "tags": ["research", "Q1-2025"]
  }
}

{
  "name": "document_operations",
  "arguments": {
    "operation": "document_create",
    "content": "# Project Report\n\nFindings...",
    "format": "docx",
    "output_path": "project_report.docx"
  }
}

Subagent Tools

10. agent_operations

Purpose: Spawn isolated subagent workflows

Description:
Delegate subtasks to specialized subagents for research, parallel work, or chunking large tasks. Subagents run in isolated conversations with fresh iteration budgets.

Operations (7): - spawn - Spawn a new isolated subagent - list - List active subagents - inbox - Check subagent inbox for messages - status - Get subagent status - kill - Terminate a subagent - send - Send message to a subagent - broadcast - Broadcast message to all subagents

Subagent Characteristics: - Runs in isolated conversation (no context pollution) - Fresh iteration budget (doesn't burn main agent's iterations) - Returns summary only (not full transcript) - Cannot spawn more subagents (recursion prevented)

Use Cases: - Processing large documents (chunk into groups) - Research before implementation - Parallel work streams (multiple focused subagents) - Complex workflows needing decomposition

Example: 32-Chapter Book Review - Main agent: Plan chunking strategy - Subagent 1: Review chapters 1-5 (returns summary) - Subagent 2: Review chapters 6-10 (returns summary) - Continue for all groups - Main agent: Synthesize all summaries

Parameters: - task (string, required): Brief task description - instructions (string, optional): Detailed instructions for subagent - model (string, optional): Model to use (default: parent's model) - maxIterations (integer, optional): Iteration limit (default: 15) - temperature (string, optional): Sampling temperature (0.0-2.0) - topP (string, optional): Top-p sampling (0.0-1.0) - enableTerminalAccess (boolean, optional): Allow terminal commands (default: false) - enableReasoning (boolean, optional): Enable chain-of-thought (default: parent's setting) - systemPromptId (string, optional): System prompt UUID (default: parent's prompt) - enableWorkflowMode (boolean, optional): Allow nested workflows (default: false) - sharedTopicId (string, optional): Shared topic UUID (default: isolated)

Example:

{
  "name": "agent_operations",
  "arguments": {
    "task": "Review chapters 1-5 of programming book",
    "instructions": "Analyze code examples, identify patterns, note any errors, create summary of key concepts",
    "maxIterations": 20,
    "enableTerminalAccess": false,
    "system_prompt_id": "research-analyst-uuid"
  }
}

Security: Terminal access disabled by default. Workflow mode disabled to prevent recursion. Isolated conversation prevents context pollution.

Multi-Tool Execution

multi_tool_use.parallel

Purpose: Execute multiple tools simultaneously

Description:
GitHub Copilot's parallel tool execution feature. Allows calling multiple tools in a single turn for efficiency. Automatically handled by the AI.

Example Scenario:
Read 3 files simultaneously instead of sequentially, reducing latency from 3 round-trips to 1.

Usage: Automatically handled - you don't invoke this directly.

Tool Invocation Format

Tools are invoked using JSON format. GitHub Copilot and OpenAI use slightly different formats:

GitHub Copilot Format

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "content": "",
    "tool_calls": [{
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "file_operations",
        "arguments": "{\"operation\":\"read_file\",\"filePath\":\"/path/to/file.txt\"}"
      }
    }]
  }
}

OpenAI Format

{
  "finish_reason": "tool_calls",
  "message": {
    "role": "assistant",
    "tool_calls": [{
      "id": "call_xyz789",
      "type": "function",
      "function": {
        "name": "memory_operations",
        "arguments": "{\"operation\":\"search_memory\",\"query\":\"authentication\"}"
      }
    }]
  }
}

Tool results are returned as:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"success\":true,\"output\":{\"content\":\"...\",\"mimeType\":\"text/plain\"}}"
}

Best Practices

DO:

  • Use think for complex multi-step tasks before taking action
  • Use semantic_search when you need "code that does X" (not exact text match)
  • Use grep_search for exact text or regex patterns
  • Include context lines (3-5) when using replace_string
  • Tag memories for better retrieval
  • Use appropriate similarity thresholds for memory search

DON'T:

  • Use file_operations for web content
  • Forget to commit changes with descriptive messages
  • Use isBackground=true for commands where you need output
  • Get stuck in thinking loops without taking action
  • Spawn subagents for simple tasks

Summary

SAM provides 12 core tools (13 with ALICE):

Tool Operations Category
think 1 Core
increase_max_iterations 1 Core
read_tool_result 1 Core
user_collaboration 1 Core
file_operations 18 Files
terminal_operations 1 Files
memory_operations 14 Memory
todo_operations 4 Planning
document_operations 3 Documents
web_operations 3 Research
calendar_operations 9 macOS
contacts_operations 6 macOS
notes_operations 6 macOS
spotlight_search 5 macOS
weather_operations 3 macOS
image_generation 2 Media
math_operations 4 Computation
code_intelligence 2 Development
version_control 9 Development
remote_execution 5 Infrastructure
apply_patch 1 Development
agent_operations 7 Infrastructure

Total: 78 operations across 22 tools

For additional help: - API Reference - REST API documentation - Getting Started - Usage tutorials - Architecture - Technical details