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	—