> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools
> The three ways an agent can call tools: built-in tools, the autonomous looper, and custom function calling
This page was previously a duplicate of the [Streaming Responses](/docs/examples/examples/streaming) guide. It now documents the API's tool mechanisms, which live under this "Tools" section of the docs.
The Swarms API gives an agent access to tools through three independent mechanisms. They can be combined on the same request.
| Mechanism | Field | Where | What it gives the agent |
| - | - | - | - |
| Built-in tools | `tools_enabled` | Top level of the `/v1/agent/completions` request body | Search the web (`auto_search`) and scrape a page (`web_scraper`) |
| Autonomous looper tools | `selected_tools` | `agent_config` (only used when `agent_config.max_loops` is `"auto"`) | Planning, file, and sub-agent tools for the autonomous execution loop |
| Custom function tools | `tools_list_dictionary` | `agent_config` | Your own function-calling tools, defined with an OpenAI-style JSON schema |
Custom function tools (`tools_list_dictionary`) and structured JSON output (`llm_args.response_format`) are documented in full, with worked examples and response parsing, on the [Structured Outputs & Function Calling](/docs/documentation/capabilities/swarms_api_tools) page. This page covers the other two mechanisms: built-in tools and the autonomous looper's tools.
## Built-in tools (`tools_enabled`)
The API ships exactly two built-in tools. Enable them by name in the `tools_enabled` array on the request body — a sibling of `agent_config`, not a field inside it:
```json theme={null}
{
"agent_config": {
"agent_name": "Research Assistant",
"model_name": "gpt-4.1",
"max_loops": 1
},
"tools_enabled": ["auto_search", "web_scraper"],
"task": "Find the latest release notes for the Swarms Python SDK and summarize the changes."
}
```
| Tool | What it does |
| - | - |
| `auto_search` | Runs a web search and returns results the agent can reason over. |
| `web_scraper` | Fetches and formats the content of a URL. |
Fetch the live catalog of built-in tool names at any time:
```bash theme={null}
curl -X GET "https://api.swarms.world/v1/tools/available" \
-H "x-api-key: $SWARMS_API_KEY"
```
```json theme={null}
{
"status": "success",
"tools": ["auto_search", "web_scraper"]
}
```
```python theme={null}
import os
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
payload = {
"agent_config": {
"agent_name": "Research Assistant",
"description": "Researches a topic using live web search",
"system_prompt": "Use search to find current information before answering.",
"model_name": "gpt-4.1",
"max_loops": 1,
"max_tokens": 4096,
},
"tools_enabled": ["auto_search", "web_scraper"],
"task": "Find the latest release notes for the Swarms Python SDK and summarize the changes.",
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload,
)
response.raise_for_status()
print(response.json())
```
```typescript theme={null}
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const payload = {
agent_config: {
agent_name: "Research Assistant",
description: "Researches a topic using live web search",
system_prompt: "Use search to find current information before answering.",
model_name: "gpt-4.1",
max_loops: 1,
max_tokens: 4096,
},
tools_enabled: ["auto_search", "web_scraper"],
task: "Find the latest release notes for the Swarms Python SDK and summarize the changes.",
};
const response = await fetch(`${BASE_URL}/v1/agent/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
```
```bash theme={null}
curl -X POST "https://api.swarms.world/v1/agent/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_config": {
"agent_name": "Research Assistant",
"description": "Researches a topic using live web search",
"system_prompt": "Use search to find current information before answering.",
"model_name": "gpt-4.1",
"max_loops": 1,
"max_tokens": 4096
},
"tools_enabled": ["auto_search", "web_scraper"],
"task": "Find the latest release notes for the Swarms Python SDK and summarize the changes."
}'
```
### Billing
| Tool | Cost |
| - | - |
| `auto_search` | \$0.04 per request |
| `web_scraper` | \$0.15 per request |
Each built-in tool listed in `tools_enabled` is charged **once per agent completion request**, at the moment the request is set up — not per individual search or scrape the agent performs during its run, and regardless of whether the agent ends up calling the tool at all while completing the task. Only enable a tool for requests that actually need it.
Current per-unit prices are also available from [`GET /v1/usage/costs`](/docs/documentation/resources/pricing) (`usage_pricing.search_cost`, `usage_pricing.scrape_cost`) rather than hardcoding them, since they can change.
## Autonomous looper tools (`selected_tools`)
When `agent_config.max_loops` is set to `"auto"`, the agent runs in an autonomous execution loop backed by its own internal tool set — separate from `tools_enabled` and `tools_list_dictionary`. Use `agent_config.selected_tools` to restrict which of these tools are available; omit it (or pass `"all"`) to allow every tool in the list below.
```json theme={null}
{
"agent_config": {
"agent_name": "Autonomous Coordinator",
"model_name": "gpt-4.1",
"max_loops": "auto",
"selected_tools": ["create_plan", "think", "complete_task", "respond_to_user"]
},
"task": "Plan and execute a multi-step research task, reporting back when done."
}
```
The full set of 12 tools the autonomous loop can use:
| Tool | Description |
| - | - |
| `create_plan` | Create or revise the step-by-step plan for completing the task. Can be called again mid-run to add, split, drop, or reorder steps as the agent learns more. |
| `think` | Analyze the current situation and decide the next action. |
| `subtask_done` | Mark a subtask as completed and move to the next step in the plan. |
| `complete_task` | Mark the main task as complete and provide a comprehensive summary. |
| `respond_to_user` | Send a message or response to the user — for status updates, questions, or important information. |
| `create_file` | Create a new file with specified content in the agent's workspace. |
| `update_file` | Update an existing file, replacing its contents or appending to it. |
| `read_file` | Read the contents of a file. |
| `list_directory` | List files and directories at a given path. |
| `delete_file` | Delete a file. Irreversible — use with caution. |
| `create_sub_agent` | Create one or more specialized sub-agents, cached for reuse across task assignments. |
| `assign_task` | Assign a task to one or more previously created sub-agents; they run asynchronously. |
`run_bash` is **not** permitted. There is no arbitrary shell-execution tool available through the autonomous loop, regardless of what `selected_tools` requests — the API filters the tool list down to the 12 above before the agent runs.
`create_sub_agent` and `assign_task` power dynamic sub-agent delegation — see [Sub-Agent Delegation](/docs/documentation/capabilities/sub_agents) for a full walkthrough, including how sub-agents inherit the coordinator's model and tools.
## Related resources
`tools_list_dictionary` custom tools and `llm_args.response_format`
`create_sub_agent` / `assign_task` and the `handoffs` field
Connect agents to external MCP servers and their tools
Full, current pricing for every billable feature
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.