Tool Use

Alma includes 20+ built-in tools that enable the AI to perform actions beyond text generation.

Tool Categories

File Operations

Tool	Description
Read	Read file contents with line numbers
Write	Create or overwrite files
Edit	Make precise edits to existing files
Glob	Find files matching patterns
Grep	Search file contents with regex
NotebookEdit	Edit Jupyter notebooks

Shell & System

Tool	Description
Bash	Execute shell commands
BashOutput	Get output from running commands
KillShell	Terminate running processes

Web

Tool	Description
WebFetch	Fetch content from URLs
WebSearch	Search the web (Google/Xiaohongshu)

Planning & Tasks

Tool	Description
Task	Create and manage agent tasks
TaskOutput	Get task results
TodoWrite	Structured task list management
EnterPlanMode	Begin multi-step planning
ExitPlanMode	Complete planning

Knowledge

Tool	Description
Recall	Retrieve from memory system
ToolSearch	Discover available tools

Extensions

Tool	Description
Skill	Execute custom skills
SlashCommand	Run slash commands

Enabling Tools

Auto Mode

The AI automatically selects appropriate tools based on your request. This is recommended for most users.

1. Click the Tools icon in the message input
2. Select Auto

Manual Selection

Choose specific tools to enable:

1. Click the Tools icon
2. Select Manual
3. Check the tools you want to enable

All Tools

Enable all available tools (including MCP tools).

No Tools

Disable all tools for text-only responses.

Tool Permissions

Some tools require your approval before executing:

Automatic Approval

Safe, read-only operations run automatically:

• Reading files
• Searching content
• Web fetching

Permission Required

Potentially impactful actions ask for approval:

• Writing files
• Running shell commands
• Deleting content

Permission Options

When prompted, you can:

• Approve: Allow this specific action
• Approve All: Approve all pending actions
• Deny: Block the action

Using Tools Effectively

File Operations

"Read the package.json file"
"Find all TypeScript files in src/"
"Search for 'TODO' comments in the codebase"

Shell Commands

"Run npm install"
"Check the git status"
"List running processes"

Web Operations

"Search for React best practices"
"Fetch the content from this URL: ..."
"Look up the latest news about AI"

Task Management

"Create a task list for this feature"
"What's on my todo list?"
"Mark the first task as complete"

Tool Configuration

Web Search Engine

Choose between search engines in Settings:

• Google: General web search
• Xiaohongshu: Chinese social platform

Tool Model

Alma uses a dedicated Tool Model for tool-related operations, separate from your main chat model. This enables:

• Faster responses: Tool analysis uses a lightweight model
• Cost savings: Frequent tool operations don't consume expensive model tokens
• Better efficiency: Main model focuses on conversation quality

What Tool Model handles:

• Analyzing which tools to use for your request
• Extracting parameters for tool calls
• Memory operations (storage, retrieval, relevance)
• Automatic thread title generation
• Background processing tasks

Recommended models (fast + good quality):

Provider	Model
OpenAI	gpt-4o-mini
Anthropic	claude-haiku-4-5
Google	gemini-2.0-flash, gemini-1.5-flash

DANGER

Never use reasoning models (o1, o3, extended thinking) as Tool Model - they are far too slow for tool operations.

Alma auto-detects the best tool model based on your providers. You can also configure it manually in Settings → General → Tool Model.

TIP

If tools feel slow, check your Tool Model configuration. Response time should be under 2.5 seconds for optimal experience.

See Tool Model Settings for detailed configuration.

MCP Tools

Additional tools from MCP servers appear with the format serverName__toolName. See MCP Integration for setup.

Troubleshooting

"Tool Not Available"

• Check if the tool is enabled
• Verify workspace is set (for file tools)
• Ensure MCP server is connected (for MCP tools)

"Permission Denied"

• You denied the tool's action
• Try approving the permission

"Command Failed"

• Check the command syntax
• Verify you have necessary permissions
• Look at the error message for details