Skip to content

Commit c93019a

Browse files
dgageotdgageot
committed
docs: deduplicate tool documentation into individual pages
Move built-in tool documentation from being duplicated across concepts/tools and configuration/tools into dedicated pages under docs/tools/ (one page per toolset). - Create individual pages for: filesystem, shell, think, todo, memory, fetch, script, transfer-task, background-agents, handoff, a2a - Slim down concepts/tools to a summary table linking to each tool page - Slim down configuration/tools to a summary table plus cross-cutting concerns (MCP, auto-install, filtering, deferred loading) - Update nav.yml to list all 14 built-in tools (was 3) Assisted-By: docker-agent
1 parent e5d75fe commit c93019a

18 files changed

Lines changed: 683 additions & 518 deletions

File tree

‎docs/_data/nav.yml‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,12 +43,34 @@
4343

4444
- section: Built-in Tools
4545
items:
46-
- title: LSP Tool
46+
- title: Filesystem
47+
url: /tools/filesystem/
48+
- title: Shell
49+
url: /tools/shell/
50+
- title: Think
51+
url: /tools/think/
52+
- title: Todo
53+
url: /tools/todo/
54+
- title: Memory
55+
url: /tools/memory/
56+
- title: Fetch
57+
url: /tools/fetch/
58+
- title: Script
59+
url: /tools/script/
60+
- title: LSP
4761
url: /tools/lsp/
48-
- title: User Prompt Tool
49-
url: /tools/user-prompt/
50-
- title: API Tool
62+
- title: API
5163
url: /tools/api/
64+
- title: User Prompt
65+
url: /tools/user-prompt/
66+
- title: Transfer Task
67+
url: /tools/transfer-task/
68+
- title: Background Agents
69+
url: /tools/background-agents/
70+
- title: Handoff
71+
url: /tools/handoff/
72+
- title: A2A
73+
url: /tools/a2a/
5274

5375
- section: Features
5476
items:

‎docs/concepts/tools/index.md‎

Lines changed: 23 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -21,175 +21,47 @@ When an agent needs to perform an action, it makes a **tool call**. The docker-a
2121
<div class="callout-title">ℹ️ Tool Confirmation
2222
</div>
2323
<p>By default, docker-agent asks for user confirmation before executing tools that have side effects (shell commands, file writes). Use <code>--yolo</code> to auto-approve all tool calls.</p>
24-
2524
</div>
2625

2726
## Built-in Tools
2827

29-
docker-agent ships with several built-in tools that require no external dependencies. Each is enabled by adding its `type` to the agent's `toolsets` list.
30-
31-
### Filesystem
32-
33-
Gives agents the ability to read, write, list, search, and navigate files and directories. The agent receives tools such as `read_file`, `write_file`, `list_directory`, `search_files_content`, `directory_tree`, and more.
34-
35-
```yaml
36-
toolsets:
37-
- type: filesystem
38-
```
39-
40-
The filesystem tool respects the working directory and allows agents to explore codebases, edit config files, create new files, and perform search-and-replace operations.
41-
42-
### Shell
43-
44-
Allows agents to execute arbitrary shell commands in the user's environment. This is one of the most powerful tools — it lets agents run builds, install dependencies, query APIs, and interact with the system.
45-
46-
```yaml
47-
toolsets:
48-
- type: shell
49-
```
50-
51-
Commands run in a fresh shell session with access to all environment variables. Each invocation is isolated — no state persists between calls. Requires user confirmation by default.
52-
53-
### Think
54-
55-
A reasoning scratchpad that lets agents think step-by-step before acting. The agent can write its thoughts without producing visible output to the user — useful for planning complex tasks, breaking down problems, and reasoning through multi-step solutions.
56-
57-
```yaml
58-
toolsets:
59-
- type: think
60-
```
61-
62-
This is a lightweight tool with no side effects. It's recommended for all agents — it improves the quality of reasoning on complex tasks at minimal cost.
63-
64-
### Todo
65-
66-
Task list management. Agents can create, update, list, and track progress on tasks. Useful for complex multi-step workflows where the agent needs to stay organized.
67-
68-
```yaml
69-
toolsets:
70-
- type: todo
71-
```
72-
73-
The agent gets tools like `create_todo`, `update_todos`, and `list_todos` with status tracking (pending, in-progress, completed).
74-
75-
### Memory
76-
77-
Persistent key-value storage backed by SQLite. Data survives across sessions, allowing agents to remember facts, user preferences, project context, and past decisions.
78-
79-
```yaml
80-
toolsets:
81-
- type: memory
82-
path: ./agent_memory.db # optional: custom database path
83-
```
84-
85-
Without `path`, a default location is used. Memory is especially useful for long-running assistants that need to recall information across conversations.
86-
87-
### Fetch
88-
89-
Make HTTP requests (GET, POST, PUT, DELETE, etc.) to external APIs. The agent can read web pages, call REST APIs, download data, and interact with web services.
90-
91-
```yaml
92-
toolsets:
93-
- type: fetch
94-
```
95-
96-
### Script
97-
98-
Define custom shell scripts as named tools. Unlike the generic `shell` tool where the agent writes the command, script tools execute predefined commands — useful for exposing safe, constrained operations.
99-
100-
```yaml
101-
toolsets:
102-
- type: script
103-
shell:
104-
run_tests:
105-
cmd: task test
106-
description: Run the project test suite
107-
lint:
108-
cmd: task lint
109-
description: Run the linter
110-
```
111-
112-
### Transfer Task
113-
114-
The `transfer_task` tool is automatically available when an agent has `sub_agents` configured. It allows the agent to delegate tasks to specialized sub-agents and receive their results. This is the core mechanism for multi-agent orchestration — you don't need to add it manually.
28+
docker-agent ships with several built-in tools that require no external dependencies. Each is enabled by adding its `type` to the agent's `toolsets` list:
29+
30+
| Tool | Description |
31+
| --- | --- |
32+
| [Filesystem](/tools/filesystem/) | Read, write, list, search, and navigate files and directories |
33+
| [Shell](/tools/shell/) | Execute arbitrary shell commands in the user's environment |
34+
| [Think](/tools/think/) | Step-by-step reasoning scratchpad for planning and decision-making |
35+
| [Todo](/tools/todo/) | Task list management for complex multi-step workflows |
36+
| [Memory](/tools/memory/) | Persistent key-value storage backed by SQLite |
37+
| [Fetch](/tools/fetch/) | Make HTTP requests to external APIs and web services |
38+
| [Script](/tools/script/) | Define custom shell scripts as named tools |
39+
| [LSP](/tools/lsp/) | Connect to Language Server Protocol servers for code intelligence |
40+
| [API](/tools/api/) | Create custom tools that call HTTP APIs without writing code |
41+
| [User Prompt](/tools/user-prompt/) | Ask users questions and collect interactive input |
42+
| [Transfer Task](/tools/transfer-task/) | Delegate tasks to sub-agents (auto-enabled with `sub_agents`) |
43+
| [Background Agents](/tools/background-agents/) | Dispatch work to sub-agents concurrently |
44+
| [Handoff](/tools/handoff/) | Delegate tasks to remote agents via A2A |
45+
| [A2A](/tools/a2a/) | Connect to remote agents via the Agent-to-Agent protocol |
11546

11647
## MCP Tools
11748

11849
docker-agent supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for extending agents with external tools. There are three ways to connect MCP tools:
11950

120-
### Docker MCP (Recommended)
121-
122-
Run MCP servers in Docker containers for security and isolation:
123-
124-
```yaml
125-
toolsets:
126-
- type: mcp
127-
ref: docker:duckduckgo # web search
128-
- type: mcp
129-
ref: docker:github-official # GitHub integration
130-
```
131-
132-
Docker MCP tools run through the [Docker MCP Gateway](https://github.com/docker/mcp-gateway), which manages container lifecycles and provides security isolation. Browse available tools in the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp).
133-
134-
### Local MCP (stdio)
135-
136-
Run MCP servers as local processes communicating over stdin/stdout. Here's an example adding `rust-mcp-filesystem` for file operations alongside a Docker MCP tool:
51+
- **Docker MCP** (recommended) — Run MCP servers in Docker containers via the [MCP Gateway](https://github.com/docker/mcp-gateway). Browse the [Docker MCP Catalog](https://hub.docker.com/search?q=&type=mcp).
52+
- **Local MCP (stdio)** — Run MCP servers as local processes communicating over stdin/stdout.
53+
- **Remote MCP (SSE / HTTP)** — Connect to MCP servers running on a network. See [Remote MCP Servers](/features/remote-mcp/).
13754

13855
```yaml
13956
toolsets:
14057
- type: mcp
14158
ref: docker:duckduckgo
142-
- type: mcp
143-
command: rust-mcp-filesystem
144-
args: ["--allow-write", "."]
145-
tools: ["read_file", "write_file"] # optional: only expose specific tools
146-
env:
147-
RUST_LOG: debug
14859
```
14960
150-
### Remote MCP (SSE / HTTP)
151-
152-
Connect to MCP servers running on a network:
153-
154-
```yaml
155-
toolsets:
156-
- type: mcp
157-
remote:
158-
url: "https://mcp.example.com"
159-
transport_type: "sse"
160-
headers:
161-
Authorization: "Bearer your-token"
162-
```
163-
164-
## Tool Filtering
165-
166-
Toolsets may expose many tools. You can use the `tools` property to whitelist only the ones you need. This works for any toolset type — not just MCP:
167-
168-
```yaml
169-
toolsets:
170-
- type: mcp
171-
ref: docker:github-official
172-
tools: ["list_issues", "create_issue"] # only these MCP tools
173-
- type: filesystem
174-
tools: ["read_file", "search_files_content"] # only these filesystem tools
175-
```
176-
177-
## Tool Instructions
178-
179-
Add custom instructions that are injected into the agent's context when a toolset is loaded:
180-
181-
```yaml
182-
toolsets:
183-
- type: mcp
184-
ref: docker:github-official
185-
instruction: |
186-
Use these tools to manage GitHub issues.
187-
Always check for existing issues before creating new ones.
188-
```
61+
See [Tool Config](/configuration/tools/#mcp-tools) for full MCP configuration reference.
18962
19063
<div class="callout callout-tip">
19164
<div class="callout-title">💡 See also
19265
</div>
193-
<p>For connecting to 50+ cloud services via remote MCP with OAuth, see <a href="{{ '/features/remote-mcp/' | relative_url }}">Remote MCP Servers</a>. For RAG (document retrieval), see <a href="{{ '/features/rag/' | relative_url }}">RAG</a>. For full tool config reference, see <a href="{{ '/configuration/tools/' | relative_url }}">Tool Config</a>.</p>
194-
66+
<p>For full configuration reference, see <a href="/configuration/tools/">Tool Config</a>. For RAG (document retrieval), see <a href="/features/rag/">RAG</a>.</p>
19567
</div>

‎docs/configuration/agents/index.md‎

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ agents:
109109

110110
## Deferred Tool Loading
111111

112-
Load tools on-demand to speed up agent startup:
112+
Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading](/configuration/tools/#deferred-tool-loading) for details.
113113

114114
```yaml
115115
agents:
@@ -121,26 +121,9 @@ agents:
121121
- type: mcp
122122
ref: docker:github-official
123123
defer: true
124-
- type: mcp
125-
ref: docker:slack
126-
defer: true
127124
- type: filesystem
128125
```
129126

130-
Or defer specific tools within a toolset:
131-
132-
```yaml
133-
agents:
134-
root:
135-
model: openai/gpt-4o
136-
toolsets:
137-
- type: mcp
138-
ref: docker:github-official
139-
defer:
140-
- "list_issues"
141-
- "search_repos"
142-
```
143-
144127
## Fallback Configuration
145128

146129
Automatically switch to backup models when the primary fails:

0 commit comments

Comments
 (0)