Skip to main content

​
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

Core tools that work reliably with any model, including small local models like Qwen 7B.
ToolCategoryDescription
read_filefilesystemRead file contents with optional line ranges
write_filefilesystemWrite or append to files
edit_filefilesystemSurgical find-and-replace in files
execexecutionRun shell commands
grepfilesystemRegex search across file contents
search_filesfilesystemFind files by glob pattern
directory_treefilesystemShow project structure
git_statusgitShow working tree status
web_fetchwebFetch URL content as text
complete_taskprofclawMark a task as complete

​
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

Register your own tools via plugins or the TypeScript SDK.

​
How Tool Execution Works

1

Model emits a tool call

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

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.
3

Security check

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

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.
5

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:
LevelDescriptionBehavior in standard mode
safeRead-only, no side effectsAlways allowed
moderateWrite operations, network requestsAllowed without prompt
dangerousShell exec, destructive file operationsRequires 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:
  1. A Zod schema defining input parameters
  2. An async execute function returning a result
  3. A security level declaration
See Custom Tools and Plugins Overview for implementation details.