amp-tool-creator

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:

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

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):

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

Describe output (full inputSchema):

{
  "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:

# 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

chmod +x path/to/tool_name

Step 5: Verify

# 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

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/:

# 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:

# 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