MCP Tools Reference

Agent Swarm exposes its functionality through MCP (Model Context Protocol) tools. Tools are grouped by capability.

Capability Flags

Every tool group is gated by a capability flag on the API server, controlled by the CAPABILITIES environment variable (or a CAPABILITIES global swarm-config entry, which takes precedence at server creation). When unset, the defaults apply:

• Enabled by default: core, task-pool, config, scripts, mcp, profiles, repo, scheduling, memory, tracker, workflows, skills, pages, metrics, kv, slack
• Disabled by default: messaging (post/read messages, channels), services (background service registry), prompt-templates, swarm-x (external command routes), agentmail, kapso (WhatsApp)

Setting CAPABILITIES replaces the whole list — it is not additive. To enable a disabled capability, provide the full default list plus the extras, e.g. CAPABILITIES=core,task-pool,...,repo,messaging. Sections below note when a tool group is disabled by default.

Capability flags shape the externally exposed MCP tool list only — they hide tools from agents' tool lists, they are not feature kill-switches. The scripts SDK bridge always builds a full-surface server instance, so scripts keep their full typed SDK (governed by the scripts SDK allowlist) regardless of CAPABILITIES. HTTP REST routes are generally not gated either.

Workers learn the server's enabled capabilities at registration (POST /api/agents returns enabledCapabilities) and automatically drop system-prompt sections that would instruct tools from disabled groups (messaging, services, Slack).

Tool Search & Annotations

All MCP tools have structured annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to improve Claude Code's Tool Search discoverability. Tools are split into two tiers:

• Core tools — Always available in context: task lifecycle, basic communication, memory recall, and swarm awareness
• Deferred tools — Discovered on demand via Claude Code's Tool Search when the agent needs them (scheduling, config, skills, workflows, MCP servers, Slack, user identity, repos, etc.)

This reduces context window overhead by ~85% compared to loading all tools upfront.

Large Result Handling

Agent-facing MCP results are capped at 10,000 serialized UTF-8 bytes. When a result exceeds that budget, Agent Swarm stores the complete scrubbed result for 24 hours in the calling agent's private mcp:overflow:<agentId> KV namespace. The bounded response keeps the largest fitting leading slice of an array, or a readable prose preview; scalar JSON is omitted as a complete unit rather than cut into invalid JSON. Both MCP result channels receive the same machine-readable truncation metadata and kv-get retrieval pointer.

kv-get returns the complete stored value, although the active harness may still apply its own display limit. For filtering or aggregation, fetch the value inside a script with ctx.swarm.kv_get and return only the derived answer. Script-internal ctx.swarm.* responses are not subject to the 10 KB model-context ceiling; see Scripts runtime for that separate boundary.

Core Tools

Always available tools for basic swarm operations.

join-swarm

Join the agent swarm with optional profile information.

poll-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.

get-swarm

Returns a list of agents in the swarm without their tasks.

get-tasks

Returns a list of tasks with various filters. Sorted by priority (desc) then lastUpdatedAt (desc).

send-task

Send a task to a specific agent, create an unassigned task, or offer a task for acceptance.

Slack metadata and requestedByUserId are auto-inherited from the creator's current task via the X-Source-Task-Id header. Slack channel/thread fields inherit as one route: explicit values that conflict with the parent or Slack context key are rejected unless both fields are provided with overrideSlackContext: true for an intentional audited handoff.

get-task-details

Returns detailed information about a specific task, including output, failure reason, and log history.

store-progress

Store task progress, or mark a task as completed or failed.

Terminal results are first-call-wins. Repeating the same result succeeds as an idempotent no-op; a different result is rejected and reported as discarded unless force: true is explicit. Forced corrections still validate outputSchema and return wasForcedOverwrite: true on success.

cancel-task

Cancel a task that is pending or in progress. Only the lead or task creator can cancel.

steer-task

Send additional instructions to a task that is already running. Set mode to queue for turn-boundary delivery or steer to request an interrupt. With the default onUnsupported: "degrade", unsupported interrupt requests fall back through queue delivery and then a follow-up task; use "fail" when interrupt semantics are mandatory.

pi-mono and Claude Managed advertise both modes. Claude Code, Devin, opencode, and Codex advertise queue only. Codex delivers queued messages at the next SessionStart, PostToolUse, or Stop lifecycle hook; messages that are never picked up are promoted to follow-up tasks by the terminal sweep. See Steer a Running Task for the capability matrix and lifecycle.

accept-steer

Acknowledge that the assigned agent incorporated a delivered steering message. Pass the ID from the [steering <id>] marker and optionally record a short note.

my-agent-info

Returns your agent ID and profile information.

Config Tools

Manage swarm-wide, agent-specific, or repo-specific configuration values. Scope resolution follows: repo > agent > global.

set-config

Set or update a configuration value. Upserts by (scope, scopeId, key).

get-config

Get resolved configuration values with scope resolution. Returns one entry per unique key with the most-specific scope winning.

list-config

List raw config entries without scope resolution. Useful for seeing exactly what's configured at each scope level.

delete-config

Delete a configuration entry by its ID.

credential-bindings

Lead-only management for scripts-runtime credential broker bindings. Use it to list, create, update, or disable [REDACTED:CONFIG_KEY] host-allowlisted substitution rules, OAuth app metadata, and token-backed auth wiring without exposing raw secrets to scripts.

script-connections

Lead-only registry for typed script API connections. Supports OpenAPI-backed ctx.api.<slug>.<operationId>(args), GraphQL ctx.api.<slug>.graphql(query, vars), and proxied MCP ctx.mcp.<slug>.<toolName>(args) clients, with optional credential bindings for authenticated requests.

Prompt Template Tools

Requires the prompt-templates capability (disabled by default).

list-prompt-templates / get-prompt-template / set-prompt-template / delete-prompt-template / preview-prompt-template

Manage the prompt-template registry (system-prompt and task-prompt sections) at runtime: list registered templates, inspect or override a template's content, delete an override to fall back to the default, and preview a template rendered with sample variables. The equivalent HTTP endpoints under /api/prompt-templates are not gated by this capability.

Slack Tools

When the v2 Slack renderer adds provenance to explicit slack-reply, slack-post, or slack-start-thread messages, it keeps the footer to agent and task identity. It deliberately omits links between Slack messages so provenance does not create link-preview unfurls.

slack-reply

Reply to a Slack thread associated with a task.

slack-read

Read messages from a Slack thread or channel.

slack-post

Post a message to a Slack channel. Defaults to a new top-level message; pass threadTs to reply within an existing thread. Leads only.

slack-start-thread

Post a new top-level message to a Slack channel and return its ts so the caller can thread replies under it. Pair with slack-post + threadTs to keep a multi-message conversation in the same thread. Leads only.

slack-create-channel

Create a public or private Slack channel. The supplied name is normalized to Slack's channel-name rules. Requires lead privileges.

slack-invite-to-channel

Invite up to 100 workspace users to a Slack channel. Users who are already members are treated as a successful no-op. Requires lead privileges.

slack-archive-channel

Archive a Slack channel. Already-archived channels are a successful no-op, while Slack's general channel cannot be archived. Requires lead privileges.

slack-list-channels

List Slack channels the bot is a member of.

slack-upload-file

Upload a file to a Slack channel or thread (max 1 GB).

slack-download-file

Download a file from Slack by file ID or URL.

register-agentmail-inbox

Register an AgentMail inbox ID to route incoming emails to this agent.

Requires the agentmail capability (disabled by default). See the AgentMail integration guide for credentials and setup.

register-kapso-number

This tool and the other Kapso/WhatsApp tools below require the kapso capability (disabled by default). See the Kapso integration guide for credentials and setup.

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, defaulting to the lead, or to a workflow.

unregister-kapso-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.

send-whatsapp-message

Send a free-form WhatsApp text via Kapso within the 24h session window. For templates, media, reactions, and other advanced operations, use the kapso-whatsapp skill.

reply-whatsapp-message

Quote-reply a WhatsApp message via Kapso. Same text-send path as send-whatsapp-message, but threaded to a specific inbound WAMID via context.message_id.

External Route Tools

Requires the swarm-x capability (disabled by default).

swarm_x

Execute an approved external command route. v1 supports target: "composio" and mirrors the CLI form agent-swarm x composio <method> <path>.

Use this when you want a thin, auditable bridge to an external tool router before investing in a dedicated MCP surface.

Metrics Tools

create_metric

Create or update a config-driven dashboard backed by read-only SQL widget queries. Calls are upsert-by-(agent, slug): reusing the same slug updates the existing metric and snapshots the prior definition into version history.

Every widget query must be SELECT/WITH only. The tool rejects mutating SQL, stores the dashboard definition, and returns the dashboard URL under /usage/metrics.

Task Pool Tools

task-action

Manage tasks in the pool: create, claim, release, accept, reject, or move to/from backlog.

Messaging Tools

Requires the messaging capability (disabled by default). Note: the swarm-chat plugin skill relies on post-message / read-messages — enable this capability if your agents use it.

post-message / read-messages

Inter-agent communication via channels.

create-channel / list-channels / delete-channel

Manage communication channels.

Profile Tools

update-profile

Update an agent's profile, identity files, and setup script. By default updates the calling agent. Lead agents can update any agent's profile by providing the agentId parameter.

context-history

View version history for an agent's context files (soulMd, identityMd, toolsMd, claudeMd, setupScript).

context-diff

Compare two versions of a context file. Shows a unified diff.

Service Tools

Requires the services capability (disabled by default).

register-service / unregister-service / list-services / update-service-status

Manage HTTP service discovery. Registry entries are keyed by the calling agent's ID/URL, and register-service only accepts project-owned executables under /workspace or /home/worker with safe interpreters/args. See Service Discovery for details.

Scheduling Tools

create-schedule / list-schedules / update-schedule / patch-schedule / delete-schedule / run-schedule-now

Manage recurring and one-time task automation. Any registered agent can update or delete schedules. Schedules now support native targetType routing: create an agent task (agent-task), trigger a workflow directly, or launch a saved catalog script. Agent-task schedules also support both a concrete model override and a portable modelTier (smol, regular, smart, ultra) that is passed through to the tasks they create.

Schedules accept a logical asset key; tasks they create inherit that namespace. list-schedules supports exact key and subtree keyPrefix filters, while update-schedule and patch-schedule can move a schedule by updating its key.

One-time schedules (v1.36.0): Set scheduleType: "one_time" with either delayMs (relative delay) or runAt (absolute ISO datetime). One-time schedules auto-disable after execution. list-schedules hides completed one-time schedules by default (hideCompleted: true).

patch-schedule is the shallow-update variant: provide only the fields you want to overwrite and leave the rest of the stored row untouched.

See Scheduled Tasks for details.

Workflow Tools

create-workflow

Create a new automation workflow with a DAG definition.

Upstream outputs require an inputs mapping. Agent-task templates may interpolate declared aliases, but executable source uses a stricter security boundary: inline script source allows only input, workflow, swarm, and run values, while named swarm-script source is never workflow-interpolated. Pass trigger and upstream values through config.args; unresolved source tokens fail the node before execution.

get-workflow

Get workflow details by ID.

list-workflows

List all workflows, optionally filtering by enabled status. Returns slim rows by default (with nodeCount instead of the full DAG definition); pass includeFull: true or call get-workflow for the full workflow payload.

update-workflow

Update a workflow's definition, name, description, or enabled status.

delete-workflow

Delete a workflow and all its run history.

trigger-workflow

Manually trigger a workflow execution.

get-workflow-run

Get details of a specific workflow run including step statuses.

Related

• CLI Reference — Terminal commands for managing agents, tasks, and configuration
• Environment Variables — Configuration variables for the swarm
• Task Lifecycle — How tasks flow through the swarm
• Workflows — DAG-based workflow definitions and automation

list-workflow-runs

List a paginated page of runs for a workflow. The default response contains slim rows (IDs, status, timestamps, error, and a trigger-data summary capped at 400 characters), omitting the full run context and trigger payload. Use get-workflow-run for one full run, or opt in with includeContext: true when the whole page genuinely needs the complete payloads.

retry-workflow-run

Retry a failed workflow run from the point of failure.

cancel-workflow-run

Cancel a running or waiting workflow run. Cancels all non-terminal steps and their associated tasks.

patch-workflow

Partially update a workflow definition by creating, updating, or deleting individual nodes. Operations are applied in order: delete → create → update. Creates a version snapshot before applying changes.

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.

Human-in-the-Loop Tools

request-human-input

Create an approval request that pauses until a human responds. 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.

Approval requests are accessible via the dashboard at /approval-requests/{id}. When resolved, a follow-up task is automatically created for the requesting agent with the human's responses.

Pages Tools

DB-backed pages let agents publish static reports, dashboards, and JSON action specs that don't need a long-lived process. Requires the pages capability on the agent.

create_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 into the version history and the row is updated.

Returns the page id, an app_url (${APP_URL}/pages/:id — opens in the SPA), and an api_url (${MCP_BASE_URL}/p/:id — direct HTML render or JSON 302→SPA). Append ?mode=full to the app URL for a maximized chrome-light view. The returned version is a monotonic edit counter (MAX(page_versions.version) + 1).

delete-page

Delete a previously created page and its version history.

App Tools

Swarm Apps are versioned, schema-backed dashboard applications. Their definitions can declare models, named queries and actions, reusable JSON-render elements, per-user configuration, and a top-level theme. App tools use the pages capability.

app-list

List app summaries. Use app-get to inspect a complete definition.

app-get

Get an app by ID, including its models, queries, actions, reusable elements, pages, and user-configuration schema.

app-upsert

Create or update an app definition. Updates pass schema-migration and exported-element compatibility gates; zero-model pure-UI apps are supported.

app-patch

Apply an RFC 7396 merge patch to an app. Lossy schema changes require explicit migration directives, and intentional exported-element breaks must name the affected elements.

app-query

Run a declared named query with optional parameters and return its rows.

app-history

List version snapshots for an app.

app-diff

Show a unified diff between two app snapshots, or between a snapshot and the current definition.

app-rollback

Restore a historical snapshot through the same schema-migration and exported-element compatibility gates used for updates.

app-sync

Refresh an app's declared sources. Each selected model/source pair runs through its source script and connection, then reconciles projected rows while preserving operator-managed fields.

KV Tools

A Redis-like, namespaced key/value store. Calls auto-resolve namespace from your current context (Slack thread / PR / Linear issue / agent scratchpad / page). 2 MiB value cap, opt-in TTL.

kv-get

Read a key. Returns the entry or null if missing/expired. Namespace defaults to your current context.

kv-set

Write a key. Each replacement is atomic but unconditional: there is no compare-and-swap, so concurrent read-modify-write callers can lose updates. Use per-writer keys and assemble on read for fan-in workloads. 2 MiB body cap.

kv-delete

Remove a key. Returns whether a row was actually deleted.

kv-incr

Atomically increment an integer entry. Creates the entry (set to by) if missing or expired. Fails if the existing value_type is not integer.

kv-list

List entries in the resolved namespace, optionally filtered by key prefix. Expired entries are filtered out.

Skill Tools

Manage reusable procedural knowledge (skills) that agents can create, share, and install.

skill-create

Create a personal skill from SKILL.md content. Parses frontmatter for name, description, and metadata.

skill-get

Get full skill content by ID or name. Name resolution checks agent scope first, then swarm, then global.

skill-get-file

Fetch a bundled reference file from a complex skill by skill ID and relative path. Use this when the file is not available on disk.

skill-list

List available skills with optional filters.

skill-search

Search skills by keyword (name and description).

skill-install

Install/assign a skill to an agent. Leads can install for other agents.

skill-uninstall

Remove a skill from an agent.

skill-update

Update a skill's content or settings. Re-parses frontmatter if content changes. System-managed default skills can still be enabled or disabled, but their content and scope are locked; fork them under a new name to customize.

skill-publish

Publish a personal skill to swarm scope. Creates an approval task for the lead agent.

skill-delete

Delete a skill. Only the owning agent or lead can delete. System-managed default skills are locked and cannot be deleted from the UI; fork them under a new name if you need a customized variant.

skill-install-remote

Fetch and install a remote skill from a GitHub repository.

skill-sync-remote

Check and update remote skills from their GitHub sources. Compares content and updates if changed.

MCP Server Tools

Manage MCP server definitions and installations. Servers are scoped (agent → swarm → global) and can be installed per-agent.

mcp-server-create

Create a new MCP server definition. Agent-scope servers are auto-installed for the creating agent. Swarm/global scope requires lead.

mcp-server-get

Get MCP server details by ID or name. Name resolution uses scope cascade: agent > swarm > global.

mcp-server-list

List MCP servers with optional filters.

mcp-server-update

Update an MCP server's configuration. Only the owner or lead can update.

mcp-server-install

Install an MCP server for an agent. Self-install is always allowed; cross-agent requires lead.

mcp-server-uninstall

Uninstall an MCP server from an agent.

mcp-server-delete

Delete an MCP server definition. Only the owning agent or lead can delete.

Scripts Tools

Reusable TypeScript scripts (the swarm-shared script catalog) — callable across agents and from workflow swarm-script nodes. The runtime evaluates user-supplied TS in a sandboxed Bun.spawn subprocess (resource limits via ulimit, 30s AbortController, 1 MB stdout cap). Agent identity + bearer are injected over the subprocess stdin as a SwarmConfigPayload — never via env vars.

Use script-run for direct reusable-script execution. For long-running or inspectable background jobs, use the durable script-run tools below. For local-only throwaway TS, use code-mode run.

script-search

Search the swarm-shared scripts catalog.

script-run

Run a named reusable script, OR inline TypeScript source (auto-saved as scratch to the catalog). Inline source executes without a compile-time typecheck. Its default export must receive args first and ctx second; import ScriptContext from "swarm-sdk" so the same source remains safe to promote with script-upsert.

script-upsert

Create or update a named script. Source must export a default function (args, ctx) and should type ctx as ScriptContext from "swarm-sdk". Unlike inline script-run, upsert runs tsc --noEmit against the generated .d.ts and rejects on diagnostics.

A script may also export a Zod schema named argsSchema describing its expected arguments. On upsert the runtime extracts it, converts it to JSON Schema via zod's toJSONSchema, and stores it on the catalog entry as argsJsonSchema — so callers can discover a script's argument shape before running it. The export is optional; scripts without it simply have a null argsJsonSchema.

There is no ambient task context: pass values such as taskId through args. Inline and named scripts receive ctx.swarm, registered ctx.api / ctx.mcp connection clients, ctx.stdlib, and ctx.logger. Durable launch-script-run workflows instead receive ctx.run and journaled ctx.step.* helpers, with no connection clients or ctx.swarm.config. See Scripts runtime for the full authoring contract.

script-delete

Delete a named script from the catalog.

script-query-types

Return the generated .d.ts SDK surface (derived from the MCP tool registry via scripts/bundle-script-types.ts). Useful for type-checking scripts locally before script-upsert.

launch-script-run

Launch a durable one-off script workflow run. The run executes in the background and can be inspected later with get-script-run for terminal status and journal entries.

get-script-run

Get a durable script workflow run by ID, including its journal entries for swarm-script, raw-llm, and agent-task steps.

list-script-runs

List durable script workflow runs, optionally filtered by status or agent ID.

Debug Tools

db-query

Execute a read-only SQL query against the swarm database. Available to all authenticated agents — be aware results may include secrets (oauth_tokens, configs). Results are capped by the operator-configurable DB_QUERY_MCP_MAX_ROWS limit.

Responses include total, truncated, and rowLimit so callers can distinguish a complete result set from one capped by the configured row limit.

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.

Memory Tools

memory-search

Search accumulated memories with natural language.

When called inside a task, memory-search may also return response-side rateHint nudges for manual and file-index memories so agents can call memory_rate(...) without looking up the signature separately.

Retrieval blends vector and full-text matches, then expands candidates through one hop of resolved memory links before reranking. Both paths are on by default; operators can set MEMORY_HYBRID_SEARCH=0 or MEMORY_GRAPH_EXPANSION=0 to restore vector-only or non-graph behavior.

memory-get

Retrieve full details of a specific memory.

Like memory-search, memory-get may include a rateHint in task context for memories that are worth rating.

memory-store

Store a learning as a searchable memory: a fix, a pattern, a gotcha, a fact about a repo or a person. This is the write path the system prompt names and it works on every harness. Long content is chunked on headings and embedded in the background. The caller always owns the row, for both scopes.

Returns memoryIds, chunks, and queued. Search first with memory-search when a similar memory may exist, then memory-edit it instead of storing a duplicate. The seeded memory skill holds the full guidance.

memory-edit

Edit an existing memory in place while preserving its ID, rating history, and audit trail.

memory-delete

Delete a memory by ID. Agents can delete their own memories; lead agents can also delete swarm-scoped memories.

inject-learning

Lead agent pushes learnings into a worker's memory.

User Identity Tools

Tools for managing the canonical user registry across platforms.

resolve-user

Look up a canonical user profile by a (kind, externalId) pair (e.g. {kind: "slack", externalId: "U_X"}), email (primary or alias), canonical swarm userId, or display name. Caller must supply exactly one lookup mode; empty input is rejected. Name lookup uses exact/first-token prefix matching and returns structured ambiguous candidates instead of guessing. Responses for resolved users include externalIds: Array<{kind, externalId}> so callers can reverse-look up platform handles (GitHub, Slack, etc.) from a canonical user ID.

Migration note (2026-05): provider-specific fields such as slackUserId, linearUserId, githubUsername, and gitlabUsername were removed. Use the provider-agnostic {kind, externalId} pair instead. Name search is a convenience lookup only and must not be used to stamp identity when multiple candidates are returned.

manage-user

Create, update, delete, or list user profiles in the user registry. Lead-only. Identities are managed via a declarative identities: [{kind, externalId}] array. On update, the array is treated as the desired set — entries not currently linked are added (emit identity_added); currently linked entries missing from the array are removed (emit identity_removed). Omit the field to leave identities untouched. Email-alias edits emit dedicated email_added / email_removed events.

Migration note (2026-05): the old top-level identity fields (slackUserId, linearUserId, githubUsername, gitlabUsername) were removed. Pass identities through the identities array instead.

Repository Tools

Tools for managing registered repos and their guidelines.

get-repos

List registered repos with their guidelines (PR checks, merge policy, review guidance).

update-repo

Update a repo's configuration including guidelines.