Skip to content

System tools

System tools are tools that the runtime owns and implements. Agent authors do not write them. Examples are loading a skill, running a skill script, asking the user a question, sending the user a progress update, and spawning a pre-authored subagent template.

They reach the model through the same ToolContract as application tools. System tools are discovered from the system_tool category in the plugin registry; plugin entries carry their default_enabled policy. Unlike application tools, they are not loaded from a kind: Tool manifest. Each tool is either implicit, meaning another part of the manifest implies it, or declared, meaning it is listed by name.

The full list, with arguments and parameters, is in the system tools reference.

Rule: the manifest lists what the model sees

An agent is offered a system tool only when one of these conditions is true:

  1. Implicit. Another part of the manifest requires the tool.
  2. Declared. spec.tools contains {kind: system, name: <tool>}. enabled: true|false explicitly opts one tool in or out. Otherwise the registry entry's default_enabled attribute applies.
  3. Host-requested. The embedding host passes the tool in system_tools. This is a programmatic API; see Host-requested tools.

No boolean enables every system tool at once. An agent with no skills and no declarations gets no system tools.

Implicit enablement

Tool(s) Enabled when
activate_skill, list_skill_files, read_skill_file spec.skills lists at least one skill
run_skill_script a listed skill ships a non-empty scripts/ directory
run_skill_script a context_sources plugin sets auto_inject: true

These tools follow from the skills themselves. Listing a skill without a way to load it would leave the model with a catalog entry it cannot use. Shipping scripts without run_skill_script would leave instructions the model cannot follow.

spec:
  skills:
    - answer-formatting        # → activate_skill (+ list/read)
    - log-analyzer             # has scripts/ → run_skill_script

Declared enablement

List a system tool in spec.tools with kind: system. The same entry carries its params:

spec:
  tools:
    - ref: ./tools/calculator.tool.yaml
    - kind: system
      name: request_human_input
      params:
        timeout: 300
        auto_resolve_decision: reject
    - kind: system
      name: inform_user
      params:
        max_message_length: 8000

Declaration is the only way to enable the user-communication tools, request_human_input and inform_user. They are never implicit. If a model asks the user when nothing in the protocol can answer, it can substitute a made-up or rubber-stamped answer for a real one, and the caller cannot detect the substitution. An agent should get these tools only when its deployment can route questions and updates to a real user.

You can also declare the skill tools explicitly, for example to offer run_skill_script for a skill whose scripts are resolved elsewhere.

An unknown name, such as a typo, fails at load time and lists the available names. The runtime does not silently skip it.

create_subagent (alias spawn_subagent) is opt-in like the others, and carries its configuration in the same entry: params.templates must declare at least one pre-authored Agent manifest, with optional params.max_spawns and params.max_depth bounds. The model sees both names. See Spawned subagents and Tutorial 7.

Third-party system tools can register with a library manifest:

types: [system_tool]
plugins:
  - type: system_tool
    name: audit_event
    urn: mas.system_tool.audit_event
    module: example.audit_tools
    class: AuditEventTool
    attributes: {default_enabled: false}

Host-requested tools

A program that embeds the runtime can add system tools without editing the manifest:

build_manifest_tool_provider(
    tools_spec,
    manifest_dir,
    system_tools=["request_human_input", "inform_user"],
)

Host-requested names are merged with the manifest declarations. The manifest still supplies their params.

Overlays

spec.tools is merged with list_ops, so an overlay can enable a system tool for one environment without changing the base agent:

# overlays/interactive.yaml
spec:
  tools:
    $op:
      add:
        - kind: system
          name: request_human_input

The same agent can run in batch mode without HITL and interactively with it. Only the overlay changes.

See also