Built-in Tools
Some tools are exposed to the agent without declaring a tools.modules
entry - they're either always-available primitives provided by the
context_builder module, or short-named aliases the runtime adds when
the corresponding module is loaded.
This page is the authoritative list. Every entry maps to a real
@action in the codebase; entries are cited with file + line.
Always-available primitives (context_builder)
context_builder is auto-loaded by the runtime (no YAML declaration
needed). It exposes 9 actions plus
1 action. Every agent in every mode
(direct / compact / discovery) gets access to these.
| Tool | Source | Description |
|---|---|---|
search_tools | Hybrid (semantic + keyword) search over the agent's visible tool index. | |
get_tool | Full JSON schema + examples + side-effects + aliases for one tool. | |
execute_tool | Execute a tool by name with parameters. The agent loop also auto-routes direct calls (e.g. filesystem.read({...})) through this action. | |
list_categories | List all tool domains (modules) currently visible to this agent. | |
browse_category | Paginated list of tools in one domain. | |
run_parallel | Execute multiple tool calls concurrently via asyncio.gather. | |
use_skill | Invoke a /command skill from dev.skills or the bundle's skills/ dir. | |
call_app | Call another deployed Digitorn app as a tool (composition pattern). | |
ask_user | Pause the loop and ask the user a typed question (HITL). | |
background_run | Launch any tool as a background task. One action, five modes dispatched by params: launch (name+params), status (task_id), cancel (task_id+cancel=true), wait (task_id+wait=true+timeout), list (list_tasks=true). |
Short-name aliases registered in:
| Short alias | FQN |
|---|---|
AskUser | context_builder.ask_user |
BackgroundRun | context_builder.background_run |
Agent | agent_spawn.agent (when the agent_spawn module is loaded - see below) |
Watcher primitives (gated by runtime.watchers: true). Seven
actions appear in the agent's tool index when runtime.watchers is
enabled.
| Tool | Source | Description |
|---|---|---|
watch_start | Start a periodic watcher that runs a tool every N seconds and records the result. | |
watch_stop | Stop a watcher (frees its slot). | |
watch_pause | Pause a running watcher. | |
watch_resume | Resume a paused watcher. | |
watch_status | Get a single watcher's status, last result, run count, error rate. | |
watch_list | List all watchers (active + paused). | |
watch_history | Last N check results for one watcher. |
Watchers are persistent - they survive across turns. Disable them
explicitly when the app no longer needs them (set runtime.watchers: false and redeploy, or call watch_stop from a turn).
Scheduler primitives (gated by runtime.scheduler: true)
Provided by the cron_native module. Three actions:
| Tool | Source | Description |
|---|---|---|
schedule | Schedule a tool call. Accepts at: <ISO timestamp> (one-shot), delay: <seconds> (one-shot), or cron: <expr> (recurring). | |
cancel_schedule | Cancel a scheduled job by id. | |
remind | Convenience wrapper that schedules a "self-prompt" reminder back to the agent at a given time. |
runtime.scheduler: true requires runtime.watchers: true
(RuntimeBlock.scheduler).
The legacy
schedule_once,schedule_cron,schedule_cancel,schedule_list,schedule_statusaction names referenced in older docs do not exist in the code. Use the three actions above.
Memory tools (gated by tools.modules.memory)
When memory is declared under tools.modules, four actions become
available (all four @action decorators).
| Tool | Short alias | Source | Description |
|---|---|---|---|
memory.task_create | TaskCreate | Create a task in the agent's working-memory todo list. | |
memory.task_update | TaskUpdate | Update a task's status (pending, in_progress, done, blocked) or other fields. | |
memory.set_goal | - | Set or update the agent's current high-level goal. | |
memory.remember | Remember | Store a long-term fact that survives compaction. Searchable via the same module's recall layer at runtime. |
Short aliases come. Anything else (set_plan,
update_plan_step, add_todo, add_fact, recall, forget, track_entity,
add_relationship, checkpoint, cache_content, get_snapshot,
add_episode, ...) does not exist as an @action - those names
appeared in older drafts and were never implemented. The four actions
above are the entire surface of the memory module today.
See Cognitive Memory for how the agent uses these in practice.
Agent-spawn tool (gated by agent_spawn module loaded)
The agent_spawn module exposes a
single @action named agent. Eight modes are dispatched by
params (the implementation routes through the _mode_* private
methods).
# Compile-time config: load the module via capabilities or per-agent grant
tools:
capabilities:
grant:
- { module: agent_spawn }
| Mode | Params | Result |
|---|---|---|
| Spawn (sync) | prompt (+ optional specialist, wait=true default) | Returns the spawned agent's final result. Blocks the parent turn. |
| Spawn (async) | prompt, wait=false | Returns agent_id immediately. Background. |
| Status | agent_id | Current state (running / done / failed / cancelled). |
| Wait one | agent_id, wait=true, timeout | Block until that agent finishes. |
| Wait many | agent_ids: [a, b, ...] (or omit for all) | Block until each is done; returns each result. |
| Cancel | agent_id, cancel=true | Force-cancel a running spawn. |
| Reassign | agent_id, reassign: <new prompt> | Cancel + respawn the same id with a new task. |
| List | list=true | All current spawns and their status. |
Short alias: Agent → agent_spawn.agent.
The legacy short names
AgentWait,AgentWaitAll,AgentResult,AgentStatus,AgentCancel,AgentList,ReassignAgentreferenced in older docs do not exist as separate tools. Every mode is reached via the singleAgent/agent_spawn.agentaction with the appropriate params.
See Multi-Agent for orchestration patterns.
Workspace tools (gated by tools.modules.workspace)
When the workspace module is loaded, six short-named actions
() appear in the agent's index. They operate on
the in-memory virtual filesystem streamed to the client via
Socket.IO, not the OS filesystem.
| Short | FQN |
|---|---|
WsWrite | workspace.write |
WsRead | workspace.read |
WsEdit | workspace.edit |
WsGlob | workspace.glob |
WsGrep | workspace.grep |
WsDelete | workspace.delete |
See Workspace & Preview for the renderer modes (react / vue / latex / slides / code) and the live-preview pipeline.
Web-preview tools (gated by tools.modules.web_preview)
When the web_preview module is loaded, four short-named
actions appear in the agent's index. They drive the iframe
preview pane - the agent attaches it to a dev server it
spawned (proxy) or to a directory it built (static), per
session.
| Short | FQN | Purpose |
|---|---|---|
PreviewProxy | web_preview.proxy | Proxy the iframe to a TCP port the agent's dev server is listening on. |
PreviewPublish | web_preview.publish | Build the project once and serve the static output same-origin under /api/apps/{id}/sessions/{sid}/published/. |
PreviewDetach | web_preview.detach | Drop a previously-registered attachment by name. |
The agent is responsible for spawning dev servers itself
(Bash(run_in_background=true)) and resolving port conflicts. The
daemon never spawns servers on its own. See
Workspace & Preview → web_preview
for the three regimes (proxy / static / declarative) and the
LLM communication contract.
Other short-name aliases
Defined and active when the corresponding module is loaded:
| Short | FQN | Module |
|---|---|---|
Read, Write, Edit, Grep, Glob | filesystem.<name> | filesystem (5 actions; use Bash for ls / mv / cp / rm) |
Bash | shell.bash | shell |
WebSearch, WebFetch | web.search, web.fetch | web (4 actions; the 2 unaliased - extract, download - are called via FQN) |
LintCheck, LintFile | lsp.diagnostics, lsp.check | lsp |
DbConnect, DbDisconnect, DbList, DbQuery, DbTransaction, DbBulkInsert, DbSchema, DbBrowse, DbRelations, DbSearch | database.<name> (high-level aliases) | database (16 actions total; the 6 lower-level ones - execute_query, fetch_results, list_tables, introspect, describe, extract_for_index - are called via FQN) |
The full mapping (single source of truth) is in the runtime tool catalog.
Tool injection - what the agent actually sees
Whether a built-in shows up in the agent's tool index depends on the tool injection mode:
| Injection | Meta + always-available primitives | Module tools (gated short aliases above) | Domain tools (filesystem, database, http, ...) |
|---|---|---|---|
direct | Direct (full schemas) | Direct | Direct |
compact_direct | Direct (full schemas) | Direct (compact: name + 1-line) | Direct (compact) |
discovery | Direct (always) | Direct (the gated short aliases stay direct) | Behind search_tools / browse_category / get_tool / execute_tool |
In every mode the meta-tools and the watcher / scheduler / agent_spawn / memory / workspace gated tools are always directly callable - the agent never has to "discover" them. Discovery mode only hides non-strategic domain tools.
Cross-references
- Tool delivery algorithm: Tools
- Per-module reference (full action list per module): modules/index.md
- Working memory model: Cognitive Memory
- Spawning specialists: Multi-Agent
- Live workspace + preview: Workspace & Preview
- Capabilities (grant / approve / deny): App Configuration → tools.capabilities, Security