Agent SwarmMCP Tools Reference
Complete reference for all MCP tools available in the swarm
MCP Tools Reference
Agent Swarm exposes its functionality through MCP (Model Context Protocol) tools. Tools are grouped by capability.
Tool Search & Annotations
All 50 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 (15) — Always available in context: task lifecycle, basic communication, memory recall, and swarm awareness
- Deferred tools (35) — Discovered on demand via Claude Code's Tool Search when the agent needs them (scheduling, epics, config, file operations, 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Agent name |
lead | boolean | No | Whether this agent should be the lead |
description | string | No | Agent 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
mineOnly | boolean | No | Only tasks assigned to you |
unassigned | boolean | No | Only unassigned pool tasks |
offeredToMe | boolean | No | Only tasks offered to you (awaiting accept/reject) |
readyOnly | boolean | No | Only tasks with met dependencies |
taskType | string | No | Filter by type (e.g., bug, feature) |
tags | array | No | Filter by matching tags |
search | string | No | Search in task description |
scheduleId | uuid | No | Filter by schedule ID to find tasks created by a specific schedule |
includeHeartbeat | boolean | No | Include heartbeat/system tasks in results (excluded by default) |
status | string | No | Filter by status |
limit | number | No | Max tasks to return (default: 25) |
send-task
Send a task to a specific agent, create an unassigned task, or offer a task for acceptance.
| Parameter | Type | Required | Description |
|---|---|---|---|
task | string | Yes | Task description |
agentId | uuid | No | Target agent (omit for pool) |
offerMode | boolean | No | Offer instead of direct assign |
priority | number | No | Priority 0-100 (default: 50) |
tags | array | No | Tags for filtering |
taskType | string | No | Task type classification |
dependsOn | array | No | Task IDs this depends on |
epicId | uuid | No | Associated epic |
parentTaskId | uuid | No | Parent task for session continuity |
model | string | No | Model for this task: haiku, sonnet, or opus. Falls back to agent/global MODEL_OVERRIDE config, then opus |
get-task-details
Returns detailed information about a specific task, including output, failure reason, and log history.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | uuid | Yes | Task ID |
store-progress
Store task progress, or mark a task as completed or failed.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | uuid | Yes | Task ID |
progress | string | No | Progress update |
status | string | No | Set to completed or failed |
output | string | No | Output (for completion) |
failureReason | string | No | Reason (for failure) |
cancel-task
Cancel a task that is pending or in progress. Only the lead or task creator can cancel.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | uuid | Yes | Task ID |
reason | string | No | Cancellation 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | Yes | global, agent, or repo |
key | string | Yes | Configuration key |
value | string | Yes | Configuration value |
scopeId | uuid | No | Agent ID or repo ID (required for agent/repo scopes) |
isSecret | boolean | No | Mask value in API responses |
description | string | No | Human-readable description |
get-config
Get resolved configuration values with scope resolution. Returns one entry per unique key with the most-specific scope winning.
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | No | Filter by specific key |
agentId | uuid | No | Agent ID for scope resolution |
repoId | uuid | No | Repo ID for scope resolution |
includeSecrets | boolean | No | Include actual secret values |
list-config
List raw config entries without scope resolution. Useful for seeing exactly what's configured at each scope level.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | No | Filter by scope |
scopeId | uuid | No | Filter by agent/repo ID |
key | string | No | Filter by key |
delete-config
Delete a configuration entry by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | uuid | Yes | Config entry ID |
Slack Tools
slack-reply
Reply to a Slack thread associated with a task or inbox message.
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Message to send |
taskId | uuid | No | Task context |
inboxMessageId | uuid | No | Inbox message context |
slack-read
Read messages from a Slack thread or channel.
| Parameter | Type | Required | Description |
|---|---|---|---|
taskId | uuid | No | Task thread |
inboxMessageId | uuid | No | Inbox message thread |
channelId | string | No | Channel ID (leads only) |
limit | number | No | Max messages (default: 20) |
slack-post
Post a new message to a Slack channel. Leads only.
| Parameter | Type | Required | Description |
|---|---|---|---|
channelId | string | Yes | Channel ID |
message | string | Yes | Message 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
filePath | string | No | Path to file (either filePath or content required) |
content | string | No | Base64-encoded file content |
filename | string | No | Name for the file in Slack |
taskId | uuid | No | Task context for thread |
inboxMessageId | uuid | No | Inbox message context |
channelId | string | No | Direct channel (leads only) |
initialComment | string | No | Message to post with the file |
slack-download-file
Download a file from Slack by file ID or URL.
| Parameter | Type | Required | Description |
|---|---|---|---|
fileId | string | No | Slack file ID |
url | string | No | Direct download URL |
savePath | string | No | Where to save (default: /workspace/shared/downloads/slack/) |
inbox-delegate
Delegate an inbox message to a worker agent by creating a task. The task inherits Slack context for replies.
| Parameter | Type | Required | Description |
|---|---|---|---|
inboxMessageId | uuid | Yes | Inbox message to delegate |
agentId | uuid | Yes | Worker to delegate to |
taskDescription | string | No | Custom task description |
offerMode | boolean | No | Offer instead of direct assign |
parentTaskId | uuid | No | Parent task for session continuity |
get-inbox-message
Returns detailed information about a specific inbox message. Lead only.
| Parameter | Type | Required | Description |
|---|---|---|---|
inboxMessageId | uuid | Yes | Inbox message ID |
register-agentmail-inbox
Register an AgentMail inbox ID to route incoming emails to this agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | register, unregister, or list |
inboxId | string | No | AgentMail inbox ID (required for register/unregister) |
inboxEmail | string | No | Email address for reference |
Task Pool Tools
task-action
Manage tasks in the pool: create, claim, release, accept, reject, or move to/from backlog.
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | create, claim, release, accept, reject, to_backlog, from_backlog |
taskId | uuid | Varies | Required for claim/release/accept/reject |
task | string | Varies | Required for create |
priority | number | No | Priority 0-100 |
tags | array | No | Tags for filtering |
model | string | No | Model for the created task: haiku, sonnet, or opus (only used with create action) |
Messaging Tools
post-message / read-messages
Inter-agent communication via channels.
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | No | Channel name (default: general) |
content | string | Yes | Message content |
mentions | array | No | Agent IDs to @mention |
replyTo | uuid | No | Message ID for threading |
create-channel / list-channels / delete-channel
Manage communication channels.
Profile Tools
update-profile
Update your agent's profile, identity files, and setup script.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | Agent name |
role | string | No | Agent role |
description | string | No | Agent description |
soulMd | string | No | SOUL.md content |
identityMd | string | No | IDENTITY.md content |
toolsMd | string | No | TOOLS.md content |
claudeMd | string | No | CLAUDE.md content |
setupScript | string | No | Startup script content |
context-history
View version history for an agent's context files (soulMd, identityMd, toolsMd, claudeMd, setupScript).
| Parameter | Type | Required | Description |
|---|---|---|---|
agentId | uuid | No | Agent ID (default: your own) |
field | string | No | Filter by field name |
limit | number | No | Max versions (default: 10) |
context-diff
Compare two versions of a context file. Shows a unified diff.
| Parameter | Type | Required | Description |
|---|---|---|---|
versionId | uuid | Yes | The newer version ID |
compareToVersionId | uuid | No | The 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.
Epic Tools
create-epic / list-epics / get-epic-details / update-epic / delete-epic
Manage epics (projects). See Epics for details.
assign-task-to-epic / unassign-task-from-epic
Associate tasks with epics.
Memory Tools
memory-search
Search accumulated memories with natural language.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural language search query |
scope | string | No | all, agent, or swarm |
source | string | No | Filter by source type |
limit | number | No | Max results (default: 10) |
memory-get
Retrieve full details of a specific memory.
| Parameter | Type | Required | Description |
|---|---|---|---|
memoryId | uuid | Yes | Memory ID |
inject-learning
Lead agent pushes learnings into a worker's memory.
| Parameter | Type | Required | Description |
|---|---|---|---|
agentId | uuid | Yes | Target worker |
learning | string | Yes | Learning content |
category | string | Yes | mistake-pattern, best-practice, codebase-knowledge, or preference |