MCP Tools

Zaru exposes the AEGIS platform to MCP clients through a set of tools organized by conversation mode. The mode you select at the start of a conversation determines which tools are active. This page covers each mode's tool set with purpose, key parameters, and example calls.

For complete input/output schemas, see the MCP Tool Reference. For client connection instructions, see Connect Zaru to Any MCP Client.

How Modes Control Tool Access

Every Zaru conversation runs in one of five modes. Modes filter the tool surface exposed to the AI assistant — the underlying platform tools do not change, but the assistant can only call what the mode makes available.

To initialize in a specific mode:

zaru init agentic

To switch modes mid-session, tell the assistant to switch — it calls zaru.mode and the tool set updates immediately.

Zaru Client Tools — All Modes

These three tools are available in every mode, including chat. They are handled by the Zaru MCP server and never forwarded to the AEGIS orchestrator.

zaru.init

Bootstraps the session. Returns the current mode, system prompt, available tools, and server version. Call this at the start of any MCP session.

// zaru.init
{ "mode": "agentic" }

zaru.mode

Switches the active conversation mode. In the Zaru web client, this renders an inline confirmation card — the user accepts or declines. In headless MCP clients the switch applies immediately.

// zaru.mode
{
  "target_mode": "architect",
  "reason": "Designing a new multi-step workflow requires architect tools."
}

zaru.docs

Searches AEGIS and Zaru documentation at docs.100monkeys.ai. Results are cached for 5 minutes per query.

// zaru.docs
{ "query": "how to configure a persistent volume for execute mode" }

Agentic Mode Tools

Agentic mode gives the assistant access to agent discovery, generation, task execution, and monitoring. Use it when you want to run existing agents or generate new ones from a description.

Agent Discovery and Generation

aegis.agent.list — Lists all deployed agents with name, version, status, and description. No parameters required. Use this to find agents before running them.

// aegis.agent.list
{}

aegis.agent.generate — Starts an async authoring loop that generates a complete agent manifest from a plain-English description and deploys it. Returns an execution_id immediately.

// aegis.agent.generate
{ "input": "An agent that reads a CSV file from /workspace, computes summary statistics for each numeric column, and writes a markdown report to /workspace/report.md" }

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

Follow with aegis.agent.wait to block until generation completes.

aegis.agent.wait — Blocks until an agent generation (or any agent execution) reaches a terminal state.

// aegis.agent.wait
{ "execution_id": "e1f2a3b4-...", "timeout_seconds": 120 }

aegis.agent.logs — Retrieves deployment events and execution summaries for a specific agent by UUID.

// aegis.agent.logs
{ "agent_id": "a1b2c3d4-...", "limit": 20 }

Task Execution and Monitoring

aegis.task.execute — Starts a new execution of a deployed agent by UUID or name. Returns an execution_id.

// aegis.task.execute
{
  "agent_id": "csv-summary-agent",
  "intent": "Summarize the sales data uploaded this morning",
  "input": { "prompt": "The file is at /workspace/sales-2026-04.csv. Focus on Q1 vs Q2 variance." }
}

aegis.task.wait — Blocks until an execution reaches a terminal state. Returns the final status, output, and error.

// aegis.task.wait
{ "execution_id": "e1f2a3b4-...", "poll_interval_seconds": 5, "timeout_seconds": 180 }

aegis.task.list — Lists recent executions, optionally filtered by agent.

aegis.task.logs — Returns paginated execution events for a specific task.

aegis.task.cancel — Cancels an active execution.

// aegis.task.cancel
{ "execution_id": "e1f2a3b4-..." }

Execution Output Files

aegis.execution.file — Reads a file from a completed execution's workspace. Available in agentic, execute, and architect modes.

// aegis.execution.file
{ "execution_id": "e1f2a3b4-...", "path": "report.md" }

Text files return their content inline. Binary files (images, PDFs, archives) return a download_url instead of inline content.

Tool Discovery

aegis.tools.list — Lists all tools available in the current security context. No parameters.

aegis.tools.search — Searches tools by name and description.

// aegis.tools.search
{ "query": "workflow" }

Execute Mode Tools

Execute mode provides a single-shot pipeline: describe a computation in plain English, optionally supply typed inputs, and Zaru generates and runs the code in a sandboxed container. No pre-existing agent is required.

For the full user guide including tier limits, supported languages, and workspace options, see Running Code with Execute Mode.

aegis.execute.intent

Starts the intent-to-execution pipeline. Discovers or generates a code-writing agent, produces the code, runs it in an isolated container, and returns the result.

// aegis.execute.intent
{
  "intent": "compute the mean, median, and standard deviation of this list of numbers",
  "inputs": { "numbers": [14, 22, 8, 31, 19, 7, 45] },
  "language": "python"
}

Returns a pipeline_execution_id. Use aegis.execute.wait to block until the pipeline finishes.

aegis.execute.status

Returns the current status of a pipeline run.

// aegis.execute.status
{ "pipeline_execution_id": "p1b2c3d4-..." }

Returns { "status": "running" } while in progress, or a completed result with final_result and duration_ms.

aegis.execute.wait

Blocks until the pipeline execution completes. Pass the pipeline_execution_id as execution_id.

// aegis.execute.wait
{ "execution_id": "p1b2c3d4-...", "timeout_seconds": 60 }

aegis.workflow.wait

Also available in execute mode for waiting on workflow executions started by the pipeline internally. Same parameters as aegis.execute.wait.

Architect Mode Tools

Architect mode adds workflow and agent design tooling on top of the agentic mode tools. Use it when you need to author new workflows or agents from natural language, validate manifests, or query schemas.

All agentic mode tools (aegis.agent.*, aegis.task.*, aegis.execution.file) are also available in architect mode. The tools below are the additions.

Workflow Generation and Management

aegis.workflow.generate — Starts an async authoring loop that generates a complete workflow manifest from a natural-language objective and registers it.

// aegis.workflow.generate
{ "input": "A three-stage pipeline: extract keywords from a document, look each keyword up in a knowledge base, then produce a structured summary with citations" }

Returns { "execution_id": "...", "status": "started" }. Follow with aegis.workflow.wait.

aegis.workflow.wait — Blocks until a workflow execution or generation completes.

// aegis.workflow.wait
{ "execution_id": "e1f2a3b4-...", "timeout_seconds": 600 }

aegis.workflow.list — Lists all registered workflows with name, version, and initial state. No required parameters.

aegis.workflow.logs — Returns paginated state-transition and lifecycle events for a workflow execution.

// aegis.workflow.logs
{ "execution_id": "e1f2a3b4-...", "limit": 100 }

Schema and Validation Tools

aegis.schema.get — Retrieves the canonical JSON Schema for a manifest kind. Use before writing a manifest to understand required and optional fields.

// aegis.schema.get
{ "key": "agent/manifest/v1" }

aegis.schema.validate — Validates a manifest YAML against its canonical schema without deploying it.

// aegis.schema.validate
{
  "kind": "agent",
  "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Agent\nmetadata:\n  name: my-agent\n..."
}

Returns { "valid": true, "errors": null } on success or { "valid": false, "errors": ["..."] } on failure.

Operator Mode Tools

Operator mode exposes all 86 tools with no filtering. It includes everything from the modes above plus the tool groups below.

Agent and Workflow Lifecycle

These tools manage the registry directly. They take a manifest YAML and register it synchronously — no async generation loop.

aegis.agent.create / aegis.agent.update — Deploy or update an agent manifest. Pass force: true to overwrite an existing name/version pair.

// aegis.agent.create
{ "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Agent\n..." }

aegis.agent.export — Retrieves the raw manifest YAML of a deployed agent by name.

// aegis.agent.export
{ "name": "csv-summary-agent" }

aegis.agent.delete — Permanently removes an agent from the registry by UUID.

// aegis.agent.delete
{ "agent_id": "a1b2c3d4-..." }

aegis.agent.search — Semantic search over deployed agents by natural-language query.

// aegis.agent.search
{ "query": "summarize CSV files and produce markdown reports", "limit": 5, "min_score": 0.7 }

aegis.workflow.create / aegis.workflow.update — Register or update a workflow manifest.

// aegis.workflow.create
{
  "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Workflow\n...",
  "task_context": "Adding a new CSV-parsing stage to the data pipeline."
}

aegis.workflow.validate — Validates a workflow manifest without registering it.

// aegis.workflow.validate
{ "manifest_yaml": "apiVersion: aegis.ai/v1\nkind: Workflow\n..." }

aegis.workflow.export — Retrieves the raw manifest YAML of a registered workflow by name.

aegis.workflow.delete — Permanently removes a workflow from the registry.

aegis.workflow.run — Executes a registered workflow by name.

// aegis.workflow.run
{
  "name": "data-pipeline",
  "intent": "Process the April sales extract",
  "input": { "source_path": "/workspace/sales-2026-04.csv" }
}

aegis.workflow.search — Semantic search over registered workflows.

// aegis.workflow.search
{ "query": "data transformation and reporting pipeline", "min_score": 0.65 }

Workflow Execution Control

aegis.workflow.cancel — Gracefully cancels a running workflow execution.

// aegis.workflow.cancel
{ "execution_id": "e1f2a3b4-..." }

aegis.workflow.signal — Sends human input to a workflow paused at a human_input state.

// aegis.workflow.signal
{ "execution_id": "e1f2a3b4-...", "response": "approved" }

aegis.workflow.status — Lightweight status snapshot for a workflow execution.

aegis.workflow.executions.list — Lists workflow executions with optional filtering by workflow and pagination.

aegis.workflow.executions.get — Full execution detail including blackboard state and state outputs.

aegis.workflow.remove — Removes a terminal execution record from the registry.

aegis.workflow.promote / aegis.workflow.demote — Change a workflow's visibility scope (user → tenant → global and back).

// aegis.workflow.promote
{ "name": "data-pipeline", "target_scope": "tenant" }

Task Status and Cleanup

aegis.task.status — Returns current status and progress of an execution by UUID.

aegis.task.remove — Removes a terminal execution record.

// aegis.task.remove
{ "execution_id": "e1f2a3b4-..." }

Volume and File Tools

aegis.volume.create — Provision a new persistent volume.

// aegis.volume.create
{ "label": "project-data", "size_limit_bytes": 5368709120 }

aegis.volume.list — List all volumes owned by the current user. No parameters.

aegis.volume.quota — Get storage quota usage. No parameters.

aegis.volume.delete — Delete a volume and all its contents.

aegis.file.list / aegis.file.read / aegis.file.write / aegis.file.delete / aegis.file.mkdir — Operate on files within a specific volume. All require volume_id and path.

// aegis.file.read
{ "volume_id": "vol-abc123", "path": "reports/april-summary.md" }

Git Repository Tools

aegis.git.clone — Create a git repo binding and trigger an async clone into a workspace volume.

// aegis.git.clone
{
  "repo_url": "https://github.com/my-org/my-repo",
  "label": "my-repo",
  "git_ref": { "kind": "branch", "value": "main" }
}

aegis.git.status — Check clone/refresh status for a binding by binding_id.

aegis.git.refresh — Pull latest remote HEAD into the bound volume.

aegis.git.diff — Return the unified diff of the bound volume's working tree.

aegis.git.commit — Stage all changes and commit with a message. Returns the new commit SHA.

aegis.git.push — Push committed changes to the remote.

aegis.git.list — List all git repo bindings.

aegis.git.delete — Delete a binding and cascade-delete the associated volume.

Script Library Tools

Scripts are TypeScript programs stored in the caller's script library. Names must be unique per tenant.

aegis.script.save — Persist a new TypeScript script.

aegis.script.list — List saved scripts, optionally filtered by tag or name substring.

aegis.script.get — Retrieve a script by id, including full version history.

aegis.script.update — Update a script. Bumps the version number monotonically.

aegis.script.delete — Soft-delete a script. Version history is retained; the name becomes available for reuse.

Runtime Discovery

aegis.runtime.list — List all supported runtime environments (language/version pairs). Filter by language to narrow results. Call this before writing spec.runtime in an agent manifest.

// aegis.runtime.list
{ "language": "python" }

See the Standard Runtime Registry for the full runtime matrix.

System Tools

aegis.system.info — Returns node version, health status, and enabled capabilities. No parameters.

aegis.system.config — Returns the full active node configuration as a string. No parameters. See the Node Configuration Reference for the schema.

Dispatch and Filesystem Tools

cmd.run, fs.* (10 tools), and web.* (2 tools) are available in operator mode. cmd.run executes a shell command inside the agent container. fs.* tools operate on the mounted workspace volume directly. web.search and web.fetch make outbound network calls.

// cmd.run
{ "command": "python /workspace/process.py --input data.csv" }

Mode-to-Tools Quick Reference

Abbreviations: C = chat, Ag = agentic, Ex = execute, Ar = architect, Op = operator.

Related

• MCP Tool Reference — complete input/output schemas for all 86 tools
• Connect Zaru to Any MCP Client — client connection setup
• Management Tools — usage patterns for agent and workflow management from agents
• Management via MCP — automation patterns for agent factories and self-managing workflows
• Running Code with Execute Mode — full guide to the execute pipeline