Find where a C/C++ symbol (function, struct, macro, typedef, enum) is defined.

Use this INSTEAD of grep or text search whenever you need a symbol's definition — it is an indexed lookup that returns only the definition site(s), not every textual occurrence, and stays fast on codebases with millions of lines. The index is built and refreshed automatically.

Args: symbol: Exact symbol name, e.g. "tcp_v4_rcv" or "list_head". project_root: Project directory. Omit to use the server's default (auto-detected by walking up from its working directory). case_insensitive: Match the symbol ignoring case. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for a structured envelope with {symbol, path, line, col, kind, typeref, scope, signature, guard, snippet} records — kind/typeref/scope/signature carry ctags metadata (what the symbol is, its type/return type, its enclosing scope, its parameter list) when available; "text" for lines of: symbol line-number file source-line.

Find all call/usage sites of a defined C/C++ symbol.

Use this INSTEAD of grep when you need who calls a function or uses a type — grep returns every textual match including comments and strings, while this returns only real reference sites from the index, instantly even on huge trees.

Args: symbol: Exact symbol name whose call/usage sites you want. project_root: Project directory. Omit to use the server's default. case_insensitive: Match the symbol ignoring case. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for structured records; "text" for lines of: symbol line-number file source-line.

Return the full source code of a symbol's definition — just the body.

Use this INSTEAD of reading a whole file when you need to see how a function, struct, or macro is implemented. It jumps straight to the definition via the index and extracts only that definition's lines, so a one-screen function never costs you a 5000-line file read.

Args: symbol: Exact symbol name, e.g. "tcp_v4_rcv". project_root: Project directory. Omit to use the server's default. max_definitions: If the symbol has multiple definitions, return at most this many bodies (default 3). format: "json" (default) for {path, line, body} items; "text" for "=== path:line ===" separated bodies.

Find the FUNCTIONS that call a symbol, deduplicated, with call counts.

Use this INSTEAD of find_references when you want the call graph rather than raw match lines: each reference site is mapped to its enclosing function, so 100 call sites inside one loop-heavy caller collapse to a single result line. This is the highest signal-to-noise view of "who uses this?" on a large codebase.

Args: symbol: Exact symbol name whose callers you want. project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for {caller, path, sites} items; "text" for lines of: caller-function file N call site(s) at lines ...

Per-file reference counts for a symbol — the cheapest wide view.

Use this FIRST for very widely used symbols (thousands of references): it collapses the result to one line per file, sorted by count, so you can see where usage concentrates and then drill into a specific file with find_references or find_callers. Never floods the context window.

Args: symbol: Exact symbol name. project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for {path, count} items plus total_references; "text" for lines of: count file.

Multi-level callers tree: who calls X, who calls THOSE, and so on.

Use this for impact analysis — "if I change this function, what code paths are affected?" — instead of running find_references over and over. Each caller is expanded recursively up to depth levels, deduplicated, cycle-safe, and capped so the output stays compact even on huge trees.

Args: symbol: Exact symbol name at the root of the tree. project_root: Project directory. Omit to use the server's default. depth: How many caller levels to expand (1-5, default 2). format: "json" (default) for a nested {caller, path, site_count, callers} tree; "text" for a box-drawing rendering.

What functions does this function CALL? (the outgoing call graph)

Use this to understand a function's dependencies without reading any file: it extracts the function's body, detects call sites, and verifies each against the index. In-tree callees come back with their definition locations (ready for get_symbol_body); external names (libc etc.) are listed separately.

Args: symbol: Exact name of the function to analyze. project_root: Project directory. Omit to use the server's default. format: "json" (default) for {in_tree: [{symbol, path, line}], external: [names]}; "text" for a sectioned listing.

One-shot overview card for a symbol — the best FIRST query.

Use this before anything else when you encounter an unfamiliar symbol: one call returns where it's defined, WHAT it is (function/macro/struct/ typedef/enum-constant, with signature and enclosing scope when available), how widely it's used, which files use it most, and which tool to reach for next. Cheaper than any combination of grep and file reads.

Args: symbol: Exact symbol name. project_root: Project directory. Omit to use the server's default. format: "json" (default) for {definitions, reference_count, file_count, top_files}; "text" for the overview card.

High-level map of the indexed tree: size, structure, and languages.

Use this FIRST in an unfamiliar repository to orient yourself before drilling into symbols — it shows where the code mass lives without reading a single file.

Args: project_root: Project directory. Omit to use the server's default. top: How many top-level directories to list (default 15). format: "json" (default) for {file_count, directories, file_types}; "text" for the summary card.

List symbols defined in a file that have ZERO references anywhere.

Use this for cleanup and refactoring tasks: instead of checking each function by hand, one call reports every dead-code candidate in the file. Caveat: entry points (main), exported APIs, and functions only referenced via pointers or macro tricks can be false positives — treat results as candidates, not verdicts.

Args: file_path: Source file to audit, relative to the project root or absolute. project_root: Project directory. Omit to use the server's default. format: "json" (default) for {symbol, path, line} items; "text" for a summary listing.

Which files #include this header? (C/C++ include-graph impact)

Use this when changing a header to see the blast radius: every file that includes it, matched by basename so both "util.h" and <net/tcp.h>-style paths are found.

Args: header_name: Header file name, e.g. "tcp.h" or "net/tcp.h". project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for structured records; "text" for raw lines.

Find usages of symbols that have no definition inside the project.

Use this when find_definition returns nothing — typically external or library identifiers (e.g. printf, malloc) and variables gtags did not record as definitions. Still an indexed lookup, not a scan.

Args: symbol: Exact symbol name. project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for structured records; "text" for raw lines.

Regex-search all indexed source files (POSIX extended regex).

Prefer find_definition / find_references for symbol questions — they are indexed and far narrower. Use this only for arbitrary text that is not a symbol name (comments, string literals, TODO markers). It still beats plain grep: it searches only files the index knows about.

Args: pattern: Regex to search for, e.g. "TODO|FIXME". project_root: Project directory. Omit to use the server's default. case_insensitive: Match the pattern ignoring case. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for structured records; "text" for raw lines.

List every symbol defined in one source file.

Use this INSTEAD of reading a whole file when you only need its API surface — functions, structs, macros it defines — as a compact list.

Args: file_path: Path to the source file, relative to the project root or absolute. project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for structured records with ctags metadata (kind/typeref/scope/signature) when available; "text" for raw lines.

List defined symbols that start with the given prefix.

Use this when you know roughly what a function is called but not its exact name — then follow up with find_definition on the right match.

Args: prefix: Symbol name prefix, e.g. "tcp_" or "init". project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for {symbol} items; "text" for one name per line.

Find indexed source files whose path matches a regex pattern.

Use this INSTEAD of find or glob scans to locate files in a large tree — it queries the index rather than walking the filesystem.

Args: pattern: Regex matched against file paths, e.g. "net/.*.c$". project_root: Project directory. Omit to use the server's default. limit: Maximum result lines to return (default 100). offset: Skip this many result lines (for pagination). format: "json" (default) for {path} items; "text" for one path per line.

Force a full (re)build of the gtags index.

Normally unnecessary — every query tool indexes automatically on first use and refreshes incrementally. Call this only to force a from-scratch rebuild (e.g. after a large branch switch or if the index seems corrupt).

Args: project_root: Project directory. Omit to use the server's default. format: "json" (default) for {status, message}; "text" for a sentence.

Synchronously refresh the index — the guaranteed-freshness barrier.

Query tools refresh the index automatically in the BACKGROUND, so their results can lag very recent edits by a few seconds. Call this when you just edited files and need the very next query to see the changes: it blocks until the refresh is complete.

Args: project_root: Project directory. Omit to use the server's default. format: "json" (default) for {status, message}; "text" for a sentence.