# MCP Tools Reference > Auto-generated from source. Do not edit manually. > Run `bun run docs:mcp` to regenerate. ## Capability Flags Every tool group is gated by a capability flag on the API server. The set of enabled capabilities comes from the `CAPABILITIES` env var (or the `CAPABILITIES` global swarm-config entry); when unset, the defaults apply. Setting `CAPABILITIES` **replaces** the whole list — it is not additive — so include every capability you want, not just the extras. Capability flags shape the **externally exposed MCP tool list only** — they hide tools from agents, they are not feature kill-switches. The scripts SDK bridge always builds a full-surface server (its surface is governed by the SDK allowlist instead), and HTTP REST routes are generally not gated. - Enabled by default: `core`, `task-pool`, `config`, `scripts`, `mcp`, `profiles`, `repo`, `scheduling`, `memory`, `tracker`, `workflows`, `skills`, `pages`, `metrics`, `kv`, `slack` - Disabled by default: `prompt-templates`, `agentmail`, `kapso`, `swarm-x`, `messaging`, `services` ## Table of Contents - [Core Tools](#core-tools) - [join-swarm](#join-swarm) - [poll-task](#poll-task) - [get-swarm](#get-swarm) - [get-tasks](#get-tasks) - [get-metrics](#get-metrics) - [send-task](#send-task) - [get-task-details](#get-task-details) - [store-progress](#store-progress) - [my-agent-info](#my-agent-info) - [cancel-task](#cancel-task) - [resolve-user](#resolve-user) - [manage-user](#manage-user) - [db-query](#db-query) - [get-oauth-access-token](#get-oauth-access-token) - [accept-steer](#accept-steer) - [steer-task](#steer-task) - [Task Pool Tools](#task-pool-tools) - [task-action](#task-action) - [Config Tools](#config-tools) - [set-config](#set-config) - [get-config](#get-config) - [list-config](#list-config) - [delete-config](#delete-config) - [credential-bindings](#credential-bindings) - [model-catalog-refresh](#model-catalog-refresh) - [model-catalog-overlay-upsert](#model-catalog-overlay-upsert) - [Scripts Tools](#scripts-tools) - [script-search](#script-search) - [script-connections](#script-connections) - [script-apis](#script-apis) - [script-run](#script-run) - [script-upsert](#script-upsert) - [extension-delete](#extension-delete) - [extension-enable](#extension-enable) - [extension-disable](#extension-disable) - [extension-activate-version](#extension-activate-version) - [extension-catalog](#extension-catalog) - [extension-install](#extension-install) - [extension-list](#extension-list) - [script-delete](#script-delete) - [script-query-types](#script-query-types) - [launch-script-run](#launch-script-run) - [get-script-run](#get-script-run) - [list-script-runs](#list-script-runs) - [MCP Server Tools](#mcp-server-tools) - [mcp-server-create](#mcp-server-create) - [mcp-server-update](#mcp-server-update) - [mcp-server-delete](#mcp-server-delete) - [mcp-server-get](#mcp-server-get) - [mcp-server-list](#mcp-server-list) - [mcp-server-install](#mcp-server-install) - [mcp-server-uninstall](#mcp-server-uninstall) - [Profiles Tools](#profiles-tools) - [update-profile](#update-profile) - [context-history](#context-history) - [context-diff](#context-diff) - [Repo Tools](#repo-tools) - [get-repos](#get-repos) - [update-repo](#update-repo) - [Scheduling Tools](#scheduling-tools) - [list-schedules](#list-schedules) - [create-schedule](#create-schedule) - [defer-task](#defer-task) - [update-schedule](#update-schedule) - [patch-schedule](#patch-schedule) - [delete-schedule](#delete-schedule) - [run-schedule-now](#run-schedule-now) - [Memory Tools](#memory-tools) - [memory-search](#memory-search) - [memory-store](#memory-store) - [memory-get](#memory-get) - [memory-edit](#memory-edit) - [memory-delete](#memory-delete) - [memory_rate](#memory_rate) - [inject-learning](#inject-learning) - [Tracker Tools](#tracker-tools) - [tracker-status](#tracker-status) - [tracker-link-task](#tracker-link-task) - [tracker-unlink](#tracker-unlink) - [tracker-sync-status](#tracker-sync-status) - [tracker-map-agent](#tracker-map-agent) - [Workflows Tools](#workflows-tools) - [create-workflow](#create-workflow) - [list-workflows](#list-workflows) - [get-workflow](#get-workflow) - [update-workflow](#update-workflow) - [patch-workflow](#patch-workflow) - [patch-workflow-node](#patch-workflow-node) - [delete-workflow](#delete-workflow) - [trigger-workflow](#trigger-workflow) - [list-workflow-runs](#list-workflow-runs) - [get-workflow-run](#get-workflow-run) - [retry-workflow-run](#retry-workflow-run) - [cancel-workflow-run](#cancel-workflow-run) - [request-human-input](#request-human-input) - [cancel-approval-request](#cancel-approval-request) - [Skills Tools](#skills-tools) - [skill-create](#skill-create) - [skill-update](#skill-update) - [skill-delete](#skill-delete) - [skill-get](#skill-get) - [skill-get-file](#skill-get-file) - [skill-list](#skill-list) - [skill-search](#skill-search) - [skill-install](#skill-install) - [skill-uninstall](#skill-uninstall) - [skill-install-remote](#skill-install-remote) - [skill-sync-remote](#skill-sync-remote) - [skill-publish](#skill-publish) - [Pages Tools](#pages-tools) - [app-get](#app-get) - [app-history](#app-history) - [app-diff](#app-diff) - [app-list](#app-list) - [app-patch](#app-patch) - [app-query](#app-query) - [app-rollback](#app-rollback) - [app-sync](#app-sync) - [app-upsert](#app-upsert) - [create_page](#create_page) - [delete-page](#delete-page) - [Metrics Tools](#metrics-tools) - [create_metric](#create_metric) - [KV Tools](#kv-tools) - [kv-get](#kv-get) - [kv-set](#kv-set) - [kv-delete](#kv-delete) - [kv-incr](#kv-incr) - [kv-list](#kv-list) - [room-get](#room-get) - [room-change](#room-change) - [room-reset](#room-reset) - [room-decode](#room-decode) - [Slack Tools](#slack-tools) - [slack-reply](#slack-reply) - [slack-read](#slack-read) - [slack-post](#slack-post) - [slack-start-thread](#slack-start-thread) - [slack-create-channel](#slack-create-channel) - [slack-invite-to-channel](#slack-invite-to-channel) - [slack-archive-channel](#slack-archive-channel) - [slack-list-channels](#slack-list-channels) - [slack-upload-file](#slack-upload-file) - [slack-download-file](#slack-download-file) - [slack-delete](#slack-delete) - [slack-update](#slack-update) - [Prompt Templates Tools](#prompt-templates-tools) - [list-prompt-templates](#list-prompt-templates) - [get-prompt-template](#get-prompt-template) - [set-prompt-template](#set-prompt-template) - [delete-prompt-template](#delete-prompt-template) - [preview-prompt-template](#preview-prompt-template) - [AgentMail Tools](#agentmail-tools) - [register-agentmail-inbox](#register-agentmail-inbox) - [Kapso (WhatsApp) Tools](#kapso-(whatsapp)-tools) - [register-kapso-number](#register-kapso-number) - [unregister-kapso-number](#unregister-kapso-number) - [send-whatsapp-message](#send-whatsapp-message) - [reply-whatsapp-message](#reply-whatsapp-message) - [Swarm X Tools](#swarm-x-tools) - [swarm_x](#swarm_x) - [Messaging Tools](#messaging-tools) - [post-message](#post-message) - [read-messages](#read-messages) - [list-channels](#list-channels) - [create-channel](#create-channel) - [delete-channel](#delete-channel) - [Services Tools](#services-tools) - [register-service](#register-service) - [unregister-service](#unregister-service) - [list-services](#list-services) - [update-service-status](#update-service-status) --- ## Core Tools *Core capability - swarm membership, task flow, progress, user identity, and lead debug tools* Capability: `core` (enabled by default) ### join-swarm **Join the agent swarm** Tool for an agent to join the swarm of agents with optional profile information. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `requestedId` | `string` | No | - | Requested ID for the agent (overridden by X-Agent-ID header). | | `lead` | `boolean` | No | false | Whether this agent should be the lead. | | `name` | `string` | Yes | - | The name of the agent joining the swarm. | | `description` | `string` | No | - | Agent description. | | `role` | `string` | No | - | Agent role (free-form, e.g., 'frontend dev', 'code reviewer'). | | `capabilities` | `array` | No | - | List of capabilities (e.g., ['typescript', 'react', 'testing']). | ### poll-task **Poll for a task** Poll for a new task assignment. Returns immediately if there are offered tasks awaiting accept/reject. Also returns count of unassigned tasks in the pool. *No parameters* ### get-swarm **Get the agent swarm** Returns a list of agents in the swarm without their tasks. Identity markdown (claudeMd/soulMd/identityMd/toolsMd/heartbeatMd/setupScript) is omitted by default — pass includeFull:true to include it. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `a` | `string` | No | - | - | | `includeFull` | `boolean` | No | - | Include the six identity-markdown blobs (claudeMd/soulMd/identityMd/toolsMd/heartbeatMd/setupScript). Default false — they are large and rarely needed at the swarm-overview level. | ### get-tasks **Get tasks** Returns a list of tasks in the swarm with various filters. Sorted by priority (desc) then lastUpdatedAt (desc). Each row carries a `taskPreview` (~300 chars) — enough to pool-triage; pass includeFull:true (or call `get-task-details` by id) for the full `task` text. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `status` | `draft \| backlog \| unassigned \| offered \| reviewing \| pending \| in_progress \| paused \| completed \| failed \| cancelled \| superseded` | No | - | Filter by task status (unassigned, offered, pending, in_progress, completed, failed). | | `mineOnly` | `boolean` | No | - | Only return tasks assigned to you. | | `unassigned` | `boolean` | No | - | Only return unassigned tasks in the pool. | | `offeredToMe` | `boolean` | No | - | Only return tasks offered to you (awaiting accept/reject). | | `readyOnly` | `boolean` | No | - | Only return tasks whose dependencies are met. | | `taskType` | `string` | No | - | Filter by task type (e.g., 'bug', 'feature'). | | `tags` | `array` | No | - | Filter by any matching tag. | | `search` | `string` | No | - | Search in task description. | | `scheduleId` | `string` | No | - | Filter by schedule ID to find tasks created by a specific schedule. | | `key` | `unknown` | No | - | Filter by exact logical namespace. | | `keyPrefix` | `unknown` | No | - | Filter by namespace subtree. | | `includeHeartbeat` | `boolean` | No | - | Include heartbeat/system tasks in results (excluded by default). | | `limit` | `number` | No | - | Max tasks to return (default: 25, max: 100). | | `includeFull` | `boolean` | No | - | Return the full `task` text instead of a ~300-char `taskPreview`. Default false. | ### get-metrics **Get swarm metrics** Returns lightweight swarm-wide counts in a single object — tasks (total + by status), agents (total + by status), workflows (total + enabled), pages, active sessions, skills. Use this instead of fetching full list payloads just to count things. Pure COUNT queries; cheap. *No parameters* ### send-task **Send a task** Sends a task to a specific agent, creates an unassigned task for the pool, or offers a task for acceptance. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | No | - | The agent to assign/offer task to. Omit to create unassigned task for pool. | | `routingReason` | `skill \| continuity \| overflow \| human_pinned \| reroute_fault` | No | - | Why this agent was selected. Required when agentId is supplied; omit for pool routing. | | `routingNote` | `string` | No | - | Why this worker fits the task. Required when agentId is supplied: at least 10 characters after trimming whitespace, maximum 200 characters. Optional for implicit parent or pool routing. | | `task` | `string` | Yes | - | The task description to send. | | `key` | `unknown` | No | - | Logical namespace key. Child tasks inherit their parent namespace when provided. | | `offerMode` | `boolean` | No | false | If true, offer the task instead of direct assign (agent must accept/reject). | | `taskType` | `string` | No | - | Task type (e.g., 'bug', 'feature', 'review'). | | `tags` | `array` | No | - | Tags for filtering (e.g., ['urgent', 'frontend']). | | `requiredCapabilities` | `array` | No | - | Capabilities required for pool routing. | | `leadOnly` | `boolean` | No | false | Structured authorization constraint for merge or other privileged work. Only Lead agents may be assigned, offered, or claim it; never inferred from task text. | | `priority` | `number` | No | - | Priority 0-100 (default: 50). | | `dependsOn` | `array` | No | - | Task IDs this task depends on. | | `parentTaskId` | `uuid` | No | - | Parent task ID for session continuity. Child task will resume the parent's Claude session. Auto-routes to the same worker unless agentId is explicitly provided. | | `dir` | `string` | No | - | Working directory (absolute path) for the agent to start in. If the directory doesn't exist, falls back to the default working directory. | | `vcsRepo` | `string` | No | - | VCS repo identifier (e.g., 'desplega-ai/agent-swarm' for GitHub or 'group/project' for GitLab). Links the task to a registered repo for workspace context. | | `model` | `string` | No | - | Concrete model override for this task, interpreted by the assignee's harness/provider. This does not switch providers. Prefer modelTier for portable intent. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected. | | `modelTier` | `smol \| regular \| smart \| ultra` | No | - | Portable model tier for this task: 'smol', 'regular', 'smart', or 'ultra'. Resolved at claim/run time using the assignee's harness/provider. Legacy model shortnames map as haiku→smol, sonnet→regular, opus→smart, fable→ultra. | | `allowCustomModel` | `boolean` | No | - | Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet (a fresh launch, a private deployment). | | `effort` | `off \| low \| medium \| high \| xhigh \| max` | No | - | Reasoning effort for this task: 'off', 'low', 'medium', 'high', 'xhigh', or 'max'. If omitted, the assignee's REASONING_EFFORT_OVERRIDE/default applies. | | `allowDuplicate` | `boolean` | No | false | If true, skip duplicate detection and create the task even if a similar one exists. | | `slackChannelId` | `string` | No | - | Slack channel ID to post progress updates to. Use this to propagate Slack context when delegating from a Slack thread. | | `slackThreadTs` | `string` | No | - | Slack thread timestamp. Required with slackChannelId for thread-level updates. | | `slackUserId` | `string` | No | - | Slack user ID of the original requester. | | `overrideSlackContext` | `boolean` | No | false | Explicitly route this task's Slack updates to a different channel/thread than its parent/contextKey. Requires slackChannelId AND slackThreadTs. Use only for deliberate cross-channel dispatch (e.g. escalation to another human's DM); logged for audit. Without this flag, a slackChannelId/slackThreadTs that disagrees with the parent task or inherited contextKey is rejected — omit the three Slack fields to inherit them from the parent as a unit instead. | | `requestedByUserId` | `string` | No | - | Registered requester ID (32 lowercase hexadecimal characters). When omitted, inherited from the caller's current task so the attribution flows through multi-hop delegation automatically. | | `followUpConfig` | `unknown` | No | - | Control the lead follow-up created when this task finishes. When to use `followUpConfig`: set `disabled: true` when you'll wait for this task to complete inline and no follow-up is needed; set `onCompleted` / `onFailed` with specific instructions when you need to follow up effectively on a particular outcome of a long-running flow; for normal one-shot tasks, leave it unset because defaults are fine. It is most valuable for long-running / complex flows. | | `outputSchema` | `object` | No | - | Optional JSON Schema the assignee's final output must satisfy. store-progress rejects a completion that does not match. Supported keywords: type, required, properties, enum, const, items. | ### get-task-details **Get task details** Returns detailed information about a specific task, including output, failure reason, and log history. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `taskId` | `uuid` | Yes | - | The ID of the task to get details for. | ### store-progress **Store task progress** Stores the progress of a specific task. Can also mark task as completed or failed, which will set the agent back to idle. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `taskId` | `uuid` | No | - | Full task UUID. Defaults to the caller-owned task in X-Source-Task-Id; required outside task context. | | `progress` | `string` | No | - | The progress update to store. | | `status` | `completed \| failed \| in_progress \| pending` | No | - | Set to 'completed' or 'failed' to finish the task. 'in_progress' and 'pending' store progress only and do not change task status. | | `output` | `string` | No | - | The task result (used when completing). For Slack-originated tasks, this is published verbatim in the thread's outcome card. Keep free-text output under 120 words by default. Name the result and every artifact link, plus any IDs the human needs. Link documents instead of inlining them; omit process narration, transcripts, and restatements of the brief. Exceed the target only when requested depth, enumerated results, essential evidence, caveats, or instructions require it, or when the task's outputSchema requires longer output. When the task carries an outputSchema, output must be JSON matching it. | | `failureReason` | `string` | No | - | The reason for failure (used when failing). | | `attachments` | `array` | No | - | Pointer-based artifacts produced by this step — agent-fs path, URL, shared-fs path, or swarm Page. No inline file data; upload to agent-fs first and attach by path. Agent-fs pointers are verified before task state changes, using the explicit org/drive pair or the registering agent's configured defaults. May be sent on any call (progress or completion) and accumulates across calls; duplicates are de-duped by sha256 (when present) or by (kind, pointer, name). | | `citations` | `array` | No | - | Claim sources, upserted by index across calls. Use only for factual claims the reader cannot already see in the thread or task tree, 1-2 sources; none on delegation, routing, acks, or status replies. Reference each one in output with [citation:N], or set general: true for a source that backs the whole answer (it renders under "General sources"). ref per kind: task = task UUID; memory = memory UUID (optional quote must appear verbatim in it); github = owner/repo#N, owner/repo@, or a github.com pull, issues, or commit URL; slack = permalink or channel/ts; agent-fs = file path; page = page id; script-run = script run id; url = http(s) URL. The first completing call is refused, and the task stays in progress, if a marker has no entry, a citation fails validation, or a non-general citation is unreferenced; the response lists each problem. After one refusal, completion proceeds and those markers and sources are dropped from rendered output. At most 50 citations per call/task, refs up to 2048 characters, labels up to 200. Invalid or oversized batches are ignored; existing indices can still be updated at capacity. | | `persistMemory` | `boolean` | No | - | Opt in to task_completion memory persistence for automatic/recurring tasks. Manual tasks are persisted by default; scheduled, system, heartbeat/boot-triage, monitor, and digest tasks are skipped unless this is true. | | `force` | `boolean` | No | - | On an already-terminal task, overwrite explicitly provided output and/or failureReason text while preserving status and finishedAt and without replaying events, memory writes, follow-up creation, business-use ensure, or capacity updates. Differing terminal text is otherwise discarded and reported as a failure. | ### my-agent-info **Get your agent info** Returns your agent ID based on the X-Agent-ID header. *No parameters* ### cancel-task **Cancel Task** Cancel a task that is pending or in progress. Only the lead or task creator can cancel tasks. The worker will be notified via hooks. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `taskId` | `uuid` | Yes | - | The ID of the task to cancel. | | `reason` | `string` | No | - | Reason for cancellation. | ### resolve-user **Resolve user identity** Provider-agnostic reverse lookup: (kind, externalId) → user, e.g. {kind: 'slack', externalId: 'U016H7XKZGS'} or {kind: 'github', externalId: 'octocat'} — the same shape for every provider, no per-provider keys. Also accepts email (primary or alias), userId (reverse lookup of all linked identities), or name (exact/prefix search). A miss returns a structured {status: 'unknown', ...} payload, never prose; an ambiguous name search returns {status: 'ambiguous', candidates: [...]}. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `kind` | `string` | No | - | Identity kind — e.g. 'slack', 'linear', 'github', 'gitlab', 'jira', 'kapso', 'whatsapp', or a custom value. Must be paired with externalId. | | `externalId` | `string` | No | - | Platform-specific identifier for the given kind (e.g. Slack user ID 'U08NR6QD6CS', Linear user UUID, GitHub login, Jira accountId). | | `email` | `string` | No | - | Email address (primary or alias). | | `userId` | `string` | No | - | Canonical swarm user ID. Use this to reverse-look up all external identities for a known user (e.g. find their GitHub handle from a requestedByUserId). | | `name` | `string` | No | - | Human display name to search for (exact, or first-token prefix). Convenience only — ambiguous matches return all candidates rather than picking one. | ### manage-user **Manage user profiles** Create, update, delete, or list user profiles in the user registry. Identities are managed via an `identities: [{kind, externalId}]` array (declarative — update computes diff). comms is the merge-safe way to set communication preferences; metadata replaces the whole blob. Lead-only. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `create \| update \| delete \| list \| get` | Yes | - | Action to perform | | `userId` | `string` | No | - | User ID (required for update/delete/get) | | `name` | `string` | No | - | Display name (required for create) | | `email` | `string` | No | - | Primary email address | | `role` | `string` | No | - | Role (e.g., "founder", "engineer") | | `notes` | `string` | No | - | Free-form notes | | `identities` | `array` | No | - | List of platform identities to link. On create: every entry is linked. On update: the list is treated as the desired set — entries not currently linked are added (identity_added), entries currently linked but missing are removed (identity_removed). | | `emailAliases` | `array` | No | - | Additional email addresses | | `preferredChannel` | `string` | No | - | Preferred contact channel | | `timezone` | `string` | No | - | Timezone (e.g., America/New_York) | | `dailyBudgetUsd` | `number` | No | - | Daily budget in USD (null clears the cap) | | `status` | `invited \| active \| suspended` | No | - | User status — invited / active / suspended | | `metadata` | `object` | No | - | Free-form JSON metadata (null clears the field) | | `comms` | `object` | No | - | Merge-safe write to metadata.comms without touching sibling metadata keys; null removes only the comms key. When metadata is also provided, it is applied first and replaces the whole blob. | ### db-query **Execute database query** Execute a read-only SQL query against the swarm database (SQLite). Available to all authenticated agents — be aware results may include secrets (oauth_tokens, configs). Runs in a short-lived child process with a wall-clock budget by default (fails gracefully with a timeout or a 429-style concurrency error rather than freezing); results capped at a default row count (operator-configurable via `DB_QUERY_MCP_MAX_ROWS`) regardless of how many the query matched. See the sql parameter's description for which tables are unsafe to read whole, and the db-query-guidance skill for config knobs. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `sql` | `string` | No | - | Read-only SQL query (writes are rejected). Runs with a wall-clock budget in a bounded child process by default, and results are capped at a default row count (operator-configurable via `DB_QUERY_MCP_MAX_ROWS`) — a query is safe to try even against a huge table. session_logs, agent_log, events, and task_context_snapshots are too large to read whole: filter on an indexed column (session_logs: taskId/sessionId; agent_log: agentId/taskId/eventType/createdAt) and add a LIMIT, don't COUNT(*)/SUM(...)/typeof() across the table, and don't split a large read into rowid chunks — each chunk still reads every row in its range. See the db-query-guidance skill for the operator config knobs (timeout, row cap, concurrency cap) if a query keeps timing out or getting rejected. | | `query` | `string` | No | - | Deprecated runtime alias for sql. | | `params` | `array` | No | [] | Query parameters | ### get-oauth-access-token **Get OAuth access token** Return a valid plaintext OAuth access token for an integrated tracker. The token is refreshed first when it is near expiry. Returns access_token only; never returns refresh_token. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `provider` | `string` | No | - | OAuth provider slug to resolve the default authorization (for example: linear, jira). Provide this OR authorizationId. | | `authorizationId` | `string` | No | - | Explicit oauth_authorizations id to resolve. Takes precedence over provider when both are given. | | `minValiditySeconds` | `number` | No | 300 | Minimum remaining token lifetime required before returning it. | ### accept-steer **Accept Steering** Acknowledge a live steering message after you have incorporated it into your current task. Pass the ID from the `[steering ]` marker on the message. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `steeringMessageId` | `uuid` | Yes | - | The steering message ID to acknowledge. | | `note` | `string` | No | - | Optional short note describing how the steering was incorporated. | ### steer-task **Steer Task** Send a message to a task that is already running. `mode:"steer"` is honored on pi and claude-managed; claude, devin, opencode and codex support queue only (codex delivery lands at the next tool-call boundary via its lifecycle hooks). Pass `onUnsupported:"fail"` to get an error instead of a downgrade. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `taskId` | `uuid` | Yes | - | The ID of the running task to steer. | | `message` | `string` | Yes | - | The message to send to the task. | | `mode` | `steer \| queue` | No | "queue" | Deliver at a turn boundary or interrupt. | | `onUnsupported` | `degrade \| fail` | No | "degrade" | Whether an unsupported mode should degrade or return an error. | ## Task Pool Tools *Task pool capability - task pool operations (create unassigned, claim, release, accept, reject)* Capability: `task-pool` (enabled by default) ### task-action **Task Pool Actions** Perform task pool operations: create unassigned tasks, claim/release tasks from pool, accept/reject offered tasks. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `create \| claim \| release \| accept \| reject \| to_backlog \| from_backlog` | Yes | - | The action to perform: 'create' creates an unassigned task, 'claim' takes a task from pool, 'release' returns task to pool, 'accept' accepts offered task, 'reject' declines offered task, 'to_backlog' moves task to backlog, 'from_backlog' moves task from backlog to pool. | | `task` | `string` | No | - | Task description (required for 'create'). | | `key` | `unknown` | No | - | Logical namespace for a created task. Defaults to a shared/task:/ resource key. | | `taskType` | `string` | No | - | Task type (e.g., 'bug', 'feature'). | | `tags` | `array` | No | - | Tags for filtering (e.g., ['urgent', 'frontend']). | | `priority` | `number` | No | - | Priority 0-100, default 50. | | `dependsOn` | `array` | No | - | Task IDs this task depends on. | | `taskId` | `uuid` | No | - | Task ID (required for claim/release/accept/reject). | | `reason` | `string` | No | - | Reason for rejection (optional for 'reject'). | | `dir` | `string` | No | - | Working directory (absolute path) for the agent to start in. Only used with 'create' action. | | `model` | `string` | No | - | Concrete model override for the created task, interpreted by the claiming worker's harness/provider. This does not switch providers. Only used with 'create' action. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected. | | `modelTier` | `smol \| regular \| smart \| ultra` | No | - | Portable model tier for the created task: 'smol', 'regular', 'smart', or 'ultra'. Resolved when a worker claims/runs the task. Only used with 'create' action. | | `allowCustomModel` | `boolean` | No | - | Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only used with 'create' action. | | `effort` | `off \| low \| medium \| high \| xhigh \| max` | No | - | Reasoning effort for the created task: 'off', 'low', 'medium', 'high', 'xhigh', or 'max'. Only used with 'create' action. | | `requiredCapabilities` | `array` | No | - | Capabilities required for pool routing. | | `leadOnly` | `boolean` | No | false | Structured authorization constraint: only Lead agents may claim this privileged task. | ## Config Tools *Config capability - swarm config management and credential bindings* Capability: `config` (enabled by default) ### set-config **Set Config** Set or update a swarm configuration value. Upserts by (scope, scopeId, key). Use scope='global' for server-wide settings, 'agent' for agent-specific, or 'repo' for repo-specific. Set isSecret=true to mask the value in API responses. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scope` | `global \| agent \| repo` | Yes | - | Config scope: 'global', 'agent', or 'repo'. | | `scopeId` | `string` | No | - | Agent ID or repo ID. Required for 'agent' and 'repo' scopes, omit for 'global'. | | `key` | `string` | Yes | - | Configuration key (e.g., 'AGENTMAIL_WEBHOOK_SECRET'). | | `value` | `string` | Yes | - | Configuration value. | | `isSecret` | `boolean` | No | - | If true, value is masked in API responses (default: false). | | `envPath` | `string` | No | - | Optional: file path to write the value as KEY=VALUE in a .env file. | | `description` | `string` | No | - | Optional human-readable description of this config entry. | ### get-config **Get Config** Get resolved configuration values with scope resolution (repo > agent > global). Returns one entry per unique key with the most-specific scope winning. Use includeSecrets=true to see secret values. IMPORTANT: never pass returned secret values directly on a command line — write them to a temp .env file and source it instead, so the literal value stays out of logged commands. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | No | - | Agent ID for scope resolution. Omit for global-only configs. | | `repoId` | `string` | No | - | Repo ID for scope resolution. Omit for agent/global-only configs. | | `key` | `string` | No | - | Filter by specific key. If omitted, returns all resolved configs. | | `includeSecrets` | `boolean` | No | - | If true, include actual secret values (default: false, secrets are masked). | ### list-config **List Config** List raw config entries with optional filters. Unlike get-config, this returns raw entries without scope resolution — useful for seeing exactly what's configured at each scope level. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scope` | `global \| agent \| repo` | No | - | Filter by scope: 'global', 'agent', or 'repo'. | | `scopeId` | `string` | No | - | Filter by agent ID or repo ID. | | `key` | `string` | No | - | Filter by specific key. | | `includeSecrets` | `boolean` | No | - | If true, include actual secret values (default: false). | ### delete-config **Delete Config** Delete a swarm configuration entry by its ID. Use list-config to find config IDs first. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | The config entry ID to delete. | ### credential-bindings **Credential Bindings** Advanced, lead-only management for standalone scripts-runtime credential broker bindings — the escape hatch for authenticating spec-less raw fetch() egress. Most connections should embed auth inline via the script-connections tool (which auto-manages its binding); those managed bindings are hidden here. Bindings map config keys to allowed egress hosts; scripts consume them only through fetch-layer placeholder substitution. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `list \| upsert \| disable \| oauth-app-upsert \| oauth-authorize-url \| oauth-authorizations-list` | Yes | - | List, add/update, disable, register/authorize OAuth apps, or list an app's authorizations. | | `id` | `string` | No | - | Existing credential binding ID for update or disable. | | `configKey` | `string` | No | - | Swarm config key whose secret value is injected through templates. | | `allowedHosts` | `array` | No | - | Allowed outbound hostnames for this binding. | | `headerTemplate` | `string` | No | - | Header template containing the config-key placeholder. | | `queryTemplate` | `string` | No | - | Query parameter template containing the config-key placeholder. | | `scope` | `global \| agent \| repo` | No | "global" | Binding visibility scope. | | `scopeId` | `unknown` | No | - | Agent UUID for agent scope or repo id (owner/name) for repo scope. | | `authKind` | `config \| oauth` | No | "config" | Use config for stored swarm config secrets or oauth for OAuth token resolution. | | `oauthAuthorizationId` | `string` | No | - | OAuth authorization ID required when authKind is oauth. | | `presetId` | `string` | No | - | Curated OAuth preset id (e.g. google, slack, github) for oauth-app-upsert. Fills endpoints/scopes/quirks; explicit fields still win. Only clientId + clientSecret are then required. | | `provider` | `string` | No | - | OAuth provider slug for oauth-app-upsert, oauth-authorize-url, and oauth-authorizations-list. | | `label` | `string` | No | - | Authorization label for oauth-authorize-url (defaults to 'default'). N per app. | | `clientId` | `string` | No | - | OAuth client ID for oauth-app-upsert. | | `clientSecret` | `string` | No | - | OAuth client secret for oauth-app-upsert. | | `authorizeUrl` | `string` | No | - | OAuth authorization URL for oauth-app-upsert. | | `tokenUrl` | `string` | No | - | OAuth token URL for oauth-app-upsert. | | `userinfoUrl` | `string` | No | - | OIDC userinfo endpoint for identity capture (SSRF-validated). | | `revocationUrl` | `string` | No | - | RFC 7009 revocation endpoint (SSRF-validated). | | `scopes` | `array` | No | - | OAuth scopes for oauth-app-upsert. | | `extraParams` | `object` | No | - | Extra OAuth authorization parameters stored with the OAuth app. | | `tokenAuthStyle` | `body \| basic` | No | - | How client credentials reach the token endpoint: body params (default) or HTTP Basic auth (required by e.g. Notion). | | `tokenBodyFormat` | `form \| json` | No | - | Token request body encoding: form-urlencoded (default) or JSON (required by e.g. Notion). | ### model-catalog-refresh **Refresh Model Catalog** Refresh the swarm model catalog (and pricing rows) from models.dev, like `pi update --models`. Without force, skips the network when the last check is under 4h old. A forced refresh is accepted once per minute; a second one inside that window returns `skipped-cooldown` with `retryAfterMs`. Lead agent only. Returns the status, model count, and newly added provider/modelId keys. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `force` | `boolean` | No | - | Fetch even if the last check is under 4h old (default false). Rate limited to one per minute. | ### model-catalog-overlay-upsert **Upsert Model Catalog Overlay** Add or update hand-verified facts for one model (e.g. a launch models.dev has not listed yet). Overlay fields win over models.dev; overlay prices fill pricing-table gaps so cost recompute prices the model. The row auto-expires once models.dev matches every fact you set. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `provider` | `string` | Yes | - | models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode. | | `modelId` | `string` | Yes | - | Model id as models.dev keys it (e.g. claude-opus-5-5). | | `name` | `string` | No | - | Display name. | | `releaseDate` | `string` | No | - | Release date, YYYY-MM-DD. | | `contextWindow` | `number` | No | - | Context window, tokens. | | `maxOutput` | `number` | No | - | Max output tokens. | | `reasoningOptions` | `array` | No | - | Reasoning options, models.dev shape: [{type, values?}]. | | `pricing` | `object` | No | - | USD per million tokens. | | `reason` | `string` | Yes | - | Why this overlay exists (source of the facts). | | `verifiedBy` | `string` | No | - | Who verified the facts (URL, person, agent). | ## Scripts Tools *Scripts capability - reusable script catalog (HTTP MCP only in v1)* Capability: `scripts` (enabled by default) ### script-search **Script Search** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | `string` | No | "" | Search query for reusable scripts. | | `scope` | `unknown` | No | - | Optional script scope filter. | | `limit` | `number` | No | 10 | Maximum results. | ### script-connections **Script Connections** Lead-only registry management for scripts ctx.api/ctx.mcp connections. Supports OpenAPI, MCP, and GraphQL script connections. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `list \| upsert-openapi \| upsert-mcp \| upsert-graphql \| refresh \| disable` | Yes | - | List, create/update, refresh, or disable a script connection. | | `id` | `string` | No | - | Existing connection ID for update, refresh, or disable. | | `slug` | `string` | No | - | Stable script namespace slug exposed under ctx.api or ctx.mcp. | | `displayName` | `string` | No | - | Human-readable connection name. | | `scope` | `global \| agent \| repo` | No | - | Connection visibility scope. | | `scopeId` | `unknown` | No | - | Agent UUID for agent scope or repo id (owner/name) for repo scope. | | `mcpServerId` | `string` | No | - | Registered MCP server ID for upsert-mcp connections. | | `baseUrl` | `string` | No | - | Base URL for OpenAPI or GraphQL connections. | | `allowedHosts` | `array` | No | - | Allowed outbound hostnames for credential substitution. | | `credentialBindingId` | `string` | No | - | Existing credential binding ID to attach to the connection. | | `auth` | `unknown` | No | - | Inline connection auth. type=bearer|header|query with an inline `secret` (stored encrypted under a derived key) or a shared `configKey`; type=oauth with an `authorizationId`; type=none clears auth. Auto-manages the connection's credential binding. | | `configKey` | `string` | No | - | Deprecated flat alias for auth: config key for a derived credential binding. | | `headerTemplate` | `string` | No | - | Deprecated flat alias for auth: header template containing the config-key placeholder. | | `queryTemplate` | `string` | No | - | Deprecated flat alias for auth: query parameter template containing the config-key placeholder. | | `openapiSpecUrl` | `string` | No | - | URL to fetch and store an OpenAPI spec for upsert-openapi and refresh. | | `openapiSpecJson` | `string` | No | - | Inline OpenAPI JSON for upsert-openapi. Mutually exclusive with openapiSpecUrl. | | `specSource` | `object` | No | - | Vendored OpenAPI source. Mutually exclusive with openapiSpecUrl and openapiSpecJson. | | `enabled` | `boolean` | No | - | Whether the connection is enabled. | ### script-apis **Script APIs** Manage external HTTP API endpoints for swarm scripts (POST /api/x/script/). list/create/update/rotate/delete. Bearer tokens are masked ('********') on list unless includeSecrets=true; create and rotate always return the fresh plaintext token once — the only time it's visible without an explicit reveal. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `list \| create \| update \| rotate \| delete` | Yes | - | list: endpoints for a script, tokens masked unless includeSecrets=true. create: expose the script as a new endpoint (returns the plaintext token once). update: enable/disable or relabel an endpoint. rotate: issue a new token (returns it once). delete: remove an endpoint. | | `scriptId` | `string` | Yes | - | The script the endpoint(s) belong to. | | `endpointId` | `string` | No | - | Required for update, rotate, and delete. | | `authMode` | `none \| bearer` | No | - | For create: 'bearer' (default, auto-generated token) or 'none' (no auth). | | `label` | `string` | No | - | For create/update. | | `agentId` | `string` | No | - | For create: the agent the endpoint runs as (its egress secrets + API connections apply). Defaults to the script's owning agent; required if the script has none. | | `enabled` | `boolean` | No | - | For update: enable or disable the endpoint. | | `includeSecrets` | `boolean` | No | - | For list only: reveal real bearer tokens (default: false — tokens come back masked as '********', mirroring get-config's includeSecrets). | ### script-run **Script Run** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `unknown` | No | - | Name of a reusable script to run. | | `source` | `string` | No | - | Inline TypeScript source to run without a compile-time typecheck. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" for promotion-safe typing. | | `args` | `unknown` | No | - | JSON-serializable script arguments. | | `intent` | `string` | No | "" | Why this script is being run. | | `scope` | `unknown` | No | - | Optional scope for named script resolution. | | `fsMode` | `unknown` | No | "none" | Filesystem mode. v1 supports none only. | | `idempotencyKey` | `string` | No | - | When set, output is auto-persisted to kv under script:executions/{key}. Re-running with the same key overwrites. Queryable via kv-get. | ### script-upsert **Script Upsert** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `unknown` | Yes | - | Stable script name within the selected scope. | | `source` | `string` | Yes | - | TypeScript source, typechecked before saving. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" to type `ctx`. | | `description` | `string` | No | "" | Human-readable script description. | | `intent` | `string` | No | "" | Why this script exists. | | `scope` | `unknown` | No | "agent" | Persist under agent or global scope. | | `fsMode` | `unknown` | No | "none" | Filesystem mode. v1 supports none only. | ### extension-delete **Extension Delete** Uninstall a disabled extension and delete its stored history. Disable it first with extension-disable. Requires a lead, operator, or dashboard user. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Installed extension ID from extension-list. | ### extension-enable **Extension Enable** Load and enable an installed extension. Requires a lead, operator, or dashboard user. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Installed extension ID from extension-list. | ### extension-disable **Extension Disable** Unload and disable an installed extension. Requires a lead, operator, or dashboard user. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Installed extension ID from extension-list. | ### extension-activate-version **Extension Activate Version** Activate a stored extension version, reloading it if enabled. Requires a lead, operator, or dashboard user. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Installed extension ID from extension-list. | | `version` | `number` | Yes | - | Stored version number to activate. | ### extension-catalog **Extension Catalog** *No parameters* ### extension-install **Extension Install** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `template` | `string` | No | - | Name of a predefined extension from extension-catalog. Mutually exclusive with manifest and files. | | `manifest` | `unknown` | No | - | Inline bundle manifest. Requires files. Needs EXTENSION_ALLOW_INLINE_INSTALL and a lead, operator, or dashboard-user caller. | | `files` | `object` | No | - | Inline bundle files keyed by relative path. Requires manifest. | | `priority` | `number` | No | - | Handler priority. Lower values run first. | | `config` | `object` | No | - | Extension configuration. | ### extension-list **Extension List** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `enabledOnly` | `boolean` | No | - | Return only enabled extensions. | ### script-delete **Script Delete** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `unknown` | Yes | - | Script name to delete. | | `scope` | `unknown` | No | "agent" | Script scope to delete from. | ### script-query-types **Script Query Types** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `unknown` | No | - | Optional script name whose signature should be fetched. Omit to get the swarm-wide sdk/stdlib type surface. | | `scope` | `unknown` | No | - | Optional scope for script resolution. | ### launch-script-run **Launch Script Run** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `source` | `string` | Yes | - | TypeScript script workflow source. Must `export default async function (args, ctx)` — args FIRST, ctx second. | | `args` | `unknown` | No | - | JSON-serializable workflow arguments. | | `idempotencyKey` | `string` | No | - | Optional key that returns the existing run instead of launching a duplicate. | | `scriptName` | `unknown` | No | - | Optional human-readable script/workflow name for the run. | | `requestedByUserId` | `string` | No | - | Optional canonical user ID to attribute the run to. | ### get-script-run **Get Script Run** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Script run ID. | ### list-script-runs **List Script Runs** | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `status` | `running \| paused \| completed \| failed \| cancelled \| aborted_limit` | No | - | Optional script run status filter. | | `agentId` | `string` | No | - | Optional agent ID filter. | | `limit` | `number` | No | 50 | Maximum runs to return. | | `offset` | `number` | No | 0 | Pagination offset. | ## MCP Server Tools *MCP capability - managed MCP server registry (CRUD + install/uninstall)* Capability: `mcp` (enabled by default) ### mcp-server-create **Create MCP Server** Create a new MCP server definition. Agent-scope servers are auto-installed for the creating agent. Swarm/global scope requires lead. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | Yes | - | Server name | | `description` | `string` | No | - | Server description | | `transport` | `stdio \| http \| sse` | Yes | - | Transport type | | `scope` | `global \| swarm \| agent` | No | "agent" | Scope: agent (personal), swarm (shared), or global. Default: agent | | `command` | `string` | No | - | Command to run (required for stdio transport) | | `args` | `string` | No | - | JSON array of command arguments (stdio only) | | `url` | `string` | No | - | Server URL (required for http/sse transport) | | `headers` | `string` | No | - | JSON object of non-secret headers (http/sse only) | | `envConfigKeys` | `string` | No | - | JSON object mapping env var names to config key paths | | `headerConfigKeys` | `string` | No | - | JSON object mapping header names to config key paths for secret headers | | `extraAuthorizeParams` | `string` | No | - | JSON object string of extra OAuth authorize-request params, e.g. {"access_type":"offline","prompt":"consent"} | ### mcp-server-update **Update MCP Server** Update an MCP server's configuration. Only the owner or lead can update. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | ID of the MCP server to update | | `name` | `string` | No | - | New name | | `description` | `string` | No | - | New description | | `transport` | `stdio \| http \| sse` | No | - | New transport type | | `command` | `string` | No | - | New command (stdio) | | `args` | `string` | No | - | New JSON array of arguments (stdio) | | `url` | `string` | No | - | New URL (http/sse) | | `headers` | `string` | No | - | New JSON object of non-secret headers | | `envConfigKeys` | `string` | No | - | New env config key mappings | | `headerConfigKeys` | `string` | No | - | New header config key mappings | | `extraAuthorizeParams` | `string` | No | - | JSON object string of extra OAuth authorize-request params, e.g. {"access_type":"offline","prompt":"consent"} | | `isEnabled` | `boolean` | No | - | Toggle enabled/disabled | ### mcp-server-delete **Delete MCP Server** Delete an MCP server definition. Only the owning agent or lead can delete. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | ID of the MCP server to delete | ### mcp-server-get **Get MCP Server** Get MCP server details by ID or name. Name resolution uses scope cascade: agent > swarm > global. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | No | - | MCP server ID | | `name` | `string` | No | - | MCP server name (resolved with scope cascade) | ### mcp-server-list **List MCP Servers** List MCP servers with optional filters. Use installedOnly to see servers installed for the calling agent. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scope` | `global \| swarm \| agent` | No | - | Filter by scope | | `transport` | `stdio \| http \| sse` | No | - | Filter by transport type | | `search` | `string` | No | - | Search by name or description | | `installedOnly` | `boolean` | No | - | Only show servers installed for the calling agent | ### mcp-server-install **Install MCP Server** Install an MCP server for an agent. Self-install is always allowed; cross-agent install requires lead. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `mcpServerId` | `string` | Yes | - | ID of the MCP server to install | | `agentId` | `string` | No | - | Target agent (default: calling agent). Lead can install for others. | ### mcp-server-uninstall **Uninstall MCP Server** Uninstall an MCP server from an agent. Self-uninstall is always allowed; cross-agent requires lead. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `mcpServerId` | `string` | Yes | - | ID of the MCP server to uninstall | | `agentId` | `string` | No | - | Target agent (default: calling agent) | ## Profiles Tools *Profiles capability - agent profile management* Capability: `profiles` (enabled by default) ### update-profile **Update Profile** Updates an agent's profile information (name, description, role, capabilities). By default updates the calling agent. Lead agents can update any agent's profile by providing the agentId parameter. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | No | - | Target agent ID to update. If omitted, updates the calling agent. Only lead agents can update other agents' profiles. | | `name` | `string` | No | - | Agent name. | | `description` | `string` | No | - | Agent description. | | `role` | `string` | No | - | Agent role (free-form, e.g., 'frontend dev', 'code reviewer'). | | `capabilities` | `array` | No | - | List of capabilities (e.g., ['typescript', 'react', 'testing']). | | `claudeMd` | `string` | No | - | Personal CLAUDE.md content. Loaded on session start and synced back on session end. Above 20,000 characters, updates may only keep or reduce the stored size; move durable overflow into memory. | | `soulMd` | `string` | No | - | Soul content: persona and behavioral directives. Updates both DB and /workspace/SOUL.md. Must be at least 200 characters; above 10,000 characters, updates may only keep or reduce the stored size. | | `identityMd` | `string` | No | - | Identity content: expertise and working style. Updates both DB and /workspace/IDENTITY.md. Must be at least 200 characters; above 10,000 characters, updates may only keep or reduce the stored size. | | `setupScript` | `string` | No | - | Setup script content (bash). Runs at container start as the worker user after privilege drop. Persists across sessions. Also written to /workspace/start-up.sh. | | `toolsMd` | `string` | No | - | Environment-specific operational knowledge. Synced to /workspace/TOOLS.md. Above 20,000 characters, updates may only keep or reduce the stored size; move durable overflow into memory. | | `heartbeatMd` | `string` | No | - | Heartbeat checklist content (HEARTBEAT.md). Checked periodically — add standing orders for the lead to review. Synced to /workspace/HEARTBEAT.md. | | `avatar` | `unknown` | No | - | Custom avatar: { type: 'lucide', icon: '', color?: '#RRGGBB' }. Pass null to reset to the default deterministic icon/color. | ### context-history **Context History** View version history for an agent's context files (soulMd, identityMd, toolsMd, claudeMd, setupScript). Returns metadata for each version without full content. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | No | - | Agent ID to query. Default: your own agent. Lead can query any agent. | | `field` | `soulMd \| identityMd \| toolsMd \| claudeMd \| setupScript` | No | - | Filter by specific field. Omit for all fields. | | `limit` | `number` | No | - | Max versions to return (default: 10). | ### context-diff **Context Diff** Compare two versions of a context file. Shows a unified diff between the specified version and its predecessor (or a specific comparison version). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `versionId` | `string` | Yes | - | The "newer" version ID to diff. | | `compareToVersionId` | `string` | No | - | The "older" version ID to compare against. Default: previous version. | ## Repo Tools *Repo capability - repository configuration management* Capability: `repo` (enabled by default) ### get-repos **Get Repos** List registered repos with their guidelines (PR checks, merge policy, review guidance). Use the optional name filter to check a specific repo. The lead should use this to verify a repo has guidelines before routing tasks. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | No | - | Filter by repo name. If omitted, returns all repos. | ### update-repo **Update Repo** Update a repo's configuration including guidelines (PR checks, merge policy, review guidance). The lead uses this to set guidelines after asking the user. Pass null for guidelines to clear them. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | The repo ID to update. | | `url` | `string` | No | - | New repo URL. | | `name` | `string` | No | - | New repo name. | | `clonePath` | `string` | No | - | New clone path. | | `defaultBranch` | `string` | No | - | New default branch. | | `autoClone` | `boolean` | No | - | Whether to auto-clone. | | `hooks` | `unknown` | No | - | Repository hook install config. Set { enabled: true } to opt into best-effort worker hook installation, or null to disable. | | `guidelines` | `unknown` | No | - | Repository guidelines: prChecks (commands before PR), mergeChecks (conditions before merge), allowMerge (default false), review (guidance for reviewers). Pass null to clear. | ## Scheduling Tools *Scheduling capability - scheduled task management* Capability: `scheduling` (enabled by default) ### list-schedules **List Scheduled Tasks** View all scheduled tasks with optional filters. Use this to discover existing schedules. Rows are slim by default — the full `taskTemplate` is replaced with a short `taskTemplatePreview`; pass includeFull:true (or call `get-schedule` by id) for the full template. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `enabled` | `boolean` | No | - | Filter by enabled status | | `name` | `string` | No | - | Filter by name (partial match) | | `key` | `unknown` | No | - | Filter by exact namespace. | | `keyPrefix` | `unknown` | No | - | Filter by namespace subtree. | | `scheduleType` | `recurring \| one_time` | No | - | Filter by schedule type | | `hideCompleted` | `boolean` | No | true | Hide completed one-time schedules (default: true) | | `consecutiveErrorsMin` | `number` | No | - | Only return schedules with at least this many consecutive dispatch errors (the scheduler failed to create the task, workflow run, or script run). Does not count spawned tasks that later failed; for those use get-tasks with scheduleId and status failed. | | `lastRunStatus` | `failed \| succeeded` | No | - | Filter by derived last dispatch status. `failed` means consecutiveErrors > 0 (the last dispatch attempt errored); `succeeded` means lastRunAt is set and consecutiveErrors is 0. Reflects dispatch only, not the outcome of spawned tasks; for those use get-tasks with scheduleId and status failed. | | `includeFull` | `boolean` | No | - | Return the full `taskTemplate` instead of a short `taskTemplatePreview`. Default false. | ### create-schedule **Create Scheduled Task** Create a new scheduled task. For recurring: provide cronExpression or intervalMs. For one-time: provide delayMs or runAt with scheduleType 'one_time'. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | No | - | Logical namespace. Defaults to a shared/schedule:/ resource key. | | `name` | `string` | Yes | - | Unique name for the schedule (e.g., 'daily-cleanup') | | `taskTemplate` | `string` | No | - | The task description that will be created each time. Required when targetType is 'agent-task' (the default). | | `targetType` | `agent-task \| workflow \| script` | No | "agent-task" | Execution target. Use 'workflow' + workflowId when the schedule only starts a workflow; use 'script' + scriptName/scriptArgs when it only runs a catalog script; use 'agent-task' only when a reasoning agent genuinely needs to be in the loop. Do not create an agent-task whose taskTemplate just tells an agent to trigger a workflow or script. | | `workflowId` | `string` | No | - | Workflow ID to trigger. Required when targetType is 'workflow'. | | `scriptName` | `string` | No | - | Catalog script name (global scope). Required when targetType is 'script'. | | `scriptArgs` | `object` | No | - | JSON args passed to the script. Used when targetType is 'script'. | | `scheduleType` | `recurring \| one_time` | No | "recurring" | Schedule type: 'recurring' (default) or 'one_time' | | `cronExpression` | `string` | No | - | Cron expression for recurring schedules (e.g., '0 9 * * *') | | `intervalMs` | `number` | No | - | Interval in milliseconds for recurring schedules (e.g., 3600000 for hourly) | | `delayMs` | `number` | No | - | Delay in milliseconds for one-time schedules (e.g., 1800000 for 30 min) | | `runAt` | `string` | No | - | ISO datetime for one-time schedules (e.g., '2026-03-06T15:00:00Z') | | `description` | `string` | No | - | Human-readable description of the schedule | | `taskType` | `string` | No | - | Task type (e.g., 'maintenance', 'report') | | `tags` | `array` | No | - | Tags to apply to created tasks | | `priority` | `number` | No | 50 | Task priority 0-100 (default: 50) | | `targetAgentId` | `string` | No | - | Agent to assign tasks to (omit for task pool) | | `timezone` | `string` | No | "UTC" | Timezone for cron schedules | | `enabled` | `boolean` | No | true | Whether the schedule is enabled (default: true) | | `model` | `string` | No | - | Concrete model override for tasks created by this schedule. Interpreted by each assignee's harness/provider and does not switch providers. Prefer modelTier for portable intent. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected. | | `modelTier` | `smol \| regular \| smart \| ultra` | No | - | Portable model tier for tasks created by this schedule: 'smol', 'regular', 'smart', or 'ultra'. Resolved by each assignee's harness/provider at run time. | | `allowCustomModel` | `boolean` | No | - | Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet. | ### defer-task **Defer Task** Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output unless the task has an outputSchema. For a task with an outputSchema, provide output as a JSON string matching that schema; it is stored verbatim as terminal output, while deferral details remain visible in the task log. A one-off schedule wakes you up later with a child task that carries this task as its parent. Optionally provide wakeOn with taskId or taskIds to wake early on task outcomes; mode defaults to all, or use any for the first match. delayMs or runAt remains required as the ceiling for the whole set. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `taskId` | `string` | Yes | - | The ID of the task you are working on. | | `delayMs` | `number` | No | - | Wake up after this many milliseconds (e.g. 1800000 for 30 min). | | `runAt` | `string` | No | - | Wake up at this ISO datetime (e.g. '2026-03-06T15:00:00Z'). Must be future. | | `wakeOn` | `object` | No | - | Wake early on a task event. Provide taskId or nonempty, unique taskIds. mode defaults to all (every member must match); any wakes on the first match. settled covers completed, failed, or cancelled. Deferred and superseded members follow their continuations; a superseded member without a resume child holds to the ceiling. Any already-terminal member rejects the request; one delayMs/runAt ceiling is still required for the whole set. The member whose settlement wakes you creates no separate lead follow-up for your agent unless its followUpConfig sets onCompleted/onFailed; an all-mode member that settles while others are pending still does. | | `summary` | `string` | Yes | - | What you did so far and where things stand. Stored in the task log for tasks with an outputSchema; otherwise becomes the task's output. | | `output` | `string` | No | - | Required when the task has an outputSchema: a JSON string matching that schema, stored verbatim as terminal output. Ignored for tasks without an outputSchema. | | `note` | `string` | Yes | - | What is pending, and what to check on wake-up. | | `checks` | `array` | No | - | Concrete things to verify on wake-up, one per entry. | ### update-schedule **Update Scheduled Task** Update an existing scheduled task. Any registered agent can update schedules. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | No | - | Move to a logical namespace. | | `scheduleId` | `string` | No | - | Schedule ID to update | | `name` | `string` | No | - | Schedule name to update (alternative to ID) | | `newName` | `string` | No | - | New name for the schedule | | `taskTemplate` | `string` | No | - | New task template | | `targetType` | `agent-task \| workflow \| script` | No | - | Change the execution target: 'agent-task', 'workflow', or 'script'. | | `workflowId` | `string` | No | - | New workflow ID (required when targetType is 'workflow'; null to clear) | | `scriptName` | `string` | No | - | New catalog script name (required when targetType is 'script'; null to clear) | | `scriptArgs` | `object` | No | - | New JSON args for the script target (null to clear) | | `cronExpression` | `string` | No | - | New cron expression (null to clear) | | `intervalMs` | `number` | No | - | New interval in milliseconds (null to clear) | | `description` | `string` | No | - | New description | | `taskType` | `string` | No | - | New task type | | `tags` | `array` | No | - | New tags | | `priority` | `number` | No | - | New priority | | `targetAgentId` | `string` | No | - | New target agent ID | | `timezone` | `string` | No | - | New timezone | | `enabled` | `boolean` | No | - | Enable or disable the schedule | | `model` | `string` | No | - | Concrete model override for tasks created by this schedule. Set to null to clear. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected. | | `modelTier` | `smol \| regular \| smart \| ultra` | No | - | Portable model tier for tasks created by this schedule. Set to null to clear. | | `allowCustomModel` | `boolean` | No | - | Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet. | ### patch-schedule **Patch Scheduled Task** Patch an existing scheduled task by shallow-merging provided fields over the current row. Any registered agent can patch schedules. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | No | - | Move to a logical namespace. | | `scheduleId` | `string` | No | - | Schedule ID to patch | | `name` | `string` | No | - | Schedule name to patch (alternative to ID) | | `newName` | `string` | No | - | New name for the schedule | | `taskTemplate` | `string` | No | - | New task template | | `targetType` | `agent-task \| workflow \| script` | No | - | Change the execution target: 'agent-task', 'workflow', or 'script'. | | `workflowId` | `string` | No | - | New workflow ID (required when targetType is 'workflow'; null to clear) | | `scriptName` | `string` | No | - | New catalog script name (required when targetType is 'script'; null to clear) | | `scriptArgs` | `object` | No | - | New JSON args for the script target (null to clear) | | `cronExpression` | `string` | No | - | New cron expression (null to clear) | | `intervalMs` | `number` | No | - | New interval in milliseconds (null to clear) | | `description` | `string` | No | - | New description | | `taskType` | `string` | No | - | New task type | | `tags` | `array` | No | - | New tags | | `priority` | `number` | No | - | New priority | | `targetAgentId` | `string` | No | - | New target agent ID | | `timezone` | `string` | No | - | New timezone | | `enabled` | `boolean` | No | - | Enable or disable the schedule | | `model` | `string` | No | - | Concrete model override for tasks created by this schedule. Set to null to clear. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected. | | `modelTier` | `smol \| regular \| smart \| ultra` | No | - | Portable model tier for tasks created by this schedule. Set to null to clear. | | `allowCustomModel` | `boolean` | No | - | Accept a `model` the model catalog does not list. Without it an unknown model id is rejected. Only for ids the catalog cannot know yet. | ### delete-schedule **Delete Scheduled Task** Delete a scheduled task permanently. Any registered agent can delete schedules. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scheduleId` | `string` | No | - | Schedule ID to delete | | `name` | `string` | No | - | Schedule name to delete (alternative to ID) | ### run-schedule-now **Run Schedule Now** Immediately execute a scheduled task, creating a task right away. Does not affect the regular schedule timing. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `scheduleId` | `string` | No | - | Schedule ID to run | | `name` | `string` | No | - | Schedule name to run (alternative to ID) | ## Memory Tools *Memory capability - persistent memory with vector search* Capability: `memory` (enabled by default) ### memory-search **Search memories** Search your accumulated memories using natural language. Returns summaries with IDs — use memory-get to retrieve full content. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | `string` | Yes | - | Natural language search query. | | `intent` | `string` | No | - | Optional reason for searching for this memory. E.g. 'looking for auth pattern to fix login bug'. | | `scope` | `all \| agent \| swarm` | No | "all" | Search scope: 'all' (own + swarm), 'agent' (own only), 'swarm' (shared only). | | `limit` | `number` | No | 10 | Max results to return. | | `source` | `manual \| file_index \| session_summary \| task_completion` | No | - | Filter by memory source type. | | `keyPrefix` | `string` | No | - | Only return memories whose key starts with this text, for example '/longterm/facts/' or '/longterm/entities/people/'. Matched literally, case-sensitive. Include the trailing '/' to stay inside one folder. | ### memory-store **Store a memory** Store a learning as a searchable memory: a fix, a pattern, a gotcha, a fact about a repo or a person. Use it when you solve something that will come back. Scope 'agent' is visible only to you. Scope 'swarm' is visible to every agent. Long content is split into chunks and embedded in the background. Search first with memory-search when a similar memory may exist, then edit it with memory-edit instead of storing a duplicate. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `content` | `string` | Yes | - | The memory body. Markdown is fine. State the fact, the context it applies to, and the evidence. | | `name` | `string` | No | - | Short title used in search results and the UI. Defaults to the first non-empty content line (up to 200 characters). A name that starts with /longterm/ is also used as the key when no key is given. | | `scope` | `agent \| swarm` | No | "agent" | 'agent' (default): only you can recall it. 'swarm': every agent can recall it. | | `tags` | `unknown` | No | - | Free-form tags as an array or a comma-separated string, for example a repo name or a topic. | | `taskId` | `uuid` | No | - | The task this learning came from, when there is one. | | `intent` | `string` | No | - | Why this is worth remembering. Kept in the audit trail. | | `key` | `string` | No | - | Optional logical path for this memory, for example '/longterm/facts/swarm-runtime/sqlite-busy-retry'. Lowercase segments joined by '/', starting with '/'. Search it with memory-search keyPrefix and move it with memory-edit newKey. Fails when you already have a memory with this key in this scope. A key under /longterm marks the memory as curated: it never expires and is protected from cleanup. It must start with /longterm/company-story, /longterm/entities/people, /longterm/entities/customers, /longterm/facts, /longterm/decisions, /longterm/workstreams or /longterm/timeline. Paths under /longterm/company-story, /longterm/entities and /longterm/timeline are lead-only. Defaults to an auto key, which makes the memory inbox material. | ### memory-get **Get memory details** Retrieve the full content of a specific memory by its ID. Use memory-search to find memory IDs first. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `memoryId` | `uuid` | No | - | The ID of the memory to retrieve (or use id). | | `id` | `uuid` | No | - | Alias for memoryId, matching memory-search results. | | `intent` | `string` | No | - | Optional reason for retrieving this memory. E.g. 'need full details of the auth fix pattern'. | ### memory-edit **Edit a memory** Edit a single memory in place while preserving its ID, usefulness posterior, and audit history. Two modes: 'replace' overwrites the entire content (requires `content`); 'exact' performs a surgical find-and-replace of `oldString` with `newString` within the existing content (fails if `oldString` is missing or ambiguous). Use 'replace' for full rewrites, 'exact' for targeted edits. Pass `newKey` alone to move the memory to another logical path (every chunk, same ID, posterior, access counts and author). A move into /longterm also clears the expiry. Agents can edit their own memories; lead agents can edit any scope. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `memoryId` | `uuid` | No | - | The memory ID to edit. | | `key` | `string` | No | - | Structured key alternative to memoryId. | | `scope` | `agent \| swarm` | No | - | Required when editing by key. | | `mode` | `replace \| exact` | No | "replace" | 'replace' overwrites the entire memory content; 'exact' finds a unique substring (oldString) and replaces it with newString. | | `content` | `string` | No | - | Full replacement content. Required for 'replace' mode, ignored in 'exact'. | | `oldString` | `string` | No | - | Substring to find in existing content. Required for 'exact' mode. Must appear exactly once. | | `newString` | `string` | No | - | Replacement for oldString. Required for 'exact' mode. Can be empty to delete. | | `intent` | `string` | Yes | - | Why you are editing this memory. | | `expectedVersion` | `number` | No | - | - | | `newKey` | `string` | No | - | Move the memory to this logical path, for example '/longterm/facts/swarm-runtime/slug'. Alone it is a pure move: omit content/oldString/newString. Fails when the key is already used in this scope by the same owner. Moving into /longterm marks the memory as curated on every chunk: it stops expiring and is protected from cleanup, and moving it out later does not bring the expiry back. A key under /longterm must start with /longterm/company-story, /longterm/entities/people, /longterm/entities/customers, /longterm/facts, /longterm/decisions, /longterm/workstreams or /longterm/timeline. Paths under /longterm/company-story, /longterm/entities and /longterm/timeline are lead-only. | ### memory-delete **Delete a memory** Delete a specific memory by its ID. Agents can delete their own memories; lead agents can also delete swarm-scoped memories. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `memoryId` | `uuid` | Yes | - | The ID of the memory to delete. | ### memory_rate **Rate a memory** Rate a memory you used in the current task. Call this when a retrieved memory was clearly useful (or actively misleading) so the swarm learns to surface better memories next time. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | No | - | Memory ID returned by memory-search (or use memoryId). | | `memoryId` | `string` | No | - | Alias for id, matching memory-get. | | `useful` | `boolean` | Yes | - | true = this memory helped solve the task; false = misled or wasted time. | | `note` | `string` | No | - | Reason, stored up to 500 characters for telemetry; not surfaced to other agents. | | `referencesSource` | `string` | No | - | Optional external source ID this memory references. Free-form string, convention ":" (e.g. "github:owner/repo#N", "linear:KEY-N", "customer:", "slack::", "agentmail:"). Pick any prefix that fits — no closed enum. When present, an edge from this memory to the external source is created/updated. | ### inject-learning **Inject learning into worker memory** Allows the lead agent to push learnings into a worker's memory. The learning will be stored as a searchable memory entry that the worker can recall in future sessions. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | Yes | - | Target worker agent ID | | `learning` | `string` | Yes | - | The learning content to inject | | `category` | `mistake-pattern \| best-practice \| codebase-knowledge \| preference` | Yes | - | Category of the learning: mistake-pattern, best-practice, codebase-knowledge, or preference | ## Tracker Tools *Tracker capability - external issue tracker integration* Capability: `tracker` (enabled by default) ### tracker-status **Tracker Status** Show all connected trackers and their OAuth status (token expiry, workspace info). Proactively refreshes near-expiry tokens before reporting, so the returned `tokenExpiresAt` reflects the row that subsequent API calls (and direct DB reads) will see. *No parameters* ### tracker-link-task **Link Task to Tracker** Link a swarm task to an external tracker issue. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `provider` | `string` | Yes | - | Tracker provider (e.g. 'linear', 'jira') | | `swarmTaskId` | `string` | Yes | - | The swarm task ID to link | | `externalId` | `string` | Yes | - | The external issue ID in the tracker | | `externalIdentifier` | `string` | No | - | Human-readable identifier (e.g. 'ENG-42') | | `externalUrl` | `string` | No | - | URL to the external issue | ### tracker-unlink **Unlink Tracker Sync** Remove a tracker sync mapping by ID. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `syncId` | `string` | Yes | - | The tracker sync mapping ID to remove | ### tracker-sync-status **Tracker Sync Status** Show all tracker sync mappings with their state. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `provider` | `string` | No | - | Filter by provider (e.g. 'linear', 'jira') | | `entityType` | `task` | No | - | Filter by entity type | ### tracker-map-agent **Map Agent to Tracker User** Map a swarm agent to an external tracker user (for assignment sync). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `provider` | `string` | Yes | - | Tracker provider (e.g. 'linear', 'jira') | | `agentId` | `string` | Yes | - | The swarm agent ID | | `externalUserId` | `string` | Yes | - | The external user ID in the tracker | | `agentName` | `string` | Yes | - | Display name for the agent mapping | ## Workflows Tools *Workflows capability - DAG-based automation workflows* Capability: `workflows` (enabled by default) ### create-workflow **Create Workflow** Create a new automation workflow. Key concepts: - Nodes are linked via 'next' (string or port-based record). - CROSS-NODE DATA: To use output from an upstream node, you MUST declare an 'inputs' mapping on the downstream node. Example: inputs: { "cityData": "generate-city" } → then use {{cityData.taskOutput.field}} in config templates. Without 'inputs', built-in trigger/input/workflow/swarm/run context remains available, but upstream outputs do not. Agent-task templates may interpolate trigger and declared upstream aliases. SECURITY: executable source for script/swarm-script nodes does not: inline script source allows only input/workflow/swarm/run values, while named swarm-script source is not workflow-interpolated. Pass dynamic trigger or upstream values through config.args (argv for inline scripts; the args object for swarm-script). - STRUCTURED OUTPUT: For agent-task nodes, put outputSchema inside 'config' to validate the agent's raw JSON output. Node-level outputSchema validates the executor's return ({taskId, taskOutput}), which is different. - Agent-task config: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }. - FOREACH NODE: type 'foreach' fans out one agent-task per item. Config: { over: , itemKey: , body: { type: 'agent-task', config: {...} } }. The body config is interpolated once per item with {{item.*}} and {{index}}. Child steps use synthetic IDs '#'; the parent waits for every child and exposes one aggregate result to successors. concurrency is not supported in v1; use definition-level onNodeFailure: 'continue' to aggregate failed children. - TRIGGER SCHEMA: Optional 'triggerSchema' is a JSON-Schema object that validates incoming trigger payloads. Supported keywords: type, required, properties, enum, const, items (recursive into arrays). Other JSON-Schema keywords (oneOf/anyOf/$ref/pattern/format/additionalProperties) are silently ignored. - WEBHOOK VERIFICATION: Webhook triggers use hmacSecret for all verification formats. Omit verification for legacy HMAC-SHA256 over the raw body with fallback header scanning; or set verification to { format: 'hmac-sha256', header }, { format: 'timestamped-hmac-sha256', header, toleranceSeconds? }, { format: 'token-equality', header }, or { format: 'standard-webhooks', toleranceSeconds? } (standardwebhooks.com: webhook-id/webhook-timestamp/webhook-signature headers, hmacSecret is the whsec_ signing secret). Example: { type: 'webhook', hmacSecret: 'secret.SUPERAGENT_WEBHOOK_SECRET', verification: { format: 'timestamped-hmac-sha256', header: 'X-Superagent-Signature', toleranceSeconds: 300 } }. - WAIT NODE: type 'wait' pauses a workflow for a duration or until a named workflowEventBus event arrives. See runbooks/workflows.md#wait-nodes for config shapes, ordering caveats, and built-in event names. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | Yes | - | Unique name for the workflow | | `key` | `unknown` | No | - | Logical namespace. Defaults to a shared/workflow:/ resource key. | | `description` | `string` | No | - | Description of what this workflow does | | `definition` | `unknown` | Yes | - | The workflow definition with nodes (each node has id, type, config, and optional next/retry/validation) | | `triggers` | `array` | No | - | Optional trigger configurations (webhook, schedule, event). Webhook verification formats: legacy omitted verification, hmac-sha256, timestamped-hmac-sha256, token-equality, standard-webhooks. | | `cooldown` | `unknown` | No | - | Optional cooldown configuration to prevent re-triggering too frequently | | `input` | `object` | No | - | Optional input values resolved at execution time (env vars like VAR_NAME, secrets secret.NAME, or literals) | | `dir` | `string` | No | - | Default working directory for all agent-task nodes (absolute path, e.g. /tmp/workspace) | | `vcsRepo` | `string` | No | - | Default VCS repo for all agent-task nodes (e.g. org/repo) | | `triggerSchema` | `object` | No | - | Optional JSON-Schema object that validates incoming trigger payloads. Supported keywords: type, required, properties, enum, const, items. Other JSON-Schema keywords are silently ignored. | ### list-workflows **List Workflows** List all automation workflows, optionally filtered by enabled status. Returns SLIM rows WITHOUT the full `definition` (DAG) — each row carries a `nodeCount` instead. To inspect or patch a workflow's nodes/triggers, call `get-workflow` by id, or pass `includeFull: true` here. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `enabled` | `boolean` | No | - | Filter by enabled status (omit to return all) | | `key` | `unknown` | No | - | Filter by exact namespace. | | `keyPrefix` | `unknown` | No | - | Filter by namespace subtree. | | `consecutiveErrorsMin` | `number` | No | - | Only return workflows with at least this many latest consecutive failed runs. | | `lastRunStatus` | `running \| waiting \| completed \| failed \| skipped \| cancelled` | No | - | Only return workflows whose latest run has this status. | | `includeFull` | `boolean` | No | - | Return the full workflow `definition` + trigger config instead of slim rows. Default false — prefer `get-workflow` to fetch a single workflow in full. | ### get-workflow **Get Workflow** Get a workflow by ID, including its definition, triggers, cooldown, input, and auto-generated edges for UI rendering. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID | ### update-workflow **Update Workflow** Update an existing workflow's name, description, definition, triggers, cooldown, input, triggerSchema, or enabled state. Creates a version snapshot before applying changes. TRIGGER SCHEMA: pass 'triggerSchema' as a JSON-Schema object to set/replace, or 'null' to clear. Supported JSON-Schema keywords: type, required, properties, enum, const, items (recursive into arrays). Other JSON-Schema keywords (oneOf/anyOf/$ref/pattern/format/additionalProperties) are silently ignored. WEBHOOK VERIFICATION: webhook triggers use hmacSecret for all verification formats. Omit verification for legacy HMAC-SHA256 over the raw body with fallback header scanning; or set verification to { format: 'hmac-sha256', header }, { format: 'timestamped-hmac-sha256', header, toleranceSeconds? }, { format: 'token-equality', header }, or { format: 'standard-webhooks', toleranceSeconds? } (standardwebhooks.com: webhook-id/webhook-timestamp/webhook-signature headers, hmacSecret is the whsec_ signing secret). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID to update | | `key` | `unknown` | No | - | Move to a logical namespace. | | `name` | `string` | No | - | New name for the workflow | | `description` | `string` | No | - | New description | | `definition` | `unknown` | No | - | New workflow definition | | `triggers` | `array` | No | - | New trigger configurations. Webhook verification formats: legacy omitted verification, hmac-sha256, timestamped-hmac-sha256, token-equality, standard-webhooks. | | `cooldown` | `unknown` | No | - | New cooldown configuration (null to remove) | | `input` | `object` | No | - | New input values (null to remove) | | `dir` | `string` | No | - | Default working directory for all agent-task nodes (null to remove) | | `vcsRepo` | `string` | No | - | Default VCS repo for all agent-task nodes (null to remove) | | `enabled` | `boolean` | No | - | Enable or disable the workflow | | `triggerSchema` | `object` | No | - | New trigger payload JSON-Schema (null to clear). Supported keywords: type, required, properties, enum, const, items. Other JSON-Schema keywords are silently ignored. | ### patch-workflow **Patch Workflow Definition** Partially update a workflow by creating, updating, or deleting individual nodes, and/or by setting/clearing the trigger payload schema. DAG operations are applied in order: delete → create → update. `triggerSchema` is independent of DAG ops: pass an object to set/replace, pass null to clear, or omit to leave unchanged. Validator subset for `triggerSchema`: type, required, properties, enum, const, items. Other JSON-Schema keywords are silently ignored. Creates a version snapshot before applying changes. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID to patch | | `key` | `unknown` | No | - | Move to a logical namespace. | | `update` | `array` | No | - | Nodes to update (partial merge) | | `delete` | `array` | No | - | Node IDs to delete | | `create` | `array` | No | - | New nodes to add | | `onNodeFailure` | `fail \| continue` | No | - | Update onNodeFailure behavior | | `triggerSchema` | `object` | No | - | Optional JSON-Schema describing the expected trigger payload. Pass an object to set/replace; pass null to clear; omit to leave unchanged. Validator subset: type, required, properties, enum, const, items. | ### patch-workflow-node **Patch Workflow Node** Partially update a single node in a workflow definition. Merges the provided fields into the existing node. Creates a version snapshot before applying changes. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID | | `nodeId` | `string` | Yes | - | Node ID to update | ### delete-workflow **Delete Workflow** Delete a workflow by ID. This also removes all associated runs and steps. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID to delete | ### trigger-workflow **Trigger Workflow** Manually trigger a workflow execution, optionally passing trigger data as context. Respects cooldown configuration. If the workflow has a triggerSchema, the payload is validated first; on failure, the response includes structured validationErrors plus the workflow's triggerSchema for self-correction. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow ID to trigger | | `triggerData` | `object` | No | - | Optional data to pass as trigger context to the workflow | ### list-workflow-runs **List Workflow Runs** List execution runs for a workflow with offset pagination (default 20, max 100), optionally filtered by status. Returns SLIM rows WITHOUT the full `context` or trigger data — each row carries a bounded `triggerDataSummary` instead. To inspect a run's context and steps, call `get-workflow-run` by id, or pass `includeContext: true` here. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `workflowId` | `string` | Yes | - | Workflow ID to list runs for | | `status` | `running \| waiting \| completed \| failed \| skipped \| cancelled` | No | - | Filter by run status (running, waiting, completed, failed, skipped, cancelled) | | `limit` | `number` | No | 20 | Runs per page (default: 20, max: 100) | | `offset` | `number` | No | 0 | Zero-based page offset | | `includeContext` | `boolean` | No | false | Return the full run `context` + trigger data instead of slim rows. Default false — prefer `get-workflow-run` to fetch a single run in full. | ### get-workflow-run **Get Workflow Run** Get details of a workflow run by ID, including all steps and their statuses. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | Workflow run ID | ### retry-workflow-run **Retry Workflow Run** Retry a failed workflow run from the beginning. The run must be in 'failed' status. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `runId` | `string` | Yes | - | Workflow run ID to retry | ### cancel-workflow-run **Cancel Workflow Run** Cancel a running or waiting workflow run. Cancels all non-terminal steps and their associated tasks. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `runId` | `string` | Yes | - | Workflow run ID to cancel | | `reason` | `string` | No | - | Optional reason for cancellation | ### request-human-input **Request human input** Create an approval request and return at once with the request id and URL. The answer arrives later as a hitl-follow-up task. Supports multiple question types: approval (yes/no), text, single-select, multi-select, and boolean. Returns the request ID and URL for the human to respond. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `title` | `string` | Yes | - | Title of the approval request | | `questions` | `array` | Yes | - | Questions to ask the human | | `timeoutSeconds` | `number` | No | - | Seconds until the request expires. After that the request becomes 'timeout' and you get a hitl-follow-up task. A request with no timeout is cancelled after APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS days (default 7). | ### cancel-approval-request **Cancel approval request** Cancel a pending approval request by id. Allowed for a lead agent, or for the agent that owns the request's source task. If the request gates a running or waiting workflow run, that run is cancelled too. A request whose explicit timeout passed is already 'timeout' and cannot be cancelled. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `requestId` | `uuid` | Yes | - | The ID of the approval request to cancel. | | `reason` | `string` | No | - | Reason for cancellation. | ## Skills Tools *Skills capability - installable skill packages (create, search, install, publish)* Capability: `skills` (enabled by default) ### skill-create **Create Skill** Create a personal skill from SKILL.md content. Parses frontmatter for name, description, and metadata. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `content` | `string` | Yes | - | Full SKILL.md content (YAML frontmatter + markdown body) | | `scope` | `agent \| swarm` | No | "agent" | Scope: agent (personal) or swarm (shared). Default: agent | ### skill-update **Update Skill** Update a skill's content or settings. Re-parses frontmatter if content changes. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | No | - | Skill ID to update | | `content` | `string` | No | - | New SKILL.md content (re-parses frontmatter) | | `isEnabled` | `boolean` | No | - | Toggle enabled/disabled | | `scope` | `agent \| swarm` | No | - | Scope: agent (personal) or swarm (shared). Only leads can promote a skill to swarm scope (used by the skill-approval flow). | ### skill-delete **Delete Skill** Delete a skill. Only the owning agent or lead can delete. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | Yes | - | ID of the skill to delete | ### skill-get **Get Skill** Get full skill content by ID or name. Name resolution checks agent scope first, then swarm, then global. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | No | - | Skill ID | | `name` | `string` | No | - | Skill name (resolved with precedence) | ### skill-get-file **Get Skill File** Fetch a bundled reference file from a complex skill by skillId and relative path. Use this when the file is not available on disk. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | Yes | - | Skill ID | | `path` | `string` | Yes | - | Relative path, e.g. references/animations.md | ### skill-list **List Skills** List available skills with optional filters. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `type` | `remote \| personal` | No | - | Filter by type | | `scope` | `global \| swarm \| agent` | No | - | Filter by scope | | `agentId` | `string` | No | - | Filter by owning agent | | `installedOnly` | `boolean` | No | - | Only show skills installed for calling agent | | `includeContent` | `boolean` | No | false | Include full content (default false) | ### skill-search **Search Skills** Search skills by keyword (name and description). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | `string` | Yes | - | Search query | | `limit` | `number` | No | 20 | - | ### skill-install **Install Skill** Install/assign a skill to an agent. Leads can install for other agents. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | Yes | - | ID of the skill to install | | `agentId` | `string` | No | - | Target agent (default: calling agent). Lead can install for others. | ### skill-uninstall **Uninstall Skill** Remove a skill from an agent. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | Yes | - | ID of the skill to uninstall | | `agentId` | `string` | No | - | Target agent (default: calling agent) | ### skill-install-remote **Install Remote Skill** Fetch and install a remote skill from a GitHub repository. Fetches SKILL.md via GitHub raw content API. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `sourceRepo` | `string` | Yes | - | GitHub repo (e.g. "vercel-labs/skills") | | `sourcePath` | `string` | No | - | Path within repo (e.g. "skills/nextjs") | | `scope` | `global \| swarm` | No | "global" | Scope for the installed skill | | `isComplex` | `boolean` | No | false | If true, registers for npx install (metadata only) | ### skill-sync-remote **Sync Remote Skills** Check and update remote skills from their GitHub sources. Compares content and updates if changed. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | No | - | Sync a specific skill, or all remote skills if omitted | | `force` | `boolean` | No | false | Force re-fetch even if hash matches | ### skill-publish **Publish Skill** Publish a personal skill to swarm scope. Creates an approval task for the lead agent. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `skillId` | `string` | Yes | - | ID of the personal skill to publish | ## Pages Tools *Pages capability - DB-backed lightweight artifacts (HTML / JSON specs).* Capability: `pages` (enabled by default) ### app-get **Get an app** Get an app by ID, including its models, named queries, actions, and json-render pages definition. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID to retrieve. | ### app-history **App history** List prior app definition snapshots with a compact digest of each version. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID whose history to inspect. | | `limit` | `number` | No | - | Maximum snapshots to return. | ### app-diff **App definition diff** Show a unified diff between two app definition snapshots, or a snapshot and CURRENT. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID to compare. | | `from` | `number` | No | - | Older snapshot version. Defaults to newest snapshot. | | `to` | `number` | No | - | Newer snapshot version. Defaults to CURRENT. | ### app-list **List apps** List app summaries without their definitions. Use app-get to inspect one app in full. *No parameters* ### app-patch **Patch an app** Partially update an app, including zero-model pure-UI apps. userConfig defines versioned field schema while per-user values live outside definitions, survive rollback, and never need migration directives; userConfig. entries are atomic. Pages may bind a declared field read-only at exactly /user/; pure and bound reusable elements must receive that value through a prop. Reusable elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. RFC 7396 merge-patch applies with this element rule: a patch value containing ONLY the elements key merges node-by-node; any other key present (mode/root/props/export) makes it a full element replace — restate every field you want kept. Page elements/params, actions, model columns, and userConfig fields are atomic; null deletes. Breaking a referenced export is blocked and names consumers unless forceElementBreak explicitly names it. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID to patch. | | `name` | `string` | No | - | Replacement human-readable app name. | | `description` | `string` | No | - | Replacement description. Pass null to clear it; omit to keep it. | | `definition` | `object` | No | - | Definition merge patch. Objects merge recursively; arrays and scalars replace; null deletes. For elements., a value containing ONLY the elements key merges node-by-node; any mode/root/props/export key makes it a full replace, so restate every field to keep. Page-element, param, action, and column entries replace atomically. | | `migration` | `unknown` | No | - | Explicit per-column directives for lossy schema changes (set, from/map/else, coerce/else, or purge). | | `forceElementBreak` | `unknown` | No | - | Exported element names whose known consumers may be broken by this patch. Use only to abandon those consumers explicitly. | ### app-query **Run an app query** Run one declared named app query with optional $param values and return its rows. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID containing the named query. | | `query` | `string` | Yes | - | Declared query name. | | `params` | `object` | No | - | Values for any $param filters declared by the named query. | ### app-rollback **Rollback an app** Restore a historical app snapshot through the schema migration and exported-element compatibility gates. Lossy row restores require migration directives; intentional consumer breaks require forceElementBreak. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID to restore. | | `version` | `number` | Yes | - | Snapshot version to restore. | | `migration` | `unknown` | No | - | Explicit per-column directives for a lossy restore (set, from/map/else, coerce/else, or purge). | | `forceElementBreak` | `unknown` | No | - | Exported element names whose consumers may be broken by this restore. | ### app-sync **Sync an app** Refresh an app's declared sources: pull each selected (model x source) pair and reconcile its rows. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `appId` | `string` | Yes | - | App ID whose sources should sync. | | `model` | `unknown` | No | - | Limit the sync to one model. | | `source` | `unknown` | No | - | Limit the sync to one declared source name. | ### app-upsert **Create or update an app** Stores a schema-backed app definition with models, queries/actions, pages, reusable elements, optional userConfig fields, and an optional top-level theme (a dashboard preset slug for the app's canvas — hive (stock; omit to inherit the viewer's theme), meadow, iris, rose, cobalt, ember, carbon, plus the classic presets github, vscode, material, solarized, tokyo, monokai, gruvbox; viewers can override it per-user; unknown slugs degrade to the viewer's dashboard theme), then returns its dashboard URL. userConfig is versioned schema only; each user's values are stored separately, survive rollback, and schema changes are always compatible. Pages may bind a declared field read-only at exactly /user/; pure and bound reusable elements must receive that value through a prop. Elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. Zero-model pure-UI apps are valid. Pass appId to update; breaking a referenced export is blocked by the compatibility gate unless forceElementBreak explicitly names it. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | Yes | - | Human-readable app name. | | `description` | `string` | No | - | Optional short app description. | | `definition` | `unknown` | Yes | - | App models, reusable pure/bound elements, named queries/actions, and json-render pages. | | `appId` | `string` | No | - | Existing app ID to update. | | `migration` | `unknown` | No | - | Explicit per-column directives for an update's lossy schema changes. Requires appId. | | `forceElementBreak` | `unknown` | No | - | Exported element names whose known consumers may be broken by this update. Requires appId and should only be used to abandon those consumers explicitly. | ### create_page **Create or update a page** Stores an HTML or JSON page in the swarm and returns shareable URLs. Calls are upsert-by-(agent, slug): if you previously created a page with the same slug, its prior state is snapshotted and the row is updated. Use this for static reports, dashboards, or JSON action specs that don't need a long-lived process. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | No | - | Logical namespace. Defaults to a shared/page:/ resource key. | | `title` | `string` | Yes | - | Human-readable title shown in listings. | | `slug` | `string` | No | - | URL slug. Defaults to the kebab-cased title. Same slug → updates the existing row. | | `body` | `string` | Yes | - | Full page body (HTML document, SVG image, or JSON-render spec, per contentType). | | `contentType` | `text/html \| application/json \| image/svg+xml` | Yes | - | 'text/html' and 'image/svg+xml' render directly at /p/:id; 'application/json' is rendered by the SPA. | | `authMode` | `public \| authed \| password` | No | "authed" | 'authed' — requires page-session cookie (default); 'public' — no gate and must be explicit; 'password' — requires key. | | `password` | `string` | No | - | Plaintext password, hashed before storage. Only meaningful for authMode='password'. | | `description` | `string` | No | - | Optional short description, used in listings + OG-tag unfurl. | | `needsCredentials` | `array` | No | - | Declared credential needs for JSON pages (renderer ignores for v1 — reserved for follow-up). | ### delete-page **Delete Page** Permanently delete one page by pageId, or by slug in the caller's page namespace. Only the lead or the page owner can delete a page. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `pageId` | `string` | No | - | Page ID to delete. | | `slug` | `string` | No | - | Page slug to delete from the caller's own (agentId, slug) namespace. Alternative to pageId. | ## Metrics Tools *Metrics capability - time-series metrics (DB-backed, for dashboards).* Capability: `metrics` (enabled by default) ### create_metric **Create or update a metric** Stores a config-driven dashboard backed by read-only SQL widget queries. Calls are upsert-by-(agent, slug), mirroring create_page: same slug updates the existing dashboard and snapshots the prior JSON definition. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `title` | `string` | Yes | - | Human-readable dashboard title. | | `slug` | `string` | No | - | URL-safe slug. Defaults to the kebab-cased title. | | `description` | `string` | No | - | Short description shown in the dashboard. | | `definition` | `unknown` | Yes | - | Dashboard JSON definition: a list of widgets, each with SELECT/WITH SQL and viz config. | ## KV Tools *KV capability — namespaced Redis-like key/value (see src/be/migrations/061_kv_store.sql).* Capability: `kv` (enabled by default) ### kv-get **KV Get** Read a key from the swarm KV store. Returns the entry or null if missing/expired. Namespace defaults to your current context (Slack thread / PR / Linear issue when invoked from a task; otherwise your agent scratchpad). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | Yes | - | KV key (≤512 chars, [a-zA-Z0-9._:/-]). | | `namespace` | `unknown` | No | - | Optional explicit namespace. Defaults to the caller's contextKey. | ### kv-set **KV Set** Write a key in the swarm KV store. Each replacement is atomic but unconditional: there is no compare-and-swap, so concurrent read-modify-write callers can lose updates. Namespace defaults to your current context. Use `expiresInSec` for opt-in TTL (default: never expires). 2 MiB body cap. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | Yes | - | KV key (≤512 chars, [a-zA-Z0-9._:/-]). | | `value` | `unknown` | Yes | - | Value. Stored as JSON by default; pass `valueType: 'string'` or `'integer'` to skip JSON wrapping. | | `valueType` | `json \| string \| integer` | No | - | How to encode `value`. Defaults to 'json'. 'integer' is required for INCR. | | `expiresInSec` | `number` | No | - | Optional TTL in seconds. Omit for no expiry. | | `namespace` | `unknown` | No | - | Optional explicit namespace. Defaults to the caller's contextKey. | ### kv-delete **KV Delete** Remove a key from the swarm KV store. Returns whether a row was actually deleted. Namespace defaults to your current context. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | Yes | - | - | | `namespace` | `unknown` | No | - | - | ### kv-incr **KV Incr** Atomically increment an integer KV entry. Creates the entry (set to `by`) if it doesn't exist or has expired. Fails if the existing value_type is not 'integer' (use kv-delete first if you want to switch). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `key` | `unknown` | Yes | - | - | | `by` | `number` | No | - | Increment (or decrement when negative). Default: 1. | | `namespace` | `unknown` | No | - | - | ### kv-list **KV List** List KV entries in the resolved namespace (optionally filtered by key prefix). Expired entries are filtered out. Pagination via limit/offset (limit capped at 1000). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `prefix` | `string` | No | - | Key prefix to filter on. | | `limit` | `number` | No | - | Max entries to return (default 100, max 1000). | | `offset` | `number` | No | - | - | | `namespace` | `unknown` | No | - | - | ### room-get **Room Get** Read the current state of a realtime room. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | No | "default" | - | | `namespace` | `unknown` | No | - | - | | `schemaVersion` | `number` | No | 1 | - | ### room-change **Room Change** Apply operations to the live state of a realtime room. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | No | "default" | - | | `namespace` | `unknown` | No | - | - | | `schemaVersion` | `number` | No | 1 | - | ### room-reset **Room Reset** Replace a realtime room with a new state and schema version. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | No | "default" | - | | `namespace` | `unknown` | No | - | - | | `schemaVersion` | `number` | No | 1 | - | ### room-decode **Room Decode** Decode a room snapshot value that the caller already holds. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `value` | `unknown` | Yes | - | - | ## Slack Tools *Slack capability - Slack integration tools (no-op if Slack is not configured)* Capability: `slack` (enabled by default) ### slack-reply **Reply to Slack thread** Send a reply to a Slack thread. Use inboxMessageId for inbox messages, or taskId for task-related threads. The engine already publishes the task tree and outcome card, so send only a distinct agent-authored message. Prefer one reply per task over several, do not post progress, receipt, or acknowledgment messages, and match its length to what the user asked for. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `inboxMessageId` | `uuid` | No | - | The inbox message ID to reply to (for leads responding to inbox). | | `taskId` | `uuid` | No | - | The task ID with Slack context (for task-related threads). | | `message` | `string` | Yes | - | The message to send to the Slack thread. | | `blocks` | `array` | No | - | Optional Block Kit blocks. When omitted, a mrkdwn section is generated. | ### slack-read **Read Slack thread/channel history** Read messages from a Slack thread or channel. Use inboxMessageId or taskId to read from a thread you have context for, or provide channelId directly for channel history (leads only). From a task, files in the messages are stored as attachments of that task, each with a ready-to-run `fetchCommand`. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `inboxMessageId` | `uuid` | No | - | Read thread history for an inbox message. | | `taskId` | `uuid` | No | - | Read thread history for a task. | | `channelId` | `string` | No | - | Slack channel ID to read from (requires lead privileges). | | `threadTs` | `string` | No | - | Thread timestamp (required with channelId for thread history). | | `limit` | `number` | No | 20 | Maximum number of messages to retrieve (default: 20, max: 100). | | `includeFiles` | `boolean` | No | true | Include file attachments in the response (default: true). From a task, they are also stored as attachments of that task. | ### slack-post **Post message to Slack channel** Post a message to a Slack channel. By default creates a new top-level message; pass `threadTs` to post as a threaded reply under an existing message (obtain the ts from `slack-start-thread`). Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID to post to. | | `message` | `string` | Yes | - | The message content to post. | | `blocks` | `array` | No | - | Optional Block Kit blocks. When omitted, a mrkdwn section is generated. | | `threadTs` | `string` | No | - | Optional parent message ts to thread under. Obtain via `slack-start-thread`. When omitted, posts as a new top-level message. | ### slack-start-thread **Start a new Slack thread** Post a new top-level message to a Slack channel and return its ts so the caller can thread replies under it. Pass the returned `ts` as `threadTs` on subsequent `slack-post` calls to keep replies in the same thread. Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID to post to. | | `message` | `string` | Yes | - | The message content to post. | | `blocks` | `array` | No | - | Optional Block Kit blocks. When omitted, a mrkdwn section is generated. | ### slack-create-channel **Create a Slack channel** Creates a public or private Slack channel. The supplied name is normalized to Slack's channel-name rules, and the normalized name is returned. Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | Yes | - | The desired Slack channel name. | | `isPrivate` | `boolean` | No | false | Whether to create a private channel. Defaults to false. | ### slack-invite-to-channel **Invite users to a Slack channel** Invites one or more workspace users to a Slack channel. Users who are already in the channel are treated as a successful no-op. Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID. | | `userIds` | `array` | Yes | - | Slack user IDs to invite (up to 100). | ### slack-archive-channel **Archive a Slack channel** Archives a Slack channel. Channels that are already archived are treated as a successful no-op, while Slack's general channel cannot be archived. Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID to archive. | ### slack-list-channels **List Slack channels** List Slack channels the bot is a member of. Use this to discover available channels for reading messages. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `types` | `array` | No | - | Filter by channel types. Options: public (public channels), private (private channels), dm (direct messages), mpim (group DMs). Default: all types. | | `limit` | `number` | No | 100 | Maximum number of channels to retrieve (default: 100, max: 200). | ### slack-upload-file **Upload file to Slack** Upload a file (image, document, etc.) to a Slack channel or thread. Use inboxMessageId or taskId for context, or provide channelId directly (leads only). Maximum file size is 1 GB. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `inboxMessageId` | `uuid` | No | - | The inbox message ID for thread context (leads only). | | `taskId` | `uuid` | No | - | The task ID with Slack context (for task-related threads). | | `channelId` | `string` | No | - | Direct channel ID to upload to (requires lead privileges). | | `threadTs` | `string` | No | - | Thread timestamp to upload as a thread reply (used with channelId). | | `filePath` | `string` | No | - | Path to the file to upload. Either filePath OR content must be provided. IMPORTANT: the file is read on the API server's filesystem (where this tool runs), NOT on the caller's. Worker/lead containers do NOT share /tmp or /workspace/personal/ with the API server — the only shared volume is /workspace/shared/. Use /workspace/shared//file.png (or a relative path like 'shared//file.png'). For files that only live on the caller (e.g. /tmp), pass them inline via `content` (base64) instead. | | `content` | `string` | No | - | Base64-encoded file content. Use this when the file lives on the caller's filesystem and isn't reachable by the API server (e.g. anything under /tmp on a worker/lead container). Either filePath OR content must be provided. | | `filename` | `string` | No | - | Name to give the file in Slack. Required when using content, defaults to original filename when using filePath. | | `initialComment` | `string` | No | - | Optional message to post with the file. | ### slack-download-file **Download file from Slack** Download a file from Slack by file ID or URL. From a task, the file is stored as an attachment of that task and the result carries a ready-to-run `fetchCommand` to get the bytes into your container. Without a task, the file is saved on the API server's disk, which your container usually can't read. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `fileId` | `string` | No | - | The Slack file ID to download (e.g., 'F0RDC39U1'). | | `url` | `string` | No | - | Direct URL to download (url_private_download from a file object). | | `taskId` | `uuid` | No | - | Task to attach the file to. Defaults to the task you are working on; must be a task you own or created. | | `savePath` | `string` | No | - | Only without a task: where to save the file on the API server (directory or full path). Defaults to /workspace/shared/downloads/{agentId}/slack/. | | `filename` | `string` | No | - | Filename to use when saving. Only used if savePath is a directory. | ### slack-delete **Delete a Slack message** Deletes a Slack message that THIS bot authored (e.g. a message previously posted via `slack-post`/`slack-reply`). Cannot delete messages authored by humans or other apps. Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID the message is in. | | `messageTs` | `string` | Yes | - | Timestamp of the message to delete. Accepts the dotted form (1783411554.596189), the 'p' deep-link form (p1783411554596189), or a full Slack permalink URL. | ### slack-update **Edit a Slack message** Edits (in place) the text of a Slack message that THIS bot authored — use it to post corrections to your own messages. Cannot edit messages authored by humans or other apps. Note: editing may reset the message's display name/icon to the app default (Slack's chat.update cannot set the crown persona). Requires lead privileges. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | Yes | - | The Slack channel ID the message is in. | | `messageTs` | `string` | Yes | - | Timestamp of the message to edit (dotted, 'p' deep-link, or full permalink URL). | | `message` | `string` | Yes | - | The new message content. | ## Prompt Templates Tools *Prompt-templates capability - prompt template management (list/get/set/delete/preview)* Capability: `prompt-templates` — **disabled by default**; add `prompt-templates` to `CAPABILITIES` to enable. ### list-prompt-templates **List Prompt Templates** List prompt templates with optional filters. Returns all templates matching the specified criteria, including defaults and overrides at all scope levels. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `eventType` | `string` | No | - | Filter by event type (e.g. 'github.pull_request.opened'). | | `scope` | `global \| agent \| repo` | No | - | Filter by scope: 'global', 'agent', or 'repo'. | | `scopeId` | `string` | No | - | Filter by scope ID (agent ID or repo ID). | | `isDefault` | `boolean` | No | - | Filter by default status. | ### get-prompt-template **Get Prompt Template** Get a prompt template by ID, including its version history and the code-defined variable definitions for its event type. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | The prompt template ID. | ### set-prompt-template **Set Prompt Template** Create or update a prompt template override. Upserts by (eventType, scope, scopeId). Use scope='global' for server-wide, 'agent' for agent-specific, or 'repo' for repo-specific overrides. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `eventType` | `string` | Yes | - | Event type identifier (e.g. 'github.pull_request.opened'). | | `scope` | `global \| agent \| repo` | No | - | Template scope: 'global' (default), 'agent', or 'repo'. | | `scopeId` | `string` | No | - | Agent ID or repo ID. Required for 'agent' and 'repo' scopes, omit for 'global'. | | `state` | `enabled \| default_prompt_fallback \| skip_event` | No | - | Template state: 'enabled' (default), 'default_prompt_fallback', or 'skip_event'. | | `body` | `string` | Yes | - | The template body text with {{variable}} placeholders. | | `changeReason` | `string` | No | - | Reason for the change (recorded in history). | ### delete-prompt-template **Delete Prompt Template** Delete a prompt template override by ID. Cannot delete default templates — use reset instead. Use list-prompt-templates to find template IDs first. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `id` | `string` | Yes | - | The prompt template ID to delete. | ### preview-prompt-template **Preview Prompt Template** Dry-run render a prompt template with provided variables. Optionally supply a custom body to preview before saving. Returns the interpolated text and any unresolved {{variable}} tokens. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `eventType` | `string` | Yes | - | Event type to preview (used to look up header and default body). | | `body` | `string` | No | - | Custom body to preview instead of the default. | | `variables` | `object` | No | - | Variables to interpolate into the template. | ## AgentMail Tools *Agentmail capability - AgentMail integration (self-service inbox mapping)* Capability: `agentmail` — **disabled by default**; add `agentmail` to `CAPABILITIES` to enable. ### register-agentmail-inbox **Register AgentMail Inbox** Register an AgentMail inbox ID to route incoming emails to this agent. When emails arrive at this inbox, they will be routed to you as tasks (for workers) or inbox messages (for leads). Use action 'register' to add a mapping, 'unregister' to remove one, or 'list' to see your current mappings. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `action` | `register \| unregister \| list` | Yes | - | Action to perform: register, unregister, or list inbox mappings. | | `inboxId` | `string` | No | - | The AgentMail inbox ID (e.g., 'inb_xxx'). Required for register/unregister. | | `inboxEmail` | `string` | No | - | Optional email address for this inbox (for reference only). | ## Kapso (WhatsApp) Tools *Kapso capability - Kapso/WhatsApp integration (native inbound provisioning + outbound)* Capability: `kapso` — **disabled by default**; add `kapso` to `CAPABILITIES` to enable. ### register-kapso-number **Register Kapso WhatsApp Number** Provision a Kapso WhatsApp phone number for native inbound routing. Lead-only. Points the number's Kapso webhook at the swarm's native handler (signed with KAPSO_WEBHOOK_HMAC_SECRET) and stores a KV mapping so inbound messages route to an agent (defaults to the lead, or a workflow if workflowId is given). Returns the stored mapping + the registered webhook URL. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `phoneNumberId` | `string` | Yes | - | Kapso/Meta phone-number ID to provision (KAPSO_PHONE_NUMBER_ID). | | `agentId` | `string` | No | - | Agent to route inbound messages to as a `kapso-inbound` task. Defaults to the lead agent when omitted. | | `workflowId` | `string` | No | - | Advanced override: dispatch inbound via this workflow's webhook trigger instead of a task. | | `name` | `string` | No | - | Human-friendly display name for the number. | ### unregister-kapso-number **Unregister Kapso WhatsApp Number** Remove a Kapso phone number's native routing mapping from the KV store. Lead-only. Inbound messages for the number stop routing through the native handler. The Kapso-side webhook is not deleted automatically — remove it in the Kapso dashboard if you want deliveries to stop. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `phoneNumberId` | `string` | Yes | - | Kapso/Meta phone-number ID whose mapping should be removed. | ### send-whatsapp-message **Send WhatsApp Message** Send a free-form WhatsApp text via Kapso (within the 24h session window). Thin wrapper over the Kapso Meta-proxy send. For templates/media/reactions use the `kapso-whatsapp` skill. If the recipient is outside the 24h window the call returns a structured error pointing at the template path. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `phoneNumberId` | `string` | Yes | - | The swarm's Kapso/Meta phone-number ID to send from (KAPSO_PHONE_NUMBER_ID). | | `to` | `string` | Yes | - | Recipient phone in E.164 WITHOUT '+' (e.g. '15551234567'). | | `body` | `string` | Yes | - | Message text. | | `previewUrl` | `boolean` | No | - | Render a link preview for URLs in the body (default false). | ### reply-whatsapp-message **Reply to WhatsApp Message** Quote-reply a WhatsApp message via Kapso — same as send-whatsapp-message but threads to a specific inbound WAMID via context.message_id. Recipient is inferred from the conversation; pass the original sender's phone as `to`. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `phoneNumberId` | `string` | Yes | - | The swarm's Kapso/Meta phone-number ID to send from (KAPSO_PHONE_NUMBER_ID). | | `to` | `string` | Yes | - | Recipient phone in E.164 WITHOUT '+'. | | `inReplyTo` | `string` | Yes | - | The inbound WAMID to quote-reply (set as context.message_id). | | `body` | `string` | Yes | - | Reply text. | ## Swarm X Tools *Swarm-x capability - external command routes mirroring the `agent-swarm x ...` CLI surface* Capability: `swarm-x` — **disabled by default**; add `swarm-x` to `CAPABILITIES` to enable. ### swarm_x **Swarm X** Execute an Agent Swarm external command route. v1 supports target='composio' and mirrors `agent-swarm x composio ` with the Composio API key injected server-side. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `target` | `unknown` | No | "composio" | External route target. Only 'composio' is supported in v1. | | `method` | `unknown` | Yes | - | HTTP method to route to Composio. | | `path` | `string` | Yes | - | Composio API path relative to the configured base URL, e.g. /tool_router/session. | | `body` | `unknown` | No | - | Optional JSON request body. | | `query` | `object` | No | - | Optional query parameters appended to the Composio path. | | `headers` | `object` | No | - | Optional extra headers. Auth headers are injected by the server. | | `baseUrl` | `string` | No | - | Optional Composio API base URL override. | | `useOrgKey` | `boolean` | No | false | Use COMPOSIO_ORG_API_KEY/x-org-api-key instead of COMPOSIO_API_KEY/x-api-key. | | `raw` | `boolean` | No | false | Return raw text instead of JSON-pretty output text. | ## Messaging Tools *Messaging capability - internal swarm chat (post/read messages, channel CRUD)* Capability: `messaging` — **disabled by default**; add `messaging` to `CAPABILITIES` to enable. ### post-message **Post Message** Posts a message to a channel for cross-agent communication. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channel` | `string` | No | "general" | Channel name (default: 'general'). | | `content` | `string` | Yes | - | Message content. | | `replyTo` | `uuid` | No | - | Message ID to reply to (for threading). | | `mentions` | `array` | No | - | Agent IDs to @mention (they'll see it in unread). | ### read-messages **Read Messages** Reads messages from a channel. If no channel is specified, returns unread messages from ALL channels. Supports filtering by unread, mentions, and time range. Automatically marks messages as read. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channel` | `string` | No | - | Channel name or ID. If omitted, returns unread messages from all channels. | | `limit` | `number` | No | 20 | Max messages to return per channel (default: 20). | | `since` | `unknown` | No | - | Only messages after this ISO timestamp. | | `unreadOnly` | `boolean` | No | false | Only return unread messages. | | `mentionsOnly` | `boolean` | No | false | Only return messages that @mention you. | | `markAsRead` | `boolean` | No | true | Update your read position after fetching (default: true). | ### list-channels **List Channels** Lists all available channels for cross-agent communication. *No parameters* ### create-channel **Create Channel** Creates a new channel for cross-agent communication. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | `string` | Yes | - | Channel name (must be unique). | | `description` | `string` | No | - | Channel description. | | `type` | `public \| dm` | No | - | Channel type: 'public' (default) or 'dm'. | | `participants` | `array` | No | - | Agent IDs for DM channels. | ### delete-channel **Delete Channel** Deletes a channel and all its messages. Only the lead agent can delete channels. The default 'general' channel cannot be deleted. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `channelId` | `string` | No | - | The ID of the channel to delete. | | `name` | `string` | No | - | Channel name (alternative to channelId). | ## Services Tools *Services capability - PM2/background service registry* Capability: `services` — **disabled by default**; add `services` to `CAPABILITIES` to enable. ### register-service **Register Service** Register a background service (e.g., PM2 process) for discovery by other agents. The service URL is automatically derived from your agent ID (https://{AGENT_ID}.{SWARM_URL}). Each agent can only run one service on port 3000. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `script` | `string` | Yes | - | Path to the script to run (required for PM2 restart). | | `description` | `string` | No | - | What this service does. | | `healthCheckPath` | `string` | No | - | Health check endpoint path (default: /health). | | `cwd` | `string` | No | - | Working directory for the script. | | `interpreter` | `string` | No | - | Interpreter to use (e.g., 'node', 'bun'). Auto-detected from extension if not set. | | `args` | `array` | No | - | Command line arguments for the script. | | `env` | `object` | No | - | Environment variables for the process. | | `metadata` | `object` | No | - | Additional metadata. | ### unregister-service **Unregister Service** Remove a service from the registry. Use this after stopping a PM2 process. You can only unregister your own services. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `serviceId` | `uuid` | No | - | Service ID to unregister. | | `name` | `string` | No | - | Service name to unregister (alternative to serviceId). | ### list-services **List Services** Query services registered by agents in the swarm. Use this to discover services exposed by other agents. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `agentId` | `string` | No | - | Filter by specific agent ID. | | `name` | `string` | No | - | Filter by service name (partial match). | | `status` | `starting \| healthy \| unhealthy \| stopped` | No | - | Filter by health status. | | `includeOwn` | `boolean` | No | true | Include services registered by calling agent (default: true). | ### update-service-status **Update Service Status** Update the health status of a registered service. Use this after a service becomes healthy or needs to be marked as stopped/unhealthy. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `serviceId` | `uuid` | No | - | Service ID to update. | | `name` | `string` | No | - | Service name to update (alternative to serviceId). | | `status` | `starting \| healthy \| unhealthy \| stopped` | Yes | - | New status: 'starting', 'healthy', 'unhealthy', or 'stopped'. |