Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
---
id: built-in-tools
title: Built-in Tools
---
Mercury has a built-in toolset it can use during conversations. These are not CLI commands — the agent decides when to call them.
## Filesystem
| Tool | What it does | Parameters |
|------|-------------|------------|
| `read_file` | Read file contents | `path` |
| `write_file` | Write to an existing file | `path`, `content` |
| `create_file` | Create a new file (creates parent dirs) | `path`, `content` |
| `edit_file` | Search and replace text in a file | `path`, `old_string`, `new_string` |
| `list_dir` | List directory contents | `path` |
| `delete_file` | Delete a file | `path` |
| `send_file` | Send file to user (Telegram upload) | `path` |
| `approve_scope` | Request read/write access to a directory | `path`, `mode` |
## Messaging
| Tool | What it does | Parameters |
|------|-------------|------------|
| `send_message` | Send a message to approved Telegram recipients | `content` |
## Shell
| Tool | What it does | Parameters |
|------|-------------|------------|
| `run_command` | Execute a shell command | `command` |
| `cd` | Change working directory (persists across calls) | `path` |
| `approve_command` | Permanently approve a command type | `command` (e.g. "curl") |
## Git
| Tool | What it does |
|------|-------------|
| `git_status` | Working tree status |
| `git_diff` | Show file changes |
| `git_log` | Commit history |
| `git_add` | Stage files |
| `git_commit` | Create a commit |
| `git_push` | Push to remote (needs approval) |
## Web, Skills, Scheduler, System
| Tool | What it does | Category |
|------|-------------|----------|
| `fetch_url` | Fetch a URL and return content (HTML stripped) | Web |
| `install_skill` | Install a skill from URL or content | Skills |
| `list_skills` | List installed skills | Skills |
| `use_skill` | Invoke a skill by name | Skills |
| `schedule_task` | Schedule recurring (cron) or one-shot (delay) task | Scheduler |
| `list_scheduled_tasks` | View all scheduled tasks | Scheduler |
| `cancel_scheduled_task` | Cancel a scheduled task | Scheduler |
| `budget_status` | Check token budget usage | System |
| `ask_user` | Ask the user a question with choices (CLI: arrow menu, Telegram: inline buttons) | System |
## Sub-Agent Delegation
| Tool | What it does | Parameters |
|------|-------------|------------|
| `delegate_task` | Spawn a sub-agent with an isolated context | `task`, `workingDirectory?`, `priority?`, `allowedTools?` |
| `list_agents` | List active sub-agents and their status | — |
| `stop_agent` | Stop a sub-agent (or all) | `agentId` (`"a1"` or `"all"`) |
## Spotify
These tools are available when Spotify is connected. Search and info tools are read-only; playback tools require Spotify Premium.
| Tool | What it does | Parameters |
|------|-------------|------------|
| `spotify_search` | Search for tracks, artists, albums, playlists | `query`, `type?`, `limit?` |
| `spotify_play` | Play a track, album, or playlist | `uri?`, `deviceId?` |
| `spotify_pause` | Pause playback | `deviceId?` |
| `spotify_next` | Skip to next track | — |
| `spotify_previous` | Skip to previous track | — |
| `spotify_now_playing` | Show currently playing track info | — |
| `spotify_devices` | List available playback devices | — |
| `spotify_queue` | Add a track to the playback queue | `uri` |
| `spotify_like` | Save a track to your library | `trackId` |
| `spotify_volume` | Set playback volume | `percent` (0–100) |
| `spotify_shuffle` | Toggle shuffle | `state` (boolean) |
| `spotify_repeat` | Set repeat mode | `state` (`off`/`track`/`context`) |
| `spotify_top_tracks` | Get user's top tracks | `timeRange?`, `limit?` |
| `spotify_playlists` | Get user's playlists | — |