Skip to main content

Overview

The SDK includes built-in tools that cover common agent operations:
  • File Operations: Read, Write, Edit, Glob, Grep
  • Shell Execution: Bash
  • Task Management: TodoWrite
  • User Interaction: AskUserQuestion
All built-in tools are available in the picrust::tools::common module.

Registering Built-in Tools

ReadTool

Reads files from the filesystem with line numbers. Supports text files, images (PNG, JPEG, GIF, WebP up to 5MB), and PDFs (up to 32MB).

Parameters

Examples

The Read tool automatically detects file type by extension and handles text, images, and PDFs appropriately.
Permissions: Required for each file read.

WriteTool

Creates or overwrites files. Creates parent directories if needed.

Parameters

WriteTool overwrites files without confirmation. Use EditTool for safer modifications to existing files.
Permissions: Required for each file write.

EditTool

Edits existing files using exact string replacement.

Parameters

Behavior:
  • Matches exact strings (not regex)
  • Fails if old_string not found
  • Fails if old_string appears multiple times (unless replace_all is true)
Permissions: Required for each file edit.

GlobTool

Finds files matching glob patterns. Results sorted by modification time (most recent first).

Parameters

Glob Patterns

  • * matches any characters except /
  • ** matches any characters including /
  • ? matches single character
  • [abc] matches one of a, b, or c
  • {foo,bar} matches foo or bar
Permissions: Safe tool — no permission required.

GrepTool

Searches file contents using regex patterns.

Parameters

Permissions: Safe tool — no permission required.

BashTool

Executes shell commands with configurable timeout.

Parameters

Behavior:
  • Executes in current working directory
  • Working directory persists between commands
  • Shell state does not persist (use && to chain)
  • Captures both stdout and stderr
BashTool is dangerous and always requires permission. Commands have full system access.

TodoWriteTool

Manages task lists for the agent. Supports create, update, complete, and list actions.

Parameters

Permissions: Safe tool — no permission required.

AskUserQuestionTool

Asks users multiple-choice questions during execution. See Ask User Questions for details. Permissions: Safe tool — no permission required.

Custom Base Directories

Some tools support custom base directories for security:

Next Steps

Custom Tools

Create your own tools

Hooks

Modify tool behavior