# 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](symbol-navigation.md)

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](#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](file-operations.md)

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](semantic-search.md)

Find code by meaning rather than by name or pattern. Requires an embedding
index built with `index(action: build)` — see the [Setup Guide](../semantic-search-guide.md). Use the optional `scope` parameter to search
within a specific library (see [Library Navigation](#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 {#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](memory.md)

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](workflow-and-config.md)

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.
