swarm-scripts

# Swarm Scripts Use swarm scripts when direct tool calls would create repetitive work, flood the context window, or require deterministic data processing across many records. Scripts run out-of-process with a typed Swarm SDK and return only the final result to your context. ## Decision Rubric | Situation | Use | |---|---| | 1-10 SDK calls, result fits in context | Direct tool call | | 10+ items or bulk fan-out SDK operations | Script | | Heavy fetch, parse, transform, or aggregation | Script or context-mode | | Single expensive web fetch | `ctx_fetch_and_index` | | Multi-agent parallel work | Workflow | | Logic needed across sessions or agents | Named script | ## Loading Script Tools The script tools are deferred. Before authoring or running a script, load the relevant tools with ToolSearch: ```text script-query-types script-upsert script-run script-search script-delete ``` Use `script-query-types` before non-trivial work so the script matches the live `swarm-sdk.d.ts` and stdlib signatures. ## Inline Script Pattern Use `script-run` with inline source for one-off work: ```typescript export default async function main(args: { status: string; limit: number }, ctx) { const { swarm, logger } = ctx; const result = await swarm.task_list({ status: args.status, limit: args.limit }); logger.info(`Fetched ${result.tasks.length} tasks`); return { total: result.tasks.length, tasks: result.tasks.map((task) => ({ id: task.id, status: task.status, ...