Last modified September 7, 2026

Muster toolsets reference

A toolset is the selector list an agent declares to say which of the gateway’s tools it’s composed with. Muster evaluates it per request as the third filter on the caller’s catalog. For the concept, see Toolsets and presets; for defining presets on your installation, see Define toolset presets. This page is the field-level reference, verified against Muster 5.12.0, the Generic agent chart 0.6.0, agent-manager 0.4.0, and the fleet meta-package agent-platform 3.11.0.

Inline selectors

A toolset, wherever it’s declared inline (header, chart value, agent-manager argument, filter_tools argument), is a list of selectors of these four forms:

Names are exact and case-sensitive; a selector matches ^(preset|server|workflow|tool):[^\s,]+$. At most 32 selectors inline—larger selections are presets. Core tools (core_*) aren’t a server: select them with tool:core_workflow_list inline or a core_* pattern in a preset; since Muster 5.13.0 they also carry annotations, so read-only includes the read-only ones.

Rejected inline, with an error result naming the toolset and the selector:

These are error results on every meta-tool call—get_resource and get_prompt included—never a silent fall-back to the unscoped catalog and never a silent degradation to the selectors that did parse. They aren’t sticky: the next request without the header is unscoped again.

The X-Muster-Toolset header

X-Muster-Toolset: preset:read-only, workflow:incident-triage

A comma-separated list of inline selectors; whitespace around each selector is trimmed. Muster reads the header on every request, nothing is bound to the MCP session, and a request without the header is unscoped—exactly the behavior before toolsets existed. Two requests on the same session with different headers get different catalogs.

Presets configuration

Presets are toolsetPresets in Muster’s config.yaml—chart value muster.toolsetPresets on the Muster chart, muster.muster.toolsetPresets on the fleet meta-package and the standalone chart, which forward their muster: block to the Muster release.

toolsetPresets:
  <name>:
    description: <string>          # shown by filter_tools with include_presets
    include:                       # rules, exactly one key each
      - tool: <exact exposed name>
      - pattern: <glob on the exposed name>
      - server: <name>
      - workflow: <name>
      - label: <key>=<value>       # or <key>; presets only
      - readOnly: true
      - preset: <name>             # composition, include only
    exclude: []                    # optional; same shapes except preset

A preset resolves to the union of its includes minus its excludes.

Validation at startup

muster serve refuses to start when toolsetPresets redefines a built-in preset, when a rule sets no key or more than one, when a pattern doesn’t compile, when readOnly is false, when exclude composes a preset, when a composition names an unknown preset, or when compositions cycle. Every error names the preset and the rule position. The label: rule requires Muster 5.12.0; an older Muster refuses to start on it.

Workflow read-only derivation

A workflow is read-only when every tool its steps reference—conditions, forEach and parallel sub-steps and onFailure handlers included, nested workflows followed—resolves in the caller’s catalog to a tool annotated read-only. A step calling a core tool that writes (core_workflow_delete, core_service_stop, …), an unknown tool, or a cycle makes the workflow not read-only; a step calling a read-only core tool (core_workflow_list, …) keeps it read-only. The derived hint fills the workflow tool’s readOnlyHint annotation, so describe_tool shows it and preset:read-only includes the pure-query workflows.

Built-in presets

Built into Muster and not redefinable by configuration:

Platform presets

Shipped by the fleet meta-package agent-platform (3.11.0 and later) as muster.muster.toolsetPresets, selecting by the label agent-platform.giantswarm.io/tool-group that every platform-shipped MCPServer resource carries:

The standalone chart 0.37.0 runs Muster 5.12.0; the two presets follow in a later standalone release and can be added to its values in the meantime (same key).

What the meta-tools do with a toolset

• list_tools, filter_tools, describe_tool, and list_core_tools read the filtered catalog. describe_tool of a tool the session can see but the toolset excludes answers tool "<name>" is outside the toolset [<selectors>]; an unknown name is still Tool not found.
• call_tool—including workflow execution (workflow_<name>)—of a name outside the toolset is refused with tool "<name>" is outside the toolset [<selectors>] and logged once at info level with the tool, the toolset, and the session. The tools a workflow’s steps call internally are the workflow author’s composition and aren’t re-checked.
• Resources and prompts follow the servers: a server is inside the toolset when at least one of its tools is selected. list_resources, filter_resources, describe_resource, list_prompts, filter_prompts, and describe_prompt hide the others; get_resource and get_prompt refuse them (resource "<uri>" is outside the toolset […]).
• list_tools’ servers_requiring_auth isn’t narrowed: it tells the caller which sign-in would make more of the toolset resolve.
• tools/list—the meta-tools themselves—is unchanged.

filter_tools arguments and response

filter_tools accepts two toolset-related arguments next to its discovery arguments:

{"name": "filter_tools", "arguments": {"toolset": ["preset:read-only", "server:pro"], "include_presets": true}}

Response additions:

Tool information

Every entry of list_tools and filter_tools, and the describe_tool response, carries:

The Generic agent chart’s toolset value

The Generic agent chart (0.6.0 and later) takes the toolset as a top-level value, a list of selector strings:

toolset:
  - preset:read-only
  - workflow:incident-triage

The schema declares toolset as [array, null] of strings; the cap and the empty-list rule are template checks so they can carry those messages. muster.toolNames is a different knob: kagent applies it to Muster’s meta-tools (list_tools, call_tool, …), so it never narrows the tools behind the gateway—a toolset is the way to do that.

agent-manager’s toolset argument

agent-manager (0.4.0 and later) composes the same chart value. Its tools and the REST routes behind them:

agent-manager validates the inline grammar—non-empty, at most 32 selectors, the four forms, toolset: reserved, label: refused—and writes the list to the chart’s toolset value exactly as given. It never resolves a toolset; resolution is Muster’s, per caller. The former toolNames argument is removed; a caller still passing it gets toolNames never narrowed anything against muster (kagent filters muster's meta-tools only); declare a toolset instead, e.g. toolset: ["preset:read-only"].

Versions

Related

• Toolsets and presets - The concept, and why a toolset is composition rather than authorization.
• Define toolset presets - Adding an installation’s own presets and verifying them.
• Meta-tools - The full filter_tools argument and response reference.
• MCPServer - The resource whose labels the platform presets select over.