Why One Explore Call Can Replace a Search Loop

CodeGraph’s agent-facing question is not “Can it search a repository?” but “Can it return enough connected evidence for the agent to reason without rebuilding the map?” This chapter examines codegraph_explore, the project’s default MCP surface, and the allocation decisions that turn a graph into bounded context. The practical result is a way to tell a useful response from a response that merely looks comprehensive.

One tool, three kinds of evidence

When an indexed project is available, CodeGraph exposes one primary MCP tool: codegraph_explore. It accepts either a natural-language structural question or a set of symbol and file names. The response returns verbatim, line-numbered source grouped by file, the call paths among relevant symbols, and a summary of what depends on them. In one payload, the agent can receive the source it needs, the relationships that give that source meaning, and an initial view of the change radius.

That combination is different from a search hit. A search hit identifies a possible location. An explore response attempts to connect that location to the surrounding mechanism. If the question is how a request reaches a database, the useful result is not just the name of a handler. It is the handler’s source, the path toward the service or persistence layer, and enough caller or dependent information to understand where the path begins and what else may be affected.

The line numbers matter because they preserve the connection between graph evidence and editable source. An agent can refer to the exact line that makes a call, inspect a route registration, or use the returned source as the basis for a later edit without first reopening the file merely to recover coordinates. The project’s guidance treats the returned source as already read, while still allowing a direct read when a specific freshness or coverage warning requires it.

A named-symbol query is useful when the reader knows the endpoints of a flow. Asking for two symbols can make the intended relationship explicit and reduce ambiguity from natural-language terms. A prose question is useful when the reader is surveying an area or does not yet know the relevant names. The two forms are not competing interfaces; they are ways of giving the graph either a conceptual question or a more constrained starting set.

The wording still shapes the evidence that can be returned. A broad question such as how a subsystem works asks the graph to discover an area and decide which files are central. A query that names the entry and destination asks it to trace a narrower path. A request for a specific file or symbol can prioritize current source at a known location. None of these forms guarantees a complete answer, but each supplies a different amount of guidance to the retrieval system. Good use of the tool is therefore not a ritual invocation; it is the act of stating the structural decision the agent needs to make.

The response also includes a blast-radius perspective. Callers and callees answer local direction questions. A flow connects named points. Impact follows dependencies outward to show what a change may touch. These views are related but not interchangeable.