Create a new virtual planning workspace. Use this tool first when starting any multi-file feature or refactoring task, before calling add_planned_symbol or validate_plan. Do not use this tool if a plan already exists for your current task. This is a mutating operation that initializes an empty Virtual AST associated with the provided plan_id. The workspace is stored in the server's graph state and persisted to disk immediately, so it remains available for the duration of the server session. If the plan_id already exists, this operation is idempotent and returns the existing workspace. Returns the initialized workspace ID on success.

Verify a change in one unified report. Returns the scope creep audit, blast radius, verification checklist, and must-read files for the supplied target symbols. When plan_id is set it also returns the plan details and post-edit compliance audit. Optional snapshot or graph path inputs add what-changed and graph-diff sections.

Apply a manual mutation to the relational index in one call. Use action='add_node' to register a concept or rationale node, action='add_edge' to record a verified relationship, action='remove_edge' to delete a stale or false-positive edge, or action='recluster' to re-run community detection. Successful mutations persist to disk immediately.

Query the relational index with keywords to find relevant nodes and explore their topology. Use this read-only tool for initial discovery when you do not yet know the exact node IDs. If you already know the target ID, use inspect_symbol instead. To trace deep multi-hop paths, use trace_path instead. The query mechanism scores nodes by keyword match and traverses their neighborhood (BFS by default, or DFS if dfs=true). Results are rendered as a structured Markdown report. To prevent context bloat, the output is strictly truncated to fit within the provided budget (default 2000).

Return a repository-level architecture summary with communities, cross-community connectors, and architectural hotspots. Set community_id to focus on one community instead of the overview, include_community_members to append its full member list, and include_god_nodes to append the most highly connected hub nodes.

Inspect a symbol and retrieve its structural neighborhood and metrics. Use this read-only tool as your primary orientation step before modifying a specific class, function, or module. Use this instead of query_graph when you already know the exact target ID and need its direct callers, neighbors, or a verification plan. The baseline response returns canonical node details. Use the boolean flags to append optional data blocks (for example, include_callers=true appends all incoming dependencies). Setting multiple flags to true (such as include_analysis and include_file_summary) can produce large responses; use only the flags needed for your immediate task to conserve context budget.

Reload the relational index from a graph.json file without restarting the MCP server. If no path is given, reloads from the path the server was launched with. Use this to point a running server at a different repository's graph, or to pick up changes after re-running gm run.

Return graph metadata, health, and diagnostics in one call. Always returns project root, schema version, build time, extraction modes, languages, node/edge/hyperedge/community counts, active policy gates, and the graph trust mode. Set include_stats to append scoped statistics, include_unresolved to list unresolved imports, include_resolution to append the resolution-quality report, and include_ambiguous to list ambiguous edges and label collisions.

Trace connectivity and multi-hop paths across the codebase architecture. Use this read-only tool to map blast radius, find shortest paths, or verify transitive layering. Use this instead of query_graph or inspect_symbol when you need to prove deep, multi-hop relationships between specific components. The tool operates in five distinct modes: shortest (finds semantic or strict AST paths between source and target), safest (finds the path with highest aggregate confidence), transitive_forward (downstream reachability), transitive_reverse (upstream callers), and module_dependencies (cross-module edges). Returns a structured Markdown report detailing the traced paths, confidence scores, and edge relations. Traversal halts when depth is reached, and output is truncated to fit the budget.

Validate a planning workspace before writing code. Always runs the Louvain modularity delta gate and surprise analysis. Unless skip_policy_rules is true, it also applies explicit .graphenium/policy.json rules when present.

Run a logic query over the codebase graph. Standard library predicates are pre-loaded (do not redefine them):

• calls_transitive(X, Y) : X transitively calls Y

• imports_transitive(X, Y) : X transitively imports Y

• depends_transitive(X, Y) : X transitively depends on Y

• same_community(X, Y) : X and Y are in the same Louvain cluster

• is_hub(X) : X has > 15 connections

• is_orphan(X) : X has no incoming/outgoing edges

• circular_dependency(X, Y) : X and Y call each other

• bypasses_layer(X, Y, Z) : X depends on Z, bypassing intermediary Y Base EDB relations: node, calls, imports, contains, inherits, implements, degree, edge. Supports user rules (:-), goals (?-), facts, and negation (not). Budget-bounded (max 10,000 steps).

Register an intended new or modified symbol and its dependency edges in a virtual planning workspace. Use this tool to declare your architectural design before writing code. Do NOT use mutate_graph (which modifies the physical index) for planned changes. Prerequisites: You must first call create_planning_workspace to obtain a valid plan_id. Side effects: This is an in-memory mutation that adds a virtual node to the specified workspace. It automatically runs pre-flight policy checks; if the proposed symbol or its dependencies violate .graphenium/policy.json rules (for example, forbidden dependencies), the tool returns a PRE_FLIGHT_VIOLATION error and blocks the registration. If the target_symbol does not exist, the tool returns an error and records nothing. Duplicate calls for the same symbol are idempotent. Returns a success confirmation or a structural violation error.