Tools Overview
codescout exposes 20 tools organized into seven categories. This page is a quick map. Each category has a dedicated reference page linked from the headings below.
Symbol Navigation
LSP-backed tools for locating and editing code by name rather than by line number. These tools require an LSP server to be running for the target language.
The navigation tools (symbols, references) accept an optional scope parameter to search library code as well as project code — see Library Navigation below.
| Tool | Description |
|---|---|
symbols | Find symbols by name pattern across the project or within a file; also provides a symbol tree for a file, directory, or glob |
symbol_at | Inspect a symbol at a position via LSP — definition location and/or hover (type + docs); auto-discovers libraries |
references | All callers and usages of a given symbol |
call_graph | Transitive call graph for a symbol — callers, callees, or both |
edit_code | Mutate a symbol: action="replace" rewrites a body, action="insert" injects adjacent code, action="remove" deletes a symbol, action="rename" renames across the codebase via LSP |
File Operations
Read, list, and search files. These tools work on any file regardless of language support.
| Tool | Description |
|---|---|
read_file | Read lines from a file, with optional range and pagination |
read_markdown | Read a Markdown file with heading-based navigation |
tree | List files and directories, optionally recursive; also finds files by glob pattern, respecting .gitignore |
grep | Search file contents with a regex pattern |
create_file | Create or overwrite a file with given content |
edit_file | Find-and-replace editing within a file |
edit_markdown | Edit a Markdown document by heading |
Semantic Search
Find code by meaning rather than by name or pattern. Requires an embedding
index built with index(action: build) — see the Setup Guide. Use the optional scope parameter to search
within a specific library (see Library Navigation).
| Tool | Description |
|---|---|
semantic_search | Search code by natural language description or code snippet |
index | Build or incrementally update the embedding index (action: build) or show index stats (action: status) |
Library Navigation
Navigate third-party dependency source code (read-only). Libraries are
auto-registered when LSP symbol_at returns a path outside the project
root; you can also register them manually.
| Tool | Description |
|---|---|
library | Show all registered libraries and their index status (action: list), or register a new library (action: register) |
Scope parameter — once a library is registered, pass scope to any
navigation or search tool to target it:
| Value | What it searches |
|---|---|
"project" (default) | Only project source code |
"lib:<name>" | A specific registered library |
"libraries" | All registered libraries |
"all" | Project + all libraries |
All results include a "source" field ("project" or "lib:<name>") so you
can tell where each result came from.
Memory
Persistent key-value store backed by markdown files in
.codescout/memories/. Survives across sessions.
| Tool | Description |
|---|---|
memory | Read, write, list, or delete memory entries via the action param |
Workflow & Config
Project setup, shell execution, and server configuration.
| Tool | Description |
|---|---|
onboarding | Initial project discovery: detect languages, read key files, write startup memory |
run_command | Run a shell command in the project root and return stdout/stderr |
approve_write | Grant write access to a directory outside the project root for this session |
workspace | Switch the active project (action: activate), display project state (action: status), or list all projects (action: list_projects) |
Which Tool Do I Use?
Use this table when you know what you want but are not sure which tool to reach for.
| You want to… | Use this |
|---|---|
| See what functions/classes a file contains | symbols |
| Find where a function is defined | symbols |
| Jump to a symbol’s definition | symbol_at with fields: ["def"] |
| Get type info or docs for a symbol | symbol_at with fields: ["hover"] |
| Find all callers of a function | references |
| Rewrite a function body | edit_code(action="replace") |
| Add a new function next to an existing one | edit_code(action="insert") |
| Delete a symbol entirely | edit_code(action="remove") |
| Rename a function everywhere | edit_code(action="rename") |
| Find code that does something (concept, not name) | semantic_search |
| Find code by concept inside a library | semantic_search with scope: "lib:<name>" (after index(action: build) on the library) |
| See what third-party libraries are registered | library(action: list) |
| Check index health, file count, drift scores | index(action: status) |
| Check project config and usage stats | workspace(action: status) |
| Search for a string or regex across files | grep |
| Find files matching a name pattern | tree (with glob) |
| Read a specific part of a file | read_file (with start_line/end_line) |
| Remember a decision for the next session | memory with action: "write" |
| Run a build or test command | run_command |
| Orient yourself in a new project | onboarding |
Choosing Between Symbol Navigation and Semantic Search
Use symbol navigation (symbols, symbols) when you know
the name of what you are looking for. LSP tools are precise and fast.
Use semantic search when you know the concept but not the name: “retry logic”, “token validation”, “connection pool initialization”. Semantic search finds code that means what you describe, regardless of what it is called.
Choosing Between symbols and symbols
symbols answers “what is in this file or directory?” — it gives
you the map. symbols answers “where is this specific thing?” — it finds
a target by name, optionally across the whole project. Start with
symbols to orient, then use symbols to drill in.
Choosing Between LSP Editing and Direct Editing
edit_code operates on named symbols via its action parameter (replace, insert, remove, rename).
It does not care about line numbers and is robust to changes above the target.
Use it when you know the symbol name.
edit_file operates on text via exact string matching. Use it for changes that are not naturally
symbol-scoped: adding an import, changing a constant value, patching a
configuration block.