Agent SwarmAgent Swarm
Reference

MCP Tools Reference

Complete reference for all MCP tools available in the swarm

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 (13) — Always available in context: task lifecycle, basic communication, memory recall, and swarm awareness
  • Deferred tools (74) — 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.

ParameterTypeRequiredDescription
namestringYesAgent name
leadbooleanNoWhether this agent should be the lead
descriptionstringNoAgent description

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

ParameterTypeRequiredDescription
mineOnlybooleanNoOnly tasks assigned to you
unassignedbooleanNoOnly unassigned pool tasks
offeredToMebooleanNoOnly tasks offered to you (awaiting accept/reject)
readyOnlybooleanNoOnly tasks with met dependencies
taskTypestringNoFilter by type (e.g., bug, feature)
tagsarrayNoFilter by matching tags
searchstringNoSearch in task description
scheduleIduuidNoFilter by schedule ID to find tasks created by a specific schedule
includeHeartbeatbooleanNoInclude heartbeat/system tasks in results (excluded by default)
statusstringNoFilter by status
limitnumberNoMax tasks to return (default: 25)

send-task

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

ParameterTypeRequiredDescription
taskstringYesTask description
agentIduuidNoTarget agent (omit for pool)
offerModebooleanNoOffer instead of direct assign
prioritynumberNoPriority 0-100 (default: 50)
tagsarrayNoTags for filtering
taskTypestringNoTask type classification
dependsOnarrayNoTask IDs this depends on
parentTaskIduuidNoParent task for session continuity
dirstringNoWorking directory (absolute path) for the agent to start in
modelstringNoModel for this task: haiku, sonnet, or opus. Falls back to agent/global MODEL_OVERRIDE config, then opus
slackChannelIdstringNoSlack channel ID for progress updates (auto-inherited if omitted)
slackThreadTsstringNoSlack thread timestamp (auto-inherited if omitted)
slackUserIdstringNoSlack user ID of the original requester (auto-inherited if omitted)

Slack metadata is auto-inherited from the creator's current task via X-Source-Task-Id header. Explicit params override auto-inherited values when provided.

get-task-details

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

ParameterTypeRequiredDescription
taskIduuidYesTask ID

store-progress

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

ParameterTypeRequiredDescription
taskIduuidYesTask ID
progressstringNoProgress update
statusstringNoSet to completed or failed
outputstringNoOutput (for completion). Validated against outputSchema if the task defines one
failureReasonstringNoReason (for failure)
costDataobjectNoSession cost tracking: totalCostUsd (required), inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, durationMs, numTurns, model

cancel-task

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

ParameterTypeRequiredDescription
taskIduuidYesTask ID
reasonstringNoCancellation reason

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

ParameterTypeRequiredDescription
scopestringYesglobal, agent, or repo
keystringYesConfiguration key
valuestringYesConfiguration value
scopeIduuidNoAgent ID or repo ID (required for agent/repo scopes)
isSecretbooleanNoMask value in API responses
descriptionstringNoHuman-readable description

get-config

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

ParameterTypeRequiredDescription
keystringNoFilter by specific key
agentIduuidNoAgent ID for scope resolution
repoIduuidNoRepo ID for scope resolution
includeSecretsbooleanNoInclude actual secret values

list-config

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

ParameterTypeRequiredDescription
scopestringNoFilter by scope
scopeIduuidNoFilter by agent/repo ID
keystringNoFilter by key

delete-config

Delete a configuration entry by its ID.

ParameterTypeRequiredDescription
iduuidYesConfig entry ID

Slack Tools

slack-reply

Reply to a Slack thread associated with a task.

ParameterTypeRequiredDescription
messagestringYesMessage to send
taskIduuidNoTask context

slack-read

Read messages from a Slack thread or channel.

ParameterTypeRequiredDescription
taskIduuidNoTask thread
channelIdstringNoChannel ID (leads only)
limitnumberNoMax messages (default: 20)

slack-post

Post a new message to a Slack channel. Leads only.

ParameterTypeRequiredDescription
channelIdstringYesChannel ID
messagestringYesMessage content

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

ParameterTypeRequiredDescription
filePathstringNoPath to file (either filePath or content required)
contentstringNoBase64-encoded file content
filenamestringNoName for the file in Slack
taskIduuidNoTask context for thread
channelIdstringNoDirect channel (leads only)
initialCommentstringNoMessage to post with the file

slack-download-file

Download a file from Slack by file ID or URL.

ParameterTypeRequiredDescription
fileIdstringNoSlack file ID
urlstringNoDirect download URL
savePathstringNoWhere to save (default: /workspace/shared/downloads/{agentId}/slack/)

register-agentmail-inbox

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

ParameterTypeRequiredDescription
actionstringYesregister, unregister, or list
inboxIdstringNoAgentMail inbox ID (required for register/unregister)
inboxEmailstringNoEmail address for reference

Task Pool Tools

task-action

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

ParameterTypeRequiredDescription
actionstringYescreate, claim, release, accept, reject, to_backlog, from_backlog
taskIduuidVariesRequired for claim/release/accept/reject
taskstringVariesRequired for create
prioritynumberNoPriority 0-100
tagsarrayNoTags for filtering
dirstringNoWorking directory (absolute path) for the agent to start in (only used with create action)
modelstringNoModel for the created task: haiku, sonnet, or opus (only used with create action)

Messaging Tools

post-message / read-messages

Inter-agent communication via channels.

ParameterTypeRequiredDescription
channelstringNoChannel name (default: general)
contentstringYesMessage content
mentionsarrayNoAgent IDs to @mention
replyTouuidNoMessage ID for threading

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.

ParameterTypeRequiredDescription
agentIdstring (UUID)NoTarget agent ID. If omitted, updates the calling agent. Only lead agents can update other agents.
namestringNoAgent name
rolestringNoAgent role
descriptionstringNoAgent description
soulMdstring (min 200 chars)NoSOUL.md content. Must be at least 200 characters to prevent accidental corruption.
identityMdstring (min 200 chars)NoIDENTITY.md content. Must be at least 200 characters to prevent accidental corruption.
toolsMdstringNoTOOLS.md content
claudeMdstringNoCLAUDE.md content
setupScriptstringNoStartup script content

context-history

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

ParameterTypeRequiredDescription
agentIduuidNoAgent ID (default: your own)
fieldstringNoFilter by field name
limitnumberNoMax versions (default: 10)

context-diff

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

ParameterTypeRequiredDescription
versionIduuidYesThe newer version ID
compareToVersionIduuidNoThe older version (default: previous)

Service Tools

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

Manage HTTP service discovery. See Service Discovery for details.

Scheduling Tools

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

Manage recurring and one-time task automation. Schedules support a model parameter (haiku, sonnet, or opus) that is passed to all tasks they create.

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

See Scheduled Tasks for details.

Workflow Tools

create-workflow

Create a new automation workflow with a DAG definition.

ParameterTypeRequiredDescription
namestringYesUnique workflow name
descriptionstringNoWhat the workflow does
definitionobjectYesDAG definition with nodes array
triggersarrayNoTrigger configs: webhook, schedule, or manual
cooldownobjectNoCooldown period: { hours, minutes, seconds }
inputobjectNoWorkflow-level input values (env vars, secrets, or literals)

get-workflow

Get workflow details by ID.

ParameterTypeRequiredDescription
iduuidYesWorkflow ID

list-workflows

List all workflows, optionally filtering by enabled status.

ParameterTypeRequiredDescription
enabledbooleanNoFilter by enabled/disabled

update-workflow

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

ParameterTypeRequiredDescription
iduuidYesWorkflow ID
namestringNoNew name
descriptionstringNoNew description
definitionobjectNoUpdated DAG definition
enabledbooleanNoEnable or disable

delete-workflow

Delete a workflow and all its run history.

ParameterTypeRequiredDescription
iduuidYesWorkflow ID

trigger-workflow

Manually trigger a workflow execution.

ParameterTypeRequiredDescription
iduuidYesWorkflow ID
triggerDataobjectNoData to pass as trigger context

get-workflow-run

Get details of a specific workflow run including step statuses.

ParameterTypeRequiredDescription
iduuidYesRun ID

list-workflow-runs

List runs for a specific workflow.

ParameterTypeRequiredDescription
workflowIduuidYesWorkflow ID
statusstringNoFilter by run status

retry-workflow-run

Retry a failed workflow run from the point of failure.

ParameterTypeRequiredDescription
runIduuidYesRun ID to retry

cancel-workflow-run

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

ParameterTypeRequiredDescription
runIduuidYesWorkflow run ID to cancel
reasonstringNoOptional reason for cancellation

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.

ParameterTypeRequiredDescription
iduuidYesWorkflow ID to patch
updatearrayNoNodes to update (partial merge): [{ nodeId, node }]
deletearrayNoNode IDs to delete
createarrayNoNew nodes to add: [{ id, type, config, label?, next?, inputs? }]
onNodeFailurestringNoUpdate failure behavior: fail or continue

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.

ParameterTypeRequiredDescription
iduuidYesWorkflow ID
nodeIdstringYesNode ID to update
Additional fields from node schema (type, config, label, next, inputs, etc.)

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.

ParameterTypeRequiredDescription
titlestringYesTitle of the approval request
questionsarrayYesQuestions to ask the human

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.

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.

ParameterTypeRequiredDescription
skillIdstringNoSkill ID
namestringNoSkill name (resolved with precedence)

skill-list

List available skills with optional filters.

ParameterTypeRequiredDescription
typestringNoFilter by type: remote or personal
scopestringNoFilter by scope: global, swarm, or agent
agentIdstringNoFilter by owning agent

Search skills by keyword (name and description).

ParameterTypeRequiredDescription
querystringYesSearch query
limitnumberNoMax results (default: 20)

skill-install

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

ParameterTypeRequiredDescription
skillIdstringYesID of the skill to install

skill-uninstall

Remove a skill from an agent.

ParameterTypeRequiredDescription
skillIdstringYesID of the skill to uninstall
agentIdstringNoTarget agent (default: calling agent)

skill-update

Update a skill's content or settings. Re-parses frontmatter if content changes.

ParameterTypeRequiredDescription
skillIdstringNoSkill ID to update
contentstringNoNew SKILL.md content
isEnabledbooleanNoToggle enabled/disabled

skill-publish

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

ParameterTypeRequiredDescription
skillIdstringYesID of the personal skill to publish

skill-delete

Delete a skill. Only the owning agent or lead can delete.

ParameterTypeRequiredDescription
skillIdstringYesID of the skill to delete

skill-install-remote

Fetch and install a remote skill from a GitHub repository.

ParameterTypeRequiredDescription
sourceRepostringYesGitHub repo (e.g. vercel-labs/skills)
sourcePathstringNoPath within repo (e.g. skills/nextjs)

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.

ParameterTypeRequiredDescription
namestringYesServer name
descriptionstringNoServer description
transportstringYesstdio, http, or sse
commandstringNoCommand to run (required for stdio)
argsstringNoJSON array of arguments (stdio only)
urlstringNoServer URL (required for http/sse)

mcp-server-get

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

ParameterTypeRequiredDescription
idstringNoMCP server ID
namestringNoMCP server name (resolved with scope cascade)

mcp-server-list

List MCP servers with optional filters.

ParameterTypeRequiredDescription
scopestringNoFilter by scope: global, swarm, or agent
transportstringNoFilter by transport: stdio, http, or sse
searchstringNoSearch by name or description

mcp-server-update

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

ParameterTypeRequiredDescription
idstringYesMCP server ID
namestringNoNew name
descriptionstringNoNew description
transportstringNoNew transport type
commandstringNoNew command (stdio)
argsstringNoNew JSON array of arguments
urlstringNoNew URL (http/sse)
headersstringNoNew JSON object of non-secret headers
envConfigKeysstringNoNew env config key mappings
headerConfigKeysstringNoNew header config key mappings
isEnabledbooleanNoToggle enabled/disabled

mcp-server-install

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

ParameterTypeRequiredDescription
mcpServerIdstringYesID of the MCP server to install

mcp-server-uninstall

Uninstall an MCP server from an agent.

ParameterTypeRequiredDescription
mcpServerIdstringYesID of the MCP server to uninstall
agentIdstringNoTarget agent (default: calling agent)

mcp-server-delete

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

ParameterTypeRequiredDescription
idstringYesMCP server ID

Debug Tools

db-query

Execute a read-only SQL query against the swarm database. Lead-only. Results capped at 100 rows.

ParameterTypeRequiredDescription
sqlstringYesSQL query (read-only only — writes are rejected)
paramsarrayNoQuery parameters

Memory Tools

Search accumulated memories with natural language.

ParameterTypeRequiredDescription
querystringYesNatural language search query
scopestringNoall, agent, or swarm
sourcestringNoFilter by source type
limitnumberNoMax results (default: 10)

memory-get

Retrieve full details of a specific memory.

ParameterTypeRequiredDescription
memoryIduuidYesMemory ID

memory-delete

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

ParameterTypeRequiredDescription
memoryIduuidYesMemory ID to delete

inject-learning

Lead agent pushes learnings into a worker's memory.

ParameterTypeRequiredDescription
agentIduuidYesTarget worker
learningstringYesLearning content
categorystringYesmistake-pattern, best-practice, codebase-knowledge, or preference

User Identity Tools

Tools for managing the canonical user registry across platforms.

resolve-user

Look up a canonical user profile by any platform-specific identifier (Slack ID, Linear ID, GitHub username, email, or name).

ParameterTypeRequiredDescription
slackUserIdstringNoSlack user ID
linearUserIdstringNoLinear user UUID
githubUsernamestringNoGitHub username
gitlabUsernamestringNoGitLab username
emailstringNoEmail address
namestringNoName (fuzzy substring match)

manage-user

Create, update, delete, or list user profiles in the user registry. Lead-only.

ParameterTypeRequiredDescription
actionstringYescreate, update, delete, list, or get
userIdstringNoUser ID (required for update/delete/get)
namestringNoDisplay name (required for create)
emailstringNoPrimary email address
rolestringNoRole (e.g., "founder", "engineer")
notesstringNoFree-form notes
slackUserIdstringNoSlack user ID
linearUserIdstringNoLinear user UUID
githubUsernamestringNoGitHub username
gitlabUsernamestringNoGitLab username
emailAliasesarrayNoAdditional email addresses
preferredChannelstringNoPreferred contact channel
timezonestringNoTimezone (e.g., America/New_York)

Repository Tools

Tools for managing registered repos and their guidelines.

get-repos

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

ParameterTypeRequiredDescription
namestringNoFilter by repo name (returns all if omitted)

update-repo

Update a repo's configuration including guidelines.

ParameterTypeRequiredDescription
idstringYesRepo ID to update
urlstringNoNew repo URL
namestringNoNew repo name
clonePathstringNoNew clone path
defaultBranchstringNoNew default branch
autoClonebooleanNoWhether to auto-clone

x402 Payments

Enable agents to make USDC micropayments on x402-gated APIs

Environment Variables

Complete reference for all configuration environment variables

On this page

Tool Search & AnnotationsCore Toolsjoin-swarmpoll-taskget-swarmget-taskssend-taskget-task-detailsstore-progresscancel-taskmy-agent-infoConfig Toolsset-configget-configlist-configdelete-configSlack Toolsslack-replyslack-readslack-postslack-list-channelsslack-upload-fileslack-download-fileregister-agentmail-inboxTask Pool Toolstask-actionMessaging Toolspost-message / read-messagescreate-channel / list-channels / delete-channelProfile Toolsupdate-profilecontext-historycontext-diffService Toolsregister-service / unregister-service / list-services / update-service-statusScheduling Toolscreate-schedule / list-schedules / update-schedule / delete-schedule / run-schedule-nowWorkflow Toolscreate-workflowget-workflowlist-workflowsupdate-workflowdelete-workflowtrigger-workflowget-workflow-runRelatedlist-workflow-runsretry-workflow-runcancel-workflow-runpatch-workflowpatch-workflow-nodeHuman-in-the-Loop Toolsrequest-human-inputSkill Toolsskill-createskill-getskill-listskill-searchskill-installskill-uninstallskill-updateskill-publishskill-deleteskill-install-remoteskill-sync-remoteMCP Server Toolsmcp-server-createmcp-server-getmcp-server-listmcp-server-updatemcp-server-installmcp-server-uninstallmcp-server-deleteDebug Toolsdb-queryMemory Toolsmemory-searchmemory-getmemory-deleteinject-learningUser Identity Toolsresolve-usermanage-userRepository Toolsget-reposupdate-repo