stack/docs/reference/TOOLS.md

Stack 2.9 - Complete Tools Reference

Stack 2.9 provides 38 built-in tools for file operations, git, code execution, web requests, memory, and task management. This document provides the complete reference with actual parameter names, types, and usage examples.

---

Tool Calling Format

Tools are called using a JSON-based function calling format. The agent automatically selects tools based on user intent, but you can also call them directly via the agent API.

Example Tool Call

{
  "tool": "read",
  "params": {
    "path": "/path/to/file.py"
  },
  "id": "call_123"
}

Return Format

All tools return a JSON-serializable dict:

{
  "success": true|false,
  "result": <tool-specific result data>,
  "error": <error message if failed>
}

---

Complete Tool Catalog

1. File Operations

read

Read file contents with optional pagination.

• Parameters:
  • path (string, required) - Path to the file
  • offset (integer, optional, default: 0) - Line number to start from (0-indexed)
  • limit (integer, optional, default: -1) - Maximum lines to read (-1 = all)
• Returns: {success, content, total_lines, path}

Example:

{
  "tool": "read",
  "params": {"path": "stack_cli/cli.py", "limit": 50}
}

write

Write content to a file (overwrites by default).

• Parameters:
  • path (string, required) - Destination file path
  • content (string, required) - Content to write
  • append (boolean, optional, default: false) - Append instead of overwrite
• Returns: {success, path, lines_written}

Example:

{
  "tool": "write",
  "params": {
    "path": "output.txt",
    "content": "Hello, World!",
    "append": false
  }
}

edit

Replace exact text in a file (single occurrence).

• Parameters:
  • path (string, required) - File to edit
  • old_text (string, required) - Text to find and replace
  • new_text (string, required) - Replacement text
• Returns: {success, path, edits_made}

Example:

{
  "tool": "edit",
  "params": {
    "path": "config.yaml",
    "old_text": "debug: false",
    "new_text": "debug: true"
  }
}

search

Recursively search for files matching a glob pattern.

• Parameters:
  • path (string, required) - Directory to search in
  • pattern (string, required) - Glob pattern (e.g., "*.py", "**/*.md")
  • exclude (array of strings, optional) - Paths to exclude
• Returns: {success, matches, count}

Example:

{
  "tool": "search",
  "params": {
    "path": ".",
    "pattern": "**/*.py",
    "exclude": ["__pycache__", "node_modules"]
  }
}

grep

Search for regex pattern across files with optional context.

• Parameters:
  • path (string, required) - File or directory to search
  • pattern (string, required) - Regular expression pattern
  • context (integer, optional, default: 0) - Lines of context before/after
• Returns: {success, matches, count} where each match has {file, line, content, context?}

Example:

{
  "tool": "grep",
  "params": {
    "path": "stack_cli",
    "pattern": "def tool_",
    "context": 2
  }
}

copy

Copy file or directory (recursive for directories).

• Parameters:
  • source (string, required) - Source path
  • destination (string, required) - Destination path
• Returns: {success, source, destination}

Example:

{
  "tool": "copy",
  "params": {
    "source": "config.example.yaml",
    "destination": "config.yaml"
  }
}

move

Move or rename file/directory.

• Parameters:
  • source (string, required) - Current path
  • destination (string, required) - New path
• Returns: {success, source, destination}

Example:

{
  "tool": "move",
  "params": {
    "source": "old_name.py",
    "destination": "new_name.py"
  }
}

delete

Delete file or directory (requires force=True for safety).

• Parameters:
  • path (string, required) - Path to delete
  • force (boolean, optional, default: false) - Actually delete when true
• Returns: {success, deleted/would_delete, warning?}

Example:

{
  "tool": "delete",
  "params": {
    "path": "obsolete_file.txt",
    "force": true
  }
}

---

2. Git Operations

git_status

Get git repository status (porcelain format).

• Parameters:
  • repo_path (string, optional, default: ".") - Repository root
• Returns: {success, files, count, repo}

Example:

{
  "tool": "git_status",
  "params": {"repo_path": "."}
}

git_commit

Stage changes and create a commit.

• Parameters:
  • repo_path (string, optional, default: ".") - Repository root
  • message (string, required) - Commit message
  • files (array of strings, optional) - Specific files to stage (stages all if omitted)
• Returns: {success, message, output}

Example:

{
  "tool": "git_commit",
  "params": {
    "repo_path": ".",
    "message": "feat: add new tool documentation",
    "files": ["TOOLS.md", "docs/tools.md"]
  }
}

git_push

Push commits to remote repository.

• Parameters:
  • repo_path (string, optional, default: ".") - Repository root
  • remote (string, optional, default: "origin") - Remote name
  • branch (string, optional) - Branch name (pushes current branch if omitted)
• Returns: {success, remote, branch, output}

Example:

{
  "tool": "git_push",
  "params": {
    "repo_path": ".",
    "remote": "origin",
    "branch": "main"
  }
}

git_pull

Pull changes from remote.

• Parameters:
  • repo_path (string, optional, default: ".") - Repository root
  • remote (string, optional, default: "origin") - Remote name
  • branch (string, optional) - Branch name (pulls current branch if omitted)
• Returns: {success, remote, branch, output}

Example:

{
  "tool": "git_pull",
  "params": {
    "repo_path": ".",
    "remote": "origin"
  }
}

git_branch

List, create, or delete branches.

• Parameters (mutually exclusive):
  • repo_path (string, optional, default: ".")
  • create (string, optional) - Create and checkout new branch
  • delete (string, optional) - Delete branch
• Returns: {success, branches?, count?, created?, deleted?}

Examples:

// List branches
{"tool": "git_branch", "params": {"repo_path": "."}}

// Create branch
{"tool": "git_branch", "params": {"create": "feature/new-docs"}}

// Delete branch
{"tool": "git_branch", "params": {"delete": "old-branch"}}

git_log

View commit history.

• Parameters:
  • repo_path (string, optional, default: ".")
  • limit (integer, optional, default: 10) - Maximum commits
• Returns: {success, commits, count}

Example:

{
  "tool": "git_log",
  "params": {"repo_path": ".", "limit": 20}
}

git_diff

Show changes between commits or working tree.

• Parameters:
  • repo_path (string, optional, default: ".")
  • file (string, optional) - Specific file to diff
  • staged (boolean, optional, default: false) - Show staged changes
• Returns: {success, diff, has_changes}

Example:

{
  "tool": "git_diff",
  "params": {
    "repo_path": ".",
    "staged": true
  }
}

---

3. Code Execution

run

Execute shell command with timeout.

• Parameters:
  • command (string, required) - Shell command to run
  • timeout (integer, optional, default: 60) - Seconds before timeout
  • cwd (string, optional) - Working directory
  • env (object, optional) - Environment variables to merge
• Returns: {success, returncode, stdout, stderr, command}

Example:

{
  "tool": "run",
  "params": {
    "command": "python -m pytest tests/ -v",
    "timeout": 300,
    "cwd": "."
  }
}

test

Run tests using pytest.

• Parameters:
  • path (string, optional, default: ".") - Test directory or file
  • pattern (string, optional, default: "test*.py") - Test file pattern
  • verbose (boolean, optional, default: true) - Verbose output
• Returns: {success, output, errors, returncode}

Example:

{
  "tool": "test",
  "params": {
    "path": "tests/",
    "pattern": "test_*.py",
    "verbose": true
  }
}

lint

Lint code with specified linter (ruff, pylint, mypy).

• Parameters:
  • path (string, optional, default: ".")
  • linter (string, optional, default: "ruff") - "ruff", "pylint", or "mypy"
• Returns: {success, output, errors}

Example:

{
  "tool": "lint",
  "params": {
    "path": "stack_cli/",
    "linter": "ruff"
  }
}

format

Format code with specified formatter.

• Parameters:
  • path (string, optional, default: ".")
  • formatter (string, optional, default: "ruff") - "ruff" or "black"
• Returns: {success, output, errors}

Example:

{
  "tool": "format",
  "params": {
    "path": ".",
    "formatter": "black"
  }
}

typecheck

Run type checking with mypy.

• Parameters:
  • path (string, optional, default: ".")
• Returns: {success, output, errors}

Example:

{
  "tool": "typecheck",
  "params": {"path": "stack_cli"}
}

server

Start a development server (optionally in background).

• Parameters:
  • command (string, required) - Command to start server
  • port (integer, required) - Port number (for reference)
  • cwd (string, optional) - Working directory
  • background (boolean, optional, default: false) - Run in background
• Returns: {success, pid?, port, message} or {success, output}

Example:

{
  "tool": "server",
  "params": {
    "command": "python -m http.server 8000",
    "port": 8000,
    "background": true
  }
}

install

Install dependencies from requirements file.

• Parameters:
  • path (string, optional, default: ".") - Project directory
  • package_manager (string, optional, default: "pip") - "pip", "poetry", or "npm"
• Returns: {success, output, errors}

Example:

{
  "tool": "install",
  "params": {
    "path": ".",
    "package_manager": "pip"
  }
}

---

4. Web & Search

web_search

Search the web using Brave Search.

• Parameters:
  • query (string, required) - Search query
  • count (integer, optional, default: 5) - Number of results (1-10)
  • freshness (string, optional) - Filter by time: "day", "week", "month", "year"
  • language (string, optional) - ISO 639-1 language code (e.g., "en", "fr")
• Returns: {success, query, results, count}

Example:

{
  "tool": "web_search",
  "params": {
    "query": "Stack 2.9 AI coding assistant",
    "count": 10,
    "freshness": "month"
  }
}

fetch

Download and extract content from a URL.

• Parameters:
  • url (string, required) - URL to fetch
  • max_chars (integer, optional, default: 10000) - Maximum content length
• Returns: {success, url, content, length}

Example:

{
  "tool": "fetch",
  "params": {
    "url": "https://example.com/README.md",
    "max_chars": 5000
  }
}

download

Download file from URL to local path.

• Parameters:
  • url (string, required) - Source URL
  • destination (string, required) - Local file path
• Returns: {success, url, destination, size}

Example:

{
  "tool": "download",
  "params": {
    "url": "https://example.com/dataset.csv",
    "destination": "data/dataset.csv"
  }
}

check_url

Check if URL is accessible (HTTP HEAD request).

• Parameters:
  • url (string, required) - URL to check
• Returns: {success, url, status_code}

Example:

{
  "tool": "check_url",
  "params": {"url": "https://github.com"}
}

screenshot

Take screenshot of a webpage (requires puppeteer).

• Parameters:
  • url (string, required) - Webpage URL
  • destination (string, optional, default: "screenshot.png") - Output path
• Returns: {success, url, destination}

Example:

{
  "tool": "screenshot",
  "params": {
    "url": "https://stack-2-9.example.com",
    "destination": "website.png"
  }
}

---

5. Memory & Knowledge

memory_recall

Search memory files for relevant entries.

• Parameters:
  • query (string, required) - Search query
  • max_results (integer, optional, default: 5) - Maximum matches
• Returns: {success, query, matches, count}

Example:

{
  "tool": "memory_recall",
  "params": {
    "query": "deployment requirements",
    "max_results": 10
  }
}

memory_save

Store a memory entry in MEMORY.md.

• Parameters:
  • key (string, required) - Entry title/heading
  • value (string, required) - Content to save
• Returns: {success, key, saved}

Example:

{
  "tool": "memory_save",
  "params": {
    "key": "GPU Requirements",
    "value": "Minimum: 8GB VRAM, Recommended: 24GB VRAM"
  }
}

memory_list

List all memory entries with preview.

• Parameters: None
• Returns: {success, entries, count} where each entry has {title, content}

Example:

{
  "tool": "memory_list",
  "params": {}
}

context_load

Load workspace context files (AGENTS.md, SOUL.md, TOOLS.md).

• Parameters:
  • projects (array of strings, optional) - Project names to load
• Returns: {success, context, loaded}

Example:

{
  "tool": "context_load",
  "params": {}
}

project_scan

Scan project structure and detect tech stack.

• Parameters:
  • path (string, optional, default: ".")
• Returns: {success, project} with {name, files, dirs, has_git, has_pyproject, has_package_json, has_dockerfile}

Example:

{
  "tool": "project_scan",
  "params": {"path": "."}
}

---

6. Task & Planning

create_task

Create a new task.

• Parameters:
  • title (string, required) - Task title
  • description (string, optional, default: "") - Detailed description
  • priority (string, optional, default: "medium") - "low", "medium", or "high"
• Returns: {success, task} with {id, title, description, priority, status, created}

Example:

{
  "tool": "create_task",
  "params": {
    "title": "Write comprehensive tool documentation",
    "description": "Create TOOLS.md with all 38 tools documented",
    "priority": "high"
  }
}

list_tasks

List tasks with optional filtering.

• Parameters:
  • status (string, optional) - Filter by "pending", "done", or "all"
  • priority (string, optional) - Filter by "low", "medium", "high"
• Returns: {success, tasks, count}

Example:

{
  "tool": "list_tasks",
  "params": {
    "status": "pending",
    "priority": "high"
  }
}

update_task

Update task status or fields.

• Parameters:
  • task_id (string, required) - Task identifier
  • status (string, optional) - New status
  • Additional fields: title, description, priority
• Returns: {success, task_id, updated}

Example:

{
  "tool": "update_task",
  "params": {
    "task_id": "a1b2c3d4",
    "status": "done"
  }
}

delete_task

Delete a task by ID.

• Parameters:
  • task_id (string, required) - Task to delete
• Returns: {success, task_id, deleted}

Example:

{
  "tool": "delete_task",
  "params": {"task_id": "a1b2c3d4"}
}

create_plan

Create an execution plan with steps.

• Parameters:
  • goal (string, required) - Plan objective
  • steps (array of strings, required) - Ordered steps
• Returns: {success, plan} with {id, goal, steps, status, created}

Example:

{
  "tool": "create_plan",
  "params": {
    "goal": "Deploy to RunPod",
    "steps": [
      "Prepare Docker image",
      "Upload to registry",
      "Launch pod with template",
      "Verify deployment"
    ]
  }
}

execute_plan

Mark a plan as in-progress (execution tracking).

• Parameters:
  • plan_id (string, required) - Plan identifier
• Returns: {success, plan_id, status, steps}

Example:

{
  "tool": "execute_plan",
  "params": {"plan_id": "p123abc"}
}

---

Tool Count Clarification

Actual tool count: 38 (not 37). The following categories:

• File Operations: 8 tools
• Git Operations: 7 tools
• Code Execution: 7 tools
• Web & Search: 5 tools
• Memory & Knowledge: 5 tools
• Task & Planning: 6 tools
• Total: 38 tools

---

Extension Mechanism

To add a new tool, edit stack_cli/tools.py:

def tool_my_feature(param1: str, param2: int = 42) -> Dict[str, Any]:
    """Brief description for LLM."""
    try:
        # Implementation
        result = do_something(param1, param2)
        return {
            "success": True,
            "result": result
        }
    except Exception as e:
        return {"success": False, "error": str(e)}

# Register in TOOLS dict
TOOLS["my_feature"] = tool_my_feature

The tool will be automatically available. Update this document when adding tools.

---

Schema Generation

For programmatic access, use:

from stack_cli.tools import get_tool_schemas, get_tool

# Get all tool schemas (for LLM function calling)
schemas = get_tool_schemas()

# Get a specific tool function
read_fn = get_tool("read")
result = read_fn(path="file.txt")

Note: The get_tool_schemas() function currently provides a limited subset. For full production use, extend it to include all 38 tools with proper JSON Schema parameters derived from function signatures.

---

Best Practices

1. Always check success in the return value before using results
2. Use pagination for large files: read(path, offset=0, limit=1000)
3. Handle errors gracefully - tools return error field when success=false
4. Be cautious with destructive operations: delete requires force=true
5. Set appropriate timeouts for long-running commands (run tool)
6. Use git_status before git_commit to verify what will be committed
7. Remember context limits - tool results count against token limits

---

Quick Reference Table

Category	Tools	Count
File Operations	read, write, edit, search, grep, copy, move, delete	8
Git	git_status, git_commit, git_push, git_pull, git_branch, git_log, git_diff	7
Execution	run, test, lint, format, typecheck, server, install	7
Web	web_search, fetch, download, check_url, screenshot	5
Memory	memory_recall, memory_save, memory_list, context_load, project_scan	5
Planning	create_task, list_tasks, update_task, delete_task, create_plan, execute_plan	6
Total		38

---

Last updated: 2026-04-02 Stack 2.9 - Pattern Memory AI