Tu cerebro estructural para tus agentes de IA de programación.
Synapse-MCP es un servidor MCP gratuito y 100 % local que convierte tu codebase en un grafo de conocimiento AST persistente y almacenado en tu dispositivo. Claude, Cursor, Copilot y todos los agentes compatibles con MCP obtienen árboles de llamadas exactos, búsqueda semántica y refactorización sin alucinaciones, con un 60% menos de gasto en tokens que las herramientas de shell. Tu código nunca sale de tu máquina.
# Linux / macOS
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | sh
# Windows PowerShell
powershell -c "irm https://downloads.synapse-mcp.dev/install.ps1 | iex"Si has usado asistentes de programación con IA — Claude, Copilot, Cursor, Devin — seguramente habrás notado que pasan mucho tiempo encontrando código antes de poder modificarlo. Hacen grep en archivos, leen imports, buscan nombres de funciones y abren archivo tras archivo. Esa exploración es cara: quema tokens, lleva tiempo y, aun así, el agente a veces falla.
Synapse MCP es la solución a ese problema.
Es un servidor MCP: un proceso en segundo plano que se conecta a tu agente de IA y le ofrece un nuevo conjunto de herramientas. En lugar de un sistema de archivos y una casilla de búsqueda, Synapse le ofrece a tu agente un grafo de conocimiento preconstruido de todo tu código: cada función, cada clase, cada relación de llamada y cada límite de módulo, indexado, estructurado y listo para consultarse en milisegundos.
Piensa en la diferencia entre un empleado nuevo en su primer día y un ingeniero sénior que lleva años trabajando en el mismo código.
El empleado nuevo abre archivos, busca cosas, hace preguntas y se confunde con nombres desconocidos. Cada tarea empieza con exploración.
El ingeniero sénior ya sabe dónde está todo. Va directo al archivo correcto, entiende los efectos de un cambio en el resto del código antes de tocarlo y sabe qué pruebas ejecutar. No explora: actúa.
Synapse convierte a tu agente de IA en el ingeniero sénior. El grafo de conocimiento se construye una sola vez, se actualiza automáticamente a medida que tu código cambia y se consulta al instante en cada petición del agente, todo ello sin que tu código salga de tu máquina.
Sin Synapse | Con Synapse |
El agente hace grep en archivos, lee imports y abre 10 archivos para encontrar una función | Una sola llamada de herramienta devuelve el fragmento exacto, sus llamantes y sus pruebas |
Cada sesión empieza desde cero | El grafo persiste y mejora a lo largo de las sesiones |
El agente escribe un archivo, el lint falla y el archivo se rompe |
|
Pega un stack trace y espera lo mejor |
|
La revisión de código es manual |
|
El código se envía a un servicio en la nube para construir el índice | Todo se ejecuta localmente, con cero egress de datos |
No cambias cómo funciona tu agente. No cambias tu flujo de trabajo. Instalas Synapse, registras tu repo y tu agente se vuelve más inteliinmediatamente.
Related MCP server: Reporecall
🔒 Tu código nunca sale de tu máquina. Synapse se ejecuta por completo en tu hardware: sin indexación en la nube, sin llamadas a API con tu código, sin telemetría y sin depender de ningún proveedor.
La mayoría de las herramientas de inteligencia de código envían tu código a un servicio en la nube para construir su índice. Synapse no. El grafo AST completo (cada función, cada arista, cada embedding) se construye y se almacena localmente en un almacén persistente en el dispositivo. Cuando el grafo está listo, tus agentes lo consultan directamente a través de MCP. Nada sale de tu máquina.
Esto es importante para:
Entornos empresariales y regulados — el código fuente permanece dentro de tu perímetro
Colaboradores de código abierto — tu trabajo sin publicar sigue sin publicar
Cualquier persona que valore la velocidad — las consultas al grafo tienen latencia submilisegundo. Nunca hay round-trip de red.
Los agentes estándar hacen grep de texto. Synapse sirve fragmentos estructurales comprimidos desde un grafo AST preconstruido —llamantes, llamados, huecos de cobertura, contratos y resúmenes— en una sola llamada MCP.
"Cuatro llamadas de herramienta. Cero lecturas de archivos. Cero greps. Con Synapse el agente gasta tokens en la tarea real, no en exploración." — del informe de benchmarks de Synapse
Métrica | Synapse vs. herramientas de shell |
Tokens y coste | −60% |
Velocidad | 2.2× de promedio |
Llamadas de herramienta | −47% |
Precisión | 100% — idéntica |
Datos enviados a la nube | 0 bytes |
Menos llamadas de herramientla y sin latencia de red = bucles de agente mucho más rápidos.
Característica | Descripción |
🔒 100% Local y Privado | El grafo se crea y se almacena en tu máquina. Cero dependencias de nube, cero salidas de datos y cero latencia de red en todas las consultas |
⚡ Consultas al grafo submilisegundo | El almacenamiento local en memoria hace que las respuestas sean instantáneas.py: sin round-trips de API que consuman presupuesto de tu agente |
🚀 Compresión SmartCrusher | Respuestas auto-minificadas 30–60%: claves cortas, nulls eliminados, rutas relativizadas. El modo Outline escanea 20+ archivos con una fracción del coste de tokens |
Tres modos de búsqueda | Semántica (lenguaje natural), por símbolo y regex PCRE completa — todas ofen IDs de fragmento estructurados, no volcados de archivos crudos |
Grafo transitivo de llamantes | Conoce a todos los llamantes directos y transitivos que generan cualquier función antes de tocar una línea de código. Profun configurable, puntuaciones de confianza, y etiquetas de aristas |
Escrituras atómicas seguras | Simula cambios en memoria, mapea el radio de impacto, escribe de forma atómopata y revierte automáticsiempre que falle el lint. Tu archivo nunca queda roto |
Resolución instantánea de errores | Pega un stack trace y obtén un análisis de causa raíz mapeado al grafo, con sugerencias de reproducción. No se necesita runtime |
Revisión de cambios e impacto | Envía un diff o rango de commits. Obtén el radio de impacto ordenado, los contratos rotos, las pruebas que ejecutar y los puntos ciegos antes de hacer push |
Memoria del agente durable | Los resúmenes de escritura en una sesión sobreviven a la siguiente. Cuanto más usas Synapse, más inteligente se vuelve el modelo de tu codebase |
Inteligencia de pruebas | Bandas de cobertura, asignación de pruebas y objetivos de pruebas ordenados — derivados del grafo sin ejecutar tu suite de pruebas |
Radiografía del codebase | Detección de lenguaje, superficie pública de APIs, seguridad para borrar código muerto, grafo dependencias inter-modulo, escaneado de contratos y oportunidades de refactor en una sola llamada |
Más de 50 lenguajes. Un único grafo. Compatible con cientos de repos. Generación de chunks con conocimiento de AST y extracción de dependencias edge para todos los lenguajes del ecosistema principal — sin plugins, sin configuración, sin nube.
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 ...y más
Consulta Guía de inicio rápido o visita synapse-mcp.dev/download para obtener la guía completa y el instalador con interfaz gráfica.
Característica | Detalles |
Indexación AST | Más de 10,000 archivos en más de 50 dígitos en unos segundos |
Búsqueda | Semántica, por símbolo y por regex — resultados estructurados, no volc peek |
Grafo de llamantes | Transición y trazado de llamadores y callees con puntuación de confianza |
Información del código | API surface, seguridad de borrado, grafo de dependencias y candidatos de refactorización |
Compresión | SmartCrusher reduce las cargas en 30–60 % antes de que lleguen a tu LLM |
Seguridad | 100 % local — cero dependencias de nube, cero salida de datos |
⚡ El ahorro típico en tokens supera el costo de suscripción.
Característica | Detalles |
Escrituras seguras | Simular, validar y líquido revertir si el lint falla |
Revisión de cambios | Radio de impacto, contratos rotos y riesgo ordenado |
Resolución de fallos | Stack trace → causa raíz → pruebas que reproduciendo |
Inteligencia de pruebas | Bandas de cobertura y enfoque de fallos exactos |
Memoria persistente | Resúmenes sobreviven entre sesiones |
Caché de conocimiento | Las consultas mejoran la clasificación de resultados con el tiempo |
La mayoría de los agent expertise no modernos no tienen memoria. Cada sesión comienza desde cero: el agente vuelve a leer los mismosarchivos, descubre las mismas funciones y prueba las mismas preguntas una y otra vez. Eso es caro y lento.
Synapse es distinto. Mantiene un grafo de conocimiento persistente en el dispositivo que se acumula en cada sesión. Pero más allá de almacenar el grafo, incorpora una capa de aprendizaje y refuerzo integrada que se vuelve más inteligente cuanto más lo usas.
Piénsalo como un colega muy organizado que toma notas.
1. Resúmenes que permanecen
Cuando un agente (o tú) explica lo que hace una función — "This handles Stripe webhook validation and checks for duplicate events" — Synapse lo escribe permanentemente en el grafo. En la siguiente sesión, cualquier agente que toque esa función recibe tu explicación automáticamente. La escribiste una vez. Todos los agentes se beneficián para siempre.
2. Consultas que aprenden solas Cada vez que una búsquueda devuelve un result se load order para el agente, Synapse registra silentemente la asociación: «cuando elguien pregunta por X, el chunk Y era la respuesta correcta». Con el tiemp, los result más útiles para las consultas frecuentes ascien al principo sin que nadie tenea que ajustar nada swap manual. Est es refuerzo de recuperación: el grafo mejoin su propio ranking a partir del uortuno real.
3. Promoción explícita Si un resultado es importantmente, puedes decirle a Synapse directamente: «para consultas sobre el procesamiento de pago, prresenta siempre este chunk como primer result». Esa instrución se almacena localmente y se respena en tutorial las sesiones futuras.
4. Detección de carencias Synapse rastrea qué partes de tu base de código se consultán más pero no tienen ninguna explicación asocia. Puede mostar estas vacíos on demand — asi sabes exactmente dynde cinco minutos de anotación tendrían el mayor impacto en las futuras sesiones de los agentes.
El resulto es un model de la base de código que se compone. El grafo se vuelve más rico, los intervals de result se afinán y los agentes dedican menos tiemp a reexplorar lo que ya se compren un has identity.
🔒 La capa de aprendizaje es totalmente local. Ninguna consulta, ningún resumen ni señal de uso abandona tu máquina.
✨ El sistema de aprendisaje y memoria es una función Pro. Es donde hemos invertido la ingeniería más original — construir un bucle de retroalimentación que esaees cada sesión agente enagentee measurably más rápidamente.
Synapse expone 13 herramientas de precisión a través de la Model Context Protocol. Todas las herramientes aceptan el flag compress_payload (valor por defeto true) que activaCrusher — 30–60 % menos to tokens de respuesta sin соглас información.
Las herramientas marcadas con FREE están disponibles en todos los planes. Las marcadas con PRO requieren una suscripción a Pro ($19/mes). Las funciones Pro son donde vive la ingeniería verdaderamente única: escrituras atómicamente seguras con reversión, aprendención de sesión a sesión, resolución de código muerto and análisis de impacto de cambios.
ask_synapse — FREEPunto de entrada natural por area: por defecto. Envía cualquier pregunta o tarea de coded in lenguage natural. Synapse routa to the suayad más appropriate, devuelve una serie de next_tool_calls seguras que seguir, e informa de un completion_state junto con agent_instruction para que siempre sepas qué se ha oint se next.
Úasélo first cuer quer era — exploración del códig, check de segmented of, editción, debuging, análisis de tests and administración. Para «¿puedode borar X?», «¿sse sigue usonde X?» o «¿debeo pri servar X?», incluye inputs.chunk_id cuando lo copies; en caso contrario incluye repo_id and un símbolo concretamente calificado por aridad en inputs.symbol. If the user gives a prose descripción, ask for the concrete symbol or show candidates in hour guess.
{ "query": "Where is the retry logic for the payment service?", "repo_id": "my-org/my-repo" }synapse_search_codebase — FREEEncuentra código por meaning, name or pattern. Mateu search maneras en una sola herramienta:
Acción | Descripció |
| Búsqueda de similitud en lengua naturaln sobre los embeddings de los chunks. «Encuentra todos los lugares que duran los errores de autenticación». |
| Búsqueda exct de símbolos nombrados por nombre de función, clase, módulo o tipo. |
| Grep PCRE completo en memoria sobre el grafo indexado. Devuelve IDs de chunks, números de línea y information of locations —, no de texto en bruto. |
{ "action": "symbol", "query": "PaymentService", "repo_id": "my-org/my-repo" }synapse_explore_graph — FREENavega por las relaciones en torno de cualquier chunk. Dado a chunk ID (de cualquier resultado de búsqueda), recorre la del AST en cualquier dirección.
Action | Instructions |
| Todos los llamadors directos e transitivo de una función, con profundidad configurable y score de confianza |
| Todos los módulos/función (called by a given chunk) |
| Conglomerado own: callers, callees, definiciones hermanas and relachunks |
| Detection de cadenas de dependencia circular en el grafo |
Use this before any tocar ninguna function to fill with the blast radius.
{ "action": "callers", "chunk_id": "abc123", "depth": 3 }synapse_get_context — free unspecifiedAdvanced context: capture context para editar, acumulación y explicación.
Action | Description |
| Investigación semántica expandida — semantic parallel + exact + fuzzy + graph in a single call |
| Safety pre-pack during edit: callers, callees, must-read files, potential tests, hazard analysis for a planned change |
| Explicación / de la lengua llana de qué hacer lo que hace un manera simple particular |
| Guía de lectura ordenada for a subsystem — optimum to familiarization with unknown código |
{ "action": "edit", "intent": "Refactor the caching layer to use Redis", "repo_id": "my-org/my-repo" }synapse_inspect_files — FREELee código source y chunks con constramiento structural.
Action | Descripción |
| Lee archivos con ranuras opcional gens line and option |
| Read a individual chunk by ID from the in-memory store directly — instanáneo, no read disk |
| Contar entire line of indexed total code in workspace |
Paseformat: "outline" for scan 20+ files at a fraction of token cost. format: "full" only if you need full implementation.
**Example.*:
️ Linting workflows: escalación pass
compress_payload: falseal leer archivos for to investigate whitespace or formatting violations. SmartCrusher removes trailing spaces. Great and trailing whitespace before returning. Return the content, which can hide the very same violations you're trying to fix.
{ "action": "read_files", "files": [{ "path": "lib/my_module.ex", "ranges": ["45-80"] }], "format": "outline" }synapse_modify_files — PROEdit code with safety guarantees — lint-validated and automatically rolled back on failure.
This is one of our proudest features. A naive write raw file by an agent is dangerous — a failed linter can cause broken file, half-written or commit that doesn't compile. write_safeely eliminates all class failures by simulating edit in memory, running your project own linter, and writing only if valid. If fails, original file remains intact.
Action | Tier | Description |
| PRO | Simulate, validate, lint, all write atomically. Autonomous on failure _automatic on failure — the file's never remains broken |
| PRO | Global search / replace across the indexed graph. |
| PRO | Removes a whole chunk from the graph/index. A no deletion of source: use evidence |
Aconstantly vendía together instantasynapse_get_context (edit) before to understand the callers and the impact.
{ "action": "write_safely", "path": "lib/my_module.ex", "content": "..." }synapse_change_review — PROReview diffs and assess the risk/h impact before pushing.
Before push, Synapse maps every chunk in the diff, sorts risk, identifies broken contracts and indicates which tests run. It replaces a manually review that typically takes 20-40+ minutes for a medium change.
|:
| analyse_diff | Analiza structural diff: which chunks only happened, what affects |
| review_diff | Full code review: risk ranking, blind spots, broken contracts, recommended tests |
| impact | Post-edit beat radius check — check what a commit change affects |
They goes a raw diff string or commit rango. Get actionreliable output before pushing.
{ "action": "review_diff", "diff": "..." }synapse_codebase_insights — FREEAnalysis at codebase in a single call. Use the dead_code action (usually via ask_synapse) to get level of evidence function whether a symbol or chunk is actually in use or if it is safe to delete.
|:
| detect | Detección de lengua gage across workspace |
| public_api | Extract public API surface from module or entire codebase |
| dead_code | Read test deletion if with only-le/at-symbol level: given chunk_id or symbol qualified, returns production callers, test callers, confidence, caveats, and safe_to_delete |
| contracts | Searches for interface contracts/behaviors/protocols and their implementations |
| dependencies | Graph of dependencies between modules — who imports whom |
| overview | Consolidated high-level views of code architecture |
| refactor_opportunities | Identifies points: logic duplicated logic duplicated, modules overweight, coupling tight coupling |
{ "action": "overview", "repo_id": "my-org/my-repo" }Feedback deletion questions should enter through usual ask_synapse so the routing, missing-entry 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" }
}Si no hay un chunk_id disponible, pasa repo_id junto con un símbolo con aridad explícita, como Parser.parse/2; la prosa descriptiva debe generar una aclaración o candidatos, no una decisión de eliminación adivinada.
Interpreta dead_code leyendo preferred_identifier, valid_input_patterns, scope, clause_level_analysis, safe_to_delete, deletion_risk, confidence, caveats y supporting_evidence.production_callers / supporting_evidence.test_callers. dead_code es de nivel de función; la alcanzabilidad a nivel de cláusula se informa actualmente como no compatible. Los llamadores en producción implican conservarlo; los llamadores solo de pruebas y la visibilidad desconocida deben presentarse como precaución, no como eliminación automática.
synapse_test_quality — PRODescubrimiento de pruebas y análisis de cobertura: no requiere ejecutor de pruebas.
Obtiene la cobertura y las carencias de prueba directamente del grafo AST, sin ejecutar ni una sola prueba. Esto es especialmente potente en bases de código grandes, donde una suite de pruebas completa tarda minutos en ejecutarse. Synapse te dice qué está cubierto, qué no y dónde centrarse a continuación, en segundos.
Acción | Descripción |
| Análisis por bandas de cobertura: qué funciones están probadas y cuáles tienen huecos |
| Localiza pruebas relacionadas con un símbolo o archivo específicos, ordenadas por confianza |
| Lista clasificada de las funciones que más necesitan pruebas según el grafo |
| Configura Trunk para la integración de linting |
{ "action": "find_tests", "symbol": "PaymentService.charge" }synapse_debug_trace — PRODepuración y trazado de ejecución directamente desde el grafo de AST.
Pega un stack trace sin procesar y obtén un análisis de causa raíz que asigna cada frame directamente a tus chunks indexados, con una prueba de reproducción sugerida y la cadena de llamadas que llevó hasta allí. Sin runtime, sin depurador, sin necesidad de volver a ejecutar el escenario de fallo.
Acción | Descripción |
| Pega un stack trace y obtén un análisis de causa raíz asignado a tu grafo con sugerencias de prueba de reproducción. No se necesita runtime |
| Rastrea la ruta de ejecución de un comportamiento o callback a través del grafo |
{ "action": "resolve_stack", "stack_trace": "..." }synapse_knowledge_cache — PROLa capa de aprendizaje y refuerzo. Conocimiento persistente que sobrevive entre sesiones.
Esta es la capacidad más singular de Synapse. Consulta Synapse Learns From Every Session para una explicación en lenguaje sencillo de cómo funciona.
Acción | Descripción |
| Asocia una descripción en lenguaje claro a un chunk. Toda futura consulta que lo encuentre recibirá tu explicación sin coste |
| Busca en la caché por intención y recupera los resultados promocionados de sesiones anteriores |
| Promociona explícitamente un chunk para una consulta, mejorando de inmediato la clasificación futura |
| Encuentra chunks con mucho tráfico que no tengan resumen; invertir aquí mejora todas las futuras sesiones |
{ "action": "save_summary", "chunk_id": "abc123", "summary": "Handles Stripe webhook validation and idempotency checks." }synapse_manage_repos — FREERegistrar, listar y gestionar repositorios en el grafo de Synapse.
Acción | Descripción |
| Lista todos los repositorios registrados con su estado de indexación |
| Registra una nueva raíz de repositorio. Detecta automáticamente los Git worktrees para una indexación solo delta |
| Pausa la indexación de un repositorio sin eliminar sus datos |
| Reactiva un repositorio archivado |
| Descarta un aviso de worktree combinado y sucio (dirty-merged) y mantén la superposición tal cual |
| Elimina un repositorio del grafo por completo |
| Actualiza los patrones glob que excluyen rutas de la indexación. |
{ "action": "register", "path": "/path/to/my-repo" }synapse_indexer_control — FREEComprobaciones del estado del sistema y administración del índice.
Acción | Descripción |
| Fase actual de indexación, conteo de archivos, preparación de embeddings y estado por repositorio |
| Comprobación de salud del sistema: confirma que el servidor está en marcha y que la tienda de grafo es accesible |
| Activa manualmente el reindexado para un repositorio específico |
{ "action": "status", "repo_id": "my-org/my-repo" }synapse_capability_manifest — FREESuperficie de herramientas autodocumentada. Devuelve la lista completa de herramientas, acciones y parámetros disponibles para la versión de Synapse en uso. Es útil para los agentes que inicializan un nueva sesión o que comprueban las funciones disponibles en el servidor conectado.
{}Indexación delta — solo se reindexan los archivos modificados, añadidos o eliminados. Casi instantánea (< 50 ms).
Prioridad de superposición — los chunks del worktree ensombrecen automáticamente los chunks del repositorio principal.
Flujos de trabajo con agentes en paralelo — abre varios subagentes en worktrees separados sin duplicar el índice principal.
Synapse implementa el Model Context Protocol, Specification abierta. Si tu herramienta habla MCP, se integra con Synapse.
IDEs y editores: Cursor · Windsurf · VS Code · Zed · JetBrains AI
Agentes: Claude Code · GitHub Copilot · Devin · Aider · Cline · Continue.dev · Replit Agent · Amazon Q · OpenHands · SWE-agent · Plandex · Antigravity
Herramientas: Sourcegraph Copy · Q.odo · Tabnine
Instalación completa e instalador con interfaz gráfica: synapse-mcp.dev/download
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | shDescarga y ejecuta el script de instalación — revísalo primero
powershell -c "irm https://downloads.synapse-mcp.dev/install.ps1 | iex"Ejecútalo desde PowerShell — revísalo antes de ejecutar
El instalador detecta automáticamente tu cliente MCP (Cursor, Claude Code, Windsurf, VS Code, etc.) y ajusta la configuración correcta.
100 % local. Synapse se ejecuta por completo en tu máquina. No sale ningún código de tu entorno, no hay dependencias en la nube, no hay salida de datos. Tu código sigue siendo tuyo.
Esta es la contribución de mayor impacto que puedes hacer.
Los LLM se entrenan con miles de millones de líneas de código en las que los desarrolladores recurren a grep, find, cat y ls para explorar una base de código. Esta memoria muscular está grabado en los pesos del modelo. Cuando un agente llega a un proyecto nuevo, su primer instinto es utilizar grep — aunque haya una herramienta más inteligente y económica disponible.
Synapse incluye un conjunto de archivos de habilidades para agentes (.agents/skills/synapse-mcp/SKILL.md, AGENTS.md) que los agentes cargan al iniciar la sesión. Estos archivos anulan el instinto de usar grep para resolver, proporcionando a los agentes reglas de enrutamiento explícitas, antespacios y ejemplos de llamadas a herramientas. De hecho, son entrenamiento en el meta — enseñan a los agentes cómo usar las herramientas de las que disponen, no solo en qué consisten.
El problema: solo podemos escribirlos lo que observamos. Tal vez hayas visto modos de fallo, zonas del enrutamiento o fórmulas que tu agente concreto ignora. Nosotros no. Los archivos de habilidades mejoran muchísimo con informes de uso reales.
Área | What to contribute |
Antipatrones | Comportamientos del agente que hayas visto y que Synapse debería suprimir (p. ej., "mi agente sigue usando |
Reglas de enrutamiento | Casos en los que un agente ha fallado la herramienta incorrecta de Synapse — cuál era la consulta y qué tenías que hacer |
Frraseos que funcionan | Si una redacción determinada impide estudiáblemente que tu agente caiga en |
Peculiaridades por agente | Claude, GPT-4o, Gemini y Copilot tienen distintas tendencias. Las secciones |
Nuevos ejemplo de herramientas | Ejemplos de JSON concretos para otras no cubiertas aún en la skill |
Flujos de trabajo que faltan | Escenarios (depuración, cambio de explic) en los que la skill no da línea |
Abre una incidencia — describe el modo de fallo o la carencia que observadas. Incluyes el agente, la consulta y qué hizo frente a lo que debería o no.
Abre un PR — edita directamente AGENTS.md o .agents/skills/synapse-mcp/SKILL.md. Las solicitudes de cambio de los archivos de skill se revisan y fusionan con rapidez — no requieren pruebas.
Comparte un benchmark — si has ejecutado Synapse contra las herramientas de shell sobre tu propia base de código y tienes números, nos guste publicarlos.
Los archivos de skill están en la raíz del repositorio y en .agents/. Son Markdown sencillo: no se requieren conos de Elixir. Si puedes describir qué fue mal, puedes escribir el arreglo.
Synapse brindan a tus agentes actuales un mapa de precisión de tu base de código. Myelix Agents es el paso siguiente: agentes de codificación con IA creados desde cero para pensar antes de codificar.
Mientras que los agentes actuales reaccionan (leer un archivo, escribir un cambio y esperar lo mejor), Myelix Agents planifica: mantienen un modelo de tarea for explicada, razonan sobre el riesgo antes de tocar el código, incorporan los aprendizajes de sesiones anteriores (a través del grafo de conocimiento de Synapse) y corrigen el rumbo cuando algo sale mal. Precisión sobre velocidad. Pensar sobre grep.
Los suscriptores de Synapse Pro obtienen acceso anticipado. Únete a la lista de espera →
¿Necesitas ayuda? Abre una incidencia y te respondemos. Se aceptan informes de errores, solicitudes de funciones y preguntas sobre integración.
🌐 synapse-mcp.dev — Sitio y documentación
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.
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_qualityScored across 14 tools
Each 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.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
