Tools Overview - profClaw

What Are Tools?

Tools are functions the AI agent can call during a conversation. When you ask profClaw to read a file, run tests, or search the web, the AI emits a structured tool call. The execution engine validates it against the security policy, runs it, and returns the result back to the model. profClaw ships 77+ built-in tools organized into tiers - essential tools work reliably with any model including small local models, while advanced tools require frontier models to use effectively.

Tool Tiers

Essential (10 tools)
Standard (25 tools)
Full (77+ tools)

Core tools that work reliably with any model, including small local models like Qwen 7B.

Tool	Category	Description
`read_file`	filesystem	Read file contents with optional line ranges
`write_file`	filesystem	Write or append to files
`edit_file`	filesystem	Surgical find-and-replace in files
`exec`	execution	Run shell commands
`grep`	filesystem	Regex search across file contents
`search_files`	filesystem	Find files by glob pattern
`directory_tree`	filesystem	Show project structure
`git_status`	git	Show working tree status
`web_fetch`	web	Fetch URL content as text
`complete_task`	profclaw	Mark a task as complete

Tools that need moderate reasoning ability - suitable for 14B+ local models or any cloud model.Includes all Essential tools plus: git_diff, git_log, git_commit, git_branch, patch_apply, web_search, memory_search, memory_get, memory_stats, env, system_info, path_info, which, create_ticket, list_tickets, update_ticket, get_ticket, create_project, list_projects, test_run, image_analyze, link_understand, github_pr, notify

Tool Categories

Filesystem

Read, write, edit, search files and directories. Path-traversal safe with FsGuard.

Git

Status, diff, commit, branch, stash, push, and pull operations.

Web Fetch

Fetch URLs, call APIs, convert HTML to text. SSRF-protected.

Web Search

Search via Brave, Serper, SearXNG, or Tavily. Config-gated.

Browser

Puppeteer-based automation: navigate, click, type, screenshot, extract.

Memory

Hybrid vector + full-text search over MEMORY.md and conversation history.

profClaw Ops

Create and manage tickets and projects directly from chat.

Sessions

Spawn, send messages to, and coordinate multi-agent sessions.

Test Runner

Auto-detect and run vitest, jest, pytest, go test, and more.

Cron

Schedule HTTP webhooks, tool calls, or shell scripts on a cron expression.

Notifications

System notifications, clipboard access, and screen capture.

Custom Tools

How Tool Execution Works

Model emits a tool call

The AI model outputs a structured JSON tool call containing the tool name and parameter values.

Schema validation

Parameters are parsed through the tool’s Zod schema. Invalid parameters return an error immediately without execution - the model receives the validation error and can retry with corrected values.

Security check

The active security mode is evaluated: mode level, allowlist, and approval requirements. Dangerous tools require explicit user approval in ask mode.

Execution

The tool executor runs. Long-running tools can stream progress updates back to the conversation. Tools that exceed POOL_TIMEOUT_MS (default: 5 minutes) are cancelled.

Result returned

The tool result (success or structured error) is appended to the conversation context. The model continues reasoning with the new information and may call additional tools.

Security Levels

Each tool declares a security level that determines behavior across different security modes:

Level	Description	Behavior in `standard` mode
`safe`	Read-only, no side effects	Always allowed
`moderate`	Write operations, network requests	Allowed without prompt
`dangerous`	Shell exec, destructive file operations	Requires approval in `ask` mode

See Security Overview for how security modes interact with tool execution.

Model-Aware Tool Routing

profClaw automatically selects the right tool tier based on which model is active. Small local models receive only Essential tools to avoid context overload and unreliable tool selection. Frontier models receive the full set.

Local model (Qwen 7B)       → Essential tier  (10 tools)
Medium model (Mistral 14B)  → Standard tier   (25 tools)
Frontier (Claude, GPT-4o)   → Full tier       (77+ tools)

Override model-aware routing for a specific tool by adding it to the promote list in your settings. This forces the tool into smaller model contexts regardless of tier:

# settings.yml
tools:
  promote:
    - browser_navigate
    - web_search

Custom Tools

Add your own tools via the plugin system. A custom tool requires:

A Zod schema defining input parameters
An async execute function returning a result
A security level declaration

See Custom Tools and Plugins Overview for implementation details.

Security Overview - How security modes control tool execution and approval
profclaw tools - List and directly execute tools from the CLI
AI Providers Overview - Model-aware tier routing depends on the active provider
Plugins Overview - Extend profClaw with custom tools via plugins

​What Are Tools?

​Tool Tiers

​Tool Categories

Filesystem

Git

Web Fetch

Web Search

Browser

Memory

profClaw Ops

Sessions

Test Runner

Cron

Notifications

Custom Tools

​How Tool Execution Works

​Security Levels

​Model-Aware Tool Routing

​Custom Tools

​Related

What Are Tools?

Tool Tiers

Tool Categories

How Tool Execution Works

Security Levels

Model-Aware Tool Routing

Custom Tools

Related