Overview

Context Engine exposes eight semantic tools and five workspace-management tools over MCP. The semantic tools share one navigation model: every result identifies symbols, and every symbol carries a handle that any other tool accepts.

Which tool first

Workspace management is separate: initialize_workspace, reload_config, restart_workspace, index_workspace, and shutdown_workspace.

Handles

A handle is a short opaque identifier — "1000t00b" — that Context Engine registers for every symbol it returns. Handles are the currency between tools: a symbol discovered by outline, grep_definition, or jump can be passed to extract, show_usage, hover, or jump without repeating the discovery.

Each handle is printed beside its symbol together with the views it offers and their cost in source lines:

- pub async fn terminate(&mut self) -> Result<()> { ... } ["1000t00b" full 124L | code 48L | docs 76L]

The agent knows what a read costs before paying for it, and picks the view it needs: full is the complete item including documentation, code is the implementation without leading documentation, docs is the documentation alone. File-scope handles additionally offer imports (imports and directives) and module-docs (module-level documentation).

Three properties matter in practice:

• Stability. A handle is addressed to the symbol's identity, not to line coordinates. It survives body edits, comment changes, reformatting, and line shifts — an agent that edits a file does not re-read the outline to find out where everything moved. Obtain a fresh handle after a rename, move, parent-chain change, or signature change.
• Canonical groups. One handle can represent multiple declaration fragments with the same canonical identity — split implementations, partial classes, re-exports. Tools that accept handles operate on the complete group; use a source-position form (file plus line) when one exact physical occurrence is intended.
• Virtual documents. Some results come from virtual documents rather than files on disk. extract reads those handles; jump, show_usage, and hover reject them.

Conventions shared by every tool

• Batching. Every semantic tool accepts batches — files for outline, symbols for jump and hover, handles for extract, locations for line_context (1–32), ranges for smart_read, query groups for grep_definition (at most 32 queries across all groups). Each extra round trip costs a full agent turn; batching related targets answers them in one.
• Output modes. Reading tools default to type_annotated: output is annotated with the language server's resolved types and call-site parameter names, as /*: Type*/ and /*param: */ comments. plain_text returns byte-exact source for editing; both returns both and doubles the output. Ranges without inlay hints fall back to plain text with a per-range note.
• Line numbers. Lines are 1-based and passed as JSON integers, never strings. smart_read ranges are inclusive.
• workspace_root. Only needed when multiple workspaces are active in the session; omit it otherwise.