Loading ToolBench
Persistent code-knowledge memory across AI chat sessions (MCP server)
Cerebro has 16 well-named, verb-prefixed tools with clear, detailed descriptions (avg ~150 chars). All tools have documented input schemas with types and descriptions. Output is compact and token-efficient by design. However, output schemas are not formally documented (only inferred from code), and error handling lacks recovery guidance. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Parameter descriptions are strong but some tools lack enum constraints where appropriate (e.g., cerebro_search could constrain query type).
Every call site of a symbol (function/class) by name. Resolves by name only (no type inference), so results may include same-named symbols from different files.
Internal calls a file makes — callees that resolve to a symbol defined somewhere in the repo (external library calls are dropped).
Circular dependencies in the codebase (structural debt). Each cycle is a list of files that import each other, directly or indirectly.
Symbols (functions, classes) defined but never called within the repo. Candidates for removal.
Backend HTTP endpoints (NestJS controllers) exposed by the codebase. Optionally filtered by query (method, path, handler, file).
Everything Cerebro knows about a file WITHOUT reading it: cached summary (with staleness flag), defined symbols, and dependency edges.
Output schemas not formally documented. Code infers structure (e.g., cerebro_get returns text with sections like '# path', 'Summary:', 'Symbols:', 'Imports'), but LLMs cannot parse unstructured text reliably. Should return structured JSON with typed fields (path, summary, symbols[], dependencies[]).
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools clearly declare Risk: READ_ONLY or WRITE in metadata, but MCP tool definitions lack these hints. Agents cannot infer safety/idempotency without explicit annotations.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | B | 71 | 2026-07-28+ | v2 |
Transitive blast radius: every file that directly OR indirectly imports `path`. Use before changing a widely-used file to see what could break.
Cheap whole-project overview: file/language counts and the most important modules ranked by dependency centrality (PageRank). Call this FIRST in a new session instead of exploring folders.
Record a decision, domain rule, or gotcha — the *why* that reading code can never recover (e.g. 'QR_MANUAL = merchant confirms payment by hand', 'Seller was refactored to Organization'). Future sessions retrieve it with cerebro_recall. Keep `content` to 1-3 sentences; `topic` is an optional short tag.
Files with no incoming or outgoing imports (isolated modules). Useful for finding dead code or entry points.
Recall decisions/rules/gotchas recorded by past sessions BEFORE re-deriving them. Pass a query to search by meaning of topic/content, or leave empty for the most recent notes.
Leave a trace: store your English understanding of a file so future sessions reuse it instead of re-analyzing. Write 1-3 dense sentences in English describing what the file does and its role.
Refresh the static index (symbols, dependency edges, hashes). Only changed/new/deleted files are reprocessed. Pass `paths` to limit scope.
Find relevant files. When the semantic index is built it ranks by meaning (intent), so phrase queries naturally ("where do we validate stock at checkout?"); it also includes keyword/symbol matches. Returns paths to cerebro_get().
What the index no longer trusts: files changed/added/deleted on disk since the last reindex, plus summaries whose source file has changed.
Catch changes made outside Claude Code (branch switch, git pull, edits in the raw editor) and reindex only the affected files. Works across nested repos.
Error handling lacks recovery guidance. Code returns bare strings like 'Index is empty. Run cerebro_reindex() first' (good), but most error paths are implicit (e.g., file_row is None → returns string). No structured error responses with error codes, categories (retryable/user-fixable/fatal), or next-step hints.
Path resolution complexity hidden from LLM. cerebro_get and others accept 'absolute, relative, or repo-relative' paths and resolve them via _resolve_path(). LLM must guess which format to use. Should document expected format in parameter description and validate early with clear error messages.
cerebro_search returns mixed format (semantic results with scores, then keyword results). No pagination or limit enforcement in output. Large codebases could return 100+ results, bloating context. Should cap at documented limit (15 default) and return structured array with consistent fields.