Built-in Tools
Last updated
28 tools always register on every OS,
public_api_list among them (a built-in since v1.3.2, formerly the API tool api_public_api_list); six more appear only when their prerequisite exists (generate_audio, generate_image, list_chatbot, send_to_chatbot, background_command and background_subagents) — 34 built-in tools in total. run_command_background was renamed background_command (Removed in v1.3.2). pkg_manage was Removed in v1.3.2; use run_command with argv ['sudo', ...] or sandbox: false instead. run_websocket was Removed in v1.3.2, with no replacement tool. find_note was removed in v1.0.23 together with operator notes; standing instructions for a session belong in its role (/role). Tools that cover several related actions take a mode argument rather than splitting into separate names — edit_file replaces the former write_file / patch_file / remove_file / restore_file, find_files replaces list_files / glob_files / search_files, and so on.Since v1.2.0 a run no longer sends every schema up front. For every provider except
claude-code, the tools array holds only find_tools, run_tool, reasoning_guide, write_todo, chat_history, ask_user and write_result (plus any client tools; reasoning_guide joined the fixed set in v1.2.1, write_todo in v1.2.3, the last three in v1.3.5); every other tool — built-in, script_*, ext_*, mcp__* — is listed by name in the per-turn context (Tools (call through run_tool; ...): ...; since v1.3.7 MCP tools are grouped by server as mcp__<server>__{a, b}). The model fetches a schema with find_tools(names=["NAME", ...]), which returns it as tool output, then calls the tool as run_tool(name, args); the runtime unpacks that into the inner tool, so confirmation, boundary checks and argument validation still apply by the real name. A direct call to a listed tool is refused with a pointer to run_tool, a run_tool call made before the schema was fetched returns the schema and asks for a re-call, and a name that is not registered never runs. Keeping the tools array fixed keeps the provider prompt cache hitting. The AlwaysLoad flag was removed; use find_tools to load a schema (Removed in v1.2.0). The claude-code provider (available whenever the local claude binary is found) gets every tool except run_tool and calls them by name, but receives only the names: a call made before find_tools fetched that tool's schema is not run and returns the schema instead.Conditional registration
These are excluded from a run while their prerequisite is missing; the LLM does not see them then.
| Tool | Concurrent | Description |
|---|---|---|
generate_audio | Speaks text with the configured text-to-speech model and writes the file to the output directory (output_dir, else ~/Downloads, else ~/.config/agenvoy/download/); returns the saved path, not the audio data. Since v1.0.13 the request asks the provider for opus and the extension follows the returned MIME type (.ogg for opus/ogg, .mp3, .aac, .flac, .wav as a fallback) — a .ogg / .oga / .opus result attached to a Telegram chat is delivered as a voice note rather than a document. voice picks a provider voice (alloy for OpenAI, Kore for Gemini), blank uses the provider default. 5 min cap. (excluded while no text-to-speech model is selected — set it with /model tts or POST /v1/model {tts}) | |
generate_image | Text to image, written to disk; also handles edits when a reference image is given. Returns the saved path, not the image data. 15 min cap. (excluded while the image generator is off — set it with /model or POST /v1/model {image}. Since v1.0.13 the setting names an image model as provider@model, probed from each credentialed provider with an image-only filter and cached for 15 minutes since v1.0.18; codex remains a bare provider name, and a bare provider name saved by an earlier version still resolves) | |
list_chatbot | List authorized chats for the specified platform (platform=telegram or platform=discord). (registered at daemon start only when telegram_enabled / discord_enabled is set and the bot token is in the keychain, and excluded from a run while neither platform qualifies) | |
send_to_chatbot | Send a formatted message to an authorized chat by target_id. Telegram: HTML + transient client. Discord: markdown + transient client. Platform formatting rules live in the channel system prompts, not in a tool | |
background_command | Starts one command in the background and returns a task id at once; its output is reported when it exits, and also whenever a new output line hits an error keyword while the command keeps running; legs started in the same turn form one group with objective and next (v1.3.8). Runs file watchers and jobs likely over 5 minutes; details on the Execution Tools page. (excluded unless the request comes from the TUI — cli- origin with no deliver target; since v1.3.2 no longer tied to a decision model) | |
background_subagents | ✓ | Starts a subagent leg in the background and returns a task id at once; its saved report path is reported when it finishes, delivered like background_command's. Details on the Coordination Tools page. (excluded unless the request comes from the TUI — cli- origin with no deliver target) |
Dynamic tool groups
Beyond the built-in registry, three prefixes resolve at call time:
| Prefix | Source |
|---|---|
script_* | Generated script tools under the script-tool directory — script.py executed in the sandbox |
ext_* | Extension tools, script backed |
mcp__* | Tools exposed by connected MCP servers |
User-defined API tools (
api_*) were Removed in v1.3.2: their JSON files are no longer loaded and each leftover file is skipped with an [Invalid] api tool warning in the log; call an endpoint with http_request, or build a script tool.RAG reaches the agent this way rather than as a built-in: KuraDB is registered as an ordinary MCP server, so its
list_rag / search_rag tools arrive under the mcp__ prefix and disappear entirely when it is unregistered or disconnected.