Default Synapse entry point for codebase questions, deletion-safety checks, edits, reviews, debugging, test discovery, repository administration, and capability discovery. It routes natural-language objectives through the existing granular tools while preserving their entitlement, readiness, validation, and mutation-safety checks. Pass top-level repo_id and path to scope repository work, and pass exact identifiers in inputs when prose might be ambiguous.

REPLACES: manual Synapse tool and action selection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Use first for ordinary Synapse requests.

Usage (long): Describe the objective in query and provide concrete identifiers or mutation payloads separately. Prefer top-level repo_id and path for scope; context.repo_path and context.target_file are accepted compatibility aliases. For deletion-safety wording such as 'can I delete X?' or 'is X still used?', provide inputs.chunk_id when available, otherwise repo_id plus an exact arity-qualified inputs.symbol so ask_synapse can route to synapse_codebase_insights/dead_code; descriptive prose without one exact target must ask for clarification instead of guessing. Inspect completion_state, agent_instruction, and follow only the returned safe next_tool_calls guidance when the response is incomplete.

Return a structured manifest describing SynapseMCP's live tool surface, including schemas, mutation characteristics, static safety classification, and tool relationships.

REPLACES: reading MCP tool schemas manually, trial-and-error tool discovery. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Returns a structured manifest of live Synapse MCP tool capabilities.

Usage (long): Use this to discover tool schemas, mutation characteristics, and capability relationships. Includes quick_start onboarding steps and readiness_routing to understand which tools work at each indexing phase.

Analyses and reviews proposed changes (via diff, commit range, chunk list, or file list). High-level actions include:

• 'analyse_diff': parses and orientates a change set quickly (modified symbols, must-read files, tests to run, contract signals).

• 'review_diff': performs a detailed safety and risk review of proposed edits, highlighting blind spots and state/event contract changes.

• 'impact': evaluates blast radius, downstream callers, and change risk.

REPLACES: git diff, manual diff review, grep_search for impact analysis. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Analyse diffs, review change risks, and evaluate downstream impact.

Usage (long): Inspect commit/branch diffs, review code changes for structural risks, or calculate blast radius impact before refactoring. Use after making changes to verify safety, or before merging to assess risk.

Analyses codebase structures, API boundaries, contracts, dependencies, and deletion safety. High-level actions include:

• 'detect': returns percentage language and framework breakdown, file count, and recommended linter audits.

• 'public_api': lists public modules and functions, helper heuristics, and external callers count.

• 'dead_code': performs a read-only function-level deletion-safety check for one exact symbol or chunk_id. Prefer chunk_id from a previous Synapse result; otherwise pass repo_id plus an arity-qualified symbol such as Parser.parse/2. It reports whether the symbol appears dead, splits production and test callers, explains confidence and deletion risk, marks clause-level analysis as unsupported, and tells the agent what to do next without deleting source.

• 'contracts': scans interface boundaries (JSON/HTTP/CLI) and outward-facing schemas.

• 'dependencies': builds an inter-module dependency graph.

• 'overview': returns a consolidated repository overview.

• 'refactor_opportunities': surfaces code quality improvement candidates.

REPLACES: grep_search for API surface discovery, wc for codebase sizing, manual language detection, find for framework detection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Detect languages, identify public APIs, check deletion safety, build dependency graphs, and surface refactoring opportunities.

Usage (long): Analyze language mix, list public API surfaces, run function-level deletion-safety checks by chunk_id or repo_id + symbol, scan interface boundaries (JSON/HTTP/CLI), build dependency graphs, surface refactoring opportunities, or retrieve a consolidated repository overview. Use 'dead_code' as the backend for ask_synapse questions like 'can I delete X?', 'is X still used?', or 'should I keep X?'. Provide chunk_id, or repo_id plus one exact symbol; bare function names are resolved only when one arity variant is indexed. If the user only gives descriptive prose, ask for the concrete symbol rather than guessing. Read scope, clause_level_analysis, safe_to_delete, deletion_risk, confidence, caveats, and supporting_evidence.production_callers/test_callers before advising. Use 'detect' to understand the language mix before choosing search modes.

Traces code paths or resolves error stack traces to understand execution flow and debug issues. High-level actions include:

• 'trace_behaviour': maps the execution flow of a function (branching, state access, side effects, tests).

• 'resolve_stack': parses a runtime crash stack trace and matches frames to repository chunks, root cause, and tests.

REPLACES: manual stack trace reading, grep_search for error origins, sequential file reads to trace execution. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Trace ranked execution paths and map crash stack traces to code chunks. Maps stack traces to chunks.

Usage (long): Trace execution flow (branching, state access, side effects) or resolve runtime stack traces to locate crash-site causes and tests. Use 'trace_behaviour' to understand how a function works without running it. Use 'resolve_stack' to map crash stack traces to indexed code chunks with root cause analysis.

Explores structural relationships within the codebase graph. High-level actions include:

• 'callers': finds all chunks that call a given chunk, with transitive depth support (1–3).

• 'callees': finds all functions, modules, or types that a chunk calls or depends on, with transitive depth support (1–3).

• 'context': retrieves rich structural context (callers, callees, related chunks) around a specific chunk.

• 'cycles': detects circular dependencies reachable from a given chunk. All four actions accept chunk_id OR (repo_id + symbol) OR (repo_id + file_path + optional line) — no separate lookup needed.

REPLACES: grep_search for caller discovery, manual import tracing, find_references, caller guessing. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Explore caller-callee dependency relationships and semantic context in the code graph. Pass symbol + repo_id directly — no separate lookup needed.

Usage (long): Trace incoming callers, downstream callees, detect cycles, or retrieve immediate neighbours/references for a code chunk. ALL four actions (callers, callees, context, cycles) accept:

1. chunk_id (direct) — fastest, use when already known.

2. repo_id + symbol — resolves the symbol and runs in one call.

3. repo_id + file_path (+ optional line) — resolves by file position. Token-saving: both callers and callees support depth 1–3. Use depth: 2+ to get multi-hop results in a SINGLE call instead of chaining multiple depth-1 calls. One-call examples: callers: {action: 'callers', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn', depth: 2} callees: {action: 'callees', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn', depth: 2} cycles: {action: 'cycles', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn'} Replaces manual import/caller guessing. Returns transitive callers/callees with depth control. Compression is on by default — graph results can be large.

Retrieves rich context about the codebase for understanding, editing, explaining, or onboarding. Pass the exact repo_id to keep results focused on the intended repository, especially when multiple repositories are registered; if repo_id is unknown, call synapse_manage_repos with action 'list'. High-level actions include:

• 'find': runs semantic search, exact symbol lookup, fuzzy matching, and call-graph traversal to locate relevant chunks. Without repo_id, it returns at most 5 high-confidence matches.

• 'edit': gathers callers, callees, related tests, risk assessment, and behaviour boundaries before editing a chunk.

• 'explain': produces a layered explanation of a chunk.

• 'onboard': builds a subsystem reading order and learning path.

REPLACES: multi-file grep_search chains, sequential view_file reads, manual code comprehension. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Retrieve codebase context, explain chunks, build onboarding reading orders, or prepare pre-edit safety packs. Pass the exact repo_id to keep results focused on the intended repository. For the freshest just-edited path, use action 'edit' (analogous to current symbol lookup and graph context workflows).

Usage (long): Prepare context before edit, retrieve layered explanations, locate files/chunks for a feature, or construct reading paths. Pass the exact repo_id to keep results focused on the intended repository. If repo_id is unknown, call synapse_manage_repos with action 'list' and copy it verbatim. Without repo_id, action 'find' returns at most 5 high-confidence matches and reports meta.unscoped_retrieval. Action 'edit' is the essential pre-edit step — always call it before modifying code. It gathers callers, callees, tests, and risk in one call.

Controls and inspects the indexing pipeline and server health. High-level actions include:

• 'health': cheap health probe for transport and runtime readiness. Call this first before anything else — one call tells you the server is alive and which tools are loaded.

• 'status': returns per-repository indexing phase progress, ETS chunk counts, embedding readiness, unresolved edge counts, and top summary candidates. Pass repo_id for a fast direct lookup of one repository; omit it to see all repositories at once. Status responses are cached for 60 seconds when all indexers are idle (5/10 s during active indexing) — this prevents 50-repo installations from timing out.

• 'trigger': triggers a re-index of a repository or a specific file/directory.

REPLACES: manual health probing, process monitoring, ad-hoc tool listing. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Confirms the server is alive and reports indexing progress per repository. Monitor indexing progress, health state, and trigger indexing manually. Always pass repo_id to status for a fast scoped lookup; omit it only when you need all repos.

Usage (long): Call 'health' first to confirm the server is running, then 'status' with a repo_id to check whether that repository is ready for search. The status response includes:

• repos[]: one entry per matching repository, each with phase progress, chunk_count, indexed_files, embeddings_partial, repo_unresolved_edges (edges whose target chunk has not yet been indexed), and needs_summary (top chunks that have been queried but lack a cached summary, ranked by hit_count — use these as summarisation targets).

• unresolved_edges: global total across all repos (useful for cross-repo health checks).

• repo_id scoping: passing repo_id performs a direct SQLite lookup rather than scanning all registered repositories, making it safe to call at 50+ repo scale.

• readiness_guide: shows which tool actions work at the current indexing phase.

• include_profile: true adds language/kind chunk distribution breakdown (slower).

Inspects files in the workspace. High-level actions include:

• 'read_files': reads one or more files from disk with line numbers, byte sizes, and metadata (supports directories too).

• 'read_chunk': reads the full raw source of a specific code chunk from the in-memory store (no disk access).

• 'count_lines': counts total lines across workspace files.

REPLACES: view_file, read_file, cat, wc, list_dir for file inspection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Read files, chunks, or count lines in the workspace.

Usage (long): Inspect multiple source files with line numbers, retrieve raw chunk code, or perform line counts across files. Supports format: 'outline' to compress function bodies during retrieval, saving context tokens — use this when scanning many files. Compression is on by default — pass compress_payload: false to opt out for debugging.

Manages persistence, feedback loops, and learning metadata within the codebase graph. High-level actions include:

• 'learn': records explicit query-to-chunk relevance; repeated evidence promotes cache hits.

• 'save_summary': persists single or batch plain-English annotations on code chunks.

• 'suggest': lists high-value chunks needing summary based on access history and traffic weight.

• 'query': searches cached summaries, identifiers, and exact learned associations to recall established patterns.

REPLACES: repeated searches for the same patterns, manual note-taking, re-discovering code paths. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Record search feedback signals, save chunk summaries, suggest docs tasks, and query cached patterns.

Usage (long): Save feedback signals to cache search queries, write natural language summaries for chunks, suggest highest priority needs_summary targets, and query established patterns.

Call 'learn' after useful search results to record explicit query-to-chunk relevance; a single learn signal is queryable immediately but remains provisional until repeated evidence promotes it. Call 'save_summary' to permanently annotate chunks with natural language descriptions. Call 'query' with natural language, filenames, symbols, or chunk IDs to retrieve matching summarized chunks and exact learned associations.

Manages repository registrations. High-level actions include:

• 'list': lists all configured repositories and their index state. Each row includes suggested_actions with ready-to-fire tool calls.

• 'register': registers a new workspace for watching and indexing. Git worktrees are transparently auto-detected.

• 'archive': marks a registered workspace as archived, stops its indexer, and keeps existing graph data searchable.

• 'restore': marks an archived workspace active again and restarts indexing.

• 'keep': dismisses a dirty-merged worktree advisory for the current session (signals that uncommitted changes are intentional).

• 'unregister': permanently removes a repository from the registry and graph store.

• 'update_excludes': updates the set of excluded paths for a repository. Clean Git worktrees whose branch work is already merged are auto-archived conservatively before indexing work is scheduled.

REPLACES: ls, find for workspace discovery, manual git worktree management. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Manage repository registrations, lifecycle, exclusions, and workspace lists.

Usage (long): Use to register new repositories, list registered repositories, manage active/archived lifecycle state, update exclude paths, or unregister repositories.

KEY WORKFLOW — always read suggested_actions first: Each 'list' row (both scoped and unscoped) contains a suggested_actions field with structured objects {label, tool, args}. These are ready-to-fire tool calls — pick the appropriate one and call it directly without reformatting.

DIRTY-MERGED WORKTREE ADVISORY: When a worktree branch is merged but has uncommitted changes, the row will contain dirty_merged_worktree: true and 3 suggested_actions:

1. archive — keep graph searchable, stop indexing

2. unregister — delete graph data permanently

3. keep — changes are intentional, dismiss advisory for this session Call one of these immediately with just repo_id + action.

LIFECYCLE RULES: Use 'archive' for stale or merged worktrees; use 'restore' to reactivate indexing; use 'unregister' only for destructive removal; use 'keep' when changes are intentional.

When registering, you MUST provide an absolute path for root (e.g. /Users/name/repo). Do not use . or relative paths. Always call 'list' first if unsure of the repo_id.

Modifies files in the workspace. For safe agent workflows, first call 'write_safely' with dry_run: true, pre_check: true, and lint: true; review the preview, then call again with dry_run: false only when applying. High-level actions include:

• 'write_safely': writes content with atomic lint validation, dry-run semantic diff simulation, pre_check blast radius mapping, and automatic rollback on failure.

• 'find_and_replace': runs global regex find-and-replace across matching indexed files with instant re-indexing.

• 'delete_chunk': removes a chunk from the index.

REPLACES: write_to_file, replace_file_content, multi_replace_file_content, manual lint + commit cycles. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Preview and apply atomic safe file writes, global find-and-replace, or delete chunks.

Usage (long): Write files safely with automatic lint checks and revert on failure, run workspace-wide find and replace, or purge chunk entries. Always call synapse_get_context (edit) before this tool to understand callers, callees, and tests. For write_safely, first call with dry_run: true, pre_check: true, and lint: true so the agent sees semantic safety, compilation errors, contract warnings, and blast radius without touching disk. Apply with dry_run: false only after reviewing that preview. Validates with Trunk linter — rolls back atomically on lint failure.

Searches the repository codebase using different modes. Pass the exact repo_id with every action to keep results focused on the intended repository; if repo_id is unknown, call synapse_manage_repos with action 'list'. High-level actions include:

• 'semantic': cosine similarity search over in-memory embeddings; best for conceptual or descriptive queries.

• 'symbol': fast exact/fuzzy symbol index lookup; best when looking for a named function, module, or class.

• 'regex': line-matching grep over indexed source; best for exact string or pattern matching. Without repo_id, every action returns at most 5 high-confidence matches across indexed repositories and reports the policy in meta.unscoped_retrieval.

REPLACES: grep_search, find, rg, list_dir for code search. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Search codebase using semantic embeddings, symbol index, or regex grep. Pass the exact repo_id to keep results focused on the intended repository. For the freshest just-edited file, use actions 'symbol' or 'regex' (analogous to current symbol, regex, and graph context workflows).

Usage (long): Run a natural language semantic search, exact/fuzzy symbol lookup, or line-matching regex grep over indexed files. Pass the exact repo_id with every action to keep results focused on the intended repository. If repo_id is unknown, call synapse_manage_repos with action 'list' and copy it verbatim. Without repo_id, semantic requires score >= 0.75, fuzzy symbols require score >= 0.90, regex keeps exact textual matches, and every action is capped at 5 results. The response reports this in meta.unscoped_retrieval. Compression is on by default — pass compress_payload: false to opt out for debugging. Actions 'symbol' and 'regex' work immediately after quick_pass — they do not require embeddings. Action 'semantic' requires embeddings — avoid when repo_status.embeddings_partial is true.

Handles code quality, testing context, and linting control. High-level actions include:

• 'coverage': reports production files with no, weak, or strong test coverage using the indexed graph.

• 'find_tests': discovers behavioral tests, features, step definitions, or fixtures covering a symbol/query. Without repo_id, it returns at most 5 direct-confidence matches and stops once that bound is filled.

• 'setup_trunk': automatically configures Trunk linting and enables recommended linters for a repository.

• 'recommend_test_targets': recommends test targets (both unit/integration and BDD features) with behaviour summaries and coverage analysis.

REPLACES: grep_search for test files, find _test. patterns, manual test-to-code mapping. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.

Usage (short): Report test coverage gaps, find relevant test files, recommend test targets, and configure Trunk linting.

Usage (long): Report static test coverage bands, locate feature files or unit tests for a symbol, recommend candidate files for unit and BDD test coverage (via recommend_test_targets) with behaviour summaries (excluding nested repositories/submodules by default, or opting in via targeted path filters), and run Trunk setup/audit check enable. Unscoped find_tests returns only direct-confidence matches, capped at 5.