Detect public API surface drift by comparing exported Go symbols (functions, types, interfaces) between the current working tree and a baseline git reference. Uses git archive to snapshot the baseline — requires git to be available and the since ref to be a valid branch, tag, or commit. Requires .gograph/graph.json — run gograph build . first. Read-only; archives only a temp directory that is removed after the call. WHEN TO USE: Before releasing or merging a PR to catch breaking-change regressions — exported symbols added, removed, or renamed since the baseline. NOT TO USE: For listing current exports without a diff baseline (use gograph_public or gograph_skeleton instead). RETURNS: JSON with added[], removed[], and changed[] arrays of exported symbol names since the baseline ref; empty arrays indicate no API drift.

Find functions and methods with more parameters than a threshold — the long-parameter-list smell. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. min sets the minimum argument count to flag (default: 5). WHEN TO USE: During code smell audits to identify candidates for parameter-struct refactoring. NOT TO USE: For struct field counts (use gograph_fields or gograph_godobj). RETURNS: List of functions exceeding the threshold with parameter count, signature, and file location; empty when all functions are below the threshold.

Check whether actual package imports violate architecture constraints defined in a boundaries.json config file. Requires both .gograph/graph.json and a boundaries config (defaults to .gograph/boundaries.json — returns an error if the config file is missing). Read-only; no side effects. WHEN TO USE: In CI gates or post-edit reviews to enforce layer separation rules (e.g., handler packages must not import repository packages directly). NOT TO USE: For general dependency exploration without a constraint file (use gograph_deps or gograph_coupling instead). RETURNS: JSON with pass bool, violation_count, and a findings[] array listing each forbidden import edge; empty findings means all constraints are satisfied.

Find all functions and methods called from inside the specified function (one-hop fan-out). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When understanding what a function depends on — its downstream execution flow, external service calls, and library usage. NOT TO USE: For upstream callers (use gograph_callers); for transitive package dependency trees (use gograph_deps). RETURNS: List of callee symbols with package paths, file locations, and call-site line numbers; empty when the function makes no calls.

Find all functions and methods that directly call the specified function (one-hop fan-in). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before renaming, removing, or changing the signature of a function — see who calls it. NOT TO USE: For transitive upstream blast radius (use gograph_impact); for downstream callees (use gograph_callees). RETURNS: List of caller symbols with package paths, file locations, and call-site line numbers; empty when no callers found (function is a root or entry point).

List all available gograph MCP tools, their purposes, and recommended agent workflows. No prerequisites — this tool always works regardless of graph state. Read-only; no side effects, credentials, or network access. WHEN TO USE: Call once per session to orient before issuing analytical queries. NOT TO USE: Do not repeat after capabilities are cached in context. RETURNS: Structured JSON with all ~50 tool names, one-line purposes, recommended workflow sequences (before_edit, after_edit, etc.), and known static-analysis limitations.

List Go symbols that have been structurally modified, added, or deleted. Without git_ref, compares the working tree against the last graph build (uncommitted changes). With git_ref, performs a static symbol diff against the named git reference. git_ref is optional. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: After editing to confirm which symbols changed before running gograph_impact or gograph_review. NOT TO USE: For line-level text diffs (use git diff instead); for blast-radius analysis (use gograph_impact with since= instead). RETURNS: Changed symbol names, kinds, and package paths grouped by change type (added/modified/deleted); empty arrays when no structural changes are detected.

Run static policy checks against the repository graph. Checks include: boundaries (package layer violations), api_drift (breaking changes vs a baseline ref), max_arity (functions with too many args), max_complexity (cyclomatic complexity), test_coverage (symbols without tests), and no_orphans. Requires .gograph/graph.json. Read-only; no side effects. WHEN TO USE: During PR review to surface policy violations or as part of a pre-commit analysis workflow. NOT TO USE: For CI/CD enforcement with non-zero exit codes (use CLI gograph gate instead). RETURNS: Structured JSON with status (pass/warn/fail), findings array (level, check, message, location), and summary counts.

Report estimated cyclomatic complexity for Go functions, sorted highest-to-lowest with severity labels (LOW/MEDIUM/HIGH/VERY HIGH). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Optional symbol substring filters to a specific function or set of functions. WHEN TO USE: During code quality audits, identifying functions that need decomposition, or setting complexity budgets in CI. NOT TO USE: For import dependency metrics (use gograph_coupling or gograph_deps); for God Object detection (use gograph_godobj). RETURNS: Structured list of functions with complexity score and severity label; empty when no functions match the filter.

Find all concurrency primitives in the codebase: goroutine spawns (go statements), channel operations, sync.Mutex/RWMutex, sync.WaitGroup, sync.Once, and select statements. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Optional term filter (e.g., "mutex", "goroutine", "channel"). WHEN TO USE: When auditing race safety, understanding async flow, or locating all synchronization points before a concurrency refactor. NOT TO USE: For standard sequential call flow analysis (use gograph_callers/gograph_callees). RETURNS: File locations, line numbers, and primitive kind for each concurrency site; empty when no concurrency primitives are found.

Find all factory and constructor functions that instantiate and return a named Go struct (functions whose return type includes the struct name). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When looking for the canonical way to create a struct, or before modifying struct initialization to ensure all construction paths are updated. NOT TO USE: For direct composite-literal sites (use gograph_literals); for struct fields (use gograph_fields). RETURNS: List of constructor function names with signatures, package paths, and file locations; empty when no factory functions are found.

Fetch a pre-flight context bundle for a single Go symbol: AST node metadata, source code, direct callers, direct callees, linked test functions, and architectural role classification — all in one call. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Set uncommitted=true to bundle context for all currently modified symbols at once. WHEN TO USE: As the first call before editing a symbol — eliminates 4–5 separate tool roundtrips. NOT TO USE: For package-level orientation (use gograph_focus); for transitive blast radius (use gograph_impact). RETURNS: JSON with node, source, callers[], callees[], tests[], and role; empty object {} when symbol not found. With uncommitted=true, returns a contexts[] array; count:0 when no uncommitted symbols exist.

Report fan-in (Ca), fan-out (Ce), and instability ratio (I = Ce/(Ca+Ce)) per package. Instability range [0,1]: 0 = maximally stable, 1 = maximally unstable. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. package filters by name substring; include_stdlib adds stdlib (default false); internal_only restricts to this module's packages only. WHEN TO USE: When evaluating package isolation, planning architectural layering, or identifying packages that are too tightly coupled. NOT TO USE: For single-function complexity (use gograph_complexity or gograph_hotspot); for reverse package dependency lookup (use gograph_dependents). RETURNS: Array of package coupling records with Ca, Ce, and instability score; empty when no packages match the filter.

Find all packages that import the named package (inverse of gograph_deps). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before a package-level interface change or removal — see every dependent package that will be affected. NOT TO USE: For a single function's callers (use gograph_callers); for the package's own outgoing imports (use gograph_deps). RETURNS: List of dependent package names and paths; empty when nothing imports the package (it may be a top-level entry point).

List the import dependencies of a named package. With transitive=false (default), returns only direct imports. With transitive=true, returns the full BFS closure of all transitive imports. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When auditing package layering, understanding what a package pulls in, or mapping import chains before removing a dependency. NOT TO USE: For reverse lookup of who imports the package (use gograph_dependents); for symbol-level call tracing (use gograph_callers/gograph_impact). RETURNS: JSON with direct[] and transitive[] import path arrays; {"found":false} when the package is not in the graph.

Generate a Mermaid architecture diagram of the repository package dependency graph. Requires .gograph/graph.json. Read-only; no side effects. WHEN TO USE: Onboarding to an unfamiliar repository, architecture review, or communicating package structure. Use group_by=module for monorepos, group_by=file for deep drill-downs. NOT TO USE: For call-graph traversal (use gograph_callers/gograph_impact); for single-package focus (use gograph_focus or gograph_deps). RETURNS: Mermaid diagram text. Note: diagrams with >30 nodes may be hard to read; use max_depth=2 or a coarser group_by level.

Fetch the Go documentation (signature + doc comment) for any package, stdlib symbol, or third-party symbol by running go doc <query>. No graph build required — works without .gograph/graph.json. WHEN TO USE: When following a call chain into stdlib (fmt, net/http, io) or a third-party dependency (pgx, gin, zap) and you need the signature or method listing without reading source files. NOT TO USE: For project-internal symbols (use gograph_source or gograph_context instead — they return callers/callees too). RETURNS: The raw go doc output text including package declaration, function/type/method signature, and full doc comment; error message when the symbol is not found or go is not on PATH.

Find all Go structs that embed the named struct via anonymous field composition. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When understanding how a base type is extended throughout the codebase, or before modifying a shared embedded struct to estimate blast radius. NOT TO USE: For interface implementations (use gograph_implementers); for named field type references in other structs (use gograph_usages). RETURNS: List of embedding parent struct names with package paths and file locations; empty when the struct is embedded nowhere.

Build a full vertical slice for one HTTP route: the matched handler symbol, a BFS call chain downstream (default depth 5), all SQL queries emitted in that chain, and all env vars read. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. LIMITATION: Nested route-group prefixes (e.g. Gin/Echo/Chi Group()) are lost at the static AST level. Always query by the final route path suffix or, ideally, by the handler function symbol name (e.g., 'CreateUser'). WHEN TO USE: When auditing what an API endpoint does end-to-end — its downstream dependencies, database queries, and configuration reads. NOT TO USE: For listing all routes (use gograph_routes first to find the pattern); for raw handler source code only (use gograph_source). RETURNS: Array of endpoint slices with route, handler, call chain, SQL, and env fields; found:false with a suggestion when the query does not match any route. query accepts route pattern ("POST /api/users"), path fragment ("/users"), or handler name. depth controls call-chain BFS depth (default: 5).

Find all environment variable reads in the codebase via os.Getenv, os.LookupEnv, and common config frameworks, with their enclosing function context. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Optional term filters by key name substring (e.g., "DATABASE" matches DATABASE_URL and DATABASE_HOST). WHEN TO USE: When compiling a deployment configuration manifest, documenting required env vars, or auditing what secrets a service reads at startup. NOT TO USE: For reading actual runtime env values (this is static analysis); for database queries (use gograph_sql). RETURNS: List of env key names, calling function, and file/line; empty when no env reads match the filter.

Trace how a named error sentinel or error message string is defined, returned, and propagates up the call graph toward HTTP handlers or CLI entry points. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Accepts either query (preferred) or term as the error name or message substring. WHEN TO USE: When auditing how a specific error is produced and handled end-to-end — find definition sites, all return sites, and upstream propagation paths (e.g., ErrNotFound). NOT TO USE: For general upstream traversal of any function (use gograph_callers or gograph_impact); for listing all error definitions (use gograph_errors). RETURNS: Definition sites, return sites, propagation path chains, and related test names; paths is empty when no propagation chain is found. Note: heuristic analysis — does not perform SSA or full data-flow tracking.

Find all error creation sites in the codebase: errors.New, fmt.Errorf, and sentinel var declarations. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Optional term filters by error message substring (e.g., "ErrInvalid", "unauthorized"). WHEN TO USE: When cataloging error codes, standardizing error messages, or checking whether a specific error string is already defined before adding a new one. NOT TO USE: For tracing how an error propagates up the call stack (use gograph_errorflow instead). RETURNS: List of error creation sites with message text, file path, and line number; empty when no matches found.

Generate a synthesized, LLM-ready narrative for a Go symbol: role classification, callers, callees, complexity, SQL, env vars, HTTP routes, concurrency primitives, tests, and interface satisfaction — all in one structured document. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: For onboarding to an unfamiliar symbol, generating PR documentation, or getting an opinionated architectural assessment without issuing multiple tool calls. NOT TO USE: For raw source code (use gograph_source); for targeted blast-radius analysis (use gograph_impact). RETURNS: Rich structured JSON with role, narrative summary, and all associated cross-references; {"found":false} when symbol is not in the graph.

Extract all declared fields from a named Go struct: field names, Go types, and raw struct tag strings (json, db, yaml, gorm, etc.). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When mapping JSON/DB serialization tags, inspecting struct layouts, or enumerating fields before adding a new one. NOT TO USE: For methods on the struct (use gograph_node or gograph_source); for all struct initialization sites (use gograph_literals). RETURNS: Array of field entries with name, type, and tag string; empty when the struct is not found.

Find test helper structs and factory/builder functions declared in *_test.go files for a named package. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before writing new tests — check what test infrastructure (helper builders, stub factories, shared setup structs) already exists in the package to avoid duplication. NOT TO USE: For test functions that exercise a symbol (use gograph_tests); for external test data files on disk (those are not tracked in the graph — use filesystem search). RETURNS: Symbols defined in test files for the package including helper structs and factory functions; empty when the package has no test helper infrastructure.

Extract a comprehensive structural summary of one Go package: all files, defined symbols, internal call edges, and package-level imports. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When orienting to an unfamiliar package before editing it — provides a full map of what the package contains and how it connects to the rest of the codebase. NOT TO USE: For a single symbol's details (use gograph_context or gograph_source); for global keyword searches (use gograph_query). RETURNS: All files, symbol names, call edges, and import paths within the package; empty when the package is not found.

Find package-level variable declarations (var blocks) and the functions that mutate them in a specific package. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When auditing mutable global state, identifying thread-safety hazards, or locating shared singleton variables before a concurrency refactor. NOT TO USE: For local-scope variables; for environment variable reads (use gograph_envs). RETURNS: Package-level variable names, types, and the functions that write to them; empty when the package has no package-level variables.

Detect God Object anti-pattern candidates by scoring structs on method count, field count, and outgoing call count. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Thresholds: methods (default: 5), fields (default: 8), calls (default: 15); top limits results (default: 10). A struct must exceed all three thresholds to be flagged. WHEN TO USE: During architecture reviews to find monolithic structs that should be decomposed. NOT TO USE: For general struct layout inspection (use gograph_fields); for single-function complexity (use gograph_complexity). RETURNS: Ranked list of candidates with method, field, and call counts; empty when no structs exceed all thresholds.

Rank functions by incoming call count (fan-in) to identify the most-depended-on symbols in the codebase. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. top controls result count (default: 10; 0 = all). Set include_tests=true to count test-file call edges — by default excluded so test helpers don't dominate rankings in test-heavy codebases. WHEN TO USE: When deciding where to invest refactoring effort or documentation — high fan-in functions are the highest-risk change targets. NOT TO USE: For single-package metrics (use gograph_focus or gograph_coupling); for complexity scores (use gograph_complexity). RETURNS: Ranked list of function names with fan-in count and package location.

Traverse the call graph backwards to find every symbol that transitively calls the target — the full upstream blast radius of a change. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Three modes: (1) single symbol via symbol; (2) uncommitted-changes blast radius via uncommitted=true; (3) git-ref changes blast radius via since. WHEN TO USE: Before refactoring a core function to see what breaks; use uncommitted=true after editing to verify scope. NOT TO USE: For direct one-hop callers only (use gograph_callers instead). RETURNS: Transitive list of upstream affected symbols; JSON with count:0 message when no symbols are modified or no callers found.

Find all concrete structs that implement a named Go interface via duck-typing (structs whose method set is a superset of the interface's methods). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Set test_only=true to restrict to structs in *_test.go files (mocks/stubs). WHEN TO USE: When tracing polymorphism, locating dependency injection points, or finding all mock implementations of an interface. NOT TO USE: For interfaces a struct satisfies — inverse direction (use gograph_interfaces instead); for struct fields (use gograph_fields). RETURNS: List of implementing struct names with package paths and file locations; empty when no struct implements the interface.

Find all files and packages in the codebase that import a specific package by its exact import path. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When isolating usage of a third-party library before removing or replacing it, or tracing where an internal package is consumed from outside. NOT TO USE: For a package's own outgoing imports (use gograph_deps); for reverse package-level dependency lookup by short name (use gograph_dependents). RETURNS: File paths and package names of all importers; empty when the package is imported nowhere.

Find all Go interfaces satisfied by a named concrete struct (duck-typing resolution — inverse of gograph_implementers). Given a struct name, returns every interface whose complete method set is a subset of that struct's methods. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When you need to know which contracts a struct implicitly fulfills — useful before refactoring a method to understand which interface contracts will break. NOT TO USE: For finding structs that implement an interface (use gograph_implementers); for listing interface declarations in a package (use gograph_node or gograph_public). RETURNS: Interface names, method signatures, and file locations; empty when the struct satisfies no known interfaces.

Find every composite-literal initialization site for a named Go struct — all locations where Foo{...} syntax is used to construct the struct. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before adding a required field to a struct — every site returned will fail to compile if the new field has no default; run this first to scope the migration blast radius. NOT TO USE: For finding string or integer magic values (use gograph_envs or grep for those); for factory functions that return the struct (use gograph_constructors). RETURNS: All file paths and line numbers where the named struct is composite-initialized; empty when the struct has no direct initialization sites.

Find structs in *_test.go files that implement a named interface — test doubles, mocks, and stubs. Equivalent to gograph_implementers with test_only=true; kept for compatibility. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When writing tests and wanting to find existing mock implementations before creating a new one. NOT TO USE: For production interface implementers (use gograph_implementers without test_only); prefer gograph_implementers(test_only=true) for new code. RETURNS: Test-file struct names implementing the interface with file locations; empty when no test mocks exist for the interface.

Find all assignment sites where a named struct field is written to anywhere in the codebase. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When diagnosing unexpected state changes, auditing field mutability, or finding all places that set a specific field before adding a validation rule. NOT TO USE: For reading field declarations (use gograph_fields); for whole-struct initialization sites (use gograph_literals). RETURNS: File paths and line numbers where the named field is assigned; empty when the field is never written to outside its struct initializers.

Fetch AST metadata for a named symbol, package, or file: kind, file path, line number, full signature, doc comment, and struct fields if applicable. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When you need structural metadata (kind, signature, line number) without the full source body — lighter than gograph_source for metadata-only lookups. NOT TO USE: For full source code (use gograph_source); for call relationships (use gograph_callers/gograph_callees). RETURNS: Node properties array with kind, file, line, and signature; empty when the name is not found.

Find all functions and methods unreachable from any entry point (main functions, exported symbols, HTTP route handlers) using full BFS reachability analysis. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: During code cleanup passes or dead-code audits to identify symbols safe to delete. NOT TO USE: For checking specific symbol usages (use gograph_usages or gograph_callers instead). RETURNS: List of orphan symbols with their package paths and file locations; empty list means no dead code detected.

Find the shortest call chain between two symbols — BFS from from to to through the call graph. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When confirming whether a handler can reach a utility function, debugging surprising call chains, or tracing execution flow between two non-adjacent symbols. NOT TO USE: For direct callers only (use gograph_callers); for all transitive upstream callers (use gograph_impact). RETURNS: JSON with from, to, found bool, and steps[] containing the symbol chain; found:false when no call path exists between the two symbols.

Generate a structured pre-edit plan for a target symbol: which symbols to read first, which tests cover them, which routes and env vars they touch, and whether the change is public-API or SQL-touching. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Set with_context=true to inline full source+callers+callees for each symbol to inspect — eliminates follow-up gograph_context calls. WHEN TO USE: Before multi-file refactoring or architectural changes to understand scope upfront. NOT TO USE: For trivial single-line fixes; for post-edit verification (use gograph_review instead). RETURNS: JSON with inspect_first[], tests[], routes[], env[], and a risk object (public_api, touches_sql, etc.); with with_context=true, also includes inspect_contexts[] with full per-symbol bundles.

List all exported (public) symbols of a specific package: functions, types, interfaces, and variables. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When reviewing a package's public contract before changing it, building integration documentation, or checking what a package exposes to callers. NOT TO USE: For unexported/private symbols (use gograph_node or gograph_focus); for API drift detection against a baseline (use gograph_api). RETURNS: List of exported symbol names with kinds and file locations; empty when the package has no exports or is not found.

Search the graph index for symbols, packages, files, and import edges that match a keyword substring. Requires .gograph/graph.json — run gograph build . first if stale (check with gograph_stale). Read-only; no side effects. WHEN TO USE: During initial exploration when you have a keyword or feature name but don't know which files or packages contain it. NOT TO USE: When you already know the exact symbol name (use gograph_source or gograph_node instead); for package dependency trees (use gograph_deps). RETURNS: List of matching symbols, files, and imports with their kind, package path, and line number; empty when no matches found.

Show how each caller uses the return value(s) of a named function: discarded, assigned, partially ignored, returned upstream, or passed directly to another call. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before changing a function's return signature — see which callers ignore the error or only use some return values. NOT TO USE: For error propagation tracing (use gograph_errorflow); for finding all callers without usage detail (use gograph_callers). RETURNS: List of call sites with usage classification (discarded/assigned/partially_ignored/returned/passed); empty when the function has no callers.

Summarize the scope and risk profile of a change: which symbols changed, which tests cover them, which routes and env vars they touch, and whether SQL is involved. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Requires either symbol or uncommitted=true. WHEN TO USE: After editing — as a post-edit verification step before committing; confirms the blast radius matches expectations. Use uncommitted=true to review all current unstaged changes at once. NOT TO USE: For boundary constraint enforcement (use gograph_boundaries); for pre-edit planning (use gograph_plan). RETURNS: JSON with changed_symbols[], tests[], routes[], env[], errors[], and a risk object (public_api, touches_sql, touches_routes, touches_env).

List all HTTP routes registered in the codebase with their HTTP methods, URL patterns, and handler function names. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. LIMITATION: Nested route-group prefixes (e.g. Gin/Echo/Chi Group()) are lost at the static AST level. Routes are recorded under their final path suffix (e.g., '/users' instead of '/api/v1/users'). WHEN TO USE: To get the complete API surface of a service before deep-diving into a specific route with gograph_endpoint. NOT TO USE: For full call chain analysis of a route (use gograph_endpoint instead). RETURNS: Structured table of method/path/handler triples; empty when no HTTP routes are registered in the graph.

Find Go structs that declare a mapping to a specific database table via struct tags (e.g., db:"table_name", gorm:"table:table_name"). Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When tracing which Go types represent a database table, or before writing a migration to understand the current ORM model. NOT TO USE: For non-tagged Go structs used as query results (use gograph_fields or gograph_query instead). RETURNS: Matching struct names with package paths and file locations; empty when no structs map to the named table.

Review and grade agent compliance (Plan rule, Review rule, Composability/Efficiency) and tool success rates. No prerequisites. WHEN TO USE: After ending a session to obtain compliance metrics and recommendations. RETURNS: Audited session details and grade.

Delete all stale inactive session telemetry JSONL logs. If no session is active, it deletes all logs. No prerequisites. WHEN TO USE: Call after auditing to keep the repository clean. RETURNS: Number of deleted session files.

Start a telemetry audit session for tracking agent compliance and tool success metrics. No prerequisites. WHEN TO USE: Call once at the start of a multi-step coding task to track your work. NOT TO USE: When a session is already active. RETURNS: Structured message with the newly generated session ID.

End the active telemetry session cleanly and write end-of-session logs. No prerequisites. WHEN TO USE: Call once after you have completed all edits and post-edit reviews. NOT TO USE: When no session is active. RETURNS: Message confirming ending of the session.

Emit the full repository's API signatures with function bodies stripped — struct definitions, interface declarations, and function/method signatures only. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WARNING: output can be very large on big repositories — consider using gograph_public per package for targeted queries. WHEN TO USE: When an LLM needs a compact map of the entire codebase's shape without reading source files individually. NOT TO USE: For full implementations (use gograph_source); for a single package (use gograph_public). RETURNS: Multi-line text of all stripped declarations across all packages; always non-empty when the graph has symbols.

Retrieve the verbatim Go source code for a named function, method, struct, or interface, including its complete body. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: When you need to read a specific implementation in full without loading a large file — a targeted alternative to reading the whole file. NOT TO USE: For call hierarchy information (use gograph_callers/gograph_callees); for AST metadata without the full body (use gograph_node). RETURNS: Raw Go source block with file path and line numbers; returns an error when the symbol is not found or the source file cannot be read.

Find all SQL query literals embedded in Go source code, with their enclosing function context and file/line locations. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. Optional term filters by SQL keyword or table name (e.g., "SELECT", "users"). WHEN TO USE: When auditing database interactions, reviewing queries for performance issues, or locating all queries that touch a specific table. NOT TO USE: For ORM struct-to-table mappings (use gograph_schema); for env-based configuration (use gograph_envs). RETURNS: List of SQL string literals with file, line, and enclosing function name; empty when no matches found.

Check whether .gograph/graph.json is outdated relative to the current Go source files — stale:true if any .go file in the working tree is newer than the graph index. Requires .gograph/graph.json to exist. Read-only; no side effects. WHEN TO USE: As a pre-flight check before any structural analysis — a stale graph may cause missed symbols or stale call edges. If stale, run gograph build . before proceeding. NOT TO USE: For Go module dependency freshness (go list -m all covers that); for finding which symbols changed (use gograph_changes). RETURNS: JSON with stale bool, graph_mtime, newest_source_mtime, and a list of source files newer than the graph; {"stale":false} when the graph is current.

Generate repository-level code statistics: total package count, file count, symbol frequencies (functions, structs, interfaces), and import edge count. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: For high-level codebase health dashboards, validating the graph was built completely, or getting a quick size estimate before planning analysis. NOT TO USE: For single-symbol profiling (use gograph_node or gograph_complexity); for detailed per-package breakdown (use gograph_focus per package). RETURNS: JSON with total counts for files, packages, functions, structs, interfaces, and import edges.

Single-call codebase briefing: top 3 hotspots (most-called symbols), worst instability package, highest cyclomatic complexity function, total orphan count, and god-object count. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: At the very start of any session — replaces running gograph_hotspot + gograph_coupling + gograph_orphans + gograph_complexity + gograph_godobj separately (5 calls → 1). NOT TO USE: For detailed drill-down into a specific metric (use the dedicated tool after reviewing summary). RETURNS: JSON with symbols, packages, hotspots[], worst_instability, top_complexity, orphan_count, and god_object_count.

Find test functions in *_test.go files that exercise a named symbol, or list all test edges in the graph when no symbol is given. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before editing a function — check what tests cover it so you know what to run; or to audit test coverage gaps across the codebase. NOT TO USE: For test helper infrastructure (use gograph_fixtures); for running the tests (use go test directly). RETURNS: Test function names, target packages, and file locations; returns all test edges when symbol is omitted; empty when no tests reference the symbol.

Alias for gograph_errorflow. Traces an error string heuristically from its definition up through the call chain to HTTP handlers. Requires .gograph/graph.json. Read-only; no side effects. WHEN TO USE: Use gograph_errorflow instead -- this alias exists purely for backward compatibility. RETURNS: Same structured output as gograph_errorflow.

Sweep the full graph in one pass and return all production functions and methods that have at least one non-test caller but zero attributed test edges. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: During test coverage audits or pre-release hardening — finds the functions most at risk of regressions (high callers, no tests). Distinct from gograph_orphans (zero callers) — untested symbols ARE used in production but lack test coverage. Replaces N sequential gograph_tests <sym> calls across the full codebase. NOT TO USE: For a single symbol's tests (use gograph_tests); for unreachable dead code (use gograph_orphans). RETURNS: JSON array sorted by caller_count descending, each entry with name, kind, file, line, caller_count, and package; empty array when all called symbols have test coverage.

Find every place a named Go type appears in function parameter lists, return type signatures, and struct field type declarations. Requires .gograph/graph.json — run gograph build . first. Read-only; no side effects. WHEN TO USE: Before changing an interface or type definition — see the full consumption blast radius across all signatures and struct fields. NOT TO USE: For call sites of a function (use gograph_callers); for struct composite-literal initialization sites (use gograph_literals); for all transitive callers (use gograph_impact). RETURNS: File paths and line locations where the type name appears in signatures or struct fields; empty when the type is not referenced.

Generate the llm-wiki/ directory of machine-first markdown pages from the static graph. Pages produced: overview.md, architecture.md, hotspots.md, routes.md, env.md, errors.md, concurrency.md, api-surface.md, and one packages/.md per internal package. Requires .gograph/graph.json — run gograph build . first. Writes files to disk; all other gograph tools are read-only. WHEN TO USE: At the start of an agent session on an unfamiliar codebase — run once to get a token-efficient orientation without issuing dozens of individual tool calls. NOT TO USE: For targeted symbol lookups (use gograph_context or gograph_source). RETURNS: JSON manifest of written page filenames and a count; error when the graph cannot be loaded or the output directory cannot be created.