Builtin Tools
Aleph's authoritative built-in tool registry, request-scoped execution surface, discovery, and runtime capability boundaries.
Aleph's built-in tools have two layers: BUILTIN_TOOL_DEFINITIONS at src/executor/builtin_registry/definitions.rs:63 is the authoritative agent-facing list of names and descriptions; src/builtin_tools/ and src/executor/builtin_registry/ provide implementations and dispatch. Whether a tool appears in a request is additionally affected by dependencies, health, agent/channel permissions, and session mode, so registry membership does not mean universal visibility.
Authoritative Registry
The registry currently covers these tool families; the source list is authoritative:
| Family | Registered names |
|---|---|
| Network and files | search, web_fetch, file_ops, file_read, file_write, file_edit, apply_patch |
| Execution and checks | bash, code_exec, code_check, pdf_generate, image_generate |
| Tools and skills | skill_list, skill_read, skill_status, skill_install, skill_manage, read_config_guide |
| Desktop and browser | desktop, desktop_ax_query_focused, desktop_ax_query_tree, desktop_ax_query_by_role, desktop_ax_snapshot, desktop_som, desktop_gui_locate, desktop_check_permissions; plus browser_open, browser_click, browser_type, browser_snapshot, browser_navigate, browser_tabs, browser_select, browser_evaluate, browser_fill_form, browser_press_key, browser_wait_for, browser_console, browser_hover, browser_scroll, browser_pdf, browser_network, browser_dialog, browser_drag, browser_upload, browser_resize, browser_emulate, browser_cookies, browser_session, browser_profile |
| Memory and sessions | memory_search, memory_browse, memory_explore, memory_timeline, memory_reflect, memory_trace, remember, recall_context, recall_events, ctx_search, session_list, session_send, session_new, session_compact, session_rename, session_set_mode, session_search, session_complete, user_profile, note_manage, note_orient, note_schema, note_graph_query |
| Self-management and runtime | self_manage, self_config, config_audit, doctor, hooks_manage, select_model, list_models, vault_store, gateway_route, agent_identity, agent_create, agent_list, agent_delete, agent_switch, agent_info |
| Cluster, channels, and media | node_list, node_invoke, node_invoke_many, node_file, node_manage, channel_pairing, media_understand, audio_transcribe, document_extract, media_send, artifact_publish, ask_user, google_meet |
| Automation, teams, and tasks | cron_manage, heartbeat_list, heartbeat_create, heartbeat_update, heartbeat_delete, heartbeat_toggle, heartbeat_report, team_create, team_delegate, team_status, team_disband, team_set_protocol, team_member_add, team_member_remove, team_digest, team_from_template, team_snapshot, team_usage, team_workflow_canvas, message_send, inbox_read, plan_submit, plan_resolve, task_create, task_update, task_list, task_wait, task_comment, task_submit, task_read_artifact, task_review, workflow, workflow_step_review |
| Extensions and agent interoperability | clawhub, hub_catalog_sync, hub_resolve_spec, hub_install_run, hub_install_verify, hub_fetch_docs, acp_delegate, acp_switch, a2a_delegate, a2a_agents, moa |
Some tools require startup-injected memory, channel, cluster, team, media, generation, or extension dependencies. If a dependency is absent, the dispatcher returns an explicit error rather than fabricating a working instance. scratchpad and voice_mode_set are runtime-added LLM tools, not entries in this static list; audio_generate, video_generate, and speech_generate are also not static names in this list.
Implementations and Execution
Tool implementations use typed AlephTool calls and JSON Schema. At runtime, BuiltinToolRegistry centrally dispatches canonical names. For each request, Gateway builds a ScopedToolService carrying permissions, health, confirmation, turn context, and definition rewriters; it implements ToolService's execute, list, dispatchable_list, describe, and metadata_schema operations.
Tool-name repair only resolves existing names or supplies suggestions; it does not turn an unregistered name into a registered tool. Unknown tools fail closed under the ask execution tier.
Tool Discovery
The current discovery path is:
- When progressive disclosure is enabled, non-core tools retain their names and descriptions while their input schemas are collapsed.
get_tool_schema(tool_name)returns the complete schema from a request snapshot.- Deferred tools are searched by
tool_search(query, limit)using BM25 over names and descriptions; results include full parameters and hits are promoted back into the next turn's callable tool array. [tools] defer_mcp_toolscan place MCP tools in the deferred tier; session modes use the same tier.- An empty core set or a core set containing
*disables progressive disclosure and preserves the old tool surface.
This mechanism optimizes presentation and context cost; it does not replace permission checks. A hidden tool can still be rejected at execution time.
Progress Callbacks
ToolProgressCallback is defined at src/builtin_tools/mod.rs:272 and emits tool-start, completion, and streaming-chunk events:
pub trait ToolProgressCallback: Send + Sync {
fn on_tool_start(&self, tool_name: &str, args_summary: &str);
fn on_tool_result(&self, tool_name: &str, result_summary: &str, success: bool);
fn on_tool_streaming_chunk(&self, tool_name: &str, chunk: &str);
}The global handler is stored in Mutex<Option<Arc<...>>>; streaming callbacks clone the handler before invoking it outside the lock.
Code Location
src/executor/builtin_registry/definitions.rs— authoritative built-in listsrc/executor/builtin_registry/registry/tool_registry_impl.rs— built-in dispatchsrc/builtin_tools/— tool implementationssrc/tools/service.rs—ToolServiceand definition metadatasrc/tools/scoped/— production request-scoped execution surfacesrc/tools/tool_search.rs— deferred-tool searchsrc/tools/schema_lookup.rs— on-demand full-schema loading
See Also
- Tool Infrastructure — execution, concurrency, and presentation
- MCP Integration — external MCP tools, resources, and prompts
- Browser Automation — browser tool backends