Retrieve a high-level structural map of the repository: languages, hub files, and top entry points. Read-only, deterministic, zero side effects. When to use: call this first at session start to understand codebase layout and identify entry points before detailed queries. Use when deciding where to investigate. When NOT to use: do not use to search code (use repo_search) or inspect call graphs (use repo_neighbours). Output: markdown summary of languages, hub files, and entry points, prefixed with a staleness note when the indexed working tree has changed since the index was built -- treat citations as suspect until rebuilt.

Search repository code for answers to questions using BM25 lexical ranking expanded with graph neighbours. Read-only, no side effects, secret files (.env) excluded. When to use: use for open-ended queries, locating implementations, or finding error strings. When NOT to use: do not use when you already have a symbol node_id and want callers/callees (use repo_neighbours); do not use for broad repo layout (use repo_map). Output: markdown citation blocks [cite: path:start-end] bounded by budget_tokens. To page, pass cursor="" then each next_cursor: token from the reply's last line.

Traverse code graph relationships from a known symbol or file node_id (callers, callees, base classes, definitions). Read-only, deterministic traversal, no side effects. When to use: use with a specific node_id (e.g. from repo_search citations) to inspect callers (CALLS in), callees (CALLS out), inheritance, definitions, or the tests that reach a symbol through calls (TESTS in). When NOT to use: do not use for text search across code (use repo_search) or repo overview (use repo_map). Output: markdown list formatted as - <EDGE_TYPE> <in|out>: <name> (<path:line>) [<node_id>], or with format="json" the same rows as JSON plus co-changed files. To page past limit, pass cursor="" then each next_cursor: token from the reply's last line.

Look up a symbol or file's node_id by name, or by path and line (the symbols enclosing that line, innermost first, then the file), for feeding into repo_neighbours, repo_read, repo_path_between or repo_blast_radius. Read-only, deterministic, zero side effects, secret files (.env) excluded. A name matches exactly first, then case-insensitively, then as a qualname's last segment; an ambiguous name returns every candidate, with its path. When to use: you know a name (from a traceback, a grep, a review comment) or a file position and want its node_id with no repo_search round trip. When NOT to use: not for open-ended text search (use repo_search) or for repo layout (use repo_map). Output: JSON array of {node_id, name, qualname, kind, path, start_line, end_line, lang}.

Read a widened window of source text around a citation, from the indexed chunks rather than the filesystem -- works with no shared filesystem between client and server, because chunks have already passed secret-path exclusion and redaction. Read-only, deterministic, zero side effects. When to use: use after repo_search or repo_neighbours to see more lines around a [cite: path:start-end] citation, with optional context lines each side. When NOT to use: do not use for a path never indexed, or an absolute or '..' path (both are refused); use repo_search or repo_find_symbol to find a valid path first. Output: [cite: path:start-end] header plus the text, bounded in size.

Find a bounded, bidirectional path between two node_ids over CALLS/DEFINES/IMPORTS edges (CO_CHANGE only if named explicitly), reporting the minimum confidence along each path. Read-only, deterministic traversal, no side effects. When to use: use for 'how does X reach Y' questions a text search cannot answer, e.g. the call chain from an HTTP handler to a database write. When NOT to use: do not use for one-hop neighbours (use repo_neighbours) or open-ended search (use repo_search). Output: JSON array of paths, each an ordered array of {node_id, path, start_line, end_line, via_edge, confidence}.

Reverse reachability from a node_id: callers of callers, subclasses of subclasses, importers of importers of its file, and historically co-edited files, by hop distance -- the blast radius of changing it. Read-only, deterministic, zero side effects, secret files excluded. When to use: use before editing a symbol to see what depends on it, or to answer 'what is the blast radius of changing X'. When NOT to use: do not use for open-ended search (use repo_search) or to read a symbol's own body (use repo_read). Output: JSON object with callers, subclasses, importers, cochange, and a summary.

Retrieve runtime diagnostic counters for the tool result cache (hits, misses, size, max_size, ttl_s). Read-only, in-memory diagnostics, zero side effects. When to use: use when evaluating cache hit rate or debugging server performance. When NOT to use: do not use to search repository contents or inspect code structure; use repo_map or repo_search instead. Output: JSON object with cache metrics.

Query progress and status of a background index build task under --async-build. Read-only check of in-memory background worker. When to use: use when polling build progress after an async index build was started. When NOT to use: do not use when building synchronously or when queries already succeed. Once completed, use repo_search or repo_map to query code. Output: JSON object with task_id, status, parsed file progress, and error details.