MCP Tool Reference

This page is the authoritative schema reference for all AEGIS MCP tools. For the skip_judge policy and inner-loop judge optimization, see Built-in Tools. For usage patterns and examples, see Management Tools.

Tool count: 86 total — 83 built-in orchestrator tools + 3 Zaru client tools (zaru.init, zaru.mode, zaru.docs).

Tool Access Tiers

AEGIS tools are divided into three access tiers. The tier determines which callers may invoke a tool.

User tools — available to all agents and Zaru users: fs.read, fs.write, fs.list, fs.create_dir, fs.delete, fs.edit, fs.multi_edit, fs.grep, fs.glob, web.search, web.fetch, cmd.run, aegis.agent.list, aegis.agent.export, aegis.agent.generate, aegis.agent.logs, aegis.agent.search, aegis.agent.wait, aegis.workflow.list, aegis.workflow.validate, aegis.workflow.export, aegis.workflow.run, aegis.workflow.generate, aegis.workflow.logs, aegis.workflow.wait, aegis.workflow.cancel, aegis.workflow.signal, aegis.workflow.executions.list, aegis.workflow.executions.get, aegis.workflow.status, aegis.workflow.search, aegis.task.execute, aegis.task.status, aegis.task.list, aegis.task.cancel, aegis.task.logs, aegis.task.wait, aegis.execute.intent, aegis.execute.status, aegis.execution.file, aegis.execute.wait, aegis.tools.list, aegis.tools.search, aegis.schema.get, aegis.schema.validate, aegis.runtime.list, aegis.file.list, aegis.file.read, aegis.file.write, aegis.file.delete, aegis.file.mkdir, aegis.volume.create, aegis.volume.list, aegis.volume.delete, aegis.volume.quota, aegis.git.clone, aegis.git.list, aegis.git.status, aegis.git.refresh, aegis.git.delete, aegis.git.commit, aegis.git.push, aegis.git.diff, aegis.script.save, aegis.script.list, aegis.script.get, aegis.script.update, aegis.script.delete, zaru.init, zaru.mode, zaru.docs

System tools — only available to agents with security_context: aegis-system-agent-runtime registered by platform operators: aegis.agent.create, aegis.agent.update, aegis.workflow.create, aegis.workflow.update, aegis.workflow.promote, aegis.workflow.demote

Operator-only tools — only available via operator SEAL sessions: aegis.agent.delete, aegis.workflow.delete, aegis.workflow.remove, aegis.task.remove, aegis.system.info, aegis.system.config

Tool Availability by Context

AEGIS tools are available across three distinct execution contexts. The tool set exposed to a caller varies by context.

See Tool Routing Architecture for the full routing pipeline.

Zaru Conversation Mode Tool Sets

Chat Mode

Only zaru.init, zaru.mode, and zaru.docs are exposed. The model cannot invoke any orchestrator tools directly from chat mode.

Agentic Mode

• zaru.init
• zaru.mode
• zaru.docs
• aegis.agent.generate
• aegis.agent.wait
• aegis.agent.list
• aegis.agent.logs
• aegis.task.execute
• aegis.task.wait
• aegis.task.list
• aegis.task.logs
• aegis.task.cancel
• aegis.execution.file
• aegis.tools.list
• aegis.tools.search

Execute Mode

• zaru.init
• zaru.mode
• zaru.docs
• aegis.execute.intent
• aegis.execute.status
• aegis.execute.wait
• aegis.execution.file
• aegis.workflow.wait

Architect Mode

• zaru.init
• zaru.mode
• zaru.docs
• aegis.workflow.generate
• aegis.workflow.list
• aegis.workflow.logs
• aegis.agent.generate
• aegis.agent.wait
• aegis.agent.list
• aegis.agent.logs
• aegis.schema.get
• aegis.schema.validate
• aegis.task.execute
• aegis.task.wait
• aegis.execution.file
• aegis.workflow.wait

Operator Mode

All 86 tools are available — no filtering is applied.

Quick-Reference Table

Zaru mode abbreviations: C = chat, Ag = agentic, Ex = execute, Ar = architect, Op = operator. Operator always has full access; only additional modes are listed per tool.

Filesystem Tools (fs.*)

Interact with the agent's mounted Workspace volume via the FSAL layer. All paths must be within the agent's path_allowlist. Absolute POSIX paths are recommended.

fs.read

Read the contents of a file at the given POSIX path from the mounted Workspace volume.

Access: User

skip_judge: true

Output:

{
  "status": "success",
  "path": "/workspace/src/main.rs",
  "content": "...",
  "size_bytes": 1024
}

fs.write

Write content to a file at the given POSIX path in the Workspace volume. Automatically creates missing parent directories.

Access: User

skip_judge: false

Output:

{
  "status": "success",
  "path": "/workspace/src/main.rs",
  "bytes_written": 1024
}

fs.list

List the contents of a directory in the Workspace volume.

Access: User

skip_judge: true

Output:

{
  "status": "success",
  "path": "/workspace/src",
  "entries": [
    { "name": "main.rs", "file_type": "file" },
    { "name": "lib", "file_type": "directory" }
  ]
}

Each entry has a file_type of either "file" or "directory".

fs.create_dir

Creates a new directory along with any necessary parent directories.

Access: User

skip_judge: false

Output:

{
  "status": "success",
  "path": "/workspace/output/reports"
}

fs.delete

Deletes a file or directory.

Access: User

skip_judge: false

Output:

{
  "status": "success",
  "path": "/workspace/tmp/cache"
}

fs.edit

Performs an exact string replacement in a file.

Access: User

skip_judge: false

Output:

{
  "status": "success",
  "path": "/workspace/src/main.rs",
  "message": "File edited successfully"
}

fs.multi_edit

Performs multiple sequential string replacements in a file.

Access: User

skip_judge: false

Output:

{
  "status": "success",
  "path": "/workspace/src/main.rs",
  "applied": 3
}

The applied field is the count of replacements successfully performed.

fs.grep

Recursively searches for a regex pattern within files in a given directory.

Access: User

skip_judge: true

Output: Formatted string of matches, one per line in path:line_number:content format.

fs.glob

Recursively matches files against a glob pattern.

Access: User

skip_judge: true

Output: Newline-separated list of matching file paths.

Web Tools (web.*)

Access external URLs and perform internet searches. These tools are subject to the agent's network_profile and any egress restrictions configured at the node level.

web.search

Performs an internet search query.

Access: User

skip_judge: true

Output: Formatted list of results, each containing title, URL, and snippet text.

web.fetch

Fetches content from a URL, optionally converting HTML to Markdown.

Access: User

skip_judge: true

Output: Response body as a string. HTML responses are converted to Markdown when the to_markdown conversion option is in effect.

Dispatch Protocol Tool (cmd.run)

cmd.run is routed via the Dispatch Protocol — not the FSAL layer. Commands execute inside the agent's ephemeral container. To expose cmd.run to an agent, the agent manifest must declare a subcommand_allowlist under spec.builtin_dispatchers:

spec:
  builtin_dispatchers:
    - name: cmd
      capabilities:
        - name: cmd.run
          subcommand_allowlist:
            - "python"
            - "pip"
            - "bash"

Only commands whose first token appears in subcommand_allowlist will be permitted.

cmd.run

Executes a shell command inside the agent's ephemeral container environment. Use this to build, run, or analyze code locally.

Access: User

skip_judge: false

Output:

{
  "stdout": "Hello, world!\n",
  "stderr": "",
  "exit_code": 0
}

Agent Management Tools (aegis.agent.*)

These tools manage the agent registry: creating, reading, updating, deleting, and searching agent definitions. For task execution (running agents), see Task Management Tools.

aegis.agent.create

Parses, validates, and deploys an Agent manifest to the registry.

Access: System

skip_judge: true

Output:

{
  "agent_id": "a1b2c3d4-...",
  "deployed": true,
  "name": "my-agent",
  "version": "1.0.0"
}

aegis.agent.list

Lists currently deployed agents and metadata.

Access: User

skip_judge: true

No parameters — accepts an empty object {}.

Output:

{
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "my-agent",
      "version": "1.0.0",
      "status": "active",
      "description": "...",
      "labels": {}
    }
  ]
}

aegis.agent.update

Updates an existing Agent manifest in the registry.

Access: System

skip_judge: true

Output:

{
  "agent_id": "a1b2c3d4-...",
  "deployed": true,
  "name": "my-agent",
  "version": "1.0.1"
}

aegis.agent.export

Exports an Agent manifest by name.

Access: User

skip_judge: true

Output:

{
  "manifest_yaml": "kind: Agent\n...",
  "id": "a1b2c3d4-...",
  "name": "my-agent",
  "version": "1.0.0"
}

aegis.agent.delete

Removes a deployed agent from the registry by UUID.

Access: Operator

skip_judge: true

Output:

{
  "agent_id": "a1b2c3d4-...",
  "deleted": true
}

aegis.agent.generate

Generates an Agent manifest from a natural-language intent.

Access: User

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "started"
}

aegis.agent.logs

Retrieve agent-level activity log snapshot.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.agent.logs",
  "agent_id": "a1b2c3d4-...",
  "events": [
    {
      "event_type": "task_started",
      "payload": {},
      "recorded_at": "2026-04-05T12:00:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

aegis.agent.search

Semantic search over deployed agents by natural-language query.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.agent.search",
  "query": "image resizer",
  "results": [
    {
      "id": "a1b2c3d4-...",
      "name": "image-resizer",
      "version": "1.0.0",
      "description": "...",
      "labels": {},
      "score": 0.92
    }
  ],
  "total": 5
}

aegis.agent.wait

Alias for aegis.task.wait. Blocks until an agent execution completes.

Access: User

skip_judge: true

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "completed",
  "iteration_count": 3,
  "last_output": "...",
  "last_error": null,
  "started_at": "2026-04-05T12:00:00Z",
  "ended_at": "2026-04-05T12:01:30Z"
}

The status field will be one of completed, failed, cancelled, or timed_out.

Workflow Management Tools (aegis.workflow.*)

These tools manage the workflow registry and control workflow execution lifecycle. For workflow authoring and schema, see the Workflow Manifest Reference.

aegis.workflow.create

Performs strict deterministic and semantic workflow validation, then registers on pass.

Access: System

skip_judge: true

Output:

{
  "workflow_id": "w1b2c3d4-...",
  "deployed": true,
  "name": "my-workflow",
  "version": "1.0.0"
}

aegis.workflow.list

Lists currently registered workflows and metadata.

Access: User

skip_judge: true

Output:

{
  "workflows": [
    {
      "id": "w1b2c3d4-...",
      "name": "my-workflow",
      "version": "1.0.0",
      "initial_state": "start"
    }
  ]
}

aegis.workflow.validate

Validate a workflow manifest against the schema.

Access: User

skip_judge: true

Output:

{
  "valid": true,
  "errors": null
}

On failure: { "valid": false, "errors": ["error message 1", "error message 2"] }

aegis.workflow.update

Updates an existing Workflow manifest in the registry.

Access: System

skip_judge: true

Output:

{
  "workflow_id": "w1b2c3d4-...",
  "deployed": true,
  "name": "my-workflow",
  "version": "1.0.1"
}

aegis.workflow.export

Exports a Workflow manifest by name.

Access: User

skip_judge: true

Output:

{
  "manifest_yaml": "kind: Workflow\n...",
  "id": "w1b2c3d4-...",
  "name": "my-workflow",
  "version": "1.0.0"
}

aegis.workflow.delete

Removes a registered workflow from the registry by name.

Access: Operator

skip_judge: false

Output:

{
  "workflow_id": "w1b2c3d4-...",
  "deleted": true
}

aegis.workflow.run

Executes a registered workflow by name with optional input parameters.

Access: User

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "started"
}

Use aegis.workflow.wait to block until completion.

aegis.workflow.generate

Generates a Workflow manifest from a natural-language objective.

Access: User

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "started"
}

aegis.workflow.logs

Returns paginated workflow execution events.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.workflow.logs",
  "execution_id": "e1f2a3b4-...",
  "status": "running",
  "events": [
    {
      "sequence": 1,
      "event_type": "state_entered",
      "state_name": "start",
      "iteration_number": null,
      "payload": {},
      "recorded_at": "2026-04-05T12:00:00Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

aegis.workflow.wait

Polls a workflow execution until it reaches a terminal state and returns the result.

Access: User

skip_judge: true

Output (completed):

{
  "execution_id": "e1f2a3b4-...",
  "workflow_id": "w1b2c3d4-...",
  "status": "completed",
  "current_state": "end",
  "blackboard": {},
  "started_at": "2026-04-05T12:00:00Z",
  "last_transition_at": "2026-04-05T12:02:00Z"
}

Output (timed out):

{
  "execution_id": "e1f2a3b4-...",
  "status": "running",
  "current_state": "processing",
  "timed_out": true
}

The status field upon completion will be one of completed, failed, or cancelled.

aegis.workflow.cancel

Cancel a running workflow execution.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.workflow.cancel",
  "cancelled": true,
  "execution_id": "e1f2a3b4-..."
}

On failure: { "cancelled": false, "error": "execution already in terminal state" }

aegis.workflow.signal

Send human input response to a paused workflow execution.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.workflow.signal",
  "signalled": true,
  "execution_id": "e1f2a3b4-..."
}

On failure: { "signalled": false, "error": "execution is not in a waiting state" }

aegis.workflow.remove

Remove a workflow execution record.

Access: Operator

skip_judge: true

Output:

{
  "tool": "aegis.workflow.remove",
  "removed": true,
  "execution_id": "e1f2a3b4-..."
}

On failure: { "removed": false, "error": "execution is not in a terminal state" }

aegis.workflow.promote

Promote a workflow from user scope to tenant scope.

Access: System

skip_judge: false

Output:

{
  "workflow_id": "w1b2c3d4-...",
  "name": "my-workflow",
  "promoted": true,
  "target_scope": "global"
}

aegis.workflow.demote

Demote a workflow from tenant scope to user scope.

Access: System

skip_judge: false

Output:

{
  "workflow_id": "w1b2c3d4-...",
  "name": "my-workflow",
  "demoted": true,
  "target_scope": "tenant"
}

aegis.workflow.executions.list

Lists workflow executions, optionally filtered.

Access: User

skip_judge: true

Output:

{
  "executions": [
    {
      "execution_id": "e1f2a3b4-...",
      "workflow_id": "w1b2c3d4-...",
      "status": "completed",
      "current_state": "end",
      "started_at": "2026-04-05T12:00:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

aegis.workflow.executions.get

Returns details of a specific workflow execution.

Access: User

skip_judge: true

Output:

{
  "execution_id": "e1f2a3b4-...",
  "workflow_id": "w1b2c3d4-...",
  "status": "completed",
  "input": {},
  "blackboard": {},
  "state_outputs": {},
  "current_state": "end",
  "started_at": "2026-04-05T12:00:00Z",
  "last_transition_at": "2026-04-05T12:02:00Z"
}

aegis.workflow.status

Returns current status of a workflow execution.

Access: User

skip_judge: true

Output:

{
  "execution_id": "e1f2a3b4-...",
  "workflow_id": "w1b2c3d4-...",
  "status": "running",
  "current_state": "processing",
  "started_at": "2026-04-05T12:00:00Z",
  "last_transition_at": "2026-04-05T12:01:00Z"
}

aegis.workflow.search

Semantic search over registered workflows.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.workflow.search",
  "query": "data pipeline",
  "results": [
    {
      "id": "w1b2c3d4-...",
      "name": "etl-pipeline",
      "version": "1.0.0",
      "description": "...",
      "labels": {},
      "score": 0.88
    }
  ],
  "total": 3
}

Task Management Tools (aegis.task.*)

These tools start and monitor individual agent executions (tasks). An agent must be deployed before a task can be dispatched against it. For agent lifecycle management, see Agent Management Tools.

aegis.task.execute

Starts a new agent execution (task) by agent UUID or name.

Access: User

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "started"
}

Use aegis.task.wait to block until completion.

aegis.task.status

Returns the current status and output of an execution by UUID.

Access: User

skip_judge: true

Output:

{
  "execution_id": "e1f2a3b4-...",
  "agent_id": "a1b2c3d4-...",
  "status": "completed",
  "iteration_count": 2,
  "last_output": "...",
  "last_error": null,
  "started_at": "2026-04-05T12:00:00Z",
  "ended_at": "2026-04-05T12:01:00Z"
}

The status field is one of pending, running, completed, failed, or cancelled.

aegis.task.list

Lists recent executions, optionally filtered by agent.

Access: User

skip_judge: true

Output:

{
  "executions": [
    {
      "id": "e1f2a3b4-...",
      "agent_id": "a1b2c3d4-...",
      "status": "completed",
      "started_at": "2026-04-05T12:00:00Z"
    }
  ]
}

aegis.task.cancel

Cancels an active agent execution by UUID.

Access: User

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "cancelled": true
}

aegis.task.remove

Removes a completed or failed execution record by UUID.

Access: Operator

skip_judge: false

Output:

{
  "execution_id": "e1f2a3b4-...",
  "removed": true
}

aegis.task.logs

Returns paginated execution events for a task by UUID.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.task.logs",
  "execution_id": "e1f2a3b4-...",
  "status": "completed",
  "events": [
    {
      "sequence": 1,
      "event_type": "iteration_started",
      "payload": {},
      "recorded_at": "2026-04-05T12:00:00Z"
    }
  ],
  "total": 8,
  "limit": 50,
  "offset": 0
}

aegis.task.wait

Polls an execution until it reaches a terminal state and returns the result.

Access: User

skip_judge: true

Output:

{
  "execution_id": "e1f2a3b4-...",
  "status": "completed",
  "iteration_count": 3,
  "last_output": "...",
  "last_error": null,
  "started_at": "2026-04-05T12:00:00Z",
  "ended_at": "2026-04-05T12:01:30Z"
}

The status field will be one of completed, failed, cancelled, or timed_out.

aegis.execution.file

Read a file from a completed execution's workspace volume. Use this to retrieve output files after an agent or task execution finishes. Supports both text and binary files.

Access: User

skip_judge: true

Available in: Agentic, Execute, Workflow modes

Output schema:

Text files include their content inline in the content field so LLMs can consume it directly. Binary files (images, PDFs, archives, etc.) omit content and instead provide a download_url for out-of-band retrieval by the client application.

Text file example:

{
  "execution_id": "e1f2a3b4-...",
  "path": "output.md",
  "content": "# Report\n\nAnalysis complete. Found 3 issues...",
  "content_type": "text/markdown",
  "is_binary": false,
  "size_bytes": 1847
}

Binary file example:

{
  "execution_id": "e1f2a3b4-...",
  "path": "chart.png",
  "content_type": "image/png",
  "is_binary": true,
  "download_url": "https://aegis.example.com/v1/executions/e1f2a3b4-.../files/chart.png?token=...",
  "size_bytes": 245120
}

Execute Pipeline Tools (aegis.execute.*)

These tools power Execute mode in Zaru and the intent-to-execution API. They run a multi-step pipeline: intent → agent discovery or generation → code generation → execution → result. No pre-existing agent is required.

aegis.execute.intent

Starts the intent-to-execution pipeline: discovers or generates an agent, writes code, executes in a container, and returns the formatted result.

Access: User

skip_judge: false

Output:

{
  "pipeline_execution_id": "p1b2c3d4-...",
  "status": "started",
  "stream_url": "https://..."
}

Use aegis.execute.status or aegis.execute.wait to track completion.

aegis.execute.status

Returns the current status of an intent-to-execution pipeline run.

Access: User

skip_judge: true

Output (running):

{ "status": "running" }

Output (completed):

{
  "status": "completed",
  "final_result": "...",
  "duration_ms": 4523,
  "reused_existing_agent": false
}

Output (failed):

{
  "status": "failed",
  "reason": "...",
  "failed_at_state": "code_generation"
}

aegis.execute.wait

Alias for aegis.workflow.wait. Blocks until pipeline execution completes.

Access: User

skip_judge: true

Output: Same shape as aegis.workflow.wait.

Tool Discovery (aegis.tools.*)

These tools enumerate the available MCP tool catalog. Results are filtered by the caller's SecurityContext — different tiers see different subsets of tools.

aegis.tools.list

List all MCP tools available to your security context with pagination and optional source/category filtering.

Access: User

skip_judge: true

No parameters — accepts an empty object {}.

Output:

{
  "tool": "aegis.tools.list",
  "tools": [
    {
      "name": "fs.read",
      "description": "Read the contents of a file...",
      "source": "builtin",
      "skip_judge": true
    }
  ],
  "total": 60
}

aegis.tools.search

Search for MCP tools by keyword, name pattern, source, category, or tags. Returns tools matching your query within your security context.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.tools.search",
  "query": "workflow",
  "tools": [
    {
      "name": "aegis.workflow.create",
      "description": "...",
      "source": "builtin",
      "skip_judge": true
    }
  ],
  "total": 19
}

System Tools (aegis.system.*)

aegis.system.info

Returns system version, status, and capabilities.

Access: Operator

skip_judge: true

No parameters — accepts an empty object {}.

Output:

{
  "version": "0.12.0",
  "status": "healthy",
  "capabilities": ["workflows", "cortex", "seal_gateway"]
}

The status field is one of healthy or unhealthy.

aegis.system.config

Returns the current node configuration.

Access: Operator

skip_judge: true

No parameters — accepts an empty object {}.

Output:

{
  "config_path": "/etc/aegis/node-config.yaml",
  "content_yaml": "..."
}

Schema Tools (aegis.schema.*)

aegis.schema.get

Returns the canonical JSON Schema for a manifest kind (agent or workflow).

Access: User

skip_judge: true

Output: The full JSON Schema object for the requested manifest type.

aegis.schema.validate

Validates a manifest YAML string against its canonical JSON Schema.

Access: User

skip_judge: true

Output:

{
  "valid": true,
  "errors": null
}

On failure: { "valid": false, "errors": ["error message 1"] }

Runtime Discovery (aegis.runtime.*)

aegis.runtime.list

List all supported standard runtime environments (language/version pairs). Call this before creating an agent manifest to ensure the declared runtime is valid.

Access: User

skip_judge: true

Output:

{
  "tool": "aegis.runtime.list",
  "runtimes": [
    {
      "language": "python",
      "version": "3.12",
      "image": "ghcr.io/100monkeys/runtime-python:3.12",
      "description": "CPython 3.12",
      "deprecated": false
    }
  ],
  "custom_runtime_supported": true
}

Volume Filesystem Tools (aegis.file.*)

These tools operate on files inside tenant-scoped persistent volumes. Every call is authorized against the caller's bearer token — callers can only reach volumes they own. Paths are resolved relative to the volume root. Volume ownership, quota, and tier limits are enforced by the orchestrator backend; the tool-availability gate itself is uniform across all tiers.

aegis.file.list

List directory contents in a user volume.

Access: User

skip_judge: true

Output: Directory listing with entry names and file / directory type discriminators.

aegis.file.read

Read the contents of a file in a user volume.

Access: User

skip_judge: true

Output: File contents. Text files return inline string content. Binary files return a base64-encoded payload or a short-lived download URL depending on size.

aegis.file.write

Write content to a file in a user volume. Creates the file if it does not exist and overwrites it if it does.

Access: User

skip_judge: false

Output: Confirmation with path and bytes written. Fails if the write would exceed the volume's quota.

aegis.file.delete

Delete a file or directory in a user volume.

Access: User

skip_judge: false

Output: Confirmation with the deleted path.

aegis.file.mkdir

Create a directory in a user volume, including any missing parent directories.

Access: User

skip_judge: false

Output: Confirmation with the created path.

Git Repository Tools (aegis.git.*)

Manage SeaweedFS-backed git repository bindings. A binding pairs a remote repository with a persistent volume mounted at /workspace/{label}. The clone is performed asynchronously — aegis.git.clone returns immediately with the binding in a Pending/Cloning state; use aegis.git.status to poll until ready. aegis.git.commit, aegis.git.push, and aegis.git.diff enable canvas-style write-back against the bound volume.

aegis.git.clone

Create a git repo binding and trigger an asynchronous clone into a workspace volume.

Access: User

skip_judge: false

Output: The newly created binding DTO with status Pending or Cloning.

aegis.git.list

List the caller's git repo bindings.

Access: User

skip_judge: true

Output: Paginated list of binding DTOs.

aegis.git.status

Get clone/refresh status for a git repo binding. Returns the binding with its current status, last commit SHA, and last_cloned_at timestamp.

Access: User

skip_judge: true

Output: Binding DTO with status and most recent commit information.

aegis.git.refresh

Trigger a fetch + checkout to update the bound volume to the latest remote HEAD (for branch refs) or re-verify the pinned ref (for tag / commit refs).

Access: User

skip_judge: false

Output: Confirmation with updated status fields.

aegis.git.delete

Soft-delete a git repo binding and cascade-delete the associated volume.

Access: User

skip_judge: false

Output: Confirmation of deletion.

aegis.git.commit

Stage all changes in the bound volume and commit with the given message. Returns the new commit SHA. Fails if there are no changes to commit.

Access: User

skip_judge: false

Output: Object containing the new commit SHA.

aegis.git.push

Push committed changes to the remote. Requires a credential_binding_id set on the binding for authenticated remotes.

Access: User

skip_judge: false

Output: Confirmation of push with remote and ref details.

aegis.git.diff

Return the unified diff of the bound volume's working tree (or index, if staged: true). Read-only.

Access: User

skip_judge: true

Output: Unified-diff text.

Script Library Tools (aegis.script.*)

Persist and retrieve saved TypeScript programs in the caller's script library. Scripts are tenant-scoped; names are unique per tenant. Updates bump a monotonic version number and append to the script's version history. Deletes are soft — version history is retained for audit and the name reservation is released.

aegis.script.save

Persist a TypeScript program to the caller's script library.

Access: User

skip_judge: false

Output: The saved script DTO with its assigned id and version: 1.

aegis.script.list

List the caller's saved scripts with optional filters.

Access: User

skip_judge: true

Output: Array of script DTOs (without the versions field).

aegis.script.get

Retrieve a saved script by ID, including its full version history.

Access: User

skip_judge: true

Output: Script DTO with versions array. Returns 404 for scripts the caller does not own.

aegis.script.update

Update a saved script. Bumps the version monotonically and appends to the script's version history.

Access: User

skip_judge: false

Output: Updated script DTO with the new version number.

aegis.script.delete

Soft-delete a saved script.

Access: User

skip_judge: false

Output: Empty body on success.

Volume Management Tools (aegis.volume.*)

Create, list, and manage tenant-scoped persistent volumes. Volumes are backed by SeaweedFS and subject to per-tier quotas enforced by the orchestrator backend. Every call is authorized against the caller's bearer token — callers can only see and modify volumes they own.

aegis.volume.create

Provision a new persistent volume with a specified storage quota.

Access: User

skip_judge: false

Output: The created volume DTO, including its volume_id.

aegis.volume.list

List all persistent volumes owned by the current user.

Access: User

skip_judge: true

No parameters — accepts an empty object {}.

Output: Array of volume DTOs.

aegis.volume.delete

Delete a persistent user volume and all of its contents.

Access: User

skip_judge: false

Output: Confirmation of deletion.

aegis.volume.quota

Get storage quota usage for the current user.

Access: User

skip_judge: true

No parameters — accepts an empty object {}.

Output: Quota summary — total bytes allowed by the caller's tier and bytes currently used across their volumes.

Zaru UI Tools

zaru.init

Activate Zaru in any MCP client. Call this tool at the start of a session to retrieve the current mode, system prompt, available tools, and server version. Any MCP client (Claude Code, Claude Desktop, or the Zaru web UI) should call zaru.init on connection to bootstrap the session.

Access: User

skip_judge: N/A (never reaches the orchestrator)

Output:

{
  "mode": "chat",
  "system_prompt": "You are Zaru, a helpful AI assistant...",
  "available_tools": ["zaru.init", "zaru.mode"],
  "version": "0.8.0"
}

zaru.mode

Switch to a different conversation mode. Use this when the user's request cannot be fulfilled in the current mode. In the Zaru web UI this renders a confirmation card inline in the chat — the user can accept, refuse, or dismiss. In headless MCP clients the mode switch is applied immediately.

Access: User

skip_judge: N/A (never reaches the orchestrator)

Output:

{
  "action": "mode_switch_requested",
  "target_mode": "agentic",
  "reason": "This request requires running an agent."
}

In the Zaru web UI, this response renders as an inline confirmation card. The user can accept, refuse, or dismiss the mode switch. In headless MCP clients (Claude Code, Claude Desktop), the mode switch is applied immediately and the response confirms the new mode.

zaru.docs

Search AEGIS and Zaru documentation. Results are fetched from docs.100monkeys.ai and cached for 5 minutes. Available in every conversation mode.

Access: User

skip_judge: N/A (never reaches the orchestrator)

Output:

{
  "query": "how to create an agent",
  "sections": [
    {
      "title": "Creating Your First Agent",
      "content": "To create an agent, define a manifest YAML...",
      "url": "https://docs.100monkeys.ai/docs/guides/creating-agents"
    }
  ],
  "total_matches": 3
}

Example call:

zaru.docs({ query: "how to create an agent" })