Toolsets
How AGH groups registry tools into named exposure sets for discovery, policy, and session startup.
- Audience
- Operators running durable agent work
- Focus
- Tools guidance shaped for scanability, day-two clarity, and operator context.
Toolsets group related tools so AGH 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:
agh toolsets list -o jsonInspect one expansion:
agh toolsets info agh__catalog -o jsonWhat happened: AGH 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.
Default catalog shape
The default discovery surface is intentionally small:
| Toolset or tool | Job |
|---|---|
agh__bootstrap | Gives a managed agent enough initial runtime context to orient itself. |
agh__catalog | Exposes the high-level registry catalog. |
agh__tool_search | Searches for tools by descriptor text. |
agh__tool_info | Returns one descriptor, schema, and diagnostics before invocation. |
The goal is progressive disclosure. Agents should not load every tool schema into context on every turn. They search, inspect, then invoke.
How toolsets help operators
Toolsets answer practical questions:
- Which tools are exposed by default?
- 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 surface.
- 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.