# How to Query the CRG Knowledge Graph: A Complete Guide to query_graph_tool

> Query the CRG knowledge graph using query_graph_tool. Explore call chains, imports, and test coverage by defining patterns and target nodes in your graph data.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Use the `query_graph_tool` MCP tool in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) with a specific pattern (e.g., `callers_of`, `tests_for`) and target node to traverse structural relationships like call chains, imports, and test coverage in the Code-Review-Graph knowledge graph.**

The Code-Review-Graph (CRG) open-source project captures structural relationships between code entities to power intelligent code reviews. When you need to query the CRG knowledge graph to understand dependencies, test coverage, or call hierarchies, the built-in MCP tool `query_graph_tool` serves as the primary interface for graph traversal. This tool exposes the underlying graph database through 16 semantic patterns that map directly to software engineering concepts.

## Understanding the query_graph_tool Interface

The `query_graph_tool` implementation in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) (lines 46-85) defines the contract for all graph explorations. The tool accepts parameters that specify both the traversal pattern and the scope of returned data.

### Required Parameters

To successfully query the CRG knowledge graph, you must provide two mandatory arguments:

- **`pattern`** – A string identifying the relationship type to traverse. Valid values include `callers_of`, `callees_of`, `tests_for`, and 13 other predefined patterns.
- **`target`** – The node identifier serving as the query origin. This can be a fully-qualified function name (e.g., `my_pkg.utils.calculate`), a class reference (e.g., `com.example.MyService`), or a file path present in the graph.

### Optional Configuration

You can refine results using additional parameters:

- **`repo_root`** – The repository root path; auto-detected if omitted.
- **`detail_level`** – Either `"standard"` (default, full metadata) or `"minimal"` (compact summary).
- **`max_results`** – Integer limit for the result set size.

## Available Query Patterns for the CRG Knowledge Graph

The CRG knowledge graph supports 16 predefined traversal patterns covering structural, behavioral, and dependency relationships:

**Call and Reference Patterns**
- **`callers_of`** – Functions or methods that invoke the target.
- **`callees_of`** – Functions called by the target.
- **`references_to`** – Any nodes referencing the target.

**Module and Import Patterns**
- **`imports_of`** – Modules imported by the target file.
- **`importers_of`** – Files that import the target module.

**Structural Containment**
- **`children_of`** – Entities contained within a file or class.
- **`file_summary`** – All nodes present in a specific file.

**Inheritance and Testing**
- **`inheritors_of`** – Classes that inherit from the target.
- **`tests_for`** – Test cases exercising the target function or class.

**Event and Scheduler Patterns**
- **`triggers_of`** – Scheduler-triggered methods invoked by the target.
- **`triggered_by`** – Schedulers or triggers that invoke the target.
- **`publishers_of`** – Methods that publish an event.
- **`listeners_of`** – Methods listening for an event.

**API and Configuration Patterns**
- **`handlers_of`** – Methods handling a specific endpoint.
- **`endpoints_for`** – Endpoints served by the target method.
- **`consumers_of`** – Spring configuration consumers.

## Practical Examples for Querying the CRG Knowledge Graph

### Command-Line Interface

Use the `code-review-graph mcp` command defined in [`code_review_graph/cli.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/cli.py) to invoke `query_graph_tool` directly from your terminal. This approach requires no Python scripting for quick lookups.

Find all callers of a Python function:

```bash
code-review-graph mcp \
  --tool query_graph_tool \
  --pattern callers_of \
  --target my_pkg.utils.calculate \
  --detail_level minimal

```

### Python API Integration

Import `query_graph_tool` from `code_review_graph.main` to embed graph queries into custom analysis scripts.

Retrieve test coverage for a Java class:

```python
from code_review_graph.main import query_graph_tool

result = query_graph_tool(
    pattern="tests_for",
    target="com.example.MyService",
    detail_level="standard",
    max_results=50,
)

print(result["nodes"])   # List of test nodes covering the class

```

### Chaining with Impact Analysis

Combine `query_graph_tool` with `get_impact_radius_tool` to drill down into high-risk change areas. This workflow starts with impact detection, then uses targeted graph queries to map dependencies.

```python
from code_review_graph.main import get_impact_radius_tool, query_graph_tool

# Identify high-risk functions from recent changes

impact = get_impact_radius_tool(max_depth=2, detail_level="minimal")
high_risk = [node["name"] for node in impact["high_risk"]]

# For each high-risk function, list its callees

for fn in high_risk:
    callees = query_graph_tool(
        pattern="callees_of",
        target=fn,
        detail_level="minimal",
    )
    print(f"Callees of {fn}:", callees["nodes"])

```

## Integrating with the Broader MCP Ecosystem

While `query_graph_tool` handles structural traversal, the CRG platform provides complementary MCP tools for comprehensive analysis. According to the documentation in [`code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md), you can chain `query_graph_tool` with:

- **`get_review_context_tool`** – For semantic context around code changes.
- **`get_impact_radius_tool`** – To identify high-risk modification areas.
- **`semantic_search_nodes_tool`** – For vector-based similarity search across the graph.

Typical workflows begin with `get_minimal_context_tool` to obtain a risk overview, then apply `query_graph_tool` to specific high-risk items using patterns like `callers_of` or `tests_for`.

## Summary

- The `query_graph_tool` in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) is the primary interface to query the CRG knowledge graph.
- You must specify a `pattern` (one of 16 relationship types) and a `target` node to execute any query.
- Supported patterns cover call hierarchies (`callers_of`, `callees_of`), dependencies (`imports_of`, `importers_of`), testing (`tests_for`), and event handling (`listeners_of`, `publishers_of`).
- Use `detail_level="minimal"` for quick summaries or `"standard"` for full node metadata.
- The tool integrates with the `code-review-graph` CLI ([`cli.py`](https://github.com/tirth8205/code-review-graph/blob/main/cli.py)) and can be chained with other MCP tools like `get_impact_radius_tool` for advanced workflows.

## Frequently Asked Questions

### What is the difference between detail_level "standard" and "minimal"?

The `"standard"` detail level (default) returns complete node metadata including all properties stored in the CRG knowledge graph. The `"minimal"` setting returns a compact summary containing only essential identifiers, which improves performance when processing large result sets or when you only need entity names for downstream filtering.

### Can I use wildcards or regex in the target parameter?

No, the `target` parameter requires a specific, fully-qualified identifier present in the graph such as `my_pkg.utils.calculate` or `com.example.MyService`. For fuzzy matching or semantic similarity searches, use the `semantic_search_nodes_tool` instead, which performs vector-based retrieval across the knowledge graph.

### How do I find all tests that cover a specific function?

Use the `tests_for` pattern. Invoke `query_graph_tool` with `pattern="tests_for"` and set `target` to your function name. The tool returns test nodes that exercise the target according to the test coverage relationships captured during the graph construction phase.

### Where is the complete list of query patterns defined?

The authoritative list of 16 supported patterns is implemented in the `query_graph_tool` function definition within [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) (lines 46-85). Additional documentation and usage examples are available in [`code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md).