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), prompt-templates, swarm-x (external command routes), agentmail, kapso (WhatsApp), chat-sdk (added automatically when CHAT_SDK_ENABLED=true)

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, Slack). The services capability was removed with the service registry; a leftover services entry in CAPABILITIES is ignored.

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 — 25 tools classified for immediate availability when their capabilities are enabled. These cover task lifecycle, memory, swarm awareness, and recurring operations: script-run, db-query, kv-get, script-query-types, get-repos, accept-steer, memory-edit, script-search, steer-task, kv-list, and get-config.
• Deferred tools — Discovered on demand via Claude Code's Tool Search, including scheduling, configuration writes, skills, workflows, MCP servers, Slack, and user identity.

Loading recurring operations upfront avoids repeated discovery while leaving less frequent tools out of the initial context.

Large Result Handling

Agent-facing MCP results are capped at 10,000 UTF-8 bytes per channel: the text content and the JSON-encoded structured content must each fit, since every harness reads only one of them. 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 the largest prose or JSON preview that fits; structured scalar JSON is omitted as a complete unit rather than cut into invalid JSON. The text channel ends with one Full value: pointer, a Shape: outline of the stored value, and a Retrieval: call; the structured channel carries the same as a truncation object.

kv-get without view arguments returns the complete stored value, although the active harness may still apply its own display limit. Pass path (a dot path such as outcome.data.rows), offset, and limit for a bounded page of the value instead; view.nextOffset says where the next page starts. For filtering or aggregation, fetch the value inside a script with ctx.swarm.kv_get (same arguments) 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.

Realtime rooms

The kv capability exposes four room tools for state shared with browser pages, agents, scripts, and workflows:

Scripts use ctx.swarm.room.get/change/reset/decode. Browser pages use swarmSdk.room(name, {schemaVersion}) for state and presence, and swarmSdk.channel(name) for transient messages. Room changes do not create page versions.

Room snapshots have a 2 MiB encoded limit and normally flush within one second. Presence and channel messages are not persisted. A schema mismatch keeps state readable but rejects writes until an explicit reset. Deploy a single API replica for shared room state.

See the Rooms API reference for request schemas.

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.

The authenticated user MCP exposes only task content and model controls. It assigns work directly to the online Lead and returns an error without creating a task when no Lead is online. Its surface does not expose task pool actions.

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.

list-model-profiles

List model profiles: named harness + model + effort combinations. Pass a profile's name as profile on send-task (or task-action create) to run that task on it, or set it as an agent's default through PATCH /api/agents/{id}/runtime. A profile runs only on its own harness. Profile writes are operator-only.

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.

For a nonterminal task, progress text such as "waiting for" or "blocked on" can return blockedWaitingElapsedMs and a nudge to use defer-task when at least three minutes have elapsed since the previous update. This is advice only; it does not create a wake-up or change the task's status.

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, Claude Managed, Codex, and Cursor advertise both modes. Claude Code, Devin, opencode, and Amp advertise queue only. Amp delivers queued messages at the next tool result; 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.

model-catalog-refresh

Lead-only. Refresh the swarm model catalog and pricing rows from models.dev. 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.

model-catalog-overlay-upsert

Lead-only. Add or update hand-verified facts for one model, for example a launch models.dev has not listed yet. Overlay fields win over models.dev, and overlay prices fill pricing-table gaps so cost recompute prices the model. The row auto-expires once models.dev matches every fact you set.

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.

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. A model the model catalog does not list is rejected unless allowCustomModel: true is set.

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.

defer-task

Complete the current task now and wake up later to continue it. Use it when the result needs time: a build, a deploy, a reply.

Pass taskId, one of delayMs or runAt, a summary of what you did and where things stand, a note that says what is pending, and optional checks to verify on wake-up. The task reaches its final state (completed) on this call and receives a deferred tag. A one-off schedule targets you, and its child task carries the deferred task as parentTaskId so the wake-up run receives the prior context. Use this tool instead of creating a continuation schedule by hand.

• Early wake-up: optionally pass wakeOn: { event: "settled", taskId: "<watched-task-id>" }, or use taskIds: ["<first-id>", "<second-id>"] instead of taskId. mode defaults to all (every member must match); use mode: "any" for the first match. Events are task.completed, task.failed, or settled (completed, failed, or cancelled). Cancellation does not match either named event. IDs must be unique, exist, be nonterminal, and differ from the task being deferred. Any invalid or already-terminal member rejects the entire call without completing the task or creating a schedule. One delayMs or runAt deadline is still required for the whole set; events and the deadline share a single wake-up so racing triggers do not create duplicate children. Pending waits survive API restarts. 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.
• Structured output: if the task has an outputSchema, pass output as a JSON string matching it. The tool stores that string verbatim as terminal output and puts the summary and deferral details in the task log. Missing or invalid output is rejected before creating a schedule. Without a schema, terminal output says when the agent will check back, or names the agents it is waiting on and the latest wake-up time; output is ignored. The time uses the requester's stored timezone, falling back to a labeled UTC time when none is set. Full summary, checks, and schedule details remain in the task log.

See deferring until another task finishes for an example.

If a watched member defers, that completion does not count as a match. The member follows its resume task across further deferrals without changing the set's ceiling. Disabling or deleting a successor schedule before it runs makes the parent's completion eligible on the next reconciliation; a wait for task.failed still falls back to its ceiling.

Superseded members follow their resume children without waking or extending the ceiling, regardless of whether supersession or child creation happens first. If no resume child exists, the wait holds to its original ceiling. Supersession itself never matches an event.

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.

Workflow triggers can use webhook, schedule, manual, or the internal event form { "type": "event", "eventName": "slack.message" }.

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

Approval requests are accessible via the dashboard at /approval-requests/{id}. Each question's label and description render there as markdown; a bare image URL on its own line in description shows as an image. The tool sends no Slack message, so share the URL yourself. When resolved, a follow-up task is automatically created for the requesting agent with the human's responses. A request with no timeoutSeconds is cancelled after APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS days (default 7) with no answer. An answer after the deadline is refused with 409.

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 second cancel returns alreadyCancelled: true. The same action is available as POST /api/approval-requests/{id}/cancel and as approval_cancel in the scripts SDK.

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.

HTML pages receive fonts, basic layout styles, and Tailwind utilities when served. Tailwind Preflight is disabled so it does not reset authored headings, spacing, or lists. These defaults apply to existing pages without regenerating their stored HTML. A page can still use explicit Tailwind utilities to override individual styles.

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. Any of path/offset/limit returns a bounded view (10 KB per channel) instead of the whole value.

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. In swarm scope the ownerless skill wins, then your own, then the only agent-owned one; when several other agents own that name, it errors with their IDs: pass skillId instead.

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 and stdio servers require 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. Changing or enabling what a stdio server runs requires lead.

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. The schema can be written with either zod or zod/mini (import * as z from "zod/mini"); Mini uses functional forms such as z.optional(z.string()).

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.fs / ctx.sh (the agent's agent-fs drive at /afs plus scratch memory, and a bash interpreter over them), ctx.stdlib, and ctx.logger. Durable launch-script-run workflows instead receive ctx.run and journaled ctx.step.* helpers, with no connection clients, no ctx.fs / ctx.sh, and no 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.

Extension tools

The scripts capability includes tools for trusted TypeScript hook bundles. Extensions run inside the API server process. See the extensions guide for the bundle format, event contracts, and lead/operator activation workflow.

extension-list

List installed extensions with their version, activation state, priority, failure count, and owner (createdByAgentId). The owner differs from the extension runtime agentId.

extension-catalog

List the predefined extensions that can be installed, with their declared assets and installed state. The catalog (also GET /api/extensions/catalog) is the only install source.

No parameters.

extension-install

Install an extension from the catalog by template name, or from an inline bundle (manifest plus files). The two forms are mutually exclusive. Inline bundles need EXTENSION_ALLOW_INLINE_INSTALL=true and a lead, operator, or dashboard-user caller; with the flag off the call fails with inline_install_disabled, and workers get 403. Install creates the extension, its ext:<name> agent, and every asset it declares (scripts, and disabled schedules, workflows and skills). Any authenticated agent can install from the catalog; the installing agent becomes its owner (createdByAgentId), and workers may install subsequent versions only for their own extensions, without activating them. A trusted lead can enable the new extension with extension-enable; operators and dashboard users can also activate it. Installation itself never enables an extension.

Extension lifecycle

Enable, disable, and version activation require a lead, operator, or dashboard user. Workers can delete their own disabled extensions, but cannot activate any extension or modify another owner's bundle. EXTENSION_ALLOW_LEAD_ACTIVATION=false restricts enable, disable, and version activation to operators/dashboard users; leads can still install drafts and delete disabled extensions. Extensions execute inside the API process without host isolation.

Get the installed id from extension-list. The script SDK exposes these tools with underscores, for example ctx.swarm.extension_enable({ id }).

Runtime pool tools

The scripts capability also registers the runtime pool tools (beta, needs RUNTIME_POOLS_ENABLED=true on the API). They proxy the runtime pools HTTP API and need HTTP MCP transport with agent identity. See Runtime pools.

Debug Tools

db-query

Execute a read-only SQL query against the swarm database. Available to all authenticated agents. Queries that read a credential table (oauth_authorizations, oauth_apps, oauth_pending, user_tokens, session_tokens, script_apis, codex_oauth_device_flows) are rejected, however the table is reached (alias, CTE, view, join or subquery). Secret-shaped values in results are redacted. Use get-oauth-access-token for OAuth tokens. Results are capped by the operator-configurable DB_QUERY_MCP_MAX_ROWS limit. Read-only enforcement also applies to fallback execution when bounded queries are disabled; write statements with RETURNING cannot bypass it.

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. Agents can edit their own memories, including memories they shared with the swarm. Editing another agent's memory by ID requires a lead agent; shared visibility does not grant edit permission.

memory-delete

Delete a memory by ID. Agents can delete their own agent-scoped memories; only the lead can delete swarm-scoped memories. The same rule applies to DELETE /api/memory/{id}, which the script SDK's memory_delete calls.

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. Only the lead can change allowMerge: resend its current value to edit other guidelines.