Amp Tool Creator

Create custom toolbox tools that extend Amp's capabilities using simple executable scripts.

When to Use

•User asks to create a custom tool for Amp
•User wants to wrap a CLI command for controlled agent use
•User needs project-specific tooling (test runners, database queries, build scripts)
•A skill needs bundled executable tools in its tools/ directory
•User says "create a tool", "make a tool", "add a command"

Overview

Toolbox tools are executable files that communicate with Amp via stdin/stdout using a simple protocol. They can be written in any language—bash, zsh, JavaScript (bun), Python, Go, etc.

Key characteristics:

•Tools receive TOOLBOX_ACTION=describe to report their schema
•Tools receive TOOLBOX_ACTION=execute with parameters on stdin
•Tools write output to stdout, errors to stderr
•Exit code 0 = success, non-zero = error
•Registered with tb__ prefix (e.g., run_tests → tb__run_tests)

Tool Locations

Global tools: ~/.config/amp/tools/ Project tools: .agents/tools/ (in workspace root) Skill-bundled tools: skill-name/tools/

The AMP_TOOLBOX environment variable controls search paths (colon-separated, like PATH).

Protocol Specification

Environment Variables for describe and execute modes

Variable	Value	Available During
`TOOLBOX_ACTION`	`"describe"` or `"execute"`	Both
`AGENT`	`"amp"`	Both
`AMP_THREAD_ID`	Current thread ID	Execute only

Communication Formats

Tools can use JSON format or text format. Amp auto-detects based on the describe output.

Text Format (Recommended for Shell Scripts)

Simple and easy to parse. Best for tools that mostly call shell commands.

Describe output:

code

name: tool_name
description: What the tool does and when to use it.
param1: string description of param1
param2: string? optional parameter (note the ?)
param3: string (optional) another way to mark optional

Execute input: Key-value pairs on stdin

code

param1: value1
param2: value2

Optional parameter markers:

•Type suffix: param: string?
•In description: param: string (optional) desc
•Description starts with "optional": param: string optional desc

JSON Format (Recommended for Complex Tools)

Better for structured parameters, arrays, and nested objects.

Describe output (compact args):

json

{
  "name": "tool_name",
  "description": "What the tool does",
  "args": {
    "workspace": ["string", "the workspace directory"],
    "patterns": ["string", "optional test patterns"]
  }
}

Describe output (full inputSchema):

json

{
  "name": "tool_name",
  "description": "What the tool does",
  "inputSchema": {
    "type": "object",
    "properties": {
      "files": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of files to process"
      }
    },
    "required": ["files"]
  }
}

Execute input: JSON object on stdin

Tool Creation Workflow

Step 1: Determine Requirements

•Purpose: What does the tool do?
•Parameters: What inputs does it need?
•Language: Bash for simple CLI wrappers, bun/node for complex logic
•Location: Global, project-local, or skill-bundled?

Step 2: Scaffold the Tool

Use CLI or create manually:

bash

# Create bash tool
amp tools make --bash tool_name

# Create zsh tool
amp tools make --zsh tool_name

# Create JavaScript/bun tool (default)
amp tools make tool_name

You may need to move the tool to the correct location after creation.

Step 3: Implement the Tool

See templates below for language-specific patterns.

Step 4: Make Executable

bash

chmod +x path/to/tool_name

Step 5: Verify

bash

# Check schema
amp tools show tb__tool_name

# Test execution
amp tools use tb__tool_name --param value

Writing Good Tool Descriptions

The description is critical—it tells the agent when to use your tool.

Good descriptions:

•"Run project tests. Use this tool instead of Bash for running tests in this workspace."
•"Query the development PostgreSQL database. Safer than raw psql commands."
•"Build and deploy to staging environment. Handles all necessary steps."

Bad descriptions:

•"Runs tests" (too vague)
•"A utility" (meaningless)
•"Do stuff with the database" (unprofessional)

Include:

•What the tool does
•When/why to use it over alternatives
•Any constraints or safety notes

Error Handling

•Write errors to stderr
•Exit with non-zero code on failure
•Provide actionable error messages

bash

if [[ -z "$required_param" ]]; then
  echo "Error: required_param is required" >&2
  echo "Usage: provide the path to the config file" >&2
  exit 1
fi

Testing Tools

Global/Project Tools

For tools in ~/.config/amp/tools/ or .agents/tools/:

bash

# View tool schema
amp tools show tb__my_tool

# Run with parameters
amp tools use tb__my_tool --param1 value1 --param2 value2

# View only output (no metadata)
amp tools use --only output tb__my_tool --param1 value1

# List all tools
amp tools list

Skill-Bundled Tools

Tools inside a skill's tools/ directory aren't loaded until the skill is active. Test them manually:

bash

# Test describe action
TOOLBOX_ACTION=describe ./skill-name/tools/my_tool

# Test execute action (text format)
echo "param1: value1" | TOOLBOX_ACTION=execute ./skill-name/tools/my_tool

# Test execute action (JSON format)
echo '{"param1": "value1"}' | TOOLBOX_ACTION=execute ./skill-name/tools/my_tool

Troubleshooting

Tool not appearing

•Verify file is executable: chmod +x tool_name
•Check location is in AMP_TOOLBOX path
•Restart Amp to rescan tools

Parse errors

•Validate JSON syntax if using JSON format
•Check text format has name: and description: lines
•Ensure no trailing whitespace issues

Execution errors

•Test manually: TOOLBOX_ACTION=execute echo "param: value" | ./tool_name
•Check stderr for error messages
•Verify all dependencies available

References

@references/owners-manual.md @references/appendix.md