SAM Tools Reference

14 consolidated tools. 83 operations.

This is how SAM gets things done. While most AI assistants just talk, SAM takes action: reading your files, importing documents, researching the web, managing memory, working with Calendar and Notes, and generating images and music through ALICE.

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 14 tools with their operations documented - When each tool applies (and what it needs to be available) - The security model behind tool use


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, each showing the tool name, operation, parameters, status, and result.

Tool Categories:

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

Some tools are always present; others depend on configuration or service availability. image_generation and music_operations only become available when an ALICE server is configured and reachable.

Security Note: All tools implement proper authorization. File operations outside the working directory require user approval, macOS integration tools require explicit permission grants, and sensitive work pauses at collaboration checkpoints.


Collaboration Tools

1. user_collaboration

Purpose: Pause and ask you something directly

Typical uses:

  • Clarifying ambiguous requests
  • Asking for approval before destructive actions
  • Requesting information only you know
  • Reporting blockers and asking how to proceed

Collaboration requests appear inline in the conversation. SAM keeps working the moment you answer.

2. todo_operations

Purpose: Plan, track, and surface progress on multi-step tasks

Operations:

  • read - Get the current todo list
  • write - Create or replace the list
  • update - Change the status of existing todos
  • add - Append new todos

This is how SAM keeps structured progress visible during longer workflows.

Memory

3. memory_operations

Purpose: Store and recall information within a conversation, across a shared topic, and long-term

Session Memory:

  • search_memory - Search stored memories semantically
  • store_memory - Store a memory with metadata
  • recall_history - Recall conversation history by time range
  • list_collections - List memory collections

Key-Value Working Memory:

  • store - Store a key-value pair
  • retrieve - Get a stored value by key
  • search_kv - Find keys by keyword
  • list_keys - List all keys
  • delete_key - Remove a stored key

Long-Term Memory (LTM):

  • add_discovery - Store discovered facts with confidence levels
  • add_solution - Store problem-solution pairs with example file paths
  • add_pattern - Store code/workflow patterns
  • ltm_stats - Get LTM statistics
  • prune_ltm - Remove old or low-confidence entries

Memory is scoped to the conversation or shared topic, so context stays relevant. LTM persists learned patterns across sessions.

Files & Documents

4. file_operations

Purpose: Read, search, and manage files in the workspace

Read Operations:

  • read_file - Read file contents (with line ranges)
  • list_dir - List directory contents
  • get_file_info - File metadata (size, dates)
  • get_errors - Compiler/linter errors for a file
  • read_tool_result - Retrieve large results stored from earlier tool calls

Search Operations:

  • file_search - Find files by name pattern
  • grep_search - Search file contents with regex
  • semantic_search - Concept-based code search
  • list_usages - Find all usages of a symbol

Write & Management Operations:

  • create_file, write_file, append_file - Create and write files
  • replace_string, multi_replace_string - Targeted find-and-replace
  • insert_at_line - Insert content at a line
  • rename_file, delete_file, create_directory - Manage files and folders

Authorization model: inside the working directory - auto-approved; outside it - requires your approval.

5. document_operations

Purpose: Import documents into conversation memory, create documents, and inspect the document inventory

Operations:

  • document_import - Import PDFs, DOCX, and more into memory and semantic retrieval
  • document_create - Generate documents in docx, pdf, txt, markdown, pptx, rtf, and xlsx
  • get_doc_info - Inspect imported document metadata

Web & Research

6. web_operations

Purpose: Web search, retrieval, and structured research

Operations:

  • research - Multi-source research with synthesis (the most comprehensive path)
  • retrieve - Access stored research from memory
  • web_search - Search the web
  • scrape - Extract structured content from a page
  • fetch - Pull content from a specific URL
  • serpapi - Search via SerpAPI (when configured)

Typical uses: current events, documentation lookup, product research, pulling content from specific URLs.

Computation & Generation

7. math_operations

Purpose: Real math, conversions, and structured formulas - Python-backed computation rather than model guesswork

Operations:

  • calculate - Evaluate expressions
  • compute - Statistical and unit computation
  • convert - Unit conversions
  • formula - Run a named formula

Available formulas: tip, mortgage, bmi, compound_interest, percentage, markup, discount, area_circle, area_rectangle, volume_cylinder, speed_distance_time, sales_tax, gpa, fuel_cost, cooking, retirement, debt_payoff, debt_strategy, budget, loan_comparison, savings_goal, net_worth, paycheck, and inflation.

8. image_generation (requires ALICE)

Purpose: Generate images through a connected ALICE server

Operations:

  • generate - Text-to-image (and img2img with an input image)
  • list_models - List models available on the server

Available only when an ALICE server is configured in Preferences and reachable. See SAM + ALICE Integration.

9. music_operations (requires ALICE)

Purpose: Generate music and audio through a connected ALICE server

Operations:

  • generate - Text-to-audio (Stable Audio Open or MiniMax Music, depending on the server)
  • list_models - List audio models available on the server

macOS Integration Tools

All macOS integration tools require explicit permission grants in System Settings the first time they're used.

10. calendar_operations

Purpose: Read and manage Calendar events and Reminders via EventKit

Calendar Operations:

  • list_events, create_event, search_events, delete_event

Reminder Operations:

  • list_reminders, create_reminder, complete_reminder, delete_reminder, list_reminder_lists

11. contacts_operations

Purpose: Work with the macOS Contacts database

Operations:

  • search, get_contact, create_contact, update_contact, list_groups, search_group

12. notes_operations

Purpose: Read and write Apple Notes

Operations:

  • search, get_note, create_note, list_folders, list_notes, append_note

Purpose: System-wide file and metadata search using macOS Spotlight

Operations:

  • search - Find files by name
  • search_content - Full-text content search
  • search_metadata - Search by metadata (type, date, author)
  • file_info - Extended attributes for a file
  • recent_files - Recently used files

14. weather_operations

Purpose: Current conditions and forecasts via Open-Meteo, using SAM's configured location

Operations:

  • current - Current conditions
  • forecast - Multi-day forecast
  • hourly - Hourly forecast

Safety Model

Tool use is constrained by:

  • File authorization boundaries (working directory vs. outside)
  • User collaboration checkpoints for sensitive work
  • Preferences-controlled capabilities
  • Service availability for optional integrations (ALICE)
  • macOS permission prompts for Calendar, Contacts, and Notes

That means SAM can be useful without silently overreaching.

See Also

For additional help: - Getting Started - Usage tutorials - Architecture - Technical details - Advanced Workflows - Shared topics and performance