Skip to content

feat(cli): add "docker agent toolsets" to list built-in toolset types#3614

Open
dwin-gharibi wants to merge 6 commits into
docker:mainfrom
dwin-gharibi:feat/toolsets-catalog
Open

feat(cli): add "docker agent toolsets" to list built-in toolset types#3614
dwin-gharibi wants to merge 6 commits into
docker:mainfrom
dwin-gharibi:feat/toolsets-catalog

Conversation

@dwin-gharibi

Copy link
Copy Markdown

Summary

Adds a new top-level command, docker agent toolsets, that lists every built-in
toolset type available for use in an agent configuration (toolsets: - type: <name>),
with a one-line summary and a docs link for each. Supports --format table (default)
and --format json.

This mirrors the existing docker agent models command and closes a discoverability
gap: until now there was no CLI way to find out which toolset types exist — the list
lived only in Go source and the JSON schema.

Motivation

Writing an agent YAML means referencing toolsets by type:

toolsets:
  - type: filesystem
  - type: shell

There was no docker agent-level way to enumerate the available types or read what
they do. docker agent debug toolsets <agent-file> is hidden, needs an agent file,
and lists a specific agent's instantiated tools rather than the catalog of types.

What changed

File Change
pkg/teamloader/toolsets/catalog.go New. BuiltinToolsetInfo + BuiltinToolsets — the catalog (type, summary, docs URL), single source of truth.
pkg/teamloader/toolsets/catalog_test.go New. Drift-guard test: catalog type set must equal the registered creators; every entry must have a summary.
cmd/root/toolsets.go New. newToolsetsCmd() — the command, with --format table|json and telemetry, following the models command pattern.
cmd/root/toolsets_cmd_test.go New. Table output, JSON-equals-catalog, NoArgs, and unknown-format tests.
cmd/root/root.go Register newToolsetsCmd() (one line, in the command list).
docs/features/cli/index.md Document the new command next to docker agent models.

How it stays correct

The command reads from BuiltinToolsets, which TestBuiltinToolsetsCatalogMatchesRegistry
asserts is exactly equal to the keys of DefaultToolsetCreators(). Adding a toolset
creator without a catalog entry (or vice versa) fails the build, so the list can never
silently drift out of sync with reality.

Example output

$ docker agent toolsets
TYPE                SUMMARY
a2a                 Connect to remote agents via the Agent-to-Agent (A2A) protocol
api                 Create custom tools that call HTTP APIs
background_agents   Dispatch work to sub-agents concurrently and collect results
background_jobs     Run and manage long-running shell commands
fetch               Read content from HTTP/HTTPS URLs
filesystem          Read, write, list, search, and navigate files and directories
lsp                 Connect to Language Server Protocol servers for code intelligence
mcp                 Extend agents with external tools via the Model Context Protocol
mcp_catalog         Discover and activate remote MCP servers from the Docker MCP Catalog
memory              Persistent key-value storage for cross-session recall
model_picker        Let the agent pick between several models per turn
open_url            Open a fixed URL in the user's default browser
openapi             Generate tools automatically from an OpenAPI specification
plan                Shared persistent scratchpad for multi-agent collaboration
rag                 Search document knowledge bases with hybrid retrieval (RAG)
script              Define custom shell scripts as named tools with typed parameters
session_context     Reference a previous session as context in the current one
session_plan        Per-session plan tracker for the draft/review/execute workflow
shell               Execute shell commands in the user's environment
tasks               Persistent task database with priorities and dependencies
think               Step-by-step reasoning scratchpad for planning
todo                Manage a task list for complex multi-step workflows
user_prompt         Ask the user questions and collect interactive input
$ docker agent toolsets --format json
[
  {
    "type": "filesystem",
    "summary": "Read, write, list, search, and navigate files and directories",
    "docs": "https://docker.github.io/docker-agent/tools/filesystem"
  },
  ...
]

Testing

go test ./pkg/teamloader/toolsets/ ./cmd/root/
  • pkg/teamloader/toolsets — drift guard + summaries present.
  • cmd/root — table lists types, --format json equals the catalog, NoArgs, unknown format rejected.

All pass; gofmt -l and go vet are clean. (Local golangci-lint/task weren't
installed on my machine — CI will run task lint / task test.)

Scope / non-goals

  • Does not touch the hidden docker agent debug toolsets <agent-file> command — different purpose (per-agent instantiated tools), left as-is.
  • Lists only built-in types (the values a user can write under toolsets:); MCP/OpenAPI tools discovered at runtime are out of scope.

Closes #3613

@dwin-gharibi dwin-gharibi requested a review from a team as a code owner July 12, 2026 17:04
@aheritier aheritier added kind/feat PR adds a new feature (maps to feat:). Use on PRs only. area/cli CLI commands, flags, output formatting area/tools For features/issues/fixes related to the usage of built-in and MCP tools area/docs Documentation changes labels Jul 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/cli CLI commands, flags, output formatting area/docs Documentation changes area/tools For features/issues/fixes related to the usage of built-in and MCP tools kind/feat PR adds a new feature (maps to feat:). Use on PRs only.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: docker agent toolsets - list built-in toolset types

2 participants