Tool Matrix SSOT
Machine-oriented routing matrix for the current m1nd tool surface.
Source Of Truth
m1nd-mcp/src/server.rstool schema registry and the livetools/listresponse are the callable surface. Usetools/listfor the exact count in your current build.- This matrix is the routing SSOT for the canonical tool surface used by agents and LLMs.
- Any page that advertises a fixed tool count can drift. Treat
tools/listas counting truth.
Row Contract
| field | meaning |
|---|---|
command | canonical bare MCP call name returned by tools/list |
category | routing bucket |
core_function | shortest truthful description of what the tool does |
choose_when | positive routing trigger |
avoid_when | disqualifier / better alternative |
required | minimum required args |
returns | stable output surface an LLM can plan around |
next | adjacent tools / likely next hop |
Foundation
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
ingest | Parse a codebase, markdown docs, or JSON domain graph into the semantic graph. | Start or refresh graph truth for a repo, file, docs corpus, or descriptor before higher-order queries. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; path | graph_counts; files_scanned; files_parsed; nodes_created; edges_created; elapsed_ms | activate -> impact -> why |
activate | Spreading activation query — fires signal into the graph and returns a 4D-scored activation pattern. | Use when the query is associative or subsystem-shaped and you want connected structure, not exact text. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; query | seeds; activated; ghost_edges; structural_holes; plasticity; elapsed_ms | activate -> impact -> why |
impact | Blast radius of a code change — BFS-propagated signal strength from a source node. | Use before edits to estimate blast radius. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; node_id | blast_radius; total_energy; causal_chains | activate -> impact -> why |
why | Shortest path between two nodes — understand how A depends on B. | Use to explain how two nodes are connected. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; source; target | path; hops; edge_types; path_weight | activate -> impact -> why |
learn | Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly. | Hebbian feedback — tell the graph which results were correct or wrong. Edge weights strengthen or weaken accordingly. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; query; feedback; node_ids | edges_modified; trust_records_updated; tremor_observations_recorded | activate -> impact -> why |
drift | What changed in the graph since your last session — structural delta for context recovery. | What changed in the graph since your last session — structural delta for context recovery. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id | baseline; changed_nodes; weight_drift; summary | activate -> impact -> why |
health | Server diagnostics — verify the MCP server is alive and the graph is loaded. | Server diagnostics — verify the MCP server is alive and the graph is loaded. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id | node_count; edge_count; sessions; graph_state | activate -> impact -> why |
seek | Find code by natural language intent — more targeted than activate for specific lookups. | Use when you know the purpose of code but not its location. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; query | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
scan | Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string. | Run structural pattern scanners. Use a predefined pattern ID or a custom pattern string. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; pattern | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
timeline | Temporal evolution of a node — change history, co-change partners, velocity, stability. | Temporal evolution of a node — change history, co-change partners, velocity, stability. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; node | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
diverge | Structural drift analysis — compare graph state against a baseline reference. | Structural drift analysis — compare graph state against a baseline reference. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; baseline | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
warmup | Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance. | Prime the graph for an upcoming task — pre-activates seed nodes to improve subsequent query relevance. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; task_description | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
federate | Unify multiple repositories into one graph — cross-repo blast radius and dependency analysis. | Use when you already know the repo list to unify. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id; repos | tool-specific JSON payload; inspect API reference / tools/list | activate -> impact -> why |
federate_auto | Discover candidate sibling repositories from explicit external path references, local manifest/workspace hints, import/package-name evidence, shared API-route signals, or basic contract artifacts and optionally execute federation in one step. | Use when you suspect neighboring repos matter but only have path/import/contract evidence. | Avoid when you already have the exact file/line or only need raw compiler/runtime truth. | agent_id | discovered_repos; suggested_repos; executed; federate_result | activate -> impact -> why |
Document Intelligence
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
document_resolve | resolve canonical local artifacts for a universally ingested document | Use when a doc already exists in the graph and you need the local canonical artifact paths. | Avoid when you only need a fresh ingest or raw source text. | agent_id | canonical_markdown_path; canonical_json_path; claims_path; producer; binding_count; drift_summary | document_bindings -> document_drift -> view |
document_provider_health | report optional provider availability, mode, detail, and install hints | Use before relying on richer HTML/PDF/office extraction or when a provider lane seems to be falling back unexpectedly. | Avoid when provider setup is irrelevant to the current task. | agent_id | python; providers[] | ingest -> document_resolve -> auto_ingest_start |
document_bindings | show deterministic document-to-code bindings for a universal document | Use when the question is “which code implements this doc?” or “what should I inspect first?” | Avoid when you only need the artifact paths or provider status. | agent_id | bindings[]; source_path | document_drift -> impact -> surgical_context_v2 |
document_drift | detect stale, missing, or ambiguous document/code links | Use after refactors, repo moves, or suspected stale specs. | Avoid before the document has been ingested or bound. | agent_id | findings[]; summary | document_bindings -> impact -> timeline |
auto_ingest_start | start local-first document watchers for supported roots and formats | Use when a docs/specs/wiki root should stay synchronized with the graph while you work. | Avoid for one-shot ingest or read-only inspection. | agent_id; roots | running; provider_status; bootstrap | auto_ingest_status -> auto_ingest_tick -> document_resolve |
auto_ingest_status | inspect the document auto-ingest runtime, semantic counts, provider status, and route/fallback counts | Use to monitor watcher state, queue depth, or document runtime telemetry. | Avoid if you only need a direct document refresh or binding result. | agent_id | running; queue_depth; semantic_*; provider_*; recent_events | auto_ingest_tick -> document_drift -> document_provider_health |
auto_ingest_tick | drain queued document changes immediately and apply them to the graph | Use when a caller needs deterministic immediate reconciliation instead of waiting for opportunistic ticks. | Avoid when no watched roots are active. | agent_id | ingested_paths; removed_paths; skipped_paths; errored_paths | document_resolve -> document_drift -> lock_diff |
auto_ingest_stop | stop document watchers and persist manifest state | Use when shutting down or changing watched roots. | Avoid during active watch-driven reconciliation you still need. | agent_id | stopped; manifest_entries | auto_ingest_start -> auto_ingest_status |
Perspective Navigation
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
perspective_start | Open a perspective anchored to a node. Perspectives are stateful navigation sessions. | Open a perspective anchored to a node. Perspectives are stateful navigation sessions. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; query | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_routes | List available navigation routes from the current focus node. | List available navigation routes from the current focus node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_follow | Move the perspective focus to a route target. | Move the perspective focus to a route target. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_back | Navigate backward to the previous focus node. | Navigate backward to the previous focus node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_peek | Read source code at the currently focused node (returns file content at the node’s location). | Read source code at the currently focused node (returns file content at the node’s location). | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_inspect | Deep metadata + 5-factor score breakdown for a route’s target node. | Deep metadata + 5-factor score breakdown for a route’s target node. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_suggest | AI navigation recommendation — the graph suggests which route to follow next. | AI navigation recommendation — the graph suggests which route to follow next. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_affinity | Check route relevance to the current investigation. | Check route relevance to the current investigation. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_branch | Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings. | Fork an independent perspective copy for parallel exploration. Two agents can investigate the same starting point independently, then compare findings. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_compare | Diff two perspectives — shared nodes, unique nodes, divergent findings. | Diff two perspectives — shared nodes, unique nodes, divergent findings. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id; perspective_id_a; perspective_id_b | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_list | All active perspectives for this agent, with memory usage. | All active perspectives for this agent, with memory usage. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
perspective_close | Release perspective state and free memory. | Release perspective state and free memory. | Avoid for stateless one-shot lookups; prefer seek/search/view when you do not need navigation state. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | perspective_routes -> perspective_follow -> perspective_inspect |
Lock System
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
lock_create | Snapshot a subgraph region. | Snapshot a subgraph region. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | agent_id; scope; root_nodes | tool-specific JSON payload; inspect API reference / tools/list | lock_watch -> lock_diff -> lock_rebase |
lock_watch | Register a change strategy on a lock. | Register a change strategy on a lock. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | lock_watch -> lock_diff -> lock_rebase |
lock_diff | Compare current graph state against the locked baseline. Returns changes since the lock was created. | Compare current graph state against the locked baseline. Returns changes since the lock was created. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | lock_watch -> lock_diff -> lock_rebase |
lock_rebase | Advance the lock baseline to the current graph state (after reviewing and accepting changes). | Advance the lock baseline to the current graph state (after reviewing and accepting changes). | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | lock_watch -> lock_diff -> lock_rebase |
lock_release | Free lock state and release memory. | Free lock state and release memory. | Avoid for solo read-only work; use only when coordination or baseline diffs matter. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | lock_watch -> lock_diff -> lock_rebase |
Superpowers
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
hypothesize | Test a claim against graph structure using Bayesian path scoring. 89% accuracy validated on 10 live claims against a production codebase. | Test a claim against graph structure using Bayesian path scoring. 89% accuracy validated on 10 live claims against a production codebase. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; claim | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
counterfactual | Simulate module removal — compute full cascade of what breaks. | Simulate module removal — compute full cascade of what breaks. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; node_ids | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
missing | Find structural holes — what should exist in a region of the graph but doesn’t. | Find structural holes — what should exist in a region of the graph but doesn’t. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; query | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
resonate | Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously. | Standing wave analysis — find structural hubs where signal reinforces across multiple dimensions simultaneously. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
fingerprint | Find structural twins — nodes with identical or near-identical topology. | Find structural twins — nodes with identical or near-identical topology. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
trace | Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality. | Map a stacktrace to root cause suspects — ranks files by suspiciousness × centrality. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; error_text | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
validate_plan | Pre-flight risk assessment for a set of planned changes — blast radius, gap count, risk score. | Use before editing or merging to pre-flight risk and test impact. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; actions | risk_score; gaps; suggested_additions; heuristic_summary | hypothesize -> validate_plan -> trace |
predict | Co-change prediction — given a file you just changed, which other files likely need changes too. | Co-change prediction — given a file you just changed, which other files likely need changes too. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; changed_node | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
trail_save | Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts. | Persist investigation state — hypotheses, conclusions, open questions, visited nodes, and activation boosts. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; label | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
trail_resume | Restore exact investigation context — nodes, weights, hypotheses — from a saved trail. | Restore exact investigation context — nodes, weights, hypotheses — from a saved trail. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; trail_id | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
trail_merge | Combine two or more agents’ independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses. | Combine two or more agents’ independent investigations. Auto-detects where they converged and flags conflicts on shared hypotheses. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; trail_ids | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
trail_list | Browse all saved investigations with optional filters. | Browse all saved investigations with optional filters. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
differential | Focused structural diff between two graph snapshots — surface what changed structurally between two points in time. | Focused structural diff between two graph snapshots — surface what changed structurally between two points in time. | Avoid for plain text lookup or trivial file reads; these are structural reasoning tools. | agent_id; snapshot_a; snapshot_b | tool-specific JSON payload; inspect API reference / tools/list | hypothesize -> validate_plan -> trace |
Superpowers Extended
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
antibody_scan | Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings. | Scan the graph against all stored bug antibody patterns (known bug shapes). Returns matches with confidence and bindings. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
antibody_list | List all stored antibodies with match history. | List all stored antibodies with match history. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
antibody_create | Create, disable, enable, or delete an antibody pattern. | Create, disable, enable, or delete an antibody pattern. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
flow_simulate | Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions). | Concurrent execution flow simulation — particles travel the graph in parallel, turbulence points are shared mutable state collisions (race conditions). | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
epidemic | SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs. | SIR epidemiological bug propagation — given known-buggy modules, predict which neighbors are most likely to harbor undiscovered bugs. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id; infected_nodes | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
tremor | Change frequency acceleration detection — identifies modules with accelerating change frequency. Acceleration precedes bugs, not just high churn. | Change frequency acceleration detection — identifies modules with accelerating change frequency. Acceleration precedes bugs, not just high churn. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
trust | Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries. | Per-module actuarial trust scores from defect history. More confirmed bugs = lower trust = higher risk weighting in activation queries. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
layers | Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations. | Auto-detect architectural layers from graph topology. Uses BFS longest-path depth assignment + Tarjan SCC for circular groups. Reports dependency violations. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
layer_inspect | Inspect a specific architectural layer: nodes, inter-layer connections, health metrics. | Inspect a specific architectural layer: nodes, inter-layer connections, health metrics. | Avoid before you have a scoped suspect area; these are deeper risk/simulation tools. | agent_id; level | tool-specific JSON payload; inspect API reference / tools/list | trust -> tremor -> heuristics_surface |
RETROBUILDER
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
ghost_edges | temporal co-change ghost edges from git history | temporal co-change ghost edges from git history | Avoid without git/runtime/security context; use only when that extra plane matters. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | runtime_overlay -> trace -> impact |
taint_trace | taint propagation over graph structure | taint propagation over graph structure | Avoid without git/runtime/security context; use only when that extra plane matters. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | runtime_overlay -> trace -> impact |
twins | structural equivalence / near-equivalence discovery | structural equivalence / near-equivalence discovery | Avoid without git/runtime/security context; use only when that extra plane matters. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | runtime_overlay -> trace -> impact |
refactor_plan | graph-native refactoring proposals | graph-native refactoring proposals | Avoid without git/runtime/security context; use only when that extra plane matters. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | runtime_overlay -> trace -> impact |
runtime_overlay | runtime heat and error overlays from OTel spans | runtime heat and error overlays from OTel spans | Avoid without git/runtime/security context; use only when that extra plane matters. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | runtime_overlay -> trace -> impact |
Surgical
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
heuristics_surface | Explain why a node/file ranked as risky or important. | Explain why a node/file ranked as risky or important. | Avoid before locating the target surface; use seek/search/impact first. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
surgical_context | Return complete context for a file in one call: full source, symbol table, callers, callees, and test coverage neighbours. Use before apply for single-file edits. | Use before single-file edits. | Avoid before locating the target surface; use seek/search/impact first. | agent_id; file_path | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
apply | apply now returns proactive_insights when a write lands on a risky or historically unstable surface. | Use to write one file and keep the graph coherent. | Avoid before locating the target surface; use seek/search/impact first. | agent_id; file_path; new_content | updated_node_ids; proactive_insights; elapsed_ms | heuristics_surface -> batch_view -> apply_batch |
view | Fast file reader with line numbers and optional auto-ingest. | Use when you already know the file and need bounded line-numbered reading. | Avoid before locating the target surface; use seek/search/impact first. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
surgical_context_v2 | Superset of surgical_context — returns the target file’s full contents AND source excerpts of all connected files (callers, callees, tests) in one call. Eliminates the need to read multiple files separately. Use before apply_batch when editing a file and its callers/tests together. | Use before multi-file edits where connected source context matters. | Avoid before locating the target surface; use seek/search/impact first. | agent_id; file_path | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
apply_batch | apply_batch now returns proactive_insights, and the final batch_completed progress event carries the same payload for streaming clients. | Use to write multiple files atomically and optionally verify. | Avoid before locating the target surface; use seek/search/impact first. | agent_id; edits | results; verification; proactive_insights; progress_events | heuristics_surface -> batch_view -> apply_batch |
edit_preview | Preview a write without touching disk. | Preview a write without touching disk. | Avoid before locating the target surface; use seek/search/impact first. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
edit_commit | Commit a previewed edit after confirmation and freshness check. | Commit a previewed edit after confirmation and freshness check. | Avoid before locating the target surface; use seek/search/impact first. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | heuristics_surface -> batch_view -> apply_batch |
Search & Efficiency
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
search | Unified literal/regex/semantic search — graph-aware grep replacement. Searches both node labels in the graph and file contents on disk, returning results with line context. | Use for exact text, regex, or semantic grep across graph + file content. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id; query | results; total_matches; proof_state; next_suggested_tool | search/glob -> batch_view -> coverage_session |
glob | Graph-aware file globbing over indexed files. | Use when you need files by path pattern, not content. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | search/glob -> batch_view -> coverage_session |
help | Self-documenting tool reference with m1nd’s visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions. | Self-documenting tool reference with m1nd’s visual identity. Returns a formatted index of all tools or detailed docs for a specific tool — including params, examples, and NEXT suggestions. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | search/glob -> batch_view -> coverage_session |
panoramic | Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts. | Full module risk panorama — ranked view of every file-level node by combined risk score. Combines blast radius, centrality, and churn into one sorted list. Critical modules (risk ≥ 0.7) trigger alerts. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | modules; critical_alerts; summary | search/glob -> batch_view -> coverage_session |
savings | Token economy report — session and global tracking of tokens saved by using m1nd instead of grep/glob, with CO2 estimation. | Token economy report — session and global tracking of tokens saved by using m1nd instead of grep/glob, with CO2 estimation. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | search/glob -> batch_view -> coverage_session |
report | Session summary — query log, timing statistics, tokens saved, and graph state for the calling agent. Provides a markdown-formatted report ready for display or logging. | Session summary — query log, timing statistics, tokens saved, and graph state for the calling agent. Provides a markdown-formatted report ready for display or logging. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | recent_queries; savings; hotspot_summary | search/glob -> batch_view -> coverage_session |
metrics | Return structural metrics per file/function/module. | Use when you want ranked structural measures, not semantic retrieval. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | entries; summary | search/glob -> batch_view -> coverage_session |
type_trace | Trace where a type/struct/enum is used across the graph. | Use when following a type across files and callsites. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | usages; file_groups | search/glob -> batch_view -> coverage_session |
diagram | Generate Mermaid or DOT graph diagrams. | Use when you need a visual graph slice for humans or downstream agents. | Avoid for write/plan validation; these help orientation and summary, not mutation safety. | agent_id | format; diagram; node_count | search/glob -> batch_view -> coverage_session |
Audit & Session
| command | core_function | choose_when | avoid_when | required | returns | next |
|---|---|---|---|---|---|---|
batch_view | multi-file read surface with stable delimiters and summaries | multi-file read surface with stable delimiters and summaries | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
scan_all | run all structural patterns in one call | run all structural patterns in one call | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
cross_verify | graph vs disk verification (existence, loc, hash) | graph vs disk verification (existence, loc, hash) | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
coverage_session | what this agent has visited so far | what this agent has visited so far | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
external_references | explicit paths outside ingest roots | explicit paths outside ingest roots | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
audit | profile-aware one-call audit | profile-aware one-call audit | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
daemon_start | activate the persisted daemon control plane and set watch roots / poll interval | activate the persisted daemon control plane and set watch roots / poll interval | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
daemon_stop | stop the daemon control plane without discarding alert history | stop the daemon control plane without discarding alert history | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | tool-specific JSON payload; inspect API reference / tools/list | audit -> batch_view -> cross_verify |
daemon_status | inspect daemon runtime state, watch roots, and alert counts | Use to inspect daemon liveness, tracked files, and recent tick metrics. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | active; tracked_files; tick_count; last_tick_duration_ms; last_tick_changed_files; last_tick_deleted_files; last_tick_alerts_emitted | audit -> batch_view -> cross_verify |
daemon_tick | poll watched roots once, incrementally re-ingest changed files, and emit deletion drift alerts | Use when you want one explicit delta-processing pass over watched roots. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | changed_files_detected; deleted_files_detected; files_reingested; alerts_emitted | audit -> batch_view -> cross_verify |
alerts_list | list persisted daemon/proactive alerts | Use to review durable daemon/proactive alerts. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | alerts; total; active | audit -> batch_view -> cross_verify |
alerts_ack | acknowledge one or more persisted daemon/proactive alerts | Use after reviewing alerts so they do not keep resurfacing. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | acked; requested; acked_at_ms | audit -> batch_view -> cross_verify |
persist | Force graph and sidecar state persistence to disk. | Use when you want to force-save graph and sidecars now. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | status; snapshot_path; plasticity_path | audit -> batch_view -> cross_verify |
boot_memory | Persist small canonical hot-state values next to the graph. | Use for tiny canonical doctrine/state values that should stay hot. | Avoid for tiny one-file questions; these are orchestration and session-shaping tools. | agent_id | action; key; value; entries | audit -> batch_view -> cross_verify |
Routing Rules
- Prefer the cheapest tool that preserves structural truth.
- Use
search/glob/viewfor exact known targets; useseek/activatewhen the question is semantic or subsystem-shaped. - Use
impact,predict,validate_plan, and the surgical tools before risky edits. - Use
audit,cross_verify,coverage_session,batch_view, and daemon tools to manage long-running sessions. - Use perspective and lock tools only when stateful navigation or multi-agent coordination is worth the overhead.