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

The Open Code Review (OCR) agent has six built-in tools defined in 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). 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).

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) around line 1562:

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:

// 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/internal/config/toolsconfig/tools.json).

Custom Tool Registry Example

Create a restricted tool set that removes search capabilities:

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:

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

The tools.md documentation 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:

{
  "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:

{
  "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:

{
  "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)	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)	JSON loader and ToolDefsByPhase filtering implementation
[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)	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/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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}