hermes-agent/website/docs/reference/tools-reference.md
Teknium 252d68fd45
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784)
* docs: deep audit — fix stale config keys, missing commands, and registry drift

Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level
user-guide, user-guide/features) against the live registries:

  hermes_cli/commands.py    COMMAND_REGISTRY (slash commands)
  hermes_cli/auth.py        PROVIDER_REGISTRY (providers)
  hermes_cli/config.py      DEFAULT_CONFIG (config keys)
  toolsets.py               TOOLSETS (toolsets)
  tools/registry.py         get_all_tool_names() (tools)
  python -m hermes_cli.main <subcmd> --help (CLI args)

reference/
- cli-commands.md: drop duplicate hermes fallback row + duplicate section,
  add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand
  lists to match --help output (status/logout/spotify, login, archive/prune/
  list-archived).
- slash-commands.md: add missing /sessions and /reload-skills entries +
  correct the cross-platform Notes line.
- tools-reference.md: drop bogus '68 tools' headline, drop fictional
  'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated),
  add missing 'kanban' and 'video' toolset sections, fix MCP example to use
  the real mcp_<server>_<tool> prefix.
- toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser'
  row, add missing 'kanban' and 'video' toolset rows, drop the stale
  '38 tools' count for hermes-cli.
- profile-commands.md: add missing install/update/info subcommands, document
  fish completion.
- environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the
  one with the correct gmi-serving.com default).
- faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just
  via OpenRouter), refresh the OpenAI model list.

getting-started/
- installation.md: PortableGit (not MinGit) is what the Windows installer
  fetches; document the 32-bit MinGit fallback.
- installation.md / termux.md: installer prefers .[termux-all] then falls
  back to .[termux].
- nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid
  'nix flake update --flake' invocation.
- updating.md: 'hermes backup restore --state pre-update' doesn't exist —
  point at the snapshot/quick-snapshot flow; correct config key
  'updates.pre_update_backup' (was 'update.backup').

user-guide/
- configuration.md: api_max_retries default 3 (not 2); display.runtime_footer
  is the real key (not display.runtime_metadata_footer); checkpoints defaults
  enabled=false / max_snapshots=20 (not true / 50).
- configuring-models.md: 'hermes model list' / 'hermes model set ...' don't
  exist — hermes model is interactive only.
- tui.md: busy_indicator -> tui_status_indicator with values
  kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none).
- security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env,
  not config.yaml.
- windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the
  OpenAI-compatible API server runs inside hermes gateway.

user-guide/features/
- computer-use.md: approvals.mode (not security.approval_level); fix broken
  ./browser-use.md link to ./browser.md.
- fallback-providers.md: top-level fallback_providers (not
  model.fallback_providers); the picker is subcommand-based, not modal.
- api-server.md: API_SERVER_* are env vars — write to per-profile .env,
  not 'hermes config set' which targets YAML.
- web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl
  modes are exposed through web_extract.
- kanban.md: failure_limit default is 2, not '~5'.
- plugins.md: drop hard-coded '33 providers' count.
- honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document
  that 'hermes honcho' subcommand is gated on memory.provider=honcho;
  reconcile subcommand list with actual --help output.
- memory-providers.md: legacy 'hermes honcho setup' redirect documented.

Verified via 'npm run build' — site builds cleanly; broken-link count went
from 149 to 146 (no regressions, fixed a few in passing).

* docs: round 2 audit fixes + regenerate skill catalogs

Follow-up to the previous commit on this branch:

Round 2 manual fixes:
- quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY;
  voice-mode and ACP install commands rewritten — bare 'pip install ...'
  doesn't work for curl-installed setups (no pip on PATH, not in repo
  dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e
  ".[voice]"'. ACP already ships in [all] so the curl install includes it.
- cli.md / configuration.md: 'auxiliary.compression.model' shown as
  'google/gemini-3-flash-preview' (the doc's own claimed default);
  actual default is empty (= use main model). Reworded as 'leave empty
  (default) or pin a cheap model'.
- built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row
  that was missing from the table.

Regenerated skill catalogs:
- ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill
  pages and both reference catalogs (skills-catalog.md,
  optional-skills-catalog.md). This adds the entries that were genuinely
  missing — productivity/teams-meeting-pipeline (bundled),
  optional/finance/* (entire category — 7 skills:
  3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model,
  merger-model, pptx-author), creative/hyperframes,
  creative/kanban-video-orchestrator, devops/watchers,
  productivity/shop-app, research/searxng-search,
  apple/macos-computer-use — and rewrites every other per-skill page from
  the current SKILL.md. Most diffs are tiny (one line of refreshed
  metadata).

Validation:
- 'npm run build' succeeded.
- Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation
  shells that lag every newly-added skill page (pre-existing pattern).
  No regressions on any en/ page.
2026-05-09 13:19:51 -07:00

22 KiB

sidebar_position title description
3 Built-in Tools Reference Authoritative reference for Hermes built-in tools, grouped by toolset

Built-in Tools Reference

This page documents Hermes' built-in tools, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets.

Quick counts (current registry): ~70 tools — 10 browser tools (core) + 2 CDP-gated browser tools, 4 file tools, 10 RL tools, 4 Home Assistant tools, 2 terminal tools, 2 web tools, 5 Feishu tools, 7 Spotify tools (registered by the bundled spotify plugin), 5 Yuanbao tools, 7 kanban tools (registered when the kanban dispatcher spawns the agent), 2 Discord tools, and a handful of standalone tools (memory, clarify, delegate_task, execute_code, cronjob, session_search, skill_view/skill_manage/skills_list, text_to_speech, image_generate, vision_analyze, video_analyze, mixture_of_agents, send_message, todo, computer_use, process).

:::tip MCP Tools In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix mcp_<server>_ (e.g., mcp_github_create_issue for the github MCP server). See MCP Integration for configuration. :::

browser toolset

Tool Description Requires environment
browser_back Navigate back to the previous page in browser history. Requires browser_navigate to be called first.
browser_click Click on an element identified by its ref ID from the snapshot (e.g., '@e5'). The ref IDs are shown in square brackets in the snapshot output. Requires browser_navigate and browser_snapshot to be called first.
browser_console Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requi…
browser_get_images Get a list of all images on the current page with their URLs and alt text. Useful for finding images to analyze with the vision tool. Requires browser_navigate to be called first.
browser_navigate Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer web_search or web_extract (faster, cheaper). Use browser tools when you need…
browser_press Press a keyboard key. Useful for submitting forms (Enter), navigating (Tab), or keyboard shortcuts. Requires browser_navigate to be called first.
browser_scroll Scroll the page in a direction. Use this to reveal more content that may be below or above the current viewport. Requires browser_navigate to be called first.
browser_snapshot Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: comp…
browser_type Type text into an input field identified by its ref ID. Clears the field first, then types the new text. Requires browser_navigate and browser_snapshot to be called first.
browser_vision Take a screenshot of the current page and analyze it with vision AI. Use this when you need to visually understand what's on the page - especially useful for CAPTCHAs, visual verification challenges, complex layouts, or when the text snaps…

browser toolset (CDP-gated tools)

These two tools live in the browser toolset but only register when a Chrome DevTools Protocol endpoint is reachable at session start — via /browser connect, browser.cdp_url config, a Browserbase session, or Camofox.

Tool Description Requires environment
browser_cdp Send a raw Chrome DevTools Protocol command. Escape hatch for browser operations not covered by the higher-level browser_* tools. See https://chromedevtools.github.io/devtools-protocol/ CDP endpoint
browser_dialog Respond to a native JavaScript dialog (alert / confirm / prompt / beforeunload). Call browser_snapshot first — pending dialogs appear in its pending_dialogs field. Then call browser_dialog(action='accept'|'dismiss'). CDP endpoint

clarify toolset

Tool Description Requires environment
clarify Ask the user a question when you need clarification, feedback, or a decision before proceeding. Supports two modes: 1. Multiple choice — provide up to 4 choices. The user picks one or types their own answer via a 5th 'Other' option. 2.…

code_execution toolset

Tool Description Requires environment
execute_code Run a Python script that can call Hermes tools programmatically. Use this when you need 3+ tool calls with processing logic between them, need to filter/reduce large tool outputs before they enter your context, need conditional branching (…

cronjob toolset

Tool Description Requires environment
cronjob Unified scheduled-task manager. Use action="create", "list", "update", "pause", "resume", "run", or "remove" to manage jobs. Supports skill-backed jobs with one or more attached skills, and skills=[] on update clears attached skills. Cron runs happen in fresh sessions with no current-chat context.

delegation toolset

Tool Description Requires environment
delegate_task Spawn one or more subagents to work on tasks in isolated contexts. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary is returned -- intermediate tool results never enter your context window. TWO…

feishu_doc toolset

Scoped to the Feishu document-comment intelligent-reply handler (gateway/platforms/feishu_comment.py). Not exposed on hermes-cli or the regular Feishu chat adapter.

Tool Description Requires environment
feishu_doc_read Read the full text content of a Feishu/Lark document (Docx, Doc, or Sheet) given its file_type and token. Feishu app credentials

feishu_drive toolset

Scoped to the Feishu document-comment handler. Drives comment read/write operations on drive files.

Tool Description Requires environment
feishu_drive_add_comment Add a top-level comment on a Feishu/Lark document or file. Feishu app credentials
feishu_drive_list_comments List whole-document comments on a Feishu/Lark file, most recent first. Feishu app credentials
feishu_drive_list_comment_replies List replies on a specific Feishu comment thread (whole-doc or local-selection). Feishu app credentials
feishu_drive_reply_comment Post a reply on a Feishu comment thread, with optional @-mention. Feishu app credentials

file toolset

Tool Description Requires environment
patch Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing…
read_file Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. NOTE: Cannot read images o…
search_files Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents. Content search (target='content'): Regex search inside files. Output modes: full matches with line…
write_file Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits.

homeassistant toolset

Tool Description Requires environment
ha_call_service Call a Home Assistant service to control a device. Use ha_list_services to discover available services and their parameters for each domain.
ha_get_state Get the detailed state of a single Home Assistant entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.).
ha_list_entities List Home Assistant entities. Optionally filter by domain (light, switch, climate, sensor, binary_sensor, cover, fan, etc.) or by area name (living room, kitchen, bedroom, etc.).
ha_list_services List available Home Assistant services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept. Use this to discover how to control devices found via ha_list_entities.

computer_use toolset

Tool Description Requires environment
computer_use Background macOS desktop control via cua-driver — screenshots (SOM / vision / AX), click / drag / scroll / type / key / wait, list_apps, focus_app. Does NOT steal the user's cursor or keyboard focus. Works with any tool-capable model. macOS only. cua-driver on $PATH (install via hermes tools).

:::note Honcho tools (honcho_profile, honcho_search, honcho_context, honcho_reasoning, honcho_conclude) are no longer built-in. They are available via the Honcho memory provider plugin at plugins/memory/honcho/. See Memory Providers for installation and usage. :::

image_gen toolset

Tool Description Requires environment
image_generate Generate high-quality images from text prompts using FAL.ai. The underlying model is user-configured (default: FLUX 2 Klein 9B, sub-1s generation) and is not selectable by the agent. Returns a single image URL. Display it using… FAL_KEY

kanban toolset

Registered only when the agent is spawned by the kanban dispatcher (HERMES_KANBAN_TASK env set). Lets workers mark tasks done with structured handoffs, block for human input, heartbeat during long ops, comment on threads, and (for orchestrators) fan out into child tasks. See Kanban Multi-Agent for the full workflow.

Tool Description Requires environment
kanban_show Show the active kanban task assigned to this worker (title, description, comments, dependencies). HERMES_KANBAN_TASK
kanban_complete Mark the current task done with a structured handoff payload (results, artifacts, follow-ups). HERMES_KANBAN_TASK
kanban_block Block the current task on a question for the user — the dispatcher pauses, surfaces the question, and resumes once a human replies. HERMES_KANBAN_TASK
kanban_heartbeat Send a progress heartbeat during a long-running operation so the dispatcher knows the worker is still alive. HERMES_KANBAN_TASK
kanban_comment Add a comment to the task thread without changing its state — useful for surfacing intermediate findings. HERMES_KANBAN_TASK
kanban_create (Orchestrator only) Fan out child tasks from the current task. HERMES_KANBAN_TASK + orchestrator role
kanban_link (Orchestrator only) Link related tasks together (blocks/blocked-by/related). HERMES_KANBAN_TASK + orchestrator role

memory toolset

Tool Description Requires environment
memory Save important information to persistent memory that survives across sessions. Your memory appears in your system prompt at session start -- it's how you remember things about the user and your environment between conversations. WHEN TO SA…

messaging toolset

Tool Description Requires environment
send_message Send a message to a connected messaging platform, or list available targets. IMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available tar…

moa toolset

Tool Description Requires environment
mixture_of_agents Route a hard problem through multiple frontier LLMs collaboratively. Makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort — use sparingly for genuinely difficult problems. Best for: complex math, advanced alg… OPENROUTER_API_KEY

rl toolset

Tool Description Requires environment
rl_check_status Get status and metrics for a training run. RATE LIMITED: enforces 30-minute minimum between checks for the same run. Returns WandB metrics: step, state, reward_mean, loss, percent_correct. TINKER_API_KEY, WANDB_API_KEY
rl_edit_config Update a configuration field. Use rl_get_current_config() first to see all available fields for the selected environment. Each environment has different configurable options. Infrastructure settings (tokenizer, URLs, lora_rank, learning_ra… TINKER_API_KEY, WANDB_API_KEY
rl_get_current_config Get the current environment configuration. Returns only fields that can be modified: group_size, max_token_length, total_steps, steps_per_eval, use_wandb, wandb_name, max_num_workers. TINKER_API_KEY, WANDB_API_KEY
rl_get_results Get final results and metrics for a completed training run. Returns final metrics and path to trained weights. TINKER_API_KEY, WANDB_API_KEY
rl_list_environments List all available RL environments. Returns environment names, paths, and descriptions. TIP: Read the file_path with file tools to understand how each environment works (verifiers, data loading, rewards). TINKER_API_KEY, WANDB_API_KEY
rl_list_runs List all training runs (active and completed) with their status. TINKER_API_KEY, WANDB_API_KEY
rl_select_environment Select an RL environment for training. Loads the environment's default configuration. After selecting, use rl_get_current_config() to see settings and rl_edit_config() to modify them. TINKER_API_KEY, WANDB_API_KEY
rl_start_training Start a new RL training run with the current environment and config. Most training parameters (lora_rank, learning_rate, etc.) are fixed. Use rl_edit_config() to set group_size, batch_size, wandb_project before starting. WARNING: Training… TINKER_API_KEY, WANDB_API_KEY
rl_stop_training Stop a running training job. Use if metrics look bad, training is stagnant, or you want to try different settings. TINKER_API_KEY, WANDB_API_KEY
rl_test_inference Quick inference test for any environment. Runs a few steps of inference + scoring using OpenRouter. Default: 3 steps x 16 completions = 48 rollouts per model, testing 3 models = 144 total. Tests environment loading, prompt construction, in… TINKER_API_KEY, WANDB_API_KEY

session_search toolset

Tool Description Requires environment
session_search Search your long-term memory of past conversations. This is your recall -- every past session is searchable, and this tool summarizes what happened. USE THIS PROACTIVELY when: - The user says 'we did this before', 'remember when', 'last ti…

skills toolset

Tool Description Requires environment
skill_manage Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live. Actions: create (full SKILL.m…
skill_view Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a…
skills_list List available skills (name + description). Use skill_view(name) to load full content.

terminal toolset

Tool Description Requires environment
process Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (sen…
terminal Execute shell commands on a Linux environment. Filesystem persists between calls. Set background=true for long-running servers. Set notify_on_complete=true (with background=true) to get an automatic notification when the process finishes — no polling needed. Do NOT use cat/head/tail — use read_file. Do NOT use grep/rg/find — use search_files.

todo toolset

Tool Description Requires environment
todo Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list. Writing: - Provide 'todos' array to create/update items - merge=…

vision toolset

Tool Description Requires environment
vision_analyze Analyze images using AI vision. Provides a comprehensive description and answers a specific question about the image content.

video toolset

Opt-in toolset (not loaded in the default hermes-cli set). Add via --toolsets video or include video in your toolsets: config.

Tool Description Requires environment
video_analyze Analyze video content from a URL or file path — captions, scene breakdowns, key timestamps, and visual descriptions.

web toolset

Tool Description Requires environment
web_search Search the web for information. Returns up to 5 results by default with titles, URLs, and descriptions. Accepts an optional limit (1-100, default 5). The query is passed through to the configured backend, so operators such as site:domain, filetype:pdf, intitle:word, -term, and "exact phrase" may work when the backend supports them. EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY
web_extract Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdown; larger pages are LLM-summarized. EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY

tts toolset

Tool Description Requires environment
text_to_speech Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider…

discord toolset

Registered on the hermes-discord platform toolset (gateway only). Uses the same bot token as the messaging adapter.

Tool Description Requires environment
discord Read and participate in a Discord server. Actions include search_members, fetch_messages, send_message, react, fetch_channel, list_channels, and more. DISCORD_BOT_TOKEN

discord_admin toolset

Registered on the hermes-discord platform toolset. Moderation actions require the bot to hold the matching Discord permissions.

Tool Description Requires environment
discord_admin Manage a Discord server via the REST API: list guilds/channels/roles, create/edit/delete channels, manage role grants, timeouts, kicks, and bans. DISCORD_BOT_TOKEN + bot permissions

spotify toolset

Registered by the bundled spotify plugin. Requires an OAuth token — run hermes spotify setup once to authorize.

Tool Description Requires environment
spotify_playback Control Spotify playback, inspect the active playback state, or fetch recently played tracks. Spotify OAuth
spotify_devices List Spotify Connect devices or transfer playback to a different device. Spotify OAuth
spotify_queue Inspect the user's Spotify queue or add an item to it. Spotify OAuth
spotify_search Search the Spotify catalog for tracks, albums, artists, playlists, shows, or episodes. Spotify OAuth
spotify_playlists List, inspect, create, update, and modify Spotify playlists. Spotify OAuth
spotify_albums Fetch Spotify album metadata or album tracks. Spotify OAuth
spotify_library List, save, or remove the user's saved Spotify tracks or albums. Spotify OAuth

hermes-yuanbao toolset

Registered only on the hermes-yuanbao platform toolset. Yuanbao is Tencent's chat app; these tools drive its DM/group/sticker APIs.

Tool Description Requires environment
yb_query_group_info Query basic info about a group (called "派/Pai" in the app): name, owner, member count. Yuanbao credentials
yb_query_group_members Query members of a group (for @-mentions, finding a user by name, listing bots). Yuanbao credentials
yb_send_dm Send a private/direct message to a user in a group, with optional media files. Yuanbao credentials
yb_search_sticker Search the built-in Yuanbao sticker (TIM face) catalogue by keyword. Yuanbao credentials
yb_send_sticker Send a built-in sticker to the current Yuanbao chat. Yuanbao credentials