run amp tools list

amp-tools.sh

# 15 tools

## Bash
Executes the given shell command in the user's default shell.

## Important notes

1. Directory Verification:
   - If the command will create new directories or files, first use the list_directory tool to verify the parent directory exists and is the correct location
   - For example, before running a mkdir command, first use list_directory to check the parent directory exists

2. Working directory:
   - Your working directory is at the root of the user's workspace unless you override it for a command by setting the `cwd` parameter.
   - Use the `cwd` parameter to specify an absolute or relative path to a directory where the command should be executed (e.g., `cwd: "core/src"`).
   - You may use `cd PATH && COMMAND` if the user explicitly requests it, otherwise prefer using the `cwd` parameter.

3. Multiple independent commands:
   - Do NOT chain multiple independent commands with `;`
   - Instead, make multiple separate tool calls for each command you want to run

4. Shell escapes:
   - Escape any special characters in the command if those are not to be interpreted by the shell

5. Truncated output:
   - Only the last 50000 characters of the output will be returned to you along with how many lines got truncated, if any
   - If necessary, when the output is truncated, consider running the command again with a grep or head filter to search through the truncated lines

6. Stateless environment:
   - Setting an environment variable or using `cd` only impacts a single command, it does not persist between commands

## Examples

- To run 'go test ./...': use { cmd: 'go test ./...' }
- To run 'cargo build' in the core/src directory: use { cmd: 'cargo build', cwd: 'core/src' }
- To run 'ps aux | grep node', use { cmd: 'ps aux | grep node' }
- To run commands in a subdirectory using cd: use { cmd: 'cd core/src && ls -la' }
- To print a special character like $ with some command `cmd`, use { cmd: 'cmd \$' }

## Git

Use this tool to interact with git. You can use it to run 'git log', 'git show', or other 'git' commands.

When the user shares a git commit SHA, you can use 'git show' to look it up. When the user asks when a change was introduced, you can use 'git log'.

If the user asks you to, use this tool to create git commits too. But only if the user asked.

<git-example>
user: commit the changes
assistant: [uses Bash to run 'git status']
[uses Bash to 'git add' the changes from the 'git status' output]
[uses Bash to run 'git commit -m "commit message"']
</git-example>

<git-example>
user: commit the changes
assistant: [uses Bash to run 'git status']
there are already files staged, do you want me to add the changes?
user: yes
assistant: [uses Bash to 'git add' the unstaged changes from the 'git status' output]
[uses Bash to run 'git commit -m "commit message"']
</git-example>

## Prefer specific tools

It's VERY IMPORTANT to use specific tools when searching for files, instead of issuing terminal commands with find/grep/ripgrep. Use codebase_search or Grep instead. Use read_file tool rather than cat, and edit_file rather than sed.


Input schema: {
  "type": "object",
  "properties": {
    "cmd": {
      "type": "string",
      "description": "The shell command to execute"
    },
    "cwd": {
      "type": "string",
      "description": "Relative path to a directory in the workspace where the command will be executed"
    }
  },
  "required": [
    "cmd"
  ]
}

## codebase_search_agent
Intelligently search your codebase with an agent that has access to: list_directory, Grep, glob, read_file.

The agent acts like your personal search assistant.

It's ideal for complex, multi-step search tasks where you need to find code based on functionality or concepts rather than exact matches.

WHEN TO USE THIS TOOL:
- When searching for high-level concepts like "how do we check for authentication headers?" or "where do we do error handling in the file watcher?"
- When you need to combine multiple search techniques to find the right code
- When looking for connections between different parts of the codebase
- When searching for keywords like "config" or "logger" that need contextual filtering

WHEN NOT TO USE THIS TOOL:
- When you know the exact file path - use read_file directly
- When looking for specific symbols or exact strings - use glob or Grep
- When you need to create, modify files, or run terminal commands

USAGE GUIDELINES:
1. Launch multiple agents concurrently for better performance
2. Be specific in your query - include exact terminology, expected file locations, or code patterns
3. Use the query as if you were talking to another engineer. Bad: "logger impl" Good: "where is the logger implemented, we're trying to find out how to log to files"
4. Make sure to formulate the query in such a way that the agent knows when it's done or has found the result.


Input schema: {
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query describing to the agent what it should. Be specific and include technical terms, file types, or expected code patterns to help the agent find relevant code. Formulate the query in a way that makes it clear to the agent when it has found the right thing."
    }
  },
  "required": [
    "query"
  ]
}

## create_file
Create or overwrite a file in the workspace.

Use this tool when you want to create a new file with the given content, or when you want to replace the contents of an existing file.

Prefer this tool over `edit_file` when you want to ovewrite the entire contents of a file.


Input schema: {
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path of the file to be created. If the file exists, it will be overwritten."
    },
    "content": {
      "type": "string",
      "description": "The content for the file."
    }
  },
  "required": [
    "path",
    "content"
  ]
}

## edit_file
Make edits to a text file.

Replaces `old_str` with `new_str` in the given file.

Returns a git-style diff showing the changes made as formatted markdown, along with the line range ([startLine, endLine]) of the changed content. The diff is also shown to the user.

The file specified by `path` MUST exist. If you need to create a new file, use `create_file` instead.

`old_str` MUST exist in the file. Use tools like `read_file` to understand the files you are editing before changing them.

`old_str` and `new_str` MUST be different from each other.

`old_str` MUST be unique within the file. Additional lines of context can be added to make the string more unique.

If you need to replace the entire contents of a file, use `create_file` instead, since it requires less tokens for the same action (since you won't have to repeat the contents before replacing)


Input schema: {
  "type": "object",
  "properties": {
    "path": {
      "description": "The path to the file. File must exist.",
      "type": "string"
    },
    "old_str": {
      "description": "Text to search for. Must match exactly.",
      "type": "string"
    },
    "new_str": {
      "description": "Text to replace old_str with.",
      "type": "string"
    }
  },
  "required": [
    "path",
    "old_str",
    "new_str"
  ],
  "additionalProperties": false,
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

## glob
Fast file pattern matching tool that works with any codebase size

Use this tool to find files by name patterns across your codebase. It returns matching file paths sorted by recent modification time.

## When to use this tool

- When you need to find specific file types (e.g., all JavaScript files)
- When you want to find files in specific directories or following specific patterns
- When you need to explore the codebase structure quickly
- When you need to find recently modified files matching a pattern

## File pattern syntax

- `**/*.js` - All JavaScript files in any directory
- `src/**/*.ts` - All TypeScript files under the src directory (searches only in src)
- `*.json` - All JSON files in the current directory
- `**/*test*` - All files with "test" in their name
- `web/src/**/*` - All files under the web/src directory
- `**/*.{js,ts}` - All JavaScript and TypeScript files (alternative patterns)
- `src/[a-z]*/*.ts` - TypeScript files in src subdirectories that start with lowercase letters

Here are examples of effective queries for this tool:

<examples>
<example>
// Finding all TypeScript files in the codebase
// Returns paths to all .ts files regardless of location
{
  filePattern: "**/*.ts"
}
</example>

<example>
// Finding test files in a specific directory
// Returns paths to all test files in the src directory
{
  filePattern: "src/**/*test*.ts"
}
</example>

<example>
// Searching only in a specific subdirectory
// Returns all Svelte component files in the web/src directory
{
  filePattern: "web/src/**/*.svelte"
}
</example>

<example>
// Finding recently modified JSON files with limit
// Returns the 10 most recently modified JSON files
{
  filePattern: "**/*.json",
  limit: 10
}
</example>

<example>
// Paginating through results
// Skips the first 20 results and returns the next 20
{
  filePattern: "**/*.js",
  limit: 20,
  offset: 20
}
</example>
</examples>

Note: Results are sorted by modification time with the most recently modified files first.


Input schema: {
  "type": "object",
  "properties": {
    "filePattern": {
      "type": "string",
      "description": "Glob pattern like \"**/*.js\" or \"src/**/*.ts\" to match files"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results to return"
    },
    "offset": {
      "type": "number",
      "description": "Number of results to skip (for pagination)"
    }
  },
  "required": [
    "filePattern"
  ],
  "additionalProperties": false
}

## Grep
Search for exact text patterns in files using ripgrep, a fast keyword search tool.

WHEN TO USE THIS TOOL:
- When you need to find exact text matches like variable names, function calls, or specific strings
- When you know the precise pattern you're looking for (including regex patterns)
- When you want to quickly locate all occurrences of a specific term across multiple files
- When you need to search for code patterns with exact syntax
- When you want to focus your search to a specific directory or file type

WHEN NOT TO USE THIS TOOL:
- For semantic or conceptual searches (e.g., "how does authentication work") - use codebase_search instead
- For finding code that implements a certain functionality without knowing the exact terms - use codebase_search
- When you already have read the entire file
- When you need to understand code concepts rather than locate specific terms

SEARCH PATTERN TIPS:
- Use regex patterns for more powerful searches (e.g., \.function\(.*\) for all function calls)
- Add context to your search with surrounding terms (e.g., "function handleAuth" rather than just "handleAuth")
- Use the path parameter to narrow your search to specific directories or file types
- For case-sensitive searches like constants (e.g., ERROR vs error), use the caseSensitive parameter

RESULT INTERPRETATION:
- Results show the file path, line number, and matching line content
- Results are grouped by file, with up to 15 matches per file
- Lines longer than 250 characters are truncated
- Match context is not included - you may need to examine the file for surrounding code

Here are examples of effective queries for this tool:

<examples>
<example>
// Finding a specific function name across the codebase
// Returns lines where the function is defined or called
{
  pattern: "registerTool",
  path: "core/src"
}
</example>

<example>
// Searching for interface definitions in a specific directory
// Returns interface declarations and implementations
{
  pattern: "interface ToolDefinition",
  path: "core/src/tools"
}
</example>

<example>
// Looking for case-sensitive error messages
// Matches ERROR: but not error: or Error:
{
  pattern: "ERROR:",
  caseSensitive: true
}
</example>

<example>
// Finding TODO comments in frontend code
// Helps identify pending work items
{
  pattern: "TODO:",
  path: "web/src"
}
</example>

<example>
// Searching for event handler methods across all files
// Returns method definitions and references to onMessage
{
  pattern: "onMessage"
}
</example>

<example>
// Using regex to find import statements for specific packages
// Finds all imports from the @core namespace
{
  pattern: 'import.*from ['|"]@core',
  path: "web/src"
}
</example>

<example>
// Finding all REST API endpoint definitions
// Identifies routes and their handlers
{
  pattern: 'app\.(get|post|put|delete)\(['|"]',
  path: "server"
}
</example>

<example>
// Locating CSS class definitions in stylesheets
// Returns class declarations to help understand styling
{
  pattern: "\.container\s*{",
  path: "web/src/styles"
}
</example>
</examples>

COMPLEMENTARY USE WITH CODEBASE_SEARCH:
- Use codebase_search first to locate relevant code concepts
- Then use Grep to find specific implementations or all occurrences
- For complex tasks, iterate between both tools to refine your understanding


Input schema: {
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "description": "The pattern to search for"
    },
    "path": {
      "type": "string",
      "description": "The file or directory path to search in"
    },
    "caseSensitive": {
      "type": "boolean",
      "description": "Whether to search case-sensitively"
    }
  },
  "required": [
    "pattern"
  ]
}

## list_directory
List the files in the workspace in a given directory. Use the glob tool for filtering files by pattern.

Input schema: {
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The directory path within the workspace to list files from. Defaults to workspace root if not specified"
    }
  },
  "required": []
}

## mermaid
Renders a Mermaid diagram from the provided code.

PROACTIVELY USE DIAGRAMS when they would better convey information than prose alone. The diagrams produced by this tool are shown to the user..

You should create diagrams WITHOUT being explicitly asked in these scenarios:
- When explaining system architecture or component relationships
- When describing workflows, data flows, or user journeys
- When explaining algorithms or complex processes
- When illustrating class hierarchies or entity relationships
- When showing state transitions or event sequences

Diagrams are especially valuable for visualizing:
- Application architecture and dependencies
- API interactions and data flow
- Component hierarchies and relationships
- State machines and transitions
- Sequence and timing of operations
- Decision trees and conditional logic

Input schema: {
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The Mermaid diagram code to render (DO NOT override with custom colors or other styles)"
    }
  },
  "required": [
    "code"
  ]
}

## read_file
Read the contents of a file in the workspace. Make sure you know that the path of the file exists, otherwise this will fail.
This tool will never return more than 1000 lines. Reading a file longer than that requires multiple calls. Files with very long lines will cause the tool to fail. Use the Grep tool to find specific content in large files or files with long lines.
Returns the contents of the file with each line prefixed by its line number. For example, if a file has contents "abc\n", you will receive "1: abc\n"

Input schema: {
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path to the file to read. This path MUST exist."
    },
    "read_range": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 2,
      "maxItems": 2,
      "description": "An array of two integers specifying the start and end line numbers to view. Line numbers are 1-indexed. If not provided, defaults to [1, 1000]. Examples: [500, 700], [700, 1400]"
    }
  },
  "required": [
    "path"
  ]
}

## read_web_page
Read the contents of a web page from a given URL and extract text content only (no HTML tags), presenting it as formatted markdown.

## When to use this tool

- When you need to fetch and read text content from a website
- When the user shares URLs to documentation, specifications, or reference materials
- When the user asks you to build something similar to what's at a URL
- When the user provides links to schemas, APIs, or other technical documentation

## When NOT to use this tool

- When visual elements of the website are important - use browser tools instead
- When navigation (clicking, scrolling) is required to access the content
- When you need to interact with the webpage or test functionality
- When you need to capture screenshots of the website

## Examples

- When user says "Read these docs: https://example.com/docs"
- When user says "Can you build something like this: https://example.com"
- When user provides links to specifications: "The schema is at https://example.com/schema.graphql"
- When user says "Please review my latest blog post. The dev server is running at http://localhost:8081"

This tool converts web content to markdown format for better readability.

Input schema: {
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL of the web page to read"
    },
    "max_length": {
      "type": "number",
      "description": "Maximum number of characters to return.",
      "default": 5000
    },
    "start_index": {
      "type": "number",
      "description": "On return output starting at this character index, useful if a previous fetch was truncated and more context is required.",
      "default": 0
    },
    "raw": {
      "type": "boolean",
      "description": "Get the actual HTML content of the requested page, without simplification.",
      "default": false
    }
  },
  "required": [
    "url"
  ]
}

## think
Use this tool to document your thinking process. This allows you to work through complex problems step by step, reason about different approaches, and clarify your understanding. The content is only visible to you.

Input schema: {
  "type": "object",
  "properties": {
    "thoughts": {
      "type": "string",
      "description": "Your detailed thinking process, reasoning, or working through a problem."
    }
  },
  "required": [
    "thoughts"
  ]
}

## todo_read (disabled)
Read the current todo list for the session

Input schema: {
  "type": "object",
  "properties": {},
  "required": []
}

## todo_write (disabled)
Update the todo list for the current session. To be used proactively and often to track progress and pending tasks.

Input schema: {
  "type": "object",
  "properties": {
    "todos": {
      "type": "array",
      "description": "The list of todo items. This replaces any existing todos.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the todo item"
          },
          "content": {
            "type": "string",
            "description": "The content/description of the todo item"
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "in-progress",
              "todo"
            ],
            "description": "The current status of the todo item"
          },
          "priority": {
            "type": "string",
            "enum": [
              "medium",
              "low",
              "high"
            ],
            "description": "The priority level of the todo item"
          }
        },
        "required": [
          "id",
          "content",
          "status",
          "priority"
        ]
      }
    }
  },
  "required": [
    "todos"
  ]
}

## undo_edit
Undo the last edit made to a file.

This command reverts the most recent edit made to the specified file.
It will restore the file to its state before the last edit was made.

Returns a git-style diff showing the changes that were undone as formatted markdown.


Input schema: {
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path to the file whose last edit should be undone"
    }
  },
  "required": [
    "path"
  ]
}

## web_search
Search the web for information.

Returns search result titles, associated URLs, and a small summary of the
relevant part of the page. If you need more information about a result, use
the `read_web_page` with the url.

## When to use this tool

- When you need up-to-date information from the internet
- When you need to find answers to factual questions
- When you need to search for current events or recent information
- When you need to find specific resources or websites related to a topic

## When NOT to use this tool

- When the information is likely contained in your existing knowledge
- When you need to interact with a website (use browser tools instead)
- When you want to read the full content of a specific page (use `read_web_page` instead)

## Examples

- Web search for: "latest TypeScript release"
- Find information about: "current weather in New York"
- Search for: "best practices for React performance optimization"

Input schema: {
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to send to the search engine"
    },
    "num_results": {
      "type": "number",
      "description": "Number of search results to return (default: 5, max: 10)",
      "default": 5
    }
  },
  "required": [
    "query"
  ]
}