# Open Code Review Agent Tools: Available Tools and Phase-Based Selection

> Explore Open Code Review agent tools. Discover the six available tools and understand how they are automatically selected based on the review phase using plan_task and main_task flags.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**The Open Code Review (OCR) agent has six built-in tools defined in [`tools.json`](https://github.com/alibaba/open-code-review/blob/main/tools.json), selected automatically based on the review phase using `plan_task` and `main_task` flags, with optional override via the `--tools` CLI flag.**

The Open Code Review (OCR) project from Alibaba provides a modern code review agent that uses an LLM to analyze code changes. Understanding what tools are available to the review agent and how they are selected is essential for customizing reviews and debugging agent behavior. This guide examines the tool registry architecture and the phase-based selection mechanism implemented in the source code.

## Built-in Tools Available to the Review Agent

The OCR agent ships with six built-in tools registered in **[[`internal/config/toolsconfig/tools.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json)**. Each tool is classified by its availability in the **plan** and **main** review phases:

| Tool | Plan Phase | Main Phase | Purpose |
|------|-----------|------------|---------|
| `task_done` | ✗ | ✅ | Signals review completion and terminates the main agent loop |
| `code_comment` | ✗ | ✅ | Emits review comments anchored to specific code locations |
| `file_read` | ✗ | ✅ | Reads line ranges from the post-change version of files |
| `file_read_diff` | ✅ | ✅ | Shows diffs of other files in the same change set |
| `file_find` | ✅ | ✅ | Finds files by filename substring matching |
| `code_search` | ✅ | ✅ | Greps the repository with literal strings or PCRE patterns |

These definitions are unmarshaled at runtime into `ToolConfigEntry` structs by the configuration loader in **[[`internal/config/toolsconfig/toolsconfig.go`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/toolsconfig.go)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/toolsconfig.go)**.

## How Tool Selection Works: The Phase-Based Filter

Tool selection is not static — the agent dynamically filters the tool set based on which **review phase** is currently executing. This filtering is implemented through the `ToolDefsByPhase` method.

### The Phase Model

OCR operates in two distinct phases:

1. **Plan Phase** — The LLM gathers context and understands the change scope. It can **read** files and search code but cannot emit comments.
2. **Main Phase** — The LLM performs the actual review, can both read files **and** submit comments via `code_comment`.

### Selection Implementation

The filtering logic appears in **[[`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)** around line 1562:

```go
defRaw, ok := e.ToolDefsByPhase(planOnly)

```

The `planOnly` boolean parameter indicates whether the agent is in the plan phase. The `ToolDefsByPhase` implementation checks the `plan_task` and `main_task` booleans from each tool's JSON definition:

```go
// Conceptual implementation from toolsconfig.go
func (e ToolConfigEntry) ToolDefsByPhase(planOnly bool) ([]byte, bool) {
    if planOnly && e.PlanTask {
        return e.Definition, true
    }
    if !planOnly && e.MainTask {
        return e.Definition, true
    }
    return nil, false
}

```

This ensures:

- **Plan phase tools**: Only `file_read_diff`, `file_find`, and `code_search` are exposed (tools where `plan_task: true`)
- **Main phase tools**: `task_done`, `code_comment`, `file_read` are added, plus the three dual-phase tools (where `main_task: true`)

## Customizing Tool Availability with `--tools`

Users can override the default tool registry without modifying source code. The `--tools` flag accepts a path to a custom JSON file that replaces the embedded [[`tools.json`](https://github.com/alibaba/open-code-review/blob/main/tools.json)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json).

### Custom Tool Registry Example

Create a restricted tool set that removes search capabilities:

```bash
cat > minimal-tools.json <<'EOF'
[
  {
    "name": "task_done",
    "plan_task": false,
    "main_task": true,
    "definition": {
      "description": "Signal that the review is complete",
      "parameters": {
        "type": "object",
        "properties": {}
      }
    }
  },
  {
    "name": "code_comment",
    "plan_task": false,
    "main_task": true,
    "definition": {
      "description": "Submit a code review comment",
      "parameters": {
        "type": "object",
        "properties": {
          "comments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "content": { "type": "string" },
                "existing_code": { "type": "string" },
                "suggestion_code": { "type": "string" },
                "category": { "type": "string" },
                "severity": { "type": "string" }
              },
              "required": ["content", "existing_code"]
            }
          }
        },
        "required": ["comments"]
      }
    }
  }
]
EOF

```

Run the agent with the custom registry:

```bash
ocr review --tools ./minimal-tools.json

```

The **[tools.md documentation](https://github.com/alibaba/open-code-review/blob/main/pages/src/content/docs/en/tools.md)** describes this override mechanism and each tool's parameter schema.

## Practical Tool Usage Examples

### Searching for Patterns with `code_search`

The `code_search` tool supports Perl-compatible regular expressions:

```json
{
  "name": "code_search",
  "input": {
    "search_text": "TODO|FIXME|XXX",
    "file_patterns": ["*.go", ":(exclude)vendor/", ":(exclude)*_test.go"],
    "case_sensitive": false,
    "use_perl_regexp": true
  }
}

```

### Reading Diff Context with `file_read_diff`

Access changes in other files without leaving the review context:

```json
{
  "name": "file_read_diff",
  "input": {
    "file_path": "internal/service/user.go",
    "view_range": [1, 50]
  }
}

```

### Submitting Structured Comments

The `code_comment` tool requires precise anchoring to existing code:

```json
{
  "name": "code_comment",
  "input": {
    "comments": [
      {
        "content": "Potential resource leak: `resp.Body` is not closed before returning",
        "existing_code": "resp, err := http.Get(url)\nif err != nil {\n    return nil, err\n}\nreturn resp, nil",
        "suggestion_code": "resp, err := http.Get(url)\nif err != nil {\n    return nil, err\n}\ndefer resp.Body.Close()\nreturn resp, nil",
        "category": "resource_leak",
        "severity": "high"
      }
    ]
  }
}

```

## Key Source Files and Architecture

| File | Responsibility |
|------|---------------|
| [[`internal/config/toolsconfig/tools.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json) | Canonical registry of all built-in tool definitions with phase flags |
| [[`internal/config/toolsconfig/toolsconfig.go`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/toolsconfig.go)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/toolsconfig.go) | JSON loader and `ToolDefsByPhase` filtering implementation |
| [[`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) | Core agent loop that invokes `ToolDefsByPhase(planOnly)` around line 1562 |
| [[`pages/src/content/docs/en/tools.md`](https://github.com/alibaba/open-code-review/blob/main/pages/src/content/docs/en/tools.md)](https://github.com/alibaba/open-code-review/blob/main/pages/src/content/docs/en/tools.md) | User-facing documentation for tool parameters and `--tools` override |

The separation between **plan** and **main** phases prevents the LLM from prematurely commenting before understanding the full change context, while the JSON-based registry allows declarative tool configuration without recompilation.

## Summary

- **Six built-in tools** are available: `task_done`, `code_comment`, `file_read`, `file_read_diff`, `file_find`, and `code_search`
- **Phase-based selection** uses `plan_task` and `main_task` booleans in [[`tools.json`](https://github.com/alibaba/open-code-review/blob/main/tools.json)](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json), filtered by `ToolDefsByPhase` in the agent loop
- **Custom tool registries** can be loaded via `--tools <path>` to disable, modify, or extend the default tool set
- **Plan phase** restricts the agent to read-only exploration; **main phase** enables comment submission and task completion
- The architecture is defined across four key files: the JSON registry, Go configuration loader, agent implementation, and markdown documentation

## Frequently Asked Questions

### What happens if a tool is missing from my custom `--tools` file?

The agent will not have access to that tool during execution. If you omit critical tools like `task_done`, the agent may be unable to terminate properly. Always include `task_done` for main-phase reviews.

### Can I add entirely new tools to the registry?

The current architecture supports redefining existing tools and adjusting their schemas, but adding fundamentally new tool implementations requires modifying the agent source code in [[`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) to handle the new tool's execution logic.

### Why are some tools restricted to the main phase only?

Tools like `code_comment` and `task_done` produce final outputs. Restricting them to the main phase prevents the LLM from submitting premature conclusions before fully exploring the codebase during the plan phase. This two-phase design improves review quality by enforcing a "think first, then respond" workflow.

### How do I see which tools are active during a specific review run?

Enable verbose logging or examine the tool definitions returned by `ToolDefsByPhase`. The agent constructs its system prompt using only the filtered tool set, so the LLM context will contain exactly the tools available for that phase.