All 16 Agent Tools, one MCP reference.

Unified lexical, content, exact-symbol, and file retrieval.

• symbols
• content
• symbol
• file

• mode · symbols
• limit · 15
• includeContent · false
• exact · false
• caseSensitive · false
• regex · false
• offset · 0

• Indexed matches with file and line provenance
• Exact symbol or bounded file source in retrieval modes
• Freshness state where available

• Missing mode-specific query, symbolName, or filePath
• Invalid regular expression
• Unknown or mode-irrelevant option

For lexical/exact retrieval use this tool. For natural-language questions over the codebase use `bb_ask` (semantic, cited answers).

Paths, line ranges, symbol kinds, and source snippets are indexed evidence; stale flags qualify that evidence.

Pagination and result limits bound retrieval; exact indexed lookup is preferred over content scanning.

Freshness modes (registered as freshnessModes): symbol, content, file. Staleness surfaces as: per-row stale flags + freshness block ({ fresh, stale, missing, staleRatio, mode, remediation }). When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Natural-language answers and semantic matches.

• answer

Planned (roadmap, not executable today): explainfeature

• limit · 5

• Natural-language answer
• Ranked semantic matches
• Similarity and source provenance

• Empty query
• Unavailable index or embedding state
• Unknown option

For exact symbol/content/file retrieval use `bb_search`; this tool answers natural-language questions with citations.

Treat matched symbols and resolvable source locations as evidence; treat generated explanation as interpretation.

The limit bounds returned semantic matches; embedding coverage and model choice affect ranking quality.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Unified index, schema, freshness, embeddings, runtime, integrity, and analysis history.

• status
• refresh

• verbose · false
• history · false
• limit · 20
• refresh · false
• force · false
• wait · true
• freshness · sampled
• sampleSize · 200
• integrity · false
• includeAnalysisRuns · false

• Index, schema, runtime, freshness, and embedding health
• Optional integrity and analysis-history summaries
• Typed warnings and refresh outcome

• Invalid freshness or sample settings
• Refresh/index failure
• Unknown option

For index size/counts use `bb index status` (CLI) or the stats surface; this tool reports index health and integrity.

Counts and versions come from the brain database; freshness compares indexed metadata with the filesystem.

Sampled freshness is the default; complete freshness and integrity checks intentionally cost more.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Pattern/orphan analysis with optional persisted run history.

• orphaned
• all

Planned (roadmap, not executable today): qualityarchitecture

• scope · all
• limit · 20
• includeOrphaned · true
• includeFramework · true
• includeAntiPatterns · true
• confidenceThreshold · 0.6
• history · false
• recordRun · false

• Pattern findings with confidence and locations
• Orphan, framework, and anti-pattern classifications
• Optional persisted run history

• Invalid scope or confidence threshold
• Unavailable index
• Unknown option

For security-specific taint findings use `bb_security`; this tool covers orphans, framework patterns, and anti-patterns.

Every finding is confidence-qualified and tied to indexed files, symbols, or relationships.

The result limit and confidence threshold bound reporting; history access is separately limited.

Freshness applies to the tool's read output (no registered per-mode split). Staleness surfaces as: per-finding [stale] markers + counts footer naming the remediation; silent when all fresh. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Cross-language findings with optional persisted run history.

• findings

Planned (roadmap, not executable today): flowsummaryhotspots

• history · false
• recordRun · false
• limit · 20

• Normalized security findings
• Cross-language source-to-sink flow evidence
• Optional persisted run history

• Unavailable index
• Invalid history limit
• Unknown option

For general code-quality patterns use `bb_patterns`; this tool focuses on taint flows and security findings.

A finding is supported by indexed source/sink locations and relationship paths; severity does not imply exploitability.

Indexed flow analysis and output/history limits bound work and response size.

Freshness applies to the tool's read output (no registered per-mode split). Staleness surfaces as: per-finding [stale] markers + counts footer naming the remediation; silent when all fresh. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Scoped canonical dependency graphs with explicit truncation and provenance.

• project
• file
• module
• symbol
• feature

• scope · project
• maxNodes · 200
• maxLinks · 5000
• format · text

• Canonical nodes and links
• Text, JSON, or self-contained HTML projection
• Provenance and explicit truncation metadata

• Missing target for a scoped graph
• Unsupported scope or format
• Unavailable index

For raw graph data use `bb_graph`; this tool renders diagrams with truncation metadata.

Nodes and links resolve to canonical indexed entities; links with omitted endpoints are not emitted.

maxNodes, maxLinks, scope, relationshipTypes, and languages constrain graph construction.

Freshness applies to the tool's read output (no registered per-mode split). Staleness surfaces as: per-node and per-link stale flags (links inherit worst-of-endpoints) + freshness envelope ({ fresh, stale, missing, staleRatio, mode, remediation }) on JSON; truncation composes with staleness. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Batch cross-language migration plans with ordering, methodology, and unsupported mappings.

• plan

• format · text

• Dependency-ordered migration plans
• Effort methodology, library mappings, and risks
• Explicit unsupported and truncation results

• Missing targetLanguage
• No symbolName or symbolNames
• Unknown option

For dependency structure use `bb_graph`; this tool produces migration plans with declared limitations.

Dependency ordering comes from indexed relationships; effort and mappings are labeled methodology-driven estimates.

Requests are capped at 100 symbols and dependency traversal is bounded.

Freshness modes (registered as freshnessModes): plan. Staleness surfaces as: per-plan sourceFile + stale flags with an up-front stale-plan notice + freshness envelope ({ fresh, stale, missing, staleRatio, mode, remediation }) on JSON. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

One typed analysis surface replacing standalone relationship and test intelligence names.

• callers
• callees
• trace
• dependencies
• stats
• complexity
• impact
• test_mapping
• test_gaps
• test_impact
• test_quality

• limit · 20

• Mode-specific typed analysis
• Graph, dependency, complexity, impact, or test evidence
• Explicit unavailable and truncation states

• Missing required mode
• Missing target for a target-based mode
• Option irrelevant to the selected mode

For the plain per-symbol call graph use `bb_graph` (same engine, evidence tiers). For bounded impact-with-files use mode `impact` (numbers identical to `bb_impact`).

Findings derive from brain_* symbols, files, relationships, complexity, and test-file classifications.

Mode-specific limits and graph traversal bounds prevent unbounded output.

Freshness modes (registered as freshnessModes): callers, callees, trace, dependencies, stats, complexity, impact, test_mapping, test_gaps, test_impact, test_quality. Staleness surfaces as: freshness block ({ fresh, stale, missing, staleRatio, mode, remediation }); graph nodes and report rows carry stale flags (project-wide modes sample or resolve visible rows only — the block names its coverage mode). When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Cited Markdown or JSON documentation over indexed source and relationships.

• symbol
• file
• module
• feature
• api
• project
• coverage

• format · markdown
• audience · developer
• detail · standard
• includeExamples · false
• includeDiagrams · false
• includeTests · false
• limit · 20
• maxTokens · 4000

• Markdown or structured JSON documentation
• Resolvable citations and evidence classifications
• Quality and website reference metadata

• Missing target for target-based mode
• Unsupported format or mode
• Unavailable indexed evidence

For raw symbol metadata use `bb_search` mode `symbol`; this tool composes documented, cited explanations.

Claims are classified as extracted, inferred, generated, or unknown and carry resolvable citations where applicable.

Evidence count and maxTokens impose explicit response budgets.

Freshness applies to the tool's read output (no registered per-mode split). Staleness surfaces as: freshness envelope ({ fresh, stale, missing, staleRatio, mode, remediation }) on JSON + footer naming the remediation; per-citation (stale) in Sources; silent when all fresh. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only); file scope → reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path). Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in src/brain/freshness.ts).

Unified safe source editing with preview, validation, rollback, and reindex.

• write
• update
• insert
• delete
• refactor

• dryRun · false
• format · true
• force · false

• Structured mutation result or dry-run preview
• Validation, formatting, rollback, and reindex status
• Affected paths and caller protection outcomes

• Path escape or symlink escape
• Stale or ambiguous indexed symbol bounds
• Caller protection, parse, formatting, or reindex failure

To attach human-visible notes to symbols use `bb_annotate`; this tool mutates source files.

Mutation bounds come from indexed AST bytes; validation and reindex state report whether post-edit evidence is current.

Only affected files are written, formatted, validated, and reindexed.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Immediately refresh the index for a just-written/edited file or directory; mode=post re-derives relationships/taints/health without re-parsing.

• auto
• file
• dir
• post

• mode · auto

• Indexed, deleted, and error counts for the refreshed path
• Mode actually applied (auto resolved, file, or dir)
• Per-file error names for any file that failed to reindex

• Missing path
• Path outside the project root
• Parse or store failure for an individual file

The CLI twin is `bb index` (same semantics; see docs/MCP_CLI_INDEXER_GUIDE.md). Refresh changed files after agent edits with mode `dir`/`file` or the CLI `--changed`.

Counts come from the real parse/store pipeline; errors name the file that failed rather than swallowing it.

A single file reindex is bounded by that file's parse cost; dir mode is bounded by the changed-file set.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Per-symbol graph with per-edge evidence tiers — the agent view of the editor's graph panel.

• graph

• maxDepth · 3

• Per-symbol dependency graph: callers and callees
• Per-edge evidence tier (structural/import_based/usage_contextual/reference_qualified/inferred) with confidence
• Declared truncation with a reason when the traversal is bounded

• Missing symbol
• maxDepth outside the declared 1-10 range
• Symbol not found in the index

For richer analysis (dependencies, complexity, tests, impact aggregation) use `bb_analyze`; for plain callers/callees with evidence tiers this is the tool.

Nodes and edges come from the canonical graph engine over brain_symbol and brain_relationship rows; each edge carries its evidence tier and confidence.

maxDepth (default 3, max 10) bounds traversal; per-edge evidence resolution is bounded by the returned subgraph.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Bounded impact with declared truncation — identical numbers to the editor's impact mode.

• impact

No declared defaults — every option is explicit.

• Downstream dependents of the symbol with per-edge evidence tiers and confidence
• Declared-absent result when the symbol is unknown — never an empty guess

• Missing symbol
• Symbol not found in the index

This is the bounded-impact specialist; `bb_analyze` mode `impact` aggregates the same canonical walk with file-level risk — the numbers are identical by gate.

Impact derives from brain_relationship rows via the same engine the editor impact panel uses.

Traversal bounds match the canonical graph engine limits; output scales with the dependents subgraph.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Stored cross-language pairs with declared absence — the agent view of the hover section.

• cross-language

No declared defaults — every option is explicit.

• Cross-language relationship pairs for the symbol with bridge mechanism and evidence tier
• Declared-absent result when no stored cross-language rows exist

• Missing symbol
• Symbol not found in the index (declared, not an empty set)

For same-language callers/callees use `bb_graph`; this tool reports cross-language pairs and bridges (declared absent when none).

Only brain_relationship rows with is_cross_language=1; identical semantics to the editor cross-language hover section.

Bounded by the stored cross-language rows for the symbol; no graph traversal.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Agent note with enforced provenance, stored where the human reads.

• annotate

No declared defaults — every option is explicit.

• Stored annotation id and provenance (tool identity, timestamp)
• Declared refusals for missing symbol, empty body, or over-limit body

• Missing or unknown symbol
• Empty body (a refusal, not a silent no-op)
• Body exceeds the declared 2000-char limit

To change source code use `bb_edit`; this tool stores provenance-enforced notes on symbols.

Annotations carry provenance (toolIdentity, time) and are stored in brain_annotation.

Constant-time store write bounded by the 2000-char body limit.

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).

Annotations with full provenance; absence declared.

• annotate

• limit · 50

• Typed annotations for a symbol or the whole project, with full provenance (author class, tool identity, timestamps)
• Declared-absent result when none exist — absence is never an error

• limit outside the declared 1-200 range

To write a note use `bb_annotate`; this tool reads stored annotations and declares absence.

Rows come from brain_annotation with provenance fields preserved.

Indexed lookup by project and symbol (brain_annotation_project_symbol_idx).

This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first (project scope: reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)).