Synapse MCP is a 100% local MCP server that turns your codebase into a persistent AST knowledge graph, giving AI agents fast, structured code intelligence and safe mutation tools.
Ask in plain language: use ask_synapse to route questions, edits, deletion checks, reviews, debugging, and admin tasks to the right tool, with safe next-step guidance.
Search code: semantic, symbol, and regex search return structured chunk IDs, line numbers, and tags instead of raw file dumps.
Explore the graph: find direct/transitive callers and callees, inspect neighbourhood context around a chunk, and detect circular dependencies.
Inspect files: read full files or chunks with line ranges, use lightweight "outline" mode to save tokens, and count indexed lines.
Modify code safely: write files with in-memory simulation, lint validation, atomic commit, and auto-rollback; run global find-and-replace; delete chunks from the index.
Review changes: analyse diffs and commit ranges to get ranked blast radius, broken contract signals, blind spots, and recommended tests before pushing.
Understand the codebase: detect languages, extract public API surfaces, perform read-only function-level deletion-safety checks, scan contracts, build dependency graphs, get architecture overviews, and surface refactor opportunities.
Work with tests: derive coverage bands from the graph without executing tests, locate related tests, get ranked test targets, and configure Trunk linting.
Debug from stack traces: map crash frames directly to code chunks, get root-cause analysis and test suggestions, and trace execution paths through behaviours.
Learn across sessions: save permanent summaries on chunks, promote important results, query learned associations, and get suggestions for high-impact documentation targets.
Manage repositories: register, list, archive, restore, unregister, update excluded paths, and get actionable recommendations for dirty-merged Git worktrees.
Control the indexer: check server health, monitor indexing progress per repo, and trigger re-indexes.
Discover capabilities: the manifest tool returns all available tools, actions, and parameters for the running server.
Provides AST-aware code intelligence for C++ codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Clojure codebases, including semantic search, caller/callee graphs, and refactoring analysis.
Provides AST-aware code intelligence for Dart codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Elixir codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Erlang codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for F# codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for GraphQL schemas and queries, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Haskell codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for HCL (HashiCorp Configuration Language) files, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for JavaScript codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Julia codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Kotlin codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Lua codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for OCaml codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for PHP codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Python codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Ruby codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Rust codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Scala codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Shell scripts, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Solidity codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Swift codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Terraform configurations, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for TypeScript codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Zig codebases, including semantic search, dependency graphs, and refactoring analysis.
Your structural brain for your coding AI agents.
🏗️ Currently in Preview. Synapse MCP is actively evolving — this is an early look at the code-intelligence layer we're building. We want your feedback. Open an issue, tell us what breaks, what's missing, and what would make you switch from grep for good.
Synapse MCP is a free, 100% local MCP server that converts your codebase into a persistent, on-device AST knowledge graph. Claude, Cursor, Copilot, and every MCP-compatible agent gets exact caller trees, semantic search, and zero-hallucination refactoring — at 60% lower token spend than shell tools. Your code never leaves your machine.
# Linux / macOS
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | sh
# Windows PowerShell
irm https://downloads.synapse-mcp.dev/install.ps1 | iexIf you've used AI coding assistants — Claude, Copilot, Cursor, Devin — you've probably noticed they spend a lot of time finding code before they can change it. They grep files, read imports, search for function names, open file after file. That exploration is expensive: it burns tokens, takes time, and the agent still sometimes gets it wrong.
Synapse MCP is the fix for that.
It is an MCP server — a background process that connects to your AI agent and gives it a new set of tools. Instead of a file system and a search box, Synapse gives your agent a pre-built knowledge graph of your entire codebase: every function, every class, every call relationship, every module boundary — indexed, structured, and ready to query in milliseconds.
Think of the difference between a new employee on their first day versus a senior engineer who has worked in the codebase for years.
The new employee opens files, searches for things, asks questions, gets confused by unfamiliar names. Every task starts with exploration.
The senior engineer already knows where everything is. They go straight to the right file, understand the downstream effects of a change before touching it, and know which tests to run. They don't explore — they act.
Synapse turns your AI agent into the senior engineer. The knowledge graph is built once, updated automatically as your code changes, and queried instantly on every agent request — all without any code leaving your machine.
Without Synapse | With Synapse |
Agent greps files, reads imports, opens 10 files to find one function | One tool call returns the exact chunk, its callers, and its tests |
Every session starts from zero | Graph persists and improves across sessions |
Agent writes a file, lint fails, file is broken |
|
You paste a stack trace and hope |
|
Code review is manual |
|
Code sent to a cloud service to build an index | Everything runs locally — zero data egress |
You don't change how your agent works. You don't change your workflow. You install Synapse, register your repo, and your agent gets smarter immediately.
Related MCP server: Reporecall
🔒 Your code never leaves your machine. Synapse runs entirely on your hardware — no cloud indexing, no API calls with your source, no telemetry, no vendor lock-in.
Most code intelligence tools send your code to a cloud service to build their index. Synapse does not. The full AST graph — every function, every edge, every embedding — is built and stored locally in a persistent on-device store. When the graph is ready, your agents query it directly over MCP. Nothing goes out.
This matters for:
Enterprise & regulated environments — source code stays inside your perimeter
Open source contributors — your unreleased work stays unreleased
Anyone who values speed — local graph queries have sub-millisecond latency. No network round-trip, ever.
Standard agents grep text. Synapse serves compressed structural slices from a pre-built AST graph — callers, callees, coverage gaps, contracts, and summaries — in a single MCP call.
"Four tool calls. Zero file reads. Zero grepping. With Synapse the agent spends tokens on the actual task — not on exploration." — from the Synapse benchmark report
Metric | Synapse vs. shell tools |
Tokens & Cost | −60% |
Speed | 2.2× faster |
Tool calls | −47% |
Accuracy | 100% — identical |
Data sent to cloud | 0 bytes |
Fewer tool calls + no network latency = dramatically faster agent loops.
Feature | Description |
🔒 100% Local & Private | The graph is built and stored on your machine. Zero cloud dependencies, zero data egress, zero network latency on queries |
⚡ Sub-millisecond Graph Queries | Local in-memory store means responses are instant — no API round-trips eating into your agent's budget |
🚀 SmartCrusher Compression | Responses auto-minified 30–60%: short keys, stripped nulls, relativised paths. Outline mode strips bodies — scan 20+ files at a fraction of the token cost |
Three Search Modes | Semantic (plain English), symbol lookup, and full PCRE regex — all returning structured chunk IDs, not raw file dumps |
Transitive Caller Graph | Know every direct and transitive caller of any function before touching a line of code. Configurable depth, confidence scores, edge labels |
Safe Atomic Writes | Simulate edits in memory, map the blast radius, write atomically, and auto-rollback on lint failure. Your file is never left broken |
Instant Crash Resolution | Paste a stack trace, get root-cause analysis mapped to your AST graph — with reproducing test suggestions. No runtime needed |
Change Review & Impact | Feed a diff or commit range. Get ranked blast radius, broken contracts, tests to run, and blind spots — before you push |
Persistent Agent Memory | Summaries written in one session survive to the next. The more you use Synapse, the smarter your codebase model becomes |
Test Intelligence | Coverage bands, test mapping, and ranked test targets — derived from the graph without executing your test suite |
Codebase X-Ray | Language detection, public API surface, dead-code deletion safety, inter-module dependency graph, contract scanning, and refactor opportunities in one call |
50+ languages. One graph. Supports 100s of repos. AST-aware chunking and dependency edge extraction for every mainstream language — no plugins, no configuration, no cloud.
Elixir Python TypeScript JavaScript Go Rust OCaml Haskell F# Clojure Scala Java Kotlin Swift C C++ C# Ruby PHP Dart Zig Erlang Julia Groovy Solidity GraphQL HCL / Terraform Protobuf SQL Shell PowerShell Lua ...and more
See Quick Start below, or visit synapse-mcp.dev/download for the full guide and GUI installer.
Feature | Details |
AST Indexing | 10,000+ files across 50 languages in seconds |
Search | Semantic, symbol & regex — structured results, not file dumps |
Caller Graph | Transitive caller & callee traversal with confidence scores |
Codebase Insights | API surface, deletion safety, dependency graph & refactor candidates |
Compression | SmartCrusher trims payloads 30–60% before they hit your LLM |
Privacy | 100% local — zero cloud dependencies, zero data egress |
⚡ Typical token savings exceed the subscription cost.
Feature | Details |
Safe Writes | Simulate, validate & auto-rollback on lint failure |
Change Review | Blast radius, broken contracts & ranked risk |
Crash Resolution | Stack trace → root cause → reproducing tests |
Test Intelligence | Coverage bands & precise gap targeting |
Persistent Memory | Summaries survive across sessions |
Knowledge Cache | Queries improve result ranking over time |
Most AI tools have no memory. Every session starts from zero — the agent reads the same files, discovers the same functions, and asks the same questions all over again. That's expensive and slow.
Synapse is different. It maintains a persistent, on-device knowledge graph that accumulates across every session. But beyond just storing the graph, it has a built-in learning and reinforcement layer that gets smarter the more you use it.
Think of it like a highly organised colleague who takes notes.
1. Summaries that stick around
When an agent (or you) explains what a function does — "This handles Stripe webhook validation and checks for duplicate events" — Synapse writes that to the graph permanently. Next session, any agent that touches that function gets your explanation attached automatically. You wrote it once. Every agent benefits forever.
2. Queries that teach themselves Every time a search returns a useful result and the agent uses it, Synapse silently records the association: "when someone asks X, chunk Y was the right answer." Over time, the most useful results for common queries bubble up to the top automatically — without anyone manually tuning anything. This is retrieval reinforcement: the graph improves its own ranking from real usage.
3. Explicit promotion If a result is particularly important, you can tell Synapse directly: "for queries about payment processing, always surface this chunk first." That instruction is stored locally and honoured in every future session.
4. Gap detection Synapse tracks which parts of your codebase get queried most but have no explanation attached. It can surface these gaps on demand — so you know exactly where a five-minute annotation would have the biggest impact on future agent sessions.
The result is a codebase model that compounds. The graph grows richer, the rankings get sharper, and agents spend less time re-exploring what's already been understood.
🔒 The learning layer is entirely local. No queries, no summaries, and no usage signals ever leave your machine.
✨ The learning and memory system is a Pro feature. It's where we invested the most original engineering work — building a feedback loop that makes every subsequent agent session measurably faster.
Synapse exposes 13 precision tools over the Model Context Protocol. All tools accept a compress_payload flag (default true) that enables SmartCrusher compression — 30–60% fewer response tokens at zero information loss.
Tools marked FREE are available on all plans. Tools marked PRO require a Pro subscription ($19/mo). Pro features are where the truly unique engineering lives — safe atomic writes with rollback, session-to-session learning, crash resolution, and change impact analysis.
ask_synapse — FREEThe default natural-language entry point. Send any codebase question or task in plain English. Synapse routes it to the optimal underlying tool, returns safe next_tool_calls to follow, and reports a completion_state plus agent_instruction so you always know what to do next.
Use this first for virtually every task — code exploration, deletion-safety checks, editing, debugging, test analysis, and administration. For "can I delete X?", "is X still used?", or "should I keep X?", include inputs.chunk_id when known; otherwise include repo_id plus an arity-qualified exact symbol in inputs.symbol. If the user gives only descriptive prose, ask for the concrete symbol or show candidates instead of guessing.
{ "query": "Where is the retry logic for the payment service?", "repo_id": "my-org/my-repo" }synapse_search_codebase — FREEFind code by meaning, name, or pattern. Three search modes in one tool:
Action | Description |
| Plain-English similarity search over chunk embeddings. "Find all places that handle auth errors" |
| Exact named-symbol lookup by function, class, module, or type name |
| Full PCRE in-memory grep across the indexed graph. Returns chunk IDs, line numbers, and tags — not raw text |
{ "action": "symbol", "query": "PaymentService", "repo_id": "my-org/my-repo" }synapse_explore_graph — FREENavigate relationships around any chunk. Given a chunk ID (from any search result), traverse the AST dependency graph in any direction.
Action | Description |
| Every direct and transitive caller of a function, with configurable depth and confidence scores |
| All functions/modules called by a given chunk |
| Rich neighbourhood — callers, callees, sibling definitions, and related chunks |
| Detect circular dependency chains in the graph |
Use this before touching any function to understand its full blast radius.
{ "action": "callers", "chunk_id": "abc123", "depth": 3 }synapse_get_context — FREEAdvanced context gathering for editing, onboarding, and explanation.
Action | Description |
| Open-ended semantic research — parallel semantic + exact + fuzzy + graph traversal in one call |
| Pre-edit safety pack: callers, callees, must-read files, likely tests, and risk assessment for a planned change |
| Plain-English explanation of what a specific chunk does |
| Guided reading order for a subsystem — optimal for understanding unfamiliar code |
{ "action": "edit", "intent": "Refactor the caching layer to use Redis", "repo_id": "my-org/my-repo" }synapse_inspect_files — FREERead source files and chunks with structural awareness.
Action | Description |
| Read files with optional line ranges and |
| Read a single chunk by ID directly from the in-memory store — instant, no disk I/O |
| Count total indexed lines across the workspace |
Pass format: "outline" to scan 20+ files at a fraction of the token cost. Use format: "full" only when you need complete implementations.
{ "action": "read_files", "files": [{ "path": "lib/my_module.ex", "ranges": ["45-80"] }], "format": "outline" }⚠️ Linting workflows: Pass
compress_payload: falsewhen reading files to investigate whitespace or formatting violations. SmartCrusher strips trailing whitespace before returning content, which can hide the very violations you are trying to fix.
synapse_modify_files — PROEdit code with safety guarantees — lint-validated and atomically rolled back on failure.
This is one of the features we're most proud of. Vanilla file writes from an agent are dangerous — a failed linter means a broken file, a half-written function, or a commit that doesn't build. write_safely eliminates that entire class of failure by simulating the edit in memory, running your project's own linter against it, and only committing the bytes to disk if validation passes. If anything fails, the original file is untouched.
Action | Tier | Description |
| PRO | Simulate, lint-validate, write atomically. Auto-rollback on failure — your file is never left broken |
| PRO | Global find-and-replace across the indexed graph with pattern matching |
| PRO | Remove a chunk from the graph/index. It is not source deletion guidance; use |
Always pair with synapse_get_context (edit) first to understand callers and impact.
{ "action": "write_safely", "path": "lib/my_module.ex", "content": "..." }synapse_change_review — PROReview diffs and assess blast radius before pushing.
Before you push, Synapse maps every chunk your diff touches, ranks the risk, identifies broken contracts, and tells you which tests to run. This replaces a manual code review pass that typically takes 20–40 minutes for a medium-sized change.
Action | Description |
| Structural analysis of a diff: which chunks changed, what they affect |
| Full review: ranked risk scores, blind spots, broken contracts, recommended tests to run |
| Post-edit blast radius check — verify what a committed change touches |
Feed a raw diff string or a commit range. Get actionable output before you push.
{ "action": "review_diff", "diff": "..." }synapse_codebase_insights — FREECodebase-level analysis in a single call. Use the dead_code action, normally through ask_synapse, when an agent needs function-level evidence about whether one exact symbol or chunk is still used or safe to delete.
Action | Description |
| Language detection across the workspace |
| Extract the full public API surface of a module or the entire codebase |
| Read-only function-level deletion-safety check: |
| Scan for interface/behaviour/protocol contracts and their implementations |
| Inter-module dependency graph — who imports whom |
| Consolidated high-level overview of the codebase architecture |
| Identify hotspots: duplicated logic, bloated modules, tight coupling |
{ "action": "overview", "repo_id": "my-org/my-repo" }Deletion-safety questions should normally enter through ask_synapse so routing, missing-input guidance, and agent_instruction are preserved:
{
"query": "Can I delete this chunk?",
"repo_id": "my-org/my-repo",
"inputs": { "chunk_id": "my-org/my-repo:lib/parser.ex:120" }
}{
"query": "Is Parser.parse/2 still used?",
"repo_id": "my-org/my-repo",
"inputs": { "symbol": "Parser.parse/2" }
}If no chunk_id is available, pass repo_id plus an arity-qualified symbol such as Parser.parse/2; descriptive prose should produce clarification or candidates, not a guessed deletion decision.
Interpret dead_code by reading preferred_identifier, valid_input_patterns, scope, clause_level_analysis, safe_to_delete, deletion_risk, confidence, caveats, and supporting_evidence.production_callers / supporting_evidence.test_callers. dead_code is function-level; clause-level reachability is currently reported as unsupported. Production callers mean keep it; test-only callers and unknown visibility should be presented as caution, not automatic deletion.
synapse_test_quality — PROTest discovery and coverage analysis — no test runner required.
Derives test coverage and gaps directly from the AST graph — without running a single test. This is particularly powerful for large codebases where a full test suite takes minutes to execute. Synapse tells you what's covered, what isn't, and where to focus next, in seconds.
Action | Description |
| Coverage band analysis — which functions are tested, which have gaps |
| Locate tests related to a specific symbol or file, confidence-ranked |
| Ranked list of functions most in need of testing based on the graph |
| Configure Trunk for linting integration |
{ "action": "find_tests", "symbol": "PaymentService.charge" }synapse_debug_trace — PRODebugging and execution tracing directly from the AST graph.
Paste a raw stack trace and get back a root-cause analysis that maps each frame directly to your indexed chunks — with a suggested reproducing test and the call chain that led there. No runtime, no debugger, no re-running the failure scenario.
Action | Description |
| Paste a stack trace; get root-cause analysis mapped to your graph with reproducing test suggestions. No runtime needed |
| Trace the execution path of a behaviour or callback through the graph |
{ "action": "resolve_stack", "stack_trace": "..." }synapse_knowledge_cache — PROThe learning and reinforcement layer. Persistent knowledge that survives across sessions.
This is Synapse's most unique capability. See Synapse Learns From Every Session for a plain-English explanation of how it works.
Action | Description |
| Attach a plain-English description to a chunk. Every future query hitting that chunk gets your explanation for free |
| Search the cache by intent — retrieve promoted results from previous sessions |
| Explicitly promote a chunk for a query, immediately improving future result ranking |
| Find high-traffic chunks that lack summaries — investing here improves all future sessions |
{ "action": "save_summary", "chunk_id": "abc123", "summary": "Handles Stripe webhook validation and idempotency checks." }synapse_manage_repos — FREERegister, list, and manage repositories in the Synapse graph.
Action | Description |
| List all registered repositories with indexing status |
| Register a new repository root. Automatically detects Git worktrees for delta-only indexing |
| Pause indexing for a repo without removing its data |
| Re-activate an archived repository |
| Dismiss a dirty-merged worktree advisory and keep the overlay as-is |
| Remove a repository from the graph entirely |
| Update glob patterns to exclude paths from indexing |
{ "action": "register", "path": "/path/to/my-repo" }synapse_indexer_control — FREEHealth checks and indexer administration.
Action | Description |
| Current indexing phase, file counts, embedding readiness, and per-repo status |
| System health check — confirms the server is up and the graph store is accessible |
| Manually trigger a re-index for a specific repository |
{ "action": "status", "repo_id": "my-org/my-repo" }synapse_capability_manifest — FREESelf-documenting tool surface. Returns the full list of available tools, actions, and parameters for the running Synapse version. Useful for agents bootstrapping a new session or checking what features are available on the connected server.
{}Synapse supports Git worktrees transparently via the Virtual Worktree Overlay (VWO):
Delta Indexing — only modified/added/deleted files are re-indexed. Near-instant (< 50ms).
Overlay Priority — worktree chunks shadow parent repo chunks automatically.
Parallel Agent Workflows — spawn multiple sub-agents in separate worktrees without duplicating the main index.
Synapse implements the open Model Context Protocol. If your tool speaks MCP, it works with Synapse.
IDEs & Editors: Cursor · Windsurf · VS Code · Zed · JetBrains AI
Agents: Claude Code · GitHub Copilot · Devin · Aider · Cline · Continue.dev · Replit Agent · Amazon Q · OpenHands · SWE-agent · Plandex · Antigravity
Tools: Sourcegraph Cody · Qodo · Tabnine
Full install guide & GUI installer: synapse-mcp.dev/download
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | shDownloads and runs the install script — inspect it first
powershell -c "irm https://downloads.synapse-mcp.dev/install.ps1 | iex"Run from PowerShell — inspect the script first
The installer auto-detects your MCP client (Cursor, Claude Code, Windsurf, VS Code, etc.) and writes the correct config.
100% local. Synapse runs entirely on your machine. No code leaves your environment, no cloud dependencies, no data egress. Your codebase stays yours.
This is the highest-leverage contribution you can make.
LLMs are trained on billions of lines of code where developers reach for grep, find, cat, and ls to explore a codebase. That muscle memory is baked into the model weights. When an agent is dropped into a new project, its first instinct is to grep — even when a smarter, cheaper tool is available.
Synapse ships a set of agent skill files (.agents/skills/synapse-mcp/SKILL.md, AGENTS.md) that agents load at session start. These files override the grep instinct by giving agents explicit routing rules, anti-patterns, and example tool calls. They are, in effect, runtime training for the meta-layer — teaching agents how to use the tools they have, not just what the tools do.
The problem: We can only write what we observe. You may have seen failure modes, routing gaps, or phrasing that your specific agent ignores. We haven't. The skill files improve dramatically with real-world usage reports.
Area | What to contribute |
Anti-patterns | Agent behaviours you've seen that Synapse should suppress (e.g. "my agent still greps even after loading the skill") |
Routing rules | Cases where an agent picked the wrong Synapse tool — what was the query, what should it have done? |
Phrasing that works | If a specific instruction wording reliably stops your agent from falling back to grep, share it |
Agent-specific quirks | Claude, GPT-4o, Gemini, and Copilot all have different tendencies. Agent-specific |
New tool examples | Concrete JSON examples for actions that aren't yet covered in the skill |
Missing workflows | Scenarios (debugging, onboarding, large refactors) where the skill gives no guidance |
Open an issue — describe the failure mode or gap you observed. Include the agent, the query, and what it did vs. what it should have done.
Open a PR — edit AGENTS.md or .agents/skills/synapse-mcp/SKILL.md directly. Skill file PRs are reviewed and merged fast — they don't require tests.
Share a benchmark — if you've run Synapse vs. shell tools on your own codebase and have numbers, we want to publish them.
The skill files live at the repo root and in .agents/. They are plain Markdown — no Elixir knowledge required. If you can describe what went wrong, you can write the fix.
Synapse gives your existing AI agents a precision map of your codebase. Myelix Agents is the next step: AI coding agents built from the ground up to think before they code.
Where current agents react — reading a file, writing a change, hoping for the best — Myelix Agents plan. They maintain an explicit task model, reason about risk before touching code, incorporate learnings from previous sessions (via Synapse's knowledge graph), and course-correct when something goes wrong. Accuracy over speed. Thought over grep.
Synapse Pro subscribers will get early access. Join the waitlist →
Need help? Open an issue and we'll get back to you. Bug reports, feature requests, and integration questions are all welcome.
🌐 synapse-mcp.dev — Website & docs
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Canonical repository-relative path filter or target. Prefer this top-level field for file scope. | |
| depth | No | ||
| limit | No | ||
| query | Yes | Natural-language question or objective. | |
| format | No | ||
| inputs | No | Explicit action data. Mutation content and replacements must be supplied here. | |
| confirm | No | ||
| context | No | Typed symbols, stack traces, diffs, or other routing context. Prefer top-level repo_id and path for scope; context.repo_path and context.target_file remain compatible aliases. | |
| repo_id | No | Canonical registered repository identifier. Prefer this top-level field for repository scope. | |
| feedback | No | Explicit feedback bound to an earlier route. | |
| route_id | No | Opaque route binding returned by an earlier incomplete response. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| preview_digest | No | ||
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. | |
| confirmation_token | No | Opaque binding returned by a pending mutation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral burden. It does so well by disclosing routing through existing granular tools, preserving entitlement/readiness/validation/mutation-safety checks, automatic compression, clarification behaviour for ambiguous targets, and the incomplete-response protocol via completion_state, agent_instruction, and next_tool_calls. It does not explicitly mention side-effect potential or confirmation semantics, but the information is generally thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is clearly structured into an overview, replacement statement, and short/long usage guidance. It is a bit longer than necessary, with some repetition around the same 'Use first' and 'instead of alternatives' ideas, but every section earns its place given the tool's complexity and broad role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 16 parameters, nested objects, no output schema, and no annotations, the description does a good job of covering the common and even advanced flow: scoping, exact identifier, mutation payload, feedback/identity, confirmation_token, compression, and next_tool_calls. It does not fully explain return shape, confirmation UI authority explicit cases, or when the agent should bypass the router, so I deduct a little for those gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 69%, and the description adds meaning beyond the schema in the right places: it explains query, top-level repo_id/path vs. global aliases, where mutation payload must live, how deletion-safety targets should be supplied, and how to use returned route ids. However, certain parameters such as depth, limit, format, and preview_digest remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as the default Synapse entry point that routes natural-language objectives across a defined set of tasks (questions, deletion-safety, edits, reviews, debugging, test discovery, repo administration, capability discovery). It distinguishes the tool from the granular sibling tools by framing it as the intelligent router preferred over manual tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit, actionable guidance: use this first, prefer top-level repo_id and path, supply concrete identifiers in inputs, and for deleting queries provide chunk_id or a qualified symbol rather than vague prose. It stops short of presenting a clear when-not-to-use case or alternatives for bypassing the router, but the routing context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| include_tools | No | When true, include per-tool descriptors. | |
| include_groups | No | When true, include capability group definitions. | |
| schema_version | No | Requested manifest schema version. Defaults to the latest stable schema. | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| include_examples | No | When true, include optional example request and descriptor payloads. | |
| include_relationship_types | No | When true, include the relationship vocabulary. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and delivers spef: it says the output is 'live', includes 'mutation characteristics', 'safety class', 'tool relationships', and mentions compression and token behavior. It could explicitly state no side-effects, but the content is substantially transparent for a meta/manifest tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into sections and is mostly useful, but the 'Usage (short)' line duplicates the first sentence almost verbatim ('Return a structured manifest...' / 'Returns a structured manifest...'). This redundancy costs the description a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by enumerating what the manifest includes: schemas, mutation characteristics, safety classification, relationships, ready routing, and quick_start. It gives enough for an agent to understand the return surface, though it could still describe the manifest's literal top-level format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all 7 optional parameters. The description adds no new per-parameter detail beyond referencing compression and discovery, which is consistent with the baseline value for when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return a structured manifest describing SynapseMCP's live tool surface,' and enumerates concrete contents (schemas, mutation characters, static safety classification, tool relationships). This clearly distinguishs it from the 11 siblings, none of which present a meta-manifest of the tool surface.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'a replaces: reading MCP tool schemas manually h trial-and-error tool discovery' and says 'Use this tool instead of these alternatives'. It doesn't cover when-not-to-use or name sibling alternates, but the context is unmistakeable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral burden. It discloses what each action produces—modified symbols, must-read files, tests to run, contract signals, blind spots, blast radius, downstream callers, and change risk—and mentions automatic token compression. It does not explicitly state read-only behavior, but the analysis/review framing strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a punchy lead sentence, action bullets, and explicit replacement topic. However, the Usage short and Usage long sections partially repeat the same guidance, and the REPLACES paragraph is slightly redundant with the opening line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description does a good job of covering all three action modes and their outcome categories, plus when to invoke the tool. It is slightly weakened by not explaining exactly how the diff/commit-range/file-list input is provided, since no input parameter exposes it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds substantial semantic value beyond the bare 'action' property by explaining what each enum value does. It also links compress_payload to the token-compression behavior and describes the high-level result categories agents can expect, which helps parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'analyses and reviews proposed changes' via diffs, commit ranges, chunk lists, or file lists. It further clarifies the three concrete action modes and explicitly distinguishes itself from alternatives like git diff, manual diff review, and grep_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'REPLACES: git diff, manual diff review, grep_search' and tells the agent to use this tool 'instead of these alternatives'. It also gives situation-specific guidance: use after making changes to verify safety, or before merging to assess risk, plus when to inspect commit/branch diffs or before refactoring.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and responds well for 'dead_code': it labels the check read-only, highlights that no source is deleted, lists confidence/risk/caveats, and disposes of unsupported clause-level analysis. Other actions get lighter treatment and no return-shape details, so the transparency is good but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized as a summary, per-action bullets, then a short usage block; it is front-loaded and uses lists well for a multi-action tool. The 'Usage' wording does partially repeat the action list, but the repetition is moderate for the complexity being described.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema tool with seven action modes, the dead_code sub-case is very complete. Other actions are described enough to be understood but 'refactor_opportunities' remains under-specified, and the schema does not actually expose the personnel IDs/symbols/chunk identifiers the description asks for, leaving an invocation gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three actual parameters already have schema descriptions, so the description is not required to carry the parameter documentation burden. It does add meaning by explaining what each action enum value accomplishes. However, the dead_code instructions tell the agent to pass repo_id/symbol/chunk_id arguments that are absent from the provided input-schema, which is misleading for actual call construction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names concrete resources — codebase structures, API boundaries, contracts, dependencies, and deletion safety — and the action bullets map directly to the schema enum, so the tool's purpose is clear and distinguishable from search/modify siblings. It loses a point because 'refactor_opportunities' is part of the enum but only mentioned in passing rather than given an explicit action bullet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance for the most complex case: use 'dead_code' as the backend for ask_synapse questions like 'can I delete X?', and prefers the chunk_id over a raw symbol. It also tells the agent to ask for the concrete symbol instead of guessing and to use 'detect' before choosing search modes. It stops short of naming when-not scenarios or explicit sibling exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavior burden. It does disclose that the tool does not run code and that it reduces token usage via automatic compression. However, it does not mention potential side effects of the save_to_file parameter, any indexing/prerequisite requirements, or whether resolution can fail for unknown stacks, so the transparency is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and organized into scannable sections: actions, REPLACES, short usage, and long usage. There is some redundancy between the short and long usage sections, but each section generally earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema and no annotations, the description provides enough context to understand what the tool does, when to choose each action, and what results conceptually look like. It does not fully describe output structure or prerequisite conditions, but the prose covers most of what an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with high description coverage, giving a baseline of 3. The tool description adds meaningful semantics to the action enum by explaining exactly what 'trace_behaviour' and 'resolve_stack' do, while the schema still handles the function signature and save_to_file details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Traces code paths or resolves error stack traces...') and names two concrete high-level actions, each with clear inputs and outcomes. It clearly distinguishes this tool from the sibling tools like synapse_search_codebase or synapse_inspect_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states what this tool replaces: manual stack trace reading, grep_search for error origins, and sequential file reads, and tells the agent to use this instead. It also gives action-specific guidance: use trace_behaviour to understand function flow without running it, and use resolve_stack to map crash frames to chunks and root cause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
chunk_id (direct) — fastest, use when already known.
repo_id + symbol — resolves the symbol and runs in one call.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden and does it well: it explains transitive behavior, depth 1–3, automatic compression, and warns graph results can be large. It doesn't explicitly state 'read-only,' but the action names and context imply no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but well-structured with bullets, preprocessing examples, and front-loaded action list. There is some redundancy, such as telling the message that 'no separate lookup needed' and 'Replaces...manual caller guessing' twice, but the overall shape is usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The behavior context is complete for a read-only, no-annotations, no-output-schema tool. It covers what is returned, how to specify targets, depth options, token-saving, compression, and which alternatives to replace. The agent has enough information to select and invoke the tool in most realistic graph-query scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents all three declared properties, so baseline is 3. The description adds real semantics: action values, how chunk_id/repo+symbol/file_path are accepted, depth behavior, and actual invocation examples. However, it references target fields like repo_id, symbol, and depth that are missing from the input schema, which oils any agent invocation and prevents a pointerfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core purpose clearly: 'Explores structural relationships within the codebase graph' and then catalogs the four concrete actions. It distinguishes itself from siblings by naming grep_search, find_references, and caller guessing as alternatives it replaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use the tool and what alternatives it replaces, plus three ways to specify a target and one-call examples. It also advises using depth 2+ for multi-hop results instead of chaining depth-1 calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter results by entity kind (used in action 'find'). | |
| line | No | Line number within file_path (used in action 'edit'). | |
| path | No | Filter results by partial path (used in action 'find'). | |
| depth | No | Callee traversal depth (used in action 'onboard', default 3). | |
| limit | No | Maximum number of results to return. | |
| query | No | Natural language query or symbol name. Required for 'onboard' (entry point for the reading guide); used in 'find' for semantic/symbol search. | |
| action | Yes | Context action to perform. | |
| format | No | Include structured result metadata and relevance provenance for action 'find'. | markdown |
| intent | No | Describe what you plan to change (used in action 'edit'). | edit behaviour safely |
| symbol | No | Target symbol name (alternative to chunk_id for action 'edit'). | |
| repo_id | No | Repository identifier. Pass the exact repo_id to keep results focused on the intended repository and avoid matches from unrelated registered repositories. If unknown, call synapse_manage_repos with action 'list' and copy the repo_id verbatim. When omitted for 'find', only high-confidence matches are returned, capped at 5. | |
| chunk_id | No | Target chunk identifier (used in action 'edit' and 'explain'). | |
| language | No | Filter results by language (used in action 'find'). | |
| file_path | No | Target file path (alternative to chunk_id for action 'edit'). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| risk_level | No | The risk level of your change (used in action 'edit'). | medium |
| exclude_tests | No | Exclude test files from results (used in action 'find'). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does well: it explains the at-most-5 high-confidence match cap without repo_id, mentions meta.unscoped_retrieval, details what each action gathers or produces, and discloses token compression behavior. A small gap is that it never explicitly states that this is a read-only operation and never mutates code, though calling it 'retrieves' strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with high-level purpose and actions, but it repeats key points: 'Pass the exact repo_id...' appears multiple times, and 'action edit' is emphasized twice. The 'Usage (short)' vs 'Usage (long)' sections also add redundancy. Overall, it is longer than necessary, but the information is organized and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of this tool (19 parameters, no output schema, no annotations), the description is largely complete: it covers all four actions, tells the agent how to obtain a repo_id, explains behavior without repo_id, and describes what the edit action should gather. It does not fully describe the overall return value structure, but the action-level descriptions and the schema help bridge most of that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full 100% description coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains why action 'edit' is the essential pre-edit step, clarifies the impact of omitted repo_id, and breaks down what each high-level action does (e.g., find's multi-mode search, explain's layered explanation, and onboard's reading order). This is extra practical guidance, not just schema repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving codebase context for understanding, editing, explaining, and onboarding. It names specific actions ('find', 'edit', 'explain', 'onboard') and directly distinguishes itself from alternatives like 'multi-file grep_search chains, sequential view_file reads' and manual code comprehension.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool, when not to, and how to handle edge cases. It says to pass the exact repo_id, to call synapse_manage_repos with action 'list' when repo_id is unknown, and that action 'edit' is required before modifying code. It also includes 'Instead of these alternatives' guidance, which helps an agent route to the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | One of quick_pass, deep_dive_1, deep_dive_2, full, or x_repo. x_repo resolves unresolved cross-repo edges without a repo_id. (used in trigger) | full |
| path | No | Absolute or repo-relative path to re-index (used in trigger) | |
| force | No | Force re-index even if checksum unchanged (used in trigger) | |
| action | Yes | The action to perform. | |
| repo_id | No | Target repository identifier (optional for status/trigger) | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| include_profile | No | Include vectorisation and language/kind profile (used in status, slower). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses status caching with idle vs. active timing, trigger's re-index side effect, cheap vs. slower options, wait-for-idle behavior, direct SQLite lookup for repo-scoped status, and output compression for lower token usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The structure is front-loaded and skimmable: action bullets, REPLACES, a short usage note, then detailed status output. It is slightly redundant because the later status-return block partially repeats and rephrases the earlier 'status' bullet, but the overall layout remains usable and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by enumerating status fields, unresolved-edge counts, top candidates, caching behavior, and readiness guidance. For a 9-parameter tool with three distinct actions and no annotations, the description is comprehensive enough to drive the apparently action selection and parameter choice without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that repo_id selects a direct SQLite lookup, include_profile trades speed for detail, and trigger accepts a file/directory path. This helps the agent map intentions to parameters more accurately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Controls and inspects the indexing pipeline and server health,' which is a specific verb and resource, then elaborates with three concrete actions: health, status, and trigger. It clearly differentiates this tool from sibling content tools like synapse_search_codebase and synapse_modify_files, whose domains are code search and file editing rather than indexing pipeline control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage sequencing ('health' first), repo_id scoping guidance, and a REPLACES line directing use instead of manual health probing, process monitoring, and ad-hoc tool listing. It lacks explicit when-not-to-use guidance against related sibling tools such as synapse_manage_repos, but the core usage context is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | A substring path filter (used in 'count_lines'). | |
| files | No | A path string, a %{path, ranges} object, or a list of either (used in 'read_files' and 'count_lines'). | |
| action | Yes | The inspection action to perform. | |
| format | No | The return format: 'full' for complete contents, 'outline' for signature-only compression. | full |
| repo_id | No | Repository ID to resolve relative paths, scope filters, or count every indexed file when files and path are omitted. | |
| chunk_id | No | The chunk ID to read (used in 'read_chunk'). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| max_read_bytes | No | Total byte budget across all files for full-file reads (default 10 MB). Ignored when ranges are specified. | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. | |
| max_read_bytes_per_file | No | Per-file byte cap for full-file reads (default 10 MB). Ignored when ranges are specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden; it meets most of it by explaining that read_files reads from disk, read_chunk reads from an in-memory store with no disk access, and count_lines counts across workspace files. It also discloses default compression behavior, the compress_payload opt-out, and the outline format compression effect. It stops short of describing exact return shape or failure behavior, which would make it fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded purpose, bulleted actions, a REPLACES note, and clear usage sections. There is a small redundancy between 'Usage (short)' and 'Usage (long)', which costs some conciseness, but the overall structure is highly scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three inner actions and eleven parameters, the description is fairly complete: it describes what each high-level action does, where the data comes from, the outline option for large scans, and the default compression behavior. There is no output schema, but the description provides enough return-oriented context for each action. The main gap is that it does not specify which parameters apply to which action, leaving the agent to infer those relationships from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of the parameters, so the baseline is 3. The description adds useful grouping of actions and states that read_files returns line numbers, byte sizes, and metadata, plus that outline compresses function bodies. However, for most parameters like repo_id, chunk_id, max_read_bytes, and wait_for_ready_ms, the description does not add meaningful meaning beyond the schema; thus it earns the baseline but not substantially more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Inspects files in the workspace') and then enumerates three concrete high-level actions: read_files, read_chunk, and count_lines. It further disambiguates from legacy inspection tools by saying 'REPLACES: view_file, read_file, cat, wc, list_dir', so an agent clearly understands what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool instead of older alternatives, noting it 'provides better results with 30-60% fewer tokens via automatic compression'. It also provides task-level advice: use 'outline' format when scanning many files, and pass 'compress_payload: false' to opt out for debugging, which is actionable usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explains persistence, that learn signals are immediately queryable but provisional until promoted by repeated evidence, that save_summary permanently annotates chunks, and that suggest uses access history and traffic weight. This goes well beyond schema details, though it could be clearer about mutation side-effects and exact behaviors for save_summary beyond persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is substantially repetitive. The action list, 'Usage (short)', 'Usage (long)', and the later 'Call learn'/'Call query' paragraphs all restate the same action set with slight wording differences. It is conceptually organized, but several sentences do not earn their place because they reproduce information already covered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-action tool with no output schema and no annotations, the description covers most of what an agent needs to select, call, and understand each action. It defines behavior, input patterns, and outcome intent. It could be more complete by describing return payloads per action and explicitly naming what distinguishes this tool from the codebase search/insight siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description supports action semantics by explaining what each enum value does, but it does not deepen the semantics of max_tokens or compress_payload beyond what the schema already describes. This is acceptable given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's role as a persistence/knowledge cache and enumerates four concrete actions with explicit result types. It differentiates itself from raw searching by positioning itself as a cache for established patterns, though it does not explicitly distinguish itself from sibling tools such as synapse_search_codebase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides solid usage context: call learn after useful search results, call save_summary for permanent annotations, and call query with natural language/filenames/symbols/chunk IDs. It says this tool replaces repeated searches, manual notetaking, and rediscovery, but it does not name the actual sibling alternatives, leaving the when-not-to-use boundary slightly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
archive — keep graph searchable, stop indexing
unregister — delete graph data permanently
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.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | CRITICAL: MUST be a full absolute path to the repository (e.g. /Users/name/repo). NEVER use '.' or relative paths. Required for register. | |
| merge | No | When true, append excludes to the existing list instead of replacing it (used in update_excludes) | |
| action | Yes | The action to perform. | |
| exclude | No | Optional relative directory paths to exclude from indexing (used in register, update_excludes) | |
| repo_id | No | Stable identifier for the repository. For 'list': when provided, returns full detail for that one repo only (fast). When omitted, returns an enriched summary of all repos. Required for register, archive, restore, keep, unregister, update_excludes. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries all behavior responsibility. It states that unregister permanently removes graph data, archive stops indexing but keeps graph searchable, restore restarts indexing, and keep dismisses advisory only for the session. The behavior of auto-detecting worktrees and auto-archiving clean merged worktrees is also disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a short introductory sentence, a numbered action list, a dedicated advisory block, and lifecycle rules. It is longer than typical descriptions, but every sentence is procedural or save-making. The critical warning about absolute paths appears immediately before telling the user to avoid '.' relative paths, so it is both front-loaded and actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 8-parameter with no output schema, so the description must provide enough operational context. It does: it explains the return meaning of list, the unique dirty-worktree situation and recomended actions, the effect of archive/restore/keep/unregister, and the correct order of actions. The agent is fully equipped to sequence 'list' → respond to suggested_actions → invoke the proper action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds meaning clearly beyond the schema: root must be an absolute path and never '.', repo_id is required for most actions and optional for quick single-repo detail, and 'list' rows actually return suggested_actions that trump the state-aware next step. This is exactly the kind of parameter insight an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete responsibility — 'Manages repository registrations' — and enumerates all seven actions it supports. This makes the tool's boundary clear and distinguishes it from sibling tools such as search, file modification, or indexer control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit selection guidance: lifecycle rules say when to use archive vs restore vs unregister vs keep, and a 'REPLACES' block says to use this instead of ls/find and manual worktree management. It also instructs to call 'list' first when unsure of repo_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by entity kind (used in 'find_and_replace'). | |
| lint | No | Set false to bypass Trunk validation and write unconditionally (used in 'write_safely'). | |
| path | No | Filter by partial file path (used in 'find_and_replace'). | |
| files | No | List of file write operations (used in 'write_safely'). Each entry requires path and mode. | |
| limit | No | Max number of files to modify (safety limit, 1-100, used in 'find_and_replace'). | |
| query | No | The PCRE regular expression to search for (used in 'find_and_replace'). | |
| action | Yes | The modification action to perform. | |
| dry_run | No | Always set true first to perform a semantic simulation of the proposed changes without writing to disk (used in 'write_safely'). Set false only after reviewing the preview and deciding to apply. | |
| repo_id | No | Repository ID to resolve relative paths or scope filters. | |
| chunk_id | No | The chunk ID to permanently delete (used in 'delete_chunk'). | |
| language | No | Filter by language (used in 'find_and_replace'). | |
| pre_check | No | Set true to run a blast radius analysis before writing (used in 'write_safely'). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| replacement | No | The replacement string. Supports backreferences like \1, \2, etc (used in 'find_and_replace'). | |
| case_insensitive | No | Set to true to ignore case (used in 'find_and_replace'). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries full disclosure burden and does so thoroughly. It reveals atomic lint validation, dry-run semantic simulation, blast radius mapping, rollback on lint failure, permanent chunk deletion, re-indexing, and the fact that dry_run: true never touches disk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the tool is complex and 17 parameters; bullets and separate Usage sections keep it scanable. There is some repeated safe dry-run guidance across the intro and long usage, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-annotation tool with no output schema, this description is unusually complete: safe workflow, action semantics, lint/rollback behavior, compression, and the required preceding call to get_conext are all present. An agent can safely invoke first dry-run and decide whether to apply.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is already strong; the description adds the phase-driven semantics of dry_run/pre_check/lint and groups filters for find_and_replace. It does not describe every parameter, but it does meaningfully bind the most safety-critical and action-specific properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear resource and scope ('files in the workspace') and then enumerates the three concrete actions: write_safely, find_and_replace, and delete_chunk. It also explicitly names the alternatives it replaces, so an agent can distinguish this tool from legacy or sibling editing tools without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete safe workflow: call write_safely with dry_run, pre_check, lint true, review preview, then call apply with dry_run false. It also names a necessary preceding tool (synapse_get_context) and states when this tool should replace common alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter results by entity kind (e.g., function, module). | |
| path | No | Filter results by partial file path. | |
| fuzzy | No | Enable fuzzy matching (default true, used in symbol). | |
| limit | No | Maximum number of results to return. | |
| query | No | Search query (natural language for semantic, regex for regex, symbol name for symbol). | |
| action | Yes | Search mode to execute. | |
| symbol | No | Symbol name to look up (alternative to query for action 'symbol'). | |
| repo_id | No | Repository identifier. Pass the exact repo_id to keep results focused on the intended repository and avoid matches from unrelated registered repositories. If unknown, call synapse_manage_repos with action 'list' and copy the repo_id verbatim. When omitted, semantic uses score >= 0.75, fuzzy symbols use score >= 0.90, and every action is capped at 5 results. | |
| language | No | Filter results by programming language. | |
| min_score | No | Minimum similarity score (used in semantic, default 0.6). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| exclude_tests | No | Exclude test files from search results (default true, used in semantic). | |
| match_per_line | No | Return per-line matches with file path, line number, and line content (like grep -n). Use this when hunting for specific function definitions or call sites — results include repo_id, file, line_number, line_content. | |
| case_insensitive | No | Ignore case in regex search (default false, used in regex). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses: compression behavior (on by default, opt-out for debugging), unscoped retrieval policy (5-result cap, score thresholds), embedding dependency (semantic requires embeddings, avoid when embeddings_partial), and freshness behavior (symbol/regex work immediately after quick_pass). This is remarkably thorough for a non-annotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with short usage + long usage sections, action list, and explicit alternatives. Front-loaded key information (exact repo_id, action modes). Some redundancy between short and long usage sections (both repeat repo_id guidance) is a minor cost, but acceptable for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter complex tool with no output schema, the description covers action selection, result caps, score thresholds, repo scoping, fallback tip (call synapse_manage_repos list), and freshness behavior. Nothing critical is left out for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers 100% of parameters with rich descriptions (per-action semantics, defaults, purpose). Description adds value by explaining cross-parameter dynamics (repo_id's effect on score thresholds, compress_payload's debugging use case) that the schema lacks. Slightly less than 5 because most parameter meaning is already in the schema rather than in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: searches codebase with 3 distinct modes (semantic, symbol, regex). Explicitly distinguishes from grep_search/find/rg/list_dir — names alternative tools it replaces. The three action modes are clearly differentiated by search type and use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance per action mode ('best for conceptual...', 'best when looking for...', 'best for exact...'). Explicitly names alternatives (grep_search, find, rg, list_dir) and states when to replace them. Also gives concrete behavioral guidance about repo_id and fallback actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | The action to perform. | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| compress_payload | No | Set false to disable lossless response-key compression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and mostly delivers: it discloses the 5-match cap, the direct-confidence limitation, nested repository exclusion, and default compression. It is slightly less transparent about setup_trunk's side effects on the existing lint configuration, but 'automatically configures Trunk linting and enables recommended linters' does convey that it changes repo state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is well-organized into actionable bullets and usage sections, and most sentences carry useful detail. However, there is noticeable redundancy: the 'Usage (short)' restates the action list, and the 5-match cap on unscoped find_tests is described twice. Trimming these would make it more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a multi-action tool with no annotations and no output schema, and the description is not enough on its own. It references repo_id, symbols, queries, and targeted path filters, but the schema only exposes action, max_tokens, and compress_payload; an agent cannot reliably determine how to provide the required inputs for find_tests or recommend_test_targets. Important return/result structure details are also absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the description is not required to re-explain action, max_tokens, or compress_payload. The added prose references repo_id and symbol/query concepts, but those are not present in the input schema, so it makes parameter semantics somewhat ambiguous for an agent trying to construct valid calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear scope of code quality, testing, and lint control, then enumerates four concrete actions with specific verbs: coverage reports, find_tests discovers, setup_trunk configures, and recommend_test_targets recommends. It also differentiates itself from generic test-file discovery via grep_search, making it distinct within its sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool instead of grep_search, manual test file patterns, and manual test-to-code mapping, and gives a token-saving rationale. It also adds usage detail about scoped versus unscoped find_tests behavior. It does not fully articulate when NOT to use this tool versus the other synapse_* siblings, so it loses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v3.13.0ask_synapsesynapse_capability_manifestsynapse_change_reviewsynapse_codebase_insightssynapse_debug_tracesynapse_explore_graphsynapse_get_contextsynapse_indexer_controlsynapse_inspect_filessynapse_knowledge_cachesynapse_manage_repossynapse_modify_filessynapse_search_codebasesynapse_test_qualityEach Synapse tool has a clearly scoped domain (graph exploration, indexing, file work, retrieval, etc.), and a shared prefix prevents collisions. Still, there is some overlap between synapse_get_context's 'find', synapse_search_codebase, and synapse_explore_graph, and ask_synapse intentionally overlaps everything as a routing layer.
All tool names use the uniform 'synapse_' prefix and snake_case, making them easy to group and remember. The naming mixes verb-led entries like synapse_inspect_files with noun-headed ones like synapse_capability_manifest or synapse_test_quality, which keeps things readable but not perfectly uniform.
At 14 tools, the surface is substantial but still well-scoped. Each tool covers a distinct functional area rather than being a thin wrapper, so the count feels appropriate for the breadth of the code graph assistant.
The tool surface covers the full lifecycle: repository registration and indexing, health/status control, code search/context retrieval, graph exploration, diff review, debug tracing, safe file modification, test discovery, and knowledge caching. There are no obvious dead ends for the stated capabilities, and operators are well covered.
Ground-truth code graph for your codebase: exact callers, callees, symbols & dependencies.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/myelixlabs/synapse-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server