Built-in Tools
Reference documentation for the built-in MCP tools provided by the AEGIS Orchestrator
The AEGIS Orchestrator provides a set of native, built-in tools out of the box. These tools are implemented internally for high performance, deep security integration, and specialized infrastructure abstraction. Built-in tools bypass the overhead of sidecar MCP servers.
For complete input and output schemas for all built-in tools, see the MCP
Tool Reference. This page documents the
skip_judge policy, argument validation, the per-tool compiled-in
defaults, and how a refused tool call is answered.
Built-in tools are divided into two main categories:
- Execution Tools: Tools like
fs.*,web.*, andcmd.runthat agents use to perform their tasks. (Documented on this page) - Management Tools: Tools like
aegis.agent.*andaegis.workflow.*used for platform administration and generative authoring. See the Management Tools reference for more details.
Inner-Loop Judge Optimization (skip_judge)
The semantic judge runs only for a call made under a deployed agent whose
manifest sets spec.execution.tool_validation. A caller of
/v1/seal/invoke whose session belongs to no deployed agent, such as an MCP
server calling tools for its user, is subject to SEAL authentication, policy
and argument validation (see Argument Validation
below) but is never sent to the judge. A call the judge rejects is refused
JUDGE_REJECTED (see Refusals and Errors).
When an agent manifest enables spec.execution.tool_validation, the orchestrator may run a semantic judge before the tool call is dispatched. The judge evaluates the proposed tool use and arguments, not the output of a completed tool run. This adds latency, but it can stop unsafe or incorrect actions before they reach a side effect boundary.
For read-only tools the judge often adds latency without meaningful safety value - the file contents or search results are deterministic and carry no write-side risk. Operators can set skip_judge: true on individual tools in spec.builtin_dispatchers[].capabilities or spec.mcp_servers[].capabilities in the Node Configuration to bypass the inner-loop judge for those specific tools.
The judge only applies to inner-loop tool calls routed through the orchestrator's tool invocation path. It is not the same as outer-loop iteration validation, and it is not part of direct SEAL authentication or policy enforcement.
The canonical explanation of this control is in Tool-Call Judging.
Compiled-in defaults:
| Tool | skip_judge default | Rationale |
|---|---|---|
cmd.run | false | State-mutating — subprocess output must be validated |
fs.read | true | Read-only |
fs.write | false | State-mutating |
fs.list | true | Read-only |
fs.search | true | Read-only |
fs.grep | true | Read-only |
fs.glob | true | Read-only |
fs.edit | false | State-mutating |
fs.multi_edit | false | State-mutating |
fs.create_dir | false | State-mutating |
fs.delete | false | State-mutating — destructive |
web.search | true | Read-only external lookup |
web.fetch | true | Read-only HTTP fetch |
aegis.agent.list | true | Read-only registry lookup |
aegis.agent.search | true | Read-only semantic search |
aegis.workflow.list | true | Read-only registry lookup |
aegis.workflow.search | true | Read-only semantic search |
aegis.schema.get | true | Read-only schema lookup |
aegis.schema.validate | true | Read-only validation |
aegis.agent.export | true | Read-only manifest lookup |
aegis.workflow.export | true | Read-only manifest lookup |
aegis.agent.create | true | Manifest deployment tool — payload contains a YAML manifest with tool names in spec.tools; the policy judge would hallucinate policy violations when reading tool names in manifest content rather than actual execution tool calls |
aegis.agent.update | true | Manifest deployment tool — payload contains a YAML manifest with tool names in spec.tools; the policy judge would hallucinate policy violations when reading tool names in manifest content rather than actual execution tool calls |
aegis.agent.delete | true | Manifest registry operation — the tool does not execute code and the registry-write path has its own validation |
aegis.agent.generate | false | Creates new agent via inner authoring loop. The agent-creator-agent always executes in the default security context, regardless of the caller's tier. |
aegis.workflow.create | true | Manifest deployment tool — payload contains a YAML manifest with tool names in spec.tools; the policy judge would hallucinate policy violations when reading tool names in manifest content rather than actual execution tool calls |
aegis.workflow.update | true | Manifest deployment tool — payload contains a YAML manifest with tool names in spec.tools; the policy judge would hallucinate policy violations when reading tool names in manifest content rather than actual execution tool calls |
aegis.workflow.delete | false | Destructive — removes workflow from registry |
aegis.workflow.run | false | Execution trigger — spawns a workflow run |
aegis.workflow.generate | false | Creates new workflow via inner authoring loop |
aegis.workflow.executions.list | true | Read-only workflow execution listing |
aegis.task.execute | false | Execution trigger — spawns an agent execution |
aegis.task.status | true | Read-only execution status query |
aegis.task.wait | true | Read-only blocking poll until terminal state |
aegis.task.list | true | Read-only execution listing |
aegis.task.logs | true | Read-only execution log query |
aegis.execution.file | true | Read-only — retrieves a file from a completed execution's workspace volume. Text files include inline content; binary files (images, PDFs, etc.) include a download URL for out-of-band retrieval. |
aegis.workflow.logs | true | Read-only execution log query |
aegis.workflow.executions.get | true | Read-only execution detail query |
aegis.workflow.status | true | Read-only execution status query |
aegis.task.cancel | false | State-mutating — terminates a running execution |
aegis.task.remove | false | Destructive — deletes an execution record |
aegis.agent.logs | true | Read-only agent activity log query |
aegis.agent.wait | true | Alias for aegis.task.wait |
aegis.workflow.wait | true | Read-only blocking poll until terminal state |
aegis.execute.wait | true | Alias for aegis.workflow.wait |
aegis.workflow.cancel | true | Read-query against execution state — cancellation is a state transition request, not a code execution |
aegis.workflow.signal | true | State-signal delivery to paused execution — not an execution tool invocation |
aegis.workflow.remove | true | Registry delete of a terminal execution record — no semantic execution risk |
aegis.workflow.validate | true | Read-only schema validation — parses and deterministically validates YAML but deploys nothing |
aegis.workflow.promote | false | Scope elevation — changes workflow visibility; not skip_judge by default |
aegis.workflow.demote | false | Scope reduction — changes workflow visibility; not skip_judge by default |
aegis.execute.intent | false | Execution trigger — spawns intent-to-execution pipeline |
aegis.execute.status | true | Read-only pipeline status query |
aegis.tools.list | true | Read-only tool discovery |
aegis.tools.search | true | Read-only tool search |
aegis.system.info | true | Read-only node status query |
aegis.system.config | true | Read-only configuration access |
aegis.runtime.list | true | Read-only runtime listing |
aegis.file.list | true | Read-only volume directory listing |
aegis.file.read | true | Read-only file content read |
aegis.file.write | false | State-mutating — writes file content in a user volume |
aegis.file.delete | false | Destructive — removes a file or directory from a user volume |
aegis.file.mkdir | false | State-mutating — creates a directory in a user volume |
aegis.volume.create | false | State-mutating — provisions a new persistent volume |
aegis.volume.list | true | Read-only volume listing |
aegis.volume.delete | false | Destructive — deletes a volume and all contents |
aegis.volume.quota | true | Read-only quota usage lookup |
aegis.git.clone | false | State-mutating — creates a binding and triggers clone |
aegis.git.list | true | Read-only binding listing |
aegis.git.status | true | Read-only clone/refresh status lookup |
aegis.git.refresh | false | State-mutating — fetches and checks out the pinned ref |
aegis.git.delete | false | Destructive — soft-deletes binding and cascades to volume |
aegis.git.commit | false | State-mutating — stages and commits workdir changes |
aegis.git.push | false | State-mutating — pushes commits to the remote |
aegis.git.land | false | State-mutating — lands a workflow run's work branch on its repository's branch; approval-gated, answered only for a workflow's landing step |
aegis.git.diff | true | Read-only unified diff of workdir or index |
aegis.script.save | false | State-mutating — persists a new TypeScript program |
aegis.script.list | true | Read-only script listing |
aegis.script.get | true | Read-only script fetch with version history |
aegis.script.update | false | State-mutating — updates a script and bumps its version |
aegis.script.delete | false | Destructive — soft-deletes a saved script |
These defaults can be overridden per-tool in the node configuration. skip_judge is an operator-level flag — agents cannot influence it.
Argument Validation
Before any tool call is dispatched — on both the inner-loop path and the external SEAL path — the orchestrator validates that all required parameters are present and non-null. If validation fails the call is rejected immediately with an InvalidArguments error; no execution target is allocated and no judge is invoked.
A caller of POST /v1/seal/invoke whose arguments fail this check is refused 422 with the code INVALID_ARGUMENTS and a message such as Invalid tool arguments: required field 'manifest_yaml' is missing or null for tool 'aegis.agent.create'. Every refusal of that route has the same body; see Refusals and Errors.
Required parameters by tool:
| Tool | Required parameters |
|---|---|
aegis.execute | prompt |
aegis.execute.intent | intent |
aegis.execute.status | pipeline_execution_id |
aegis.agent.create, aegis.agent.update | manifest_yaml |
aegis.agent.export | name |
aegis.agent.delete, aegis.task.execute | agent_id |
aegis.agent.search, aegis.workflow.search | query |
aegis.agent.generate, aegis.workflow.generate | input |
aegis.workflow.create, aegis.workflow.update | manifest_yaml |
aegis.workflow.export, aegis.workflow.delete, aegis.workflow.run | name |
aegis.workflow.logs, aegis.task.logs | execution_id |
aegis.workflow.status, aegis.workflow.executions.get | execution_id |
aegis.task.status, aegis.task.wait, aegis.agent.wait, aegis.task.cancel, aegis.task.remove | execution_id |
aegis.execution.file | path; execution_id unless volume_id |
aegis.workflow.cancel, aegis.workflow.wait, aegis.execute.wait, aegis.workflow.remove | execution_id |
aegis.workflow.signal | execution_id, response |
aegis.agent.logs | agent_id |
aegis.schema.get | key |
aegis.schema.validate | kind, manifest_yaml |
cmd.run | command (must be a non-empty string) |
fs.read, fs.list, fs.create_dir, fs.delete | path |
fs.write | path, content |
fs.edit | path, target_content, replacement_content |
fs.multi_edit | path, edits |
fs.search | needle |
fs.grep, fs.glob | pattern, path |
web.search | query |
web.fetch | url |
aegis.file.list, aegis.file.read, aegis.file.delete, aegis.file.mkdir | volume_id, path |
aegis.file.write | volume_id, path, content |
aegis.volume.create | label, size_limit_bytes |
aegis.volume.delete | volume_id |
aegis.git.clone | repo_url, label |
aegis.git.refresh, aegis.git.delete | binding_id |
aegis.git.commit | message |
aegis.script.save | name, code |
aegis.script.get, aegis.script.delete | id |
aegis.script.update | id, name, code |
Tools with no required parameters (e.g. aegis.agent.list, aegis.tools.list, aegis.system.info, aegis.runtime.list, aegis.volume.list, aegis.volume.quota, aegis.git.list, aegis.script.list) accept any object including {}. aegis.runtime.list accepts an optional language string to filter results by language name (e.g. "python", "go"). aegis.tools.search accepts an optional query string but has no required fields. aegis.agent.search and aegis.workflow.search require a query string. aegis.git.list accepts optional page / limit integers. aegis.git.status, aegis.git.diff and aegis.git.push have no required field: inside a run they take repository, a label of the run's, which a run holding one repository may leave out, and outside a run binding_id (Git Repository Tools). aegis.script.list accepts optional tag and q filter strings.
Refusals and Errors
This section is what the orchestrator's POST /v1/seal/invoke answers when it refuses a tool call or cannot complete it. That is the route an MCP server or an SDK's SEAL client calls. Two other surfaces answer differently:
- An agent's tool call inside its own execution loop is not answered by this route. The model is told the refusal's own sentence in the form "Tool '<name>' was not run: <the refusal>", for example "Tool 'fs_run' was not run: Policy violation: tool 'fs_run' is not allowed; permitted tools: [fs.*, cmd.run]", and reads it in its next step.
- The standalone SEAL Gateway answers its own invocation endpoints with numeric codes; see SEAL Protocol: Error Codes.
How Zaru's MCP server passes these answers on to an MCP client is described in When AEGIS Refuses a Tool Call.
The Error Body
A refused or failed call gets an HTTP status other than 2xx and this body:
{
"protocol": "seal/v1",
"request_id": "3f9c2a71-5b8e-4d0a-9c1e-7a2b6d4e8f10",
"status": "error",
"error": {
"code": "INVALID_ARGUMENTS",
"message": "Invalid tool arguments: required field 'manifest_yaml' is missing or null for tool 'aegis.agent.create'",
"context": null,
"tool": "aegis.agent.create"
}
}| Field | Meaning |
|---|---|
protocol | Always seal/v1. |
request_id | A UUID minted for this refused call. The orchestrator writes one log line for the refusal (log target aegis::seal::invoke) carrying the same request_id, the code and the tool. |
status | policy_violation when the session's security policy or the semantic judge refused the call; error for every other answer. |
error.code | A stable machine code from the table below. Branch on the code, never on the message. |
error.message | A refusal's message is about your own call only: what was refused and why. An internal failure's message is a fixed sentence. |
error.context | Always null. |
error.tool | The tool name your call carried, or null when it carried none. |
error.needs | Present only when the call was refused because you lack a connection or because the profile chosen does not admit the tool: {"family", "page"}. family is mailbox, calendar, a remote server's name (github or carbon-forge) or profile; page is the Zaru Web page that resolves it: /vault/connections for a connection, /vault/profiles/<profile id> for a profile that does not admit the tool, /vault/profiles for a profile that no longer exists. Every other refusal carries none. carbon-forge was formerly named nuclear-notes; the former name is still accepted for at least 90 days from 21 October 2026. |
What request_id is for. It ties the answer you received to the orchestrator's log line for the same call. When you report a failure, quote the request_id: it lets an operator find the log line. For an internal failure, that log line is the only place the detail is kept.
A request body that is not a JSON SEAL envelope at all (not JSON, or missing security_token, signature or payload) is rejected by the HTTP layer before the route runs. It gets a plain-text 4xx and not this body.
The Codes
Session and envelope. Every session condition is answered 401. A client that holds a session attests again on a 401 and sends the call once more. A 403 refuses the call itself, and attesting again does not change it.
| Code | HTTP | What it means | What to do |
|---|---|---|---|
MALFORMED_ENVELOPE | 400 | The envelope lacks protocol or timestamp, or its payload is malformed, for example it names no tool. The message says what is missing or malformed. | Fix the envelope. Sending it again unchanged gets the same answer. |
SIGNATURE_INVALID | 401 | The envelope's signature or the security token did not verify. | Attest again and sign with the new session's key. |
ENVELOPE_REPLAYED | 401 | Replay protection refused the envelope: its timestamp is too old, or its nonce was already seen. | Build a new envelope with a fresh timestamp. Never resend the same bytes. |
SESSION_INACTIVE | 401 | The security token names no active session: it is unknown, revoked or expired. | Attest again. |
SESSION_EXPIRED | 401 | The session has expired. | Attest again. |
OPERATOR_ESCALATION_EXPIRED | 401 | The session was attested under an operator escalation, and that escalation has ended. | The operator tools need a new escalation. |
The session's policy and the judge (status is policy_violation):
| Code | HTTP | What it means | What to do |
|---|---|---|---|
TOOL_NOT_ALLOWED | 403 | The session's security context does not permit the tool. The message lists the tool patterns it does permit. | Use a permitted tool, or a session whose context permits this one. |
TOOL_DENIED | 403 | The security context explicitly denies the tool. | As above. |
PATH_NOT_ALLOWED | 403 | The path is outside the boundaries the context allows. | Use a path inside them. |
PATH_TRAVERSAL | 403 | The path attempts to traverse out of its boundary. | Use a path without traversal. |
DOMAIN_NOT_ALLOWED | 403 | The domain is not on the context's allowed domains, which the message lists. | Use an allowed domain. |
COMMAND_NOT_ALLOWED | 403 | The command is not allowed by the context. | Use an allowed command. |
SUBCOMMAND_NOT_ALLOWED | 403 | The subcommand is not allowed for that command. | Use an allowed subcommand. |
POLICY_ARGUMENT_REQUIRED | 403 | The policy requires an argument the call did not carry. The message names it. | Add the argument. |
LIMIT_EXCEEDED | 403 | The call exceeds one of the context's limits: a timeout, the concurrent execution limit, the output size limit or the execution timeout ceiling. | Stay within the limit the message names. |
RATE_LIMIT_EXCEEDED | 429 | Your rate limit is reached. The message names the limit and the seconds to wait. The answer carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time in seconds). | Wait Retry-After seconds, then call again. |
JUDGE_REJECTED | 403 | The semantic judge configured for the agent rejected the call. The message gives its score, the minimum and its reasoning. | Change the call. The same call is likely to be rejected again. |
CREDENTIAL_BINDING_REQUIRED | 403 | The tool needs your own credential and the call carries none. A run's call, a schedule's included, for a family that neither its profile nor its connections chosen one by one name is answered "This run has no profile that names your <mailbox | calendar | GitHub | Carbon Forge | <server>>. Choose a profile that names it, then start the run again." with error.needs naming the Profiles page; a grant to the agent or workflow does not widen what a run reaches. A call on an API key whose profile, and whose request, name no connection of the family is answered "This key reaches none of your connections. Choose a profile for it on the API keys page in Zaru Web, or name one in the request." with the same needs. A call with no person recorded for the run is refused too. A call acting as you with no run, for a mailbox, a calendar or a remote server you have not connected, is answered "You have not connected <a mailbox | a calendar | GitHub | Carbon Forge | <server>> to Zaru. Connect it on the Connections page in Zaru Web (ask.myzaru.com/vault/connections), then try again." with error.needs. | Connect the account, or choose a profile that names it for the run, schedule or key. |
TOOL_NOT_IN_PROFILE | 403 | The profile chosen does not admit the tool: "This tool is not in the profile chosen for this conversation." for a conversation's call, "This tool is not in the profile chosen for this run." for a run's. The answer carries error.needs naming the profile's page. | Choose another profile, or change the profile. |
CONTEXT_NOT_ALLOWED | 403 | An attestation asked for a security context your identity may not attest. The message names no context. | Attest for a context your identity is entitled to. |
A policy refusal is deterministic: the same call in the same session gets the same answer.
Your own resources and arguments (status is error):
| Code | HTTP | What it means | What to do |
|---|---|---|---|
TENANT_MISMATCH | 403 | The call names a tenant that is not yours. The message names your tenant and the one you named. | Name your own tenant, or none. |
INVALID_ARGUMENTS | 422 | The arguments are not valid. The message says how. A call whose chosen profile no longer exists is answered "Invalid tool arguments: The profile chosen for this run no longer exists." with error.needs {"family": "profile", "page": "/vault/profiles"}. | Correct the arguments. |
QUOTA_EXCEEDED | 422 | You reached one of your own limits: the volume count, storage, your tier's limits, the git binding or script limits, or the file size limit. The message names it. | Free space or resources, or raise your tier. |
NOT_FOUND | 404 | No resource of yours has that name or id: a volume, file, git binding, script, edge, edge group or tool. The message names it as you sent it. A resource of another user or tenant is answered the same way. | Check the name or id. |
CONFLICT | 409 | The call conflicts with the state of your resources: a duplicate name, a volume still attached, nothing to commit, or a busy git binding. | Resolve the conflict the message names. |
NOT_IMPLEMENTED | 501 | The operation is not built yet. The message names it. | Do not retry. |
EDGE_UNAVAILABLE | 503 | Your edge host is offline, missed its dispatch deadline or disconnected. | Bring the edge host back online, then call again. |
CREDENTIAL_REJECTED | 403 | A remote tool server refused your stored credential. The message never carries the credential. | Connect the account again. |
REMOTE_TOOL_ERROR | 422 | A remote tool server refused the call with an error of its own. The message is the server's text, with any echo of the credential removed. | Act on the server's message. |
Internal failures (status is error). The message is the fixed sentence below. The body never carries the failure's detail: no backend path, configuration key, database or upstream error, another tenant's identifier, or the node's tool list. The detail is written only to the orchestrator's log under the answer's request_id.
| Code | HTTP | Message | What to do |
|---|---|---|---|
INTERNAL_ERROR | 500 | "The request could not be completed because of an internal error." | Report the failure with its request_id. |
UPSTREAM_UNAVAILABLE | 503 | "A service this tool depends on did not answer. Try again in a moment." The answer of POST /v1/seal/invoke carries Retry-After: 5. | Call again after Retry-After seconds. |
SERVICE_UNAVAILABLE | 503 | "This tool is not available right now." The tool, or a service it needs, is not configured on this node. | Ask the operator of the deployment; calling again does not help until it is configured. |
CREDENTIAL_CHANNEL_NOT_CONFIDENTIAL | 503 | "This tool is not available right now." A call that would carry a credential found no confidential channel to the SEAL gateway. | Ask the operator of the deployment. |
Filesystem Abstraction Layer (FSAL) Tools
The fs.* tools interact directly with the AegisFSAL (File System Abstraction Layer), meaning they work transparently across SeaweedFS, Local Host storage, and OpenDAL backends. They automatically respect the agent's volume ownership and FilesystemPolicy.
Every fs.* tool answers in the paths the agent sent, never a storage path:
- A path that does not exist: "[AEGIS] '<path>' does not exist; fs.list of its parent lists what does." A caller of
POST /v1/seal/invokegets it asNOT_FOUND(404). - A directory given to
fs.read,fs.edit,fs.multi_editorfs.write: the tool is not run, "[AEGIS] <tool> was not run: <path> is a directory, not a file; fs.list lists a directory."fs.writecreates nothing. - Any other storage failure: "[AEGIS] <tool> of '<path>' failed; the server logged the cause.", answered as an internal failure; the cause is written only to the orchestrator's log.
Writes inside a run's repositories. A workflow's agent state whose run holds repositories writes only inside them: fs.write, fs.edit, fs.multi_edit, fs.create_dir and fs.delete refuse a path outside every repository mount before anything is written, with "'<path>' is outside this run's repository; this step writes only under <mount>" (each mount, /workspace/<label>, named, separated by commas). Reads are not confined, and cmd.run is not covered. An execution whose run holds no repository writes its workspace as before. See Repositories of a Run.
fs.read
Reads the contents of a file, whole or a range of its lines.
Parameters:
path(string, required): Absolute or relative POSIX path of the file to read.line_start(integer, optional, at least 1): First line to return, counted from 1.line_end(integer, optional, at least 1): Last line to return, included.
Returns: Without line_start and line_end, the whole file. With either, the lines from line_start (default 1) to line_end (default the file's last line), followed by a line naming the range and the file's line count, such as "Lines 5 to 8 of 20 in /workspace/notes.txt.", with line_start, line_end and line_count beside the content. A range that runs past the file's end stops at its last line; one that starts after it answers "No lines: the range starts at line <n> and <path> has <count> lines." An empty file reads as its empty content.
Errors: PathOutsideBoundary if path is outside the path_allowlist; the not-found sentence above if the file does not exist; the directory refusal above if the path is a directory; PERMISSION_DENIED if the SecurityContext denies access; invalid arguments for a line number that is not a whole number of 1 or more, or a line_end before line_start.
fs.write
Writes content to a file, creating it if it doesn't exist or overwriting it if it does.
Parameters:
path(string, required): Absolute or relative POSIX path of the file to write to.content(string, required): The string content to write.
Returns: Confirmation string with the path written.
Errors: PathOutsideBoundary if path is outside the allowlist; PERMISSION_DENIED if the SecurityContext denies fs.write; storage backend error if the volume is full.
fs.list
Lists the contents of a directory.
Parameters:
path(string, required): Absolute or relative POSIX path of the directory to list. Defaults to/if not provided.
Returns: A newline-separated list of entry names in the directory, annotated with a trailing / for subdirectories.
Errors: NOT_FOUND if the directory does not exist; PathOutsideBoundary if outside the allowlist.
fs.create_dir
Creates a new directory along with any necessary parent directories.
Parameters:
path(string, required): Absolute or relative POSIX path of the directory to create.
Returns: Confirmation string with the path created.
Errors: PathOutsideBoundary if path is outside the allowlist; ALREADY_EXISTS if the directory already exists (treated as success).
fs.delete
Deletes a file or directory.
Parameters:
path(string, required): Absolute or relative POSIX path of the file or directory to delete.recursive(boolean, optional): Set totrueto delete a directory and all its contents recursively. Default isfalse.
Returns: Confirmation string with the path deleted.
Errors: NOT_FOUND if the path does not exist; PathOutsideBoundary if outside the allowlist; PERMISSION_DENIED if fs.delete is in the SecurityContext deny_list; error if recursive is false and the path is a non-empty directory.
fs.edit
Performs an exact string replacement in a file. The target content must match exactly one occurrence in the file.
Parameters:
path(string, required): Absolute or relative POSIX path of the file to edit.target_content(string, required): Exact string content to find and replace.replacement_content(string, required): New string content to insert. An empty replacement deletes the target, keeping the file's line endings.
Returns: Confirmation string with the path edited and a summary of the change.
Errors: the not-found sentence above if the file does not exist; an empty target_content is not run: "[AEGIS] fs.edit was not run: target_content is empty, and an empty target matches everywhere; the target is the file's existing text that the replacement takes the place of." (fs.multi_edit names the edit: "edit <n> of <m>: …"); error if target_content matches zero or more than one location in the file (must be unique); PathOutsideBoundary if outside the allowlist.
fs.multi_edit
Performs multiple sequential string replacements in a file. Provides a more atomic way to apply several edits at once.
Parameters:
path(string, required): Absolute or relative POSIX path of the file to edit.edits(array of objects, required): Array of edits to apply sequentially. Each object must have:target_content(string, required)replacement_content(string, required)
Returns: Confirmation string with the number of replacements applied.
Errors: Same as fs.edit — any edit that fails (zero or multiple matches) aborts the entire operation and leaves the file unchanged.
fs.search
Searches the files under a folder for a piece of text, plain text and not a pattern, and finds code by its parsed structure. Use it to find where something is; use fs.read to read around a result.
Parameters:
needle(string, required): The text to search for. A needle with no capital letters matches any case.path(string, optional): The folder or file to search. Without it, the run's repository when the run holds exactly one, otherwise/workspace. A repository mounted beneath the folder is searched with it.exact_case(boolean, optional): Match the needle's case exactly, even when it has no capital letter.whole_word(boolean, optional): Match only where the needle is not part of a longer word.file_type(string, optional): Search only files with this extension, such asrs.include_ignored(boolean, optional): Also search what is skipped by default: files a.gitignorenames, build output and dependency folders (target,node_modules,vendor,dist,build,__pycache__,.venv,venv), lock files and minified or map files..gitis always skipped.
Returns: A first line of counts, "Searched <root> for "<needle>" in exact case: <n> lines in <m> files; <k> files read." (or "in any case"), or "…: no line holds it; <k> files read." when nothing matches. Then the matching lines grouped by file and ranked (declarations, then source, then tests, then generated files): at most 40 lines of at most 200 characters, up to 8 per file first, then up to 10 more file names, and a closing line counting what was not shown and what was skipped. A needle of two or more words also answers up to 8 declarations whose names or comments share those words, each with its path, line, kind, name and an excerpt; camelCase, snake_case and spaced forms of the words find the same declaration. Every path is container-absolute, one fs.read takes as written. The answer is at most 30,720 bytes, and the same call on the same files answers the same bytes.
Limits: at most 10,000 files are read, and the answer says where the walk stopped; a file over 10 MiB, a binary file and a file that is not UTF-8 are skipped and counted. Nothing is stored between calls.
Errors: an empty needle is refused: "the string to search for is empty, which occurs everywhere in every file; fs.search needs something to look for"; a path under a volume not registered for the execution is refused; PathOutsideBoundary if outside the allowlist.
fs.grep
Recursively searches for a regex pattern within files in a given directory. Uses the AegisFSAL to traverse the directory structure.
Parameters:
pattern(string, required): Regex pattern to search for.path(string, required): Directory path to start the recursive search from.
Returns: A formatted list of matches, each showing the file path, line number, and the matching line.
Errors: PathOutsideBoundary if outside the allowlist; error if the regex pattern is invalid.
fs.glob
Recursively matches files against a glob pattern.
Parameters:
pattern(string, required): Glob pattern to match files (e.g.,*.rs,src/**/*.ts).path(string, required): Directory path to start the recursive search from.
Returns: A newline-separated list of matching file paths relative to path.
Errors: PathOutsideBoundary if outside the allowlist; empty result (not an error) if no files match.
Web Tools
The web.* tools provide native HTTP request and web search capabilities.
web.search
Performs an internet search query using the Brave Search REST API. This is a native builtin — no external MCP server process is required.
Requires configuration: An API key must be set via the api_key field on the web.search entry in spec.builtin_dispatchers. See Configuring Tools — Enabling web.search for setup instructions.
Free tier: 2,000 requests/month.
Parameters:
query(string, required): The search query.max_results(integer, optional): Maximum number of results to return. Default is10.
Returns: A formatted list of search results, each containing title, URL, and snippet text.
Errors:
- Configuration error if
api_keyis not set:web.search is not configured: add api_key to the web.search entry in spec.builtin_dispatchers DomainNotAllowedif the SecurityContext'sdomain_allowlistdoes not permit the Brave Search API domain- Network error if the external request fails
web.fetch
Fetches content from a URL, optionally converting HTML pages into clean Markdown.
Parameters:
url(string, required): URL to fetch content from. Must start withhttp://orhttps://.to_markdown(boolean, optional): Convert HTML to markdown. Default istrue.follow_redirects(boolean, optional): Whether to follow HTTP redirects. Default istrue.timeout_secs(integer, optional): Request timeout in seconds. Default is30.offset(integer ≥ 0, optional): Character position in the page to start from. Default is0. An offset at or past the end of the page is refused.
Returns: The response body in the result's content (Markdown if to_markdown is true and the response is HTML, otherwise raw text/JSON).
Long pages: one call returns at most 50,000 characters of the page. When the page is longer, the result's content holds characters offset to offset + 50,000, and the result adds truncated: true, total_chars (the page's whole length), offset, next_offset and a notice; call web.fetch again with the same url and offset set to next_offset to read on. The last part carries truncated: false and no next_offset. A page within the bound comes back unchanged.
Errors: DomainNotAllowed if the URL domain is not in the SecurityContext allowlist; network or timeout error if the remote server is unreachable; error if the response status is 4xx/5xx.
Mail Tools
The mail.* tools read, sort and send the person's own mail over IMAP and SMTP, inside the orchestrator: a mailbox connection's password or OAuth token never reaches an agent. Every tool names its mailbox by mailbox, the id of one of the caller's own active mailbox connections. They work by message uid; bodies are read without marking anything read.
Which mailboxes a call may use. A tool acts for the call's person; a service account is refused. When the run or conversation has chosen mailboxes (its connections, or a profile holding a mailbox), mailbox must be one of them: "This tool needs your own mailbox, and the one named is not among those chosen for this run."; when it chose none: "This tool needs your own mailbox, and none was chosen for this run." A run that chose no mailbox, by its profile or one by one, reaches none, whatever is granted to its agent or workflow: "This run has no profile that names your mailbox. Choose a profile that names it, then start the run again." A conversation in Zaru Web that chose nothing is admitted on ownership alone; a call on an API key reaches only the mailboxes its profile, or its request, names. mailbox may be left out when the person has one mailbox connected: a call acting as the person outside a run then uses their own, and the answer names it in mailbox_name (What a key reaches); with no mailbox connected the call is refused with the sentence naming the Connections page. Inside a run, a call without mailbox uses the one mailbox the run chose, else the newest of those it chose. In Zaru, a conversation is offered the mail tools when a mailbox, or a profile holding one, is chosen in its context selector.
Folders. mail.list, mail.read, mail.attachment and mail.forward take folder: inbox (the default), sent, drafts, trash, archive or all, each found by the server's own marking of that folder; one folder per call, since uids are per folder. mail.label, mail.reply, mail.delete and mail.archive work on threads in the inbox and refuse another folder: "This tool works on threads in the inbox only; leave out 'folder' or set it to inbox." A thread is found by its messages' Message-ID, In-Reply-To and References.
| Tool | Required | Waits for approval | What it does |
|---|---|---|---|
mail.list | mailbox | No | Lists threads in one folder that match query, from, unread_only, flagged_only and since (YYYY-MM-DD), newest first, limit 1 to 50 (default 20): each thread's id, subject, participants, latest date, message count, unread count, flag and labels. |
mail.read | mailbox, thread_id | No | Reads every message of a thread in one folder, oldest first: uid, headers, flags, labels, plain-text body and attachments, each by name, type, size and part. |
mail.attachment | mailbox, uid, part | No | Saves one attachment to the person's own files (their chat-attachments volume), answering its volume, path, name, type, size and SHA-256, and the text of a short text attachment. An attachment over 20 MiB, or larger than the person's files allow, is refused with nothing written. |
mail.label | mailbox, thread_id | No | Adds or removes labels (add, remove), flags or unflags (flagged) and marks read or unread (seen) every message of a thread. A label the server does not keep is refused with nothing changed. |
mail.draft | mailbox, body | No | Saves a plain-text message in the Drafts folder, optionally as a reply in a thread. Sends nothing. |
mail.send | mailbox, to, subject, body | Yes | Sends a plain-text message to to and cc (at most 50 recipients), then saves a copy in Sent. |
mail.reply | mailbox, thread_id, to, subject, body | Yes | Replies to a thread's newest inbox message, threaded to it, then saves a copy in Sent. |
mail.forward | mailbox, thread_id, to | Yes | Forwards a thread from one folder, or one message of it by message_uid: each message attached whole as it arrived, after an optional plain-text note, to to and cc, then saves a copy in Sent. At most 20 messages and 20 MiB. Without subject, the subject is "Fwd:" and the oldest message's subject. |
mail.archive | mailbox, thread_id | Yes | Moves every inbox message of a thread to the Archive folder (on a server that keeps all mail in one folder, out of the inbox). Deletes nothing. |
mail.delete | mailbox, thread_id | Yes | Moves every inbox message of a thread to Trash. Deletes nothing permanently. |
Attaching the person's files. mail.send, mail.reply and mail.forward take attachments: up to 10 of the person's own files, 20 MiB together, each by volume_id and path (an uploaded file's reference, or one mail.attachment saved). The approval shows each file's name and size, and a file changed after the approval is not sent: "A file to attach changed after it was approved; nothing was sent."
What the approval shows. A call that waits for approval is summarised from its own arguments: the recipients, subject and text of a send or reply; for a forward, the recipients, subject, note and each forwarded message's sender, subject and date; for an archive or delete, the thread's subject and senders. A forward sends only the messages read for it before it was approved: a message that left the folder since is refused with "A message to forward is no longer in this folder; nothing was sent."
Dispatch Protocol Tools
These tools map to the AEGIS Dispatch Protocol, meaning the orchestrator intercepts the tool call and fulfills it by injecting execution commands into the agent's isolation boundary (e.g., Docker container).
cmd.run
Executes a shell command within the agent's containerized workspace. Subject to the agent's subcommand_allowlist policy and the node's builtin_dispatchers.cmd resource ceilings.
Parameters:
command(string, required): The base shell command to execute (e.g.,"cargo","git","npm").args(array of strings, optional): Positional arguments passed to the command (e.g.,["build"],["status"]).env_additions(object of strings, optional): Environment variables added for this command.stdin(string, optional): Text written to the command's standard input, which is then closed; at mostmax_output_bytesbytes.cwd(string, optional): The directory the command runs in, such as/workspace/app;/workspacewhen absent.timeout_secs(integer, optional): Seconds the command may run before it is stopped; 600 when absent.max_output_bytes(integer, optional): The most bytes of output kept from the command; 1048576 when absent.
The tool's schema declares each of these. A call naming any other argument is refused, each such argument named, with "its arguments are command, args, cwd, env_additions, stdin, timeout_secs and max_output_bytes, and the directory a command runs in is cwd (/workspace when absent)"; nothing runs.
env_additions(object of strings, optional): Environment variables added for this command.stdin(string, optional): Text written to the command's standard input, which is then closed; at mostmax_output_bytesbytes.cwd(string, optional): The directory the command runs in, such as/workspace/app;/workspacewhen absent.timeout_secs(integer, optional): Seconds the command may run before it is stopped; 600 when absent.max_output_bytes(integer, optional): The most bytes of output kept from the command; 1048576 when absent.
The tool's schema declares each of these. A call naming any other argument is refused, each such argument named, with "its arguments are command, args, cwd, env_additions, stdin, timeout_secs and max_output_bytes, and the directory a command runs in is cwd (/workspace when absent)"; nothing runs.
Returns: An object containing stdout (string), stderr (string), and exit_code (integer). A non-zero exit_code is returned as a successful tool result — the agent's LLM receives all three fields and can interpret the failure.
Subcommand Policy:
Every cmd.run call is validated against the subcommand_allowlist. This allowlist ensures that agents can only execute approved base commands and specific subcommands (the first positional argument).
# Manifest Example
tools:
- name: cmd
executor: "builtin:cmd"
config:
subcommand_allowlist:
git: [clone, add, commit, push, status]
cargo: [build, test, fmt, clippy]A call like cmd.run(command="cargo", args=["build"]) is permitted, while cmd.run(command="cargo", args=["publish"]) would be rejected with SubcommandNotAllowed.
Errors:
ToolNotAllowed: Thecmdtool is not in the agent'sspec.toolslist.CommandNotAllowed: The base command is not present in thesubcommand_allowlist.SubcommandNotAllowed: The first positional argument is not in the allowed list for that base command.OutputSizeLimitExceeded: The combinedstdoutandstderrexceeded themax_output_byteslimit (default 512 KB).ExecTimeoutCeilingExceeded: The execution exceeded thetimeout_ceiling_secs.
Edge Fleet Tools (System Tier)
Three system-tier tools handle multi-host fleet operations against user-installed edge daemons. They are gated by an operator/tenant-admin SecurityContext and surface in operator-mode conversations and the Zaru Fleet Launcher.
aegis.edge.fleet.invoke
Invoke any registered tool against an EdgeTarget (Node / Group / Selector / All) with a FleetDispatchPolicy. Per-node CommandProgress chunks stream back tagged with node_id; the terminal payload is a FleetExecutionResult carrying targets_resolved, targets_skipped, per_node, and a summary.
The dispatch policy controls fan-out:
- Mode:
Sequential,Parallel, orRolling { batch }. - Failure policy:
FailFast,ContinueOnError, orStopAfter(N). require_min_targets: refuses upfront if fewer matches resolve.per_target_deadline_secs: propagated to each daemon asEdgeCommand.deadline.
Tool descriptors carry a fleet_capable: bool flag — tools that are inherently single-target refuse multi-target dispatch even when the caller tries to fan them out.
aegis.edge.fleet.list
Resolve an EdgeTarget to a node list without dispatching. Operationally critical before destructive fan-outs — Zaru's selector preview panel is built on this tool.
aegis.edge.fleet.cancel
Broadcast Cancel { command_id } to every in-flight per-node command in a fleet operation, addressed by fleet_command_id. Already-completed nodes are unaffected.
For the full fleet model, see fleet operations; for the REST shape, see edge REST API.