Tools Reference

Detailed documentation for each MCP tool exposed by CtxE. All tools require a workspace parameter — the absolute path to your project root.

ask_context

The primary high-level tool for understanding a codebase. Performs multi-round retrieval (semantic search, FTS5, graph expansion) and returns synthesized evidence with source locations.

Layer: Agentic · Read-only

Parameters

workspacerequired — Absolute path to the project root
queryrequired — Natural language question about the codebase. Be specific — include symbol names, modules, or flows.

When to use

  • Understanding architecture or module relationships
  • Tracing request/data flows end-to-end
  • Impact analysis before changing an API
  • Finding the source of an error
  • Comparing implementations across modules

Example

{
  "workspace": "/home/user/projects/my-app",
  "query": "How does the payment processing pipeline work from API handler to database?"
}

get_status

Health check for a workspace. Returns whether it's indexed, file/chunk counts, and available capabilities (vector search, reranker, graph, FTS5).

Layer: Primitive · Read-only

Parameters

workspacerequired — Absolute path to the project root

Response includes

  • indexed_files — number of files indexed
  • total_chunks — number of code chunks
  • capabilities — available search features
  • degraded — list of degraded capabilities (if any)

index_workspace

Index or reindex a workspace. Use when get_status shows the workspace is not indexed or out of date.

Layer: Primitive · Write

Parameters

workspacerequired — Absolute path to the project root
forceoptional (default: false) — Full reindex instead of incremental

list_workspaces

List all workspaces registered with the CtxE daemon. Use to check whether the current project has been indexed.

Layer: Primitive · Read-only

Parameters

No parameters required.

fetch_chunks

Read the actual source code content of chunks by their IDs. This is the main tool for viewing code after discovering relevant chunks via other tools.

Layer: Primitive · Read-only

Parameters

workspacerequired — Absolute path to the project root
chunk_idsrequired — Array of chunk IDs from a previous tool call. Never invent IDs.

Example

{
  "workspace": "/home/user/projects/my-app",
  "chunk_ids": [142, 143, 287]
}

find_definitions

Find where one or more symbols are defined. Matches both simple names and qualified names. Follow up with fetch_chunks to read the actual code.

Layer: Primitive · Read-only · Requires graph capability

Parameters

workspacerequired — Absolute path to the project root
symbolsrequired — List of symbol names to look up

Example

{
  "workspace": "/home/user/projects/my-app",
  "symbols": ["UserService", "handle_request"]
}

find_callers

Find all call sites (incoming references) to a given symbol. Useful for impact analysis before modifying code.

Layer: Primitive · Read-only · Requires graph capability

Parameters

workspacerequired — Absolute path to the project root
symbol_namerequired — Name of the symbol whose callers you want to find

find_implementors

Find all implementations of a given trait or interface. Useful for understanding polymorphism and locating concrete types.

Layer: Primitive · Read-only · Requires graph capability

Parameters

workspacerequired — Absolute path to the project root
trait_namerequired — Name of the trait or interface

get_workspace_tree

Returns a structured directory tree of all indexed files with per-file stats: chunk count, embedded count, language, line count, and file size.

Layer: Primitive · Read-only

Parameters

workspacerequired — Absolute path to the project root
rootoptional — Subtree root path (relative to workspace) to limit scope
max_depthoptional — Maximum directory depth to include

inspect_path

Explore indexed chunks under a specific file or directory. Optionally pass a natural language query to semantically rerank results within that path.

Layer: Primitive · Read-only

Parameters

workspacerequired — Absolute path to the project root
pathrequired — File or directory path (relative to workspace root)
queryoptional — Natural language query to rerank chunks semantically
offsetoptional — Pagination offset
limitoptional — Maximum chunks to return

Example

{
  "workspace": "/home/user/projects/my-app",
  "path": "src/services/auth",
  "query": "token refresh logic"
}

get_dependencies

Extract dependency information from the project's manifest files (Cargo.toml, package.json, etc.). Useful for understanding what external libraries the project uses.

Layer: Composed · Read-only

Parameters

workspacerequired — Absolute path to the project root
pathoptional — Specific subdirectory to get dependencies for

Typical workflow

Tools are designed to be used together. A typical exploration flow:

  1. get_status — check workspace is indexed and healthy
  2. ask_context — ask a high-level question to understand the area
  3. find_definitions / find_callers — drill into specific symbols
  4. fetch_chunks — read the actual source code for chunks of interest
  5. inspect_path — browse related code in the same directory

The AI assistant orchestrates this workflow automatically based on your questions — you don't need to call tools manually.