webber/webber-api/src/domains/tools

Tools Domain

This domain contains tool implementations for agent use.

Tool Categories

File Tools (file/)

Tools for reading, writing, and finding files.

Tool	Purpose	Key Parameters
Read	Read file contents	file_path, offset, limit
Write	Create/overwrite files	file_path, content
Edit	Exact string replacement	file_path, old_string, new_string, replace_all
Glob	Find files by pattern	pattern, path

Read Tool:

• Returns line-numbered content (cat -n format)
• Supports offset/limit for large files
• Can read images, PDFs, Jupyter notebooks
• Default: 2000 lines, 2000 chars per line

Edit Tool:

• Performs exact string replacements
• Fails if old_string is not unique (use replace_all or provide more context)
• Preserves indentation from Read output

Glob Tool:

• Supports patterns like **/*.py, src/**/*.ts
• Returns files sorted by modification time
• Use for finding files by name patterns

---

Shell Tools (shell/)

Tools for executing system commands.

Tool	Purpose	Key Parameters
Bash	Execute shell commands	command, timeout, description

Bash Tool:

• Persistent shell session
• 2-minute default timeout (max 10 minutes)
• Supports background execution (run_in_background)
• Quote paths with spaces: cd "/path with spaces"

Git Operations:

• Never commit to main/master directly
• Use conventional commits format
• Never use -i flag (interactive)
• Never skip hooks unless explicitly requested
• Never force push to main/master

Security:

• Sandboxed execution when SANDBOX_ENABLED=true
• Validates against ALLOWED_PATHS
• Timeout enforcement

---

Search Tools (search/)

Tools for searching content and the web.

Tool	Purpose	Key Parameters
Grep	Search file contents	pattern, path, glob, output_mode
WebSearch	Search the web	query, allowed_domains, blocked_domains
WebFetch	Fetch and analyze URLs	url, prompt

Grep Tool:

• Built on ripgrep (NOT grep/rg bash commands)
• Supports regex patterns
• Output modes: files_with_matches (default), content, count
• Context lines: -A, -B, -C

WebSearch Tool:

• Returns search results with URLs
• Always include sources in responses
• Domain filtering supported

WebFetch Tool:

• Fetches URL, converts HTML to markdown
• Processes content with AI for extraction
• 15-minute cache for repeated URLs
• Handles redirects (returns redirect URL)

---

Structure

tools/
├── router.py            # Tool routes (list, execute)
├── controller.py        # Tool orchestration
├── schemas.py           # Tool request/response models
│
├── file/                # File operation tools
│   ├── __init__.py
│   ├── read.py          # Read file contents
│   ├── write.py         # Write file contents
│   ├── edit.py          # Edit file contents
│   ├── glob.py          # Find files by pattern
│   └── example-prompt.md
│
├── shell/               # Shell execution tools
│   ├── __init__.py
│   ├── bash.py          # Execute bash commands
│   └── example-prompt.md
│
└── search/              # Search tools
    ├── __init__.py
    ├── grep.py          # Search file contents
    ├── web.py           # Web search and fetch
    └── example-prompt.md

Tool Pattern

Tools are registered with PydanticAI agents via the @agent.tool decorator. Each tool should:

1. Have clear input/output types
2. Include a docstring (used by LLM)
3. Handle errors gracefully
4. Respect sandbox settings

from src.shared.config import get_settings
from src.shared.logging import logged

settings = get_settings()

@logged()
async def read_file(file_path: str, limit: int = 2000) -> str:
    """
    Read contents of a file.

    Args:
        file_path: Absolute path to the file
        limit: Maximum lines to read

    Returns:
        File contents as string with line numbers
    """
    # Check path is allowed
    if settings.sandbox_enabled:
        _validate_path(file_path, settings.allowed_paths)

    # Read and return with line numbers
    pass

Adding a New Tool

1. Create a new file in appropriate category (file/, shell/, search/)
2. Implement the tool function with proper types and docstring
3. Add @logged() decorator for timing
4. Handle sandbox restrictions
5. Register with agents that need it
6. Add tests

Reference Prompts

Each tool category directory contains an example-prompt.md file with reference prompts from the claude-code-system-prompts repository. These document the expected behavior and usage patterns for each tool.