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 listwrite- Create or replace the listupdate- Change the status of existing todosadd- 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 semanticallystore_memory- Store a memory with metadatarecall_history- Recall conversation history by time rangelist_collections- List memory collections
Key-Value Working Memory:
store- Store a key-value pairretrieve- Get a stored value by keysearch_kv- Find keys by keywordlist_keys- List all keysdelete_key- Remove a stored key
Long-Term Memory (LTM):
add_discovery- Store discovered facts with confidence levelsadd_solution- Store problem-solution pairs with example file pathsadd_pattern- Store code/workflow patternsltm_stats- Get LTM statisticsprune_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 contentsget_file_info- File metadata (size, dates)get_errors- Compiler/linter errors for a fileread_tool_result- Retrieve large results stored from earlier tool calls
Search Operations:
file_search- Find files by name patterngrep_search- Search file contents with regexsemantic_search- Concept-based code searchlist_usages- Find all usages of a symbol
Write & Management Operations:
create_file,write_file,append_file- Create and write filesreplace_string,multi_replace_string- Targeted find-and-replaceinsert_at_line- Insert content at a linerename_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 retrievaldocument_create- Generate documents indocx,pdf,txt,markdown,pptx,rtf, andxlsxget_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 memoryweb_search- Search the webscrape- Extract structured content from a pagefetch- Pull content from a specific URLserpapi- 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 expressionscompute- Statistical and unit computationconvert- Unit conversionsformula- 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
13. spotlight_search
Purpose: System-wide file and metadata search using macOS Spotlight
Operations:
search- Find files by namesearch_content- Full-text content searchsearch_metadata- Search by metadata (type, date, author)file_info- Extended attributes for a filerecent_files- Recently used files
14. weather_operations
Purpose: Current conditions and forecasts via Open-Meteo, using SAM's configured location
Operations:
current- Current conditionsforecast- Multi-day forecasthourly- 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