Script Tool

Define custom shell scripts as named tools with typed parameters.

Overview

The script tool lets you define custom shell scripts as named tools. Unlike the generic shell tool where the agent writes the command, script tools execute predefined commands — ideal for exposing safe, well-scoped operations with descriptive names.

Configuration

Simple Scripts

toolsets:
  - type: script
    shell:
      run_tests:
        cmd: task test
        description: Run the project test suite
      lint:
        cmd: task lint
        description: Run the linter

Scripts with Parameters

Use ${param} interpolation and JSON Schema to define typed arguments:

toolsets:
  - type: script
    shell:
      deploy:
        cmd: ./scripts/deploy.sh ${env}
        description: Deploy to an environment
        args:
          env:
            type: string
            enum: [staging, production]
        required: [env]

Properties

Tip

Script vs. Shell

Use the shell tool when the agent needs to run arbitrary commands. Use the script tool when you want to expose specific, predefined operations with clear names and typed parameters — giving the agent less freedom but more safety.