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 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.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.execute.wait, aegis.tools.list, aegis.tools.search, aegis.schema.get, aegis.schema.validate, aegis.runtime.list, zaru.switch_mode

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.switch_mode is exposed. The model cannot invoke any orchestrator tools directly from chat mode.

Agentic Mode

• zaru.switch_mode
• 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.tools.list
• aegis.tools.search

Execute Mode

• zaru.switch_mode
• aegis.execute.intent
• aegis.execute.status
• aegis.execute.wait
• aegis.workflow.wait

Architect Mode

• zaru.switch_mode
• 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.workflow.wait

Operator Mode

All 61 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.create.dir

Alias for fs.create_dir. Creates a new directory along with any necessary parent directories.

Access: User

skip_judge: false

Output: Same as fs.create_dir.

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.

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
}

Zaru UI Tools

zaru.switch_mode

Suggest the user switch to a different conversation mode. Use this when the user's request cannot be fulfilled in the current mode. This renders a confirmation card inline in the chat — the user can accept, refuse, or dismiss.

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."
}

The Zaru client renders this response as an inline confirmation card. The user can accept, refuse, or dismiss the mode switch.