Aegis Orchestrator
Reference

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:

  1. Execution Tools: Tools like fs.*, web.*, and cmd.run that agents use to perform their tasks. (Documented on this page)
  2. Management Tools: Tools like aegis.agent.* and aegis.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:

Toolskip_judge defaultRationale
cmd.runfalseState-mutating — subprocess output must be validated
fs.readtrueRead-only
fs.writefalseState-mutating
fs.listtrueRead-only
fs.searchtrueRead-only
fs.greptrueRead-only
fs.globtrueRead-only
fs.editfalseState-mutating
fs.multi_editfalseState-mutating
fs.create_dirfalseState-mutating
fs.deletefalseState-mutating — destructive
web.searchtrueRead-only external lookup
web.fetchtrueRead-only HTTP fetch
aegis.agent.listtrueRead-only registry lookup
aegis.agent.searchtrueRead-only semantic search
aegis.workflow.listtrueRead-only registry lookup
aegis.workflow.searchtrueRead-only semantic search
aegis.schema.gettrueRead-only schema lookup
aegis.schema.validatetrueRead-only validation
aegis.agent.exporttrueRead-only manifest lookup
aegis.workflow.exporttrueRead-only manifest lookup
aegis.agent.createtrueManifest 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.updatetrueManifest 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.deletetrueManifest registry operation — the tool does not execute code and the registry-write path has its own validation
aegis.agent.generatefalseCreates 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.createtrueManifest 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.updatetrueManifest 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.deletefalseDestructive — removes workflow from registry
aegis.workflow.runfalseExecution trigger — spawns a workflow run
aegis.workflow.generatefalseCreates new workflow via inner authoring loop
aegis.workflow.executions.listtrueRead-only workflow execution listing
aegis.task.executefalseExecution trigger — spawns an agent execution
aegis.task.statustrueRead-only execution status query
aegis.task.waittrueRead-only blocking poll until terminal state
aegis.task.listtrueRead-only execution listing
aegis.task.logstrueRead-only execution log query
aegis.execution.filetrueRead-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.logstrueRead-only execution log query
aegis.workflow.executions.gettrueRead-only execution detail query
aegis.workflow.statustrueRead-only execution status query
aegis.task.cancelfalseState-mutating — terminates a running execution
aegis.task.removefalseDestructive — deletes an execution record
aegis.agent.logstrueRead-only agent activity log query
aegis.agent.waittrueAlias for aegis.task.wait
aegis.workflow.waittrueRead-only blocking poll until terminal state
aegis.execute.waittrueAlias for aegis.workflow.wait
aegis.workflow.canceltrueRead-query against execution state — cancellation is a state transition request, not a code execution
aegis.workflow.signaltrueState-signal delivery to paused execution — not an execution tool invocation
aegis.workflow.removetrueRegistry delete of a terminal execution record — no semantic execution risk
aegis.workflow.validatetrueRead-only schema validation — parses and deterministically validates YAML but deploys nothing
aegis.workflow.promotefalseScope elevation — changes workflow visibility; not skip_judge by default
aegis.workflow.demotefalseScope reduction — changes workflow visibility; not skip_judge by default
aegis.execute.intentfalseExecution trigger — spawns intent-to-execution pipeline
aegis.execute.statustrueRead-only pipeline status query
aegis.tools.listtrueRead-only tool discovery
aegis.tools.searchtrueRead-only tool search
aegis.system.infotrueRead-only node status query
aegis.system.configtrueRead-only configuration access
aegis.runtime.listtrueRead-only runtime listing
aegis.file.listtrueRead-only volume directory listing
aegis.file.readtrueRead-only file content read
aegis.file.writefalseState-mutating — writes file content in a user volume
aegis.file.deletefalseDestructive — removes a file or directory from a user volume
aegis.file.mkdirfalseState-mutating — creates a directory in a user volume
aegis.volume.createfalseState-mutating — provisions a new persistent volume
aegis.volume.listtrueRead-only volume listing
aegis.volume.deletefalseDestructive — deletes a volume and all contents
aegis.volume.quotatrueRead-only quota usage lookup
aegis.git.clonefalseState-mutating — creates a binding and triggers clone
aegis.git.listtrueRead-only binding listing
aegis.git.statustrueRead-only clone/refresh status lookup
aegis.git.refreshfalseState-mutating — fetches and checks out the pinned ref
aegis.git.deletefalseDestructive — soft-deletes binding and cascades to volume
aegis.git.commitfalseState-mutating — stages and commits workdir changes
aegis.git.pushfalseState-mutating — pushes commits to the remote
aegis.git.landfalseState-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.difftrueRead-only unified diff of workdir or index
aegis.script.savefalseState-mutating — persists a new TypeScript program
aegis.script.listtrueRead-only script listing
aegis.script.gettrueRead-only script fetch with version history
aegis.script.updatefalseState-mutating — updates a script and bumps its version
aegis.script.deletefalseDestructive — 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:

ToolRequired parameters
aegis.executeprompt
aegis.execute.intentintent
aegis.execute.statuspipeline_execution_id
aegis.agent.create, aegis.agent.updatemanifest_yaml
aegis.agent.exportname
aegis.agent.delete, aegis.task.executeagent_id
aegis.agent.search, aegis.workflow.searchquery
aegis.agent.generate, aegis.workflow.generateinput
aegis.workflow.create, aegis.workflow.updatemanifest_yaml
aegis.workflow.export, aegis.workflow.delete, aegis.workflow.runname
aegis.workflow.logs, aegis.task.logsexecution_id
aegis.workflow.status, aegis.workflow.executions.getexecution_id
aegis.task.status, aegis.task.wait, aegis.agent.wait, aegis.task.cancel, aegis.task.removeexecution_id
aegis.execution.filepath; execution_id unless volume_id
aegis.workflow.cancel, aegis.workflow.wait, aegis.execute.wait, aegis.workflow.removeexecution_id
aegis.workflow.signalexecution_id, response
aegis.agent.logsagent_id
aegis.schema.getkey
aegis.schema.validatekind, manifest_yaml
cmd.runcommand (must be a non-empty string)
fs.read, fs.list, fs.create_dir, fs.deletepath
fs.writepath, content
fs.editpath, target_content, replacement_content
fs.multi_editpath, edits
fs.searchneedle
fs.grep, fs.globpattern, path
web.searchquery
web.fetchurl
aegis.file.list, aegis.file.read, aegis.file.delete, aegis.file.mkdirvolume_id, path
aegis.file.writevolume_id, path, content
aegis.volume.createlabel, size_limit_bytes
aegis.volume.deletevolume_id
aegis.git.clonerepo_url, label
aegis.git.refresh, aegis.git.deletebinding_id
aegis.git.commitmessage
aegis.script.savename, code
aegis.script.get, aegis.script.deleteid
aegis.script.updateid, 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"
  }
}
FieldMeaning
protocolAlways seal/v1.
request_idA 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.
statuspolicy_violation when the session's security policy or the semantic judge refused the call; error for every other answer.
error.codeA stable machine code from the table below. Branch on the code, never on the message.
error.messageA refusal's message is about your own call only: what was refused and why. An internal failure's message is a fixed sentence.
error.contextAlways null.
error.toolThe tool name your call carried, or null when it carried none.
error.needsPresent 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.

CodeHTTPWhat it meansWhat to do
MALFORMED_ENVELOPE400The 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_INVALID401The envelope's signature or the security token did not verify.Attest again and sign with the new session's key.
ENVELOPE_REPLAYED401Replay 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_INACTIVE401The security token names no active session: it is unknown, revoked or expired.Attest again.
SESSION_EXPIRED401The session has expired.Attest again.
OPERATOR_ESCALATION_EXPIRED401The 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):

CodeHTTPWhat it meansWhat to do
TOOL_NOT_ALLOWED403The 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_DENIED403The security context explicitly denies the tool.As above.
PATH_NOT_ALLOWED403The path is outside the boundaries the context allows.Use a path inside them.
PATH_TRAVERSAL403The path attempts to traverse out of its boundary.Use a path without traversal.
DOMAIN_NOT_ALLOWED403The domain is not on the context's allowed domains, which the message lists.Use an allowed domain.
COMMAND_NOT_ALLOWED403The command is not allowed by the context.Use an allowed command.
SUBCOMMAND_NOT_ALLOWED403The subcommand is not allowed for that command.Use an allowed subcommand.
POLICY_ARGUMENT_REQUIRED403The policy requires an argument the call did not carry. The message names it.Add the argument.
LIMIT_EXCEEDED403The 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_EXCEEDED429Your 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_REJECTED403The 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_REQUIRED403The 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_PROFILE403The 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_ALLOWED403An 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):

CodeHTTPWhat it meansWhat to do
TENANT_MISMATCH403The 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_ARGUMENTS422The 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_EXCEEDED422You 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_FOUND404No 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.
CONFLICT409The 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_IMPLEMENTED501The operation is not built yet. The message names it.Do not retry.
EDGE_UNAVAILABLE503Your edge host is offline, missed its dispatch deadline or disconnected.Bring the edge host back online, then call again.
CREDENTIAL_REJECTED403A remote tool server refused your stored credential. The message never carries the credential.Connect the account again.
REMOTE_TOOL_ERROR422A 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.

CodeHTTPMessageWhat to do
INTERNAL_ERROR500"The request could not be completed because of an internal error."Report the failure with its request_id.
UPSTREAM_UNAVAILABLE503"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_UNAVAILABLE503"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_CONFIDENTIAL503"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/invoke gets it as NOT_FOUND (404).
  • A directory given to fs.read, fs.edit, fs.multi_edit or fs.write: the tool is not run, "[AEGIS] <tool> was not run: <path> is a directory, not a file; fs.list lists a directory." fs.write creates 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 to true to delete a directory and all its contents recursively. Default is false.

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 as rs.
  • include_ignored (boolean, optional): Also search what is skipped by default: files a .gitignore names, build output and dependency folders (target, node_modules, vendor, dist, build, __pycache__, .venv, venv), lock files and minified or map files. .git is 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 is 10.

Returns: A formatted list of search results, each containing title, URL, and snippet text.

Errors:

  • Configuration error if api_key is not set: web.search is not configured: add api_key to the web.search entry in spec.builtin_dispatchers
  • DomainNotAllowed if the SecurityContext's domain_allowlist does 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 with http:// or https://.
  • to_markdown (boolean, optional): Convert HTML to markdown. Default is true.
  • follow_redirects (boolean, optional): Whether to follow HTTP redirects. Default is true.
  • timeout_secs (integer, optional): Request timeout in seconds. Default is 30.
  • offset (integer ≥ 0, optional): Character position in the page to start from. Default is 0. 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.

ToolRequiredWaits for approvalWhat it does
mail.listmailboxNoLists 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.readmailbox, thread_idNoReads 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.attachmentmailbox, uid, partNoSaves 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.labelmailbox, thread_idNoAdds 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.draftmailbox, bodyNoSaves a plain-text message in the Drafts folder, optionally as a reply in a thread. Sends nothing.
mail.sendmailbox, to, subject, bodyYesSends a plain-text message to to and cc (at most 50 recipients), then saves a copy in Sent.
mail.replymailbox, thread_id, to, subject, bodyYesReplies to a thread's newest inbox message, threaded to it, then saves a copy in Sent.
mail.forwardmailbox, thread_id, toYesForwards 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.archivemailbox, thread_idYesMoves 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.deletemailbox, thread_idYesMoves 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 most max_output_bytes bytes.
  • cwd (string, optional): The directory the command runs in, such as /workspace/app; /workspace when 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 most max_output_bytes bytes.
  • cwd (string, optional): The directory the command runs in, such as /workspace/app; /workspace when 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: The cmd tool is not in the agent's spec.tools list.
  • CommandNotAllowed: The base command is not present in the subcommand_allowlist.
  • SubcommandNotAllowed: The first positional argument is not in the allowed list for that base command.
  • OutputSizeLimitExceeded: The combined stdout and stderr exceeded the max_output_bytes limit (default 512 KB).
  • ExecTimeoutCeilingExceeded: The execution exceeded the timeout_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, or Rolling { batch }.
  • Failure policy: FailFast, ContinueOnError, or StopAfter(N).
  • require_min_targets: refuses upfront if fewer matches resolve.
  • per_target_deadline_secs: propagated to each daemon as EdgeCommand.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.

On this page