Query Tools
Core AST query operations exposed to AI agents through the act MCP server. Available for every supported language. These are the tools an agent calls to understand a codebase before changing it: skeleton, symbols, references, callers, graph, control_flow, mutations, get_type, repo_outline, and more.
Exploration
| Tool | Description | Parameters | Requires LSP |
|---|---|---|---|
repo_outline |
Get a compressed overview of the repository — file tree with languages and line counts. Scope it: unscoped on a medium repo this is ~10,000 tokens that stay in context for the rest of the session, where `depth`, `include` or `max_files` answer the same question for a few hundred. `symbols: true` adds every top-level name and multiplies the size again. Params: none [, path (string), depth (u32), include (glob), exclude (glob), symbols (bool), max_files (u32), relative (bool)] | none [, path (string), depth (u32), include (glob), exclude (glob), symbols (bool), max_files (u32), relative (bool)] |
— |
skeleton |
Get a file's structure — function signatures, class declarations, type definitions — without implementation bodies. Use INSTEAD of reading the full file to understand its API. Typically 5-10x fewer tokens than reading the raw file. Params: file (string) | file (string) |
— |
symbols |
List all symbols (functions, classes, variables, types, constants) defined in a file with their locations and kinds. Use INSTEAD of reading a file when you need to know what's defined in it. Much cheaper than reading the full file. IMPORTANT: file must be a path to a single source file — never a directory or empty string. Params: file (string) | file (string) |
— |
symbols_batch |
Retrieve symbols from multiple files in a single call, instead of calling symbols() in a loop. Pass `pattern` (name regex) or `kinds` unless you genuinely need every symbol: three medium files unfiltered is ~10,000 tokens and the same query filtered is ~300. If you want one symbol's location, `symbols` on its file with a pattern is cheaper still. Params: none [, files (string[]), ids (string[]), kinds (string[]), pattern (string)] — provide files or ids | none [, files (string[]), ids (string[]), kinds (string[]), pattern (string)] — provide files or ids |
— |
Navigation
| Tool | Description | Parameters | Requires LSP |
|---|---|---|---|
callers |
Find every call site of a function or method across the codebase. Use to understand who depends on a function before changing its signature. Requires LSP; the language server starts on the first call, and the answer names it in `resolved_by` (e.g. `lsp:rust-analyzer`). Params: symbol (string) [, file (string)] | symbol (string) [, file (string)] |
Yes |
definition |
Jump to definition — find where a symbol is defined given a usage location. Uses AST-based parsing by default, no LSP required. Params: symbol (string), file (string), line (u32), column (u32) | symbol (string), file (string), line (u32), column (u32) |
— |
graph |
Build a dependency graph from a file — trace what it imports and what imports it, across multiple hops. Use to understand module relationships and change impact before refactoring. Params: file (string) [, depth (u32), direction (string), leaves (bool), order (string)] | file (string) [, depth (u32), direction (string), leaves (bool), order (string)] |
— |
references |
Find every usage of a symbol across the entire codebase — all files, not just the current one. Use before renaming, refactoring, or deleting to understand full impact. Requires LSP; the language server starts on the first call, and the answer names it in `resolved_by` (e.g. `lsp:rust-analyzer`). Params: symbol (string), file (string) | symbol (string), file (string) |
Yes |
Understanding
| Tool | Description | Parameters | Requires LSP |
|---|---|---|---|
control_flow |
Get a function's control flow — branches, loops, early returns, and basic blocks in execution order. Use to understand complex logic without reading the full implementation. Params: target (string), file (string) | target (string), file (string) |
— |
data_flow |
Intra-procedural def-use — variable definitions, uses, def→use edges, and which locals flow into the return. The dual of control_flow. Single-file. Params: target (string), file (string) | target (string), file (string) |
— |
effect_closure |
Transitive effect closure of a function across the call graph — composed reads/writes/raises/allocates/blocks/awaits with provenance, recorded cycles, and the unresolved-call frontier. Params: target (string), file (string) [, max_depth (u32), max_nodes (u32)] | target (string), file (string) [, max_depth (u32), max_nodes (u32)] |
— |
effect_summary |
Get a function's effect signature — reads, writes, raises, allocates, blocking calls, and awaits — plus the unresolved-call frontier. Single-file, intra-procedural. Params: target (string), file (string) | target (string), file (string) |
— |
get_type |
Get the compiler-inferred type of any expression at a position. Use to understand types without reading surrounding code. Requires LSP. Params: file (string), line (u32), column (u32) | file (string), line (u32), column (u32) |
Yes |
interface |
Get a symbol's public API — signatures, types, and docstrings without implementation bodies. Like skeleton but for a single symbol. Use to understand how to call something without reading its internals. Params: target (string), file (string) [, include_private (bool)] | target (string), file (string) [, include_private (bool)] |
— |
mutations |
Identify side effects — what external state a function reads or writes (globals, file I/O, network, etc.). Use to understand if a function is pure or has hidden dependencies. Params: target (string), file (string) | target (string), file (string) |
— |
Verification
| Tool | Description | Parameters | Requires LSP |
|---|---|---|---|
diagnostics |
Preflight check: compiler errors and warnings from the language server. Run it once over the change, not once per file per turn — pass `files` with the paths you edited. `file` scopes to one path or directory; omitting both checks the workspace. Broad scopes list the first `limit` diagnostics (default 20) and summarise the rest as per-file counts, and the response is capped so it always fits in one reply. Requires LSP. Params: none [, files (string[]), file (string), limit (usize, default 20), errors_only (bool, default false)] | none [, files (string[]), file (string), limit (usize, default 20), errors_only (bool, default false)] |
Yes |
fix_auto |
Auto-fix all deterministic issues in a file, directory, or workspace — missing imports, unused imports, simple type errors. Runs multiple fix-revalidate cycles. Use after making changes to clean up automatically. Requires LSP. Params: none [, file (string), workspace_mode (bool), category (string), commit (bool), max_rounds (u32)] | none [, file (string), workspace_mode (bool), category (string), commit (bool), max_rounds (u32)] |
Yes |
import_organize |
Organize, sort, and deduplicate imports in a file. Removes unused imports. Use after adding new code or moving symbols to clean up import blocks automatically. Params: file (string) [, preview (bool)] | file (string) [, preview (bool)] |
Yes |