Toolsets
How CompozyOS groups registry tools into named exposure sets for discovery, policy, and session startup.
Toolsets group related tools so CompozyOS can expose a coherent operating surface without forcing every agent or operator to reason about hundreds of individual tool IDs first.
Use toolsets when you need to understand why a session can see one family of tools, why a tool is missing, or how a catalog expands into concrete tool IDs.
In one sentence
A toolset is a named bundle of registry tools with expansion diagnostics.
Inspect toolsets
List known toolsets:
compozy toolsets list -o jsonInspect one expansion:
compozy toolsets info compozy__catalog -o jsonWhat happened: CompozyOS resolved the toolset through the registry and returned the expanded tool IDs plus diagnostics. Use diagnostics when an expected tool is missing or unavailable in the current scope.
Bootstrap and catalog shape
Bootstrap and catalog toolsets identify the registry tools that help an agent orient itself:
| Toolset or tool | Job |
|---|---|
compozy__bootstrap | Gives a managed agent enough initial runtime context to orient itself. |
compozy__catalog | Exposes the high-level registry catalog. |
compozy__tool_search | Searches for tools by descriptor text. |
compozy__tool_info | Returns one descriptor, schema, and diagnostics before invocation. |
These toolsets no longer cap the hosted MCP projection for a bare managed session. When no agent or
session policy narrows the tool surface, hosted MCP projects the full availability-gated callable
catalog. Explicit tools, toolsets, deny_tools, session lineage, disabled sources, and approval
gates still restrict invocation.
The goal is precise discovery. Agents should not load every tool schema into context on every turn.
They resolve the canonical discovery ToolID through the active harness, search, inspect, then invoke
the returned tool reference. compozy__tool_list shows the currently callable projection;
compozy__tool_search and compozy__tool_info can also report known but denied tools with reason codes.
Operational toolsets
CompozyOS groups runtime capabilities by owning subsystem. These toolsets are canonical IDs that can be
granted through agent definitions or inspected through compozy toolsets info.
| Toolset | Includes |
|---|---|
compozy__sessions | Session lifecycle, prompt, history, wait, and control tools, including compozy__session_compact. |
compozy__tasks | Task CRUD, task runs, reviews, execution profiles, and notifications. |
compozy__provider_models | Provider model catalog list, curation, refresh, and source-status tools. |
compozy__provider_usage | Experimental provider usage read and background refresh tools. |
compozy__automation | Automation job, trigger, and run management. |
compozy__extensions | Extension marketplace, install, update, enable, disable, and remove tools. |
compozy__resources | Desired-state resource list, info, and snapshot inspection tools. |
compozy__mcp | MCP server probe/status diagnostics without login or logout tool calls. |
compozy__mcp_auth | Redacted MCP OAuth status for configured servers. |
compozy__clarify | One operator question through the read-only compozy__clarify tool; the wait is unbounded by default. |
Toolsets expose current canonical tool IDs only. compozy__session_compact (risk mutating, input
{session_id}, experimental) asks the agent of an idle session in the caller's workspace to
compact its own context through the command that agent advertises. It follows an unstable upstream
agent contract. When the session is busy or the agent advertises no compaction command, the tool
fails with the structural error code session_busy or compaction_unsupported. See
Session compaction.
How toolsets help operators
Toolsets answer practical questions:
- Which tools are grouped for a policy grant?
- Which concrete tool IDs are in this catalog?
- Is a tool unavailable because of scope, policy, missing daemon state, or configuration?
- Which tools should a managed agent inspect first?
How toolsets help agents
Agents should treat toolsets as navigation, not as permission to call everything blindly.
Recommended flow:
- Use the bootstrap/catalog discovery tools.
- Search for the task-specific tool family.
- Inspect the descriptor and input schema.
- Invoke only after the target and required fields are clear.
- Report the result or failure using the owning task/session surface.
Related pages
- Tool Registry explains the registry model.
- Policy and Invocation explains what happens at call time.
- Toolsets CLI Reference is the generated command reference.