# Tools reference

> Named tool registry: terminal, file, browser, search engines, memory store/search, agent delegation tools, result tools, barrier tools, and assistant flow-control tools with argument shapes.

- Repository: vxcontrol/pentagi
- GitHub: https://github.com/vxcontrol/pentagi
- Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5
- Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt

## Source Files

- `backend/pkg/tools/registry.go`
- `backend/pkg/tools/args.go`
- `backend/pkg/tools/tools.go`
- `backend/pkg/tools/executor.go`
- `backend/pkg/tools/flow_manager.go`
- `backend/docs/flow_execution.md`
- `backend/pkg/tools/registry_test.go`

---

---
title: "Tools reference"
description: "Named tool registry: terminal, file, browser, search engines, memory store/search, agent delegation tools, result tools, barrier tools, and assistant flow-control tools with argument shapes."
---

Named LLM tools live in `backend/pkg/tools`. Constants and JSON schemas are registered in `registryDefinitions`; argument structs live in `args.go`; per-agent tool bundles are assembled by `flowToolsExecutor.Get*Executor`; runtime dispatch, logging, summarization, and barrier detection run through `customExecutor.Execute`.

Every tool name maps to a `ToolType` used for observability and storage policy:

| `ToolType` | String | Role |
|---|---|---|
| `EnvironmentToolType` | `environment` | Docker terminal/file and assistant flow-control tools |
| `SearchNetworkToolType` | `search_network` | Browser and external search engines |
| `SearchVectorDbToolType` | `search_vector_db` | pgvector and Graphiti retrieval |
| `StoreVectorDbToolType` | `store_vector_db` | Guide/answer/code store tools |
| `AgentToolType` | `agent` | Specialist delegation tools |
| `StoreAgentResultToolType` | `store_agent_result` | Specialist result and plan outputs |
| `BarrierToolType` | `barrier` | Primary-agent exit tools (`done`, `ask`) |

<Note>
Executor-level **barriers** are broader than `BarrierToolType`. Each agent executor marks its terminal result tool (for example `code_result`, `hack_result`, `subtask_list`) in `customExecutor.barriers` so a successful call ends that agent turn.
</Note>

## Registry catalog

| Name | Type | Schema struct | Summary |
|---|---|---|---|
| `terminal` | environment | `TerminalAction` | Run a command in the flow Docker container |
| `file` | environment | `FileAction` | Read or write a file by absolute path |
| `browser` | search_network | `Browser` | Fetch page content (markdown/html/links) |
| `google` | search_network | `SearchAction` | Google CSE short query |
| `duckduckgo` | search_network | `SearchAction` | Anonymous DuckDuckGo query |
| `tavily` | search_network | `SearchAction` | Detailed Tavily research |
| `traversaal` | search_network | `SearchAction` | Traversaal Q&A + links |
| `perplexity` | search_network | `SearchAction` | LLM-augmented research report |
| `searxng` | search_network | `SearchAction` | Privacy meta-search |
| `sploitus` | search_network | `SploitusAction` | Exploit/PoC aggregator |
| `search_in_memory` | search_vector_db | `SearchInMemoryAction` | Multi-query vector memory search |
| `search_guide` / `store_guide` | search/store vector | `SearchGuideAction` / `StoreGuideAction` | Guide memory |
| `search_answer` / `store_answer` | search/store vector | `SearchAnswerAction` / `StoreAnswerAction` | Answer memory |
| `search_code` / `store_code` | search/store vector | `SearchCodeAction` / `StoreCodeAction` | Code sample memory |
| `graphiti_search` | search_vector_db | `GraphitiSearchAction` | Temporal knowledge graph search |
| `search` | agent | `ComplexSearch` | Delegate to searcher agent |
| `coder` | agent | `CoderAction` | Delegate to coder agent |
| `pentester` | agent | `PentesterAction` | Delegate to pentester agent |
| `maintenance` | agent | `MaintenanceAction` | Delegate to installer/DevOps agent |
| `memorist` | agent | `MemoristAction` | Delegate to memorist agent |
| `advice` | agent | `AskAdvice` | Delegate to adviser/mentor |
| `search_result` | store_agent_result | `SearchResult` | Searcher terminal output |
| `code_result` | store_agent_result | `CodeResult` | Coder terminal output |
| `hack_result` | store_agent_result | `HackResult` | Pentester terminal output |
| `maintenance_result` | store_agent_result | `TaskResult` | Installer terminal output |
| `memorist_result` | store_agent_result | `MemoristResult` | Memorist terminal output |
| `enricher_result` | store_agent_result | `EnricherResult` | Enricher terminal output |
| `report_result` | store_agent_result | `TaskResult` | Reporter terminal output |
| `subtask_list` | store_agent_result | `SubtaskList` | Generator full plan |
| `subtask_patch` | store_agent_result | `SubtaskPatch` | Refiner delta plan |
| `done` | barrier | `Done` | Finish subtask success/failure |
| `ask` | barrier | `AskUser` | Pause for user input (`ASK_USER`) |
| `get_flow_status` | environment | `GetFlowStatusAction` | Assistant flow status query |
| `stop_flow` | environment | `StopFlowAction` | Cancel running automation task |
| `submit_flow_input` | environment | `SubmitFlowInputAction` | Answer `ask` or start a new task |
| `patch_flow_subtasks` | environment | `PatchFlowSubtasksAction` | Patch planned subtasks |
| `wait_flow_completion` | environment | `WaitFlowCompletionAction` | Block until running task ends |

## Argument conventions

Most tools require a `message` engagement-log field (1–2 short sentences in the engagement language). Technical payloads (`query`, `question`, `result`, stored knowledge) are English-only so shared indexes stay searchable.

Boolean/integer JSON fields use custom `Bool` / `Int64` wrappers so models can pass loose types safely.

### Environment tools

<ParamField body="terminal.input" type="string" required>
Command to run in the primary Docker container. One command per call.
</ParamField>
<ParamField body="terminal.cwd" type="string" required>
Working directory inside the container.
</ParamField>
<ParamField body="terminal.detach" type="boolean" required>
`true` for interactive/long-running processes (shells, listeners, servers); no stdout capture. `false` for batch commands that must finish and return output.
</ParamField>
<ParamField body="terminal.timeout" type="integer" required>
Seconds. `0` or non-positive uses server default (`TERMINAL_TOOL_TIMEOUT`, default `1200`). Explicit values accepted up to `10800` (3 hours); out-of-range values fall back to the server default.
</ParamField>
<ParamField body="terminal.message" type="string" required>
Engagement-log commentary for the command.
</ParamField>

```json
{
  "input": "timeout 55 nmap -sV 10.0.0.5",
  "cwd": "/work",
  "detach": false,
  "timeout": 60,
  "message": "Service scan on the target before web enumeration."
}
```

<ParamField body="file.action" type="string" required>
`read_file` or `write_file`.
</ParamField>
<ParamField body="file.path" type="string" required>
Absolute path in the container.
</ParamField>
<ParamField body="file.content" type="string">
Raw file body for `write_file`.
</ParamField>
<ParamField body="file.message" type="string" required>
Engagement-log commentary.
</ParamField>

User uploads and resources are synced under `/work/uploads` and `/work/resources` on the primary container.

### Browser and search engines

| Field | Tools | Constraints |
|---|---|---|
| `url` | `browser` | Required target URL |
| `action` | `browser` | `markdown` \| `html` \| `links` |
| `query` | engines | English technical query |
| `max_results` | engines | Min 1; max 10 (default 5). Sploitus max 25 (default 10) |
| `exploit_type` | `sploitus` | Optional `exploits` (default) or `tools` |
| `sort` | `sploitus` | Optional `default` \| `date` \| `score` |
| `message` | all | Engagement-log commentary |

Network tools register only when `IsAvailable()` is true (scraper URLs, API keys, feature flags). Missing engines are omitted from the agent tool list rather than failing at call time.

### Memory store and search

| Tool | Required filters / fields |
|---|---|
| `search_in_memory` | `questions` (1–5 English queries); optional `task_id`, `subtask_id` hard filters |
| `search_guide` / `store_guide` | `type`: `install` \| `configure` \| `use` \| `pentest` \| `development` \| `other` |
| `search_answer` / `store_answer` | `type`: `guide` \| `vulnerability` \| `code` \| `tool` \| `other` |
| `search_code` | `lang` (markdown language id, e.g. `python`) |
| `store_code` | `code`, `question`, `lang`, `explanation`, `description` |
| Store tools | Anonymize IPs, domains, credentials, paths, API keys before store |

Multi-query search merges, deduplicates, and ranks by relevance. Embeddings and pgvector availability gate these tools.

### Graphiti search

`graphiti_search` is optional and requires an enabled Graphiti client.

<ParamField body="search_type" type="string" required>
One of: `temporal_window`, `entity_relationships`, `diverse_results`, `episode_context`, `successful_tools`, `recent_context`, `entity_by_label`.
</ParamField>
<ParamField body="query" type="string" required>
English natural-language graph query.
</ParamField>

Optional fields depend on type: `time_start`/`time_end` (ISO 8601) for `temporal_window`; `center_node_uuid` and `max_depth` (default 2, max 3) for `entity_relationships`; `diversity_level` (`low`/`medium`/`high`); `min_mentions`; `recency_window` (`1h`/`6h`/`24h`/`7d`); `node_labels`; `edge_types`; `max_results`.

If Graphiti is disabled, the handler returns an informational string instead of an error.

### Agent delegation tools

| Tool | Payload | Result tool |
|---|---|---|
| `search` | `question` (English research brief) | `search_result` |
| `coder` | `question` (dev task) | `code_result` |
| `pentester` | `question` (pentest task) | `hack_result` |
| `maintenance` | `question` (env/tool setup) | `maintenance_result` |
| `memorist` | `question`; optional `task_id`/`subtask_id` | `memorist_result` |
| `advice` | `question`; optional `code`, `output` | (mentor reply; no result tool) |

Delegation tools are `AgentToolType` and create Langfuse agent observations. Result tools are executor barriers for the specialist turn.

### Planning and report tools

| Tool | Agent | Shape |
|---|---|---|
| `subtask_list` | Generator | `subtasks[]` with `title` + `description`; barrier |
| `subtask_patch` | Refiner | `operations[]` of `add` / `remove` / `modify` / `reorder`; empty ops = no change; barrier |
| `report_result` | Reporter | `success`, `result`, `message` (`TaskResult`); barrier |
| `enricher_result` | Enricher | `result`, `message`; barrier |

`SubtaskOperation` rules:

- `add`: requires `title` and `description`; optional `after_id` (null/0 = start)
- `remove` / `modify` / `reorder`: require `id`
- `modify`: optional new `title`/`description`
- `reorder`: uses `after_id` for new position

### Barrier tools (primary agent)

| Tool | Fields | Effect |
|---|---|---|
| `done` | `success`, `result`, `message` | Completes the current subtask |
| `ask` | `message` | Pauses for user input |

`ask` is registered only when `ASK_USER=true` (default `false`). Both are primary-agent barriers and use span observations in Langfuse.

### Assistant flow-control tools

Always present for the assistant executor: `get_flow_status`. The remaining tools appear only when the corresponding `FlowManagerHandlers` callback is non-nil.

| Tool | Key args | Behavior |
|---|---|---|
| `get_flow_status` | `detail`, optional `task_id`, `verbose` | `summary` \| `tasks` \| `subtasks` \| `running` \| `planned` |
| `stop_flow` | `reason`, `message` | Cancels running task; flow → waiting. No-op if nothing running |
| `submit_flow_input` | `input`, `message` | Answers an `ask` checkpoint, or starts a new task when idle. Errors if a task is running |
| `patch_flow_subtasks` | `task_id`, `operations`, `message` | Delta-patch planned subtasks; can reset an active/waiting subtask to `created`. Errors if a task is running |
| `wait_flow_completion` | `timeout` (seconds), `message` | Wait for running task. Default 60s when ≤0; cap 3600s. Returns immediately if nothing running |

`get_flow_status` message limits: 10 recent agent messages by default, 50 with `verbose=true`. Operation timeout for stop/status paths is 15 seconds.

## Per-agent tool bundles

`flowToolsExecutor` builds a filtered definition/handler map per role. Optional tools appear only when backends are available.

| Executor | Core tools | Optional |
|---|---|---|
| **Primary** | `done`, `advice`, `coder`, `maintenance`, `memorist`, `pentester`, `search` | `ask` if `ASK_USER` |
| **Installer** | `maintenance_result`, `advice`, `memorist`, `search`, `terminal`, `file` | `browser`, `store_guide`/`search_guide` |
| **Coder** | `code_result`, `advice`, `maintenance`, `memorist`, `search`, `terminal`, `file` | `browser`, `search_code`/`store_code`, `graphiti_search` |
| **Pentester** | `hack_result`, `advice`, `coder`, `maintenance`, `memorist`, `search`, `terminal`, `file` | `browser`, guides, `graphiti_search`, `sploitus` |
| **Searcher** | `search_result`, `memorist` | all network engines, `browser`, `search_answer`/`store_answer` |
| **Generator** | `subtask_list`, `memorist`, `search`, `terminal`, `file` | `browser` |
| **Refiner** | `subtask_patch`, `memorist`, `search`, `terminal`, `file` | `browser` |
| **Memorist** | `memorist_result`, `terminal`, `file` | `search_in_memory`, `graphiti_search` |
| **Enricher** | `enricher_result`, `terminal`, `file` | `search_in_memory`, `graphiti_search`, `browser` |
| **Reporter** | `report_result` only | — |
| **Assistant** (`UseAgents=true`) | `terminal`, `file`, agent tools | `browser`, flow-control tools |
| **Assistant** (`UseAgents=false`) | `terminal`, `file`, direct memory/search engines | `browser`, flow-control tools |

Primary agent does **not** get direct `terminal`/`file`/network tools; it orchestrates via specialists.

## Runtime behavior

### Execution path

```text
LLM tool call
  → customExecutor.Execute
      → resolve handler by name
      → observation by ToolType (tool / agent / span / noop for vector search)
      → msglog + toolcall log
      → handler(ctx, name, args)
      → optional summarize/truncate large results
      → optional store into long-term memory
      → update msglog result
```

Unknown tool names return a soft string error (`function '…' not found`) rather than panicking. Invalid JSON args return a soft fix-it message so the model can retry.

### Result size handling

- Default result size budget before summarization: **16 KB** (`DefaultResultSizeLimit`)
- Summarization allowed for: `terminal`, `browser` (when a summarizer is configured)
- Without summarizer, oversized summarizable results are head/tail truncated at 2× the limit

### Memory auto-store allowlist

Successful results from these tools may be stored in vector memory when the store is available: `terminal`, `file`, `search`, `google`, `duckduckgo`, `tavily`, `traversaal`, `perplexity`, `searxng`, `sploitus`, `maintenance`, `coder`, `pentester`, `advice`.

### Terminal timeouts

| Setting | Value |
|---|---|
| `TERMINAL_TOOL_TIMEOUT` default | 1200 seconds |
| Hard max explicit timeout | 10800 seconds (3 hours) |
| Extra exec buffer | +5 seconds on the configured default |
| Detached commands | No stdout/stderr capture; return confirmation only |

### External / disabled functions

Flows can supply `Functions` with:

- `Disabled[]` — disable named tools per context (`agent`, `adviser`, `coder`, `searcher`, `generator`, `memorist`, `enricher`, `reporter`, `assistant`)
- `Function[]` — external HTTP tools with URL, optional timeout, context scopes, and JSON schema

## Failure modes

| Condition | Behavior |
|---|---|
| Tool not in executor map | Soft string: function not found |
| Network engine not configured | Tool omitted from definitions |
| Graphiti disabled | Soft informational string on call |
| pgvector/embedder unavailable | Memory tools omitted |
| Terminal/file with no container | Handler error / prepare failure |
| `submit_flow_input` / `patch_flow_subtasks` while task running | Error: cancel first |
| `wait_flow_completion` timeout | Soft string suggesting `get_flow_status` detail `running` |
| `stop_flow` with no running task | Informational no-op |
| Tool handler error | Soft-swallowed for some tools (e.g. terminal); toolcall log marked failed when dispatch fails hard |

## Related pages

<CardGroup>
  <Card title="Tools and sandbox execution" href="/tools-and-sandbox">
    Tool categories, Docker isolation, timeouts, and default images.
  </Card>
  <Card title="Agents and supervision" href="/agents-and-supervision">
    Specialist agents, monitor, planning step, and tool-call hard limits.
  </Card>
  <Card title="Memory and knowledge" href="/memory-and-knowledge">
    pgvector tools, embeddings, chain summarizer, flow files under /work.
  </Card>
  <Card title="Search engines" href="/search-engines">
    Enable DuckDuckGo, Google, Tavily, Traversaal, Perplexity, Sploitus, Searxng.
  </Card>
  <Card title="Knowledge graph" href="/knowledge-graph">
    Graphiti enablement and graphiti_search behavior.
  </Card>
  <Card title="Flows, tasks, and subtasks" href="/flows-tasks-subtasks">
    Lifecycle, Generator/Refiner plans, and putUserInput / stopFlow boundaries.
  </Card>
</CardGroup>