MCP Tools Reference

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

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.

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.

cancel-task

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

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.

Slack Tools

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

register-kapso-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, 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

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

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

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.

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 runs for a specific workflow.

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.

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. Upserts atomically. 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).

script-upsert

Create or update a named script. Source must export a default function. 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.

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 capped at 100 rows.

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.

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