Copy as MD MD

Tools Reference

The current MCP registry exposes 16 stable public tools. Every workspace-aware request uses an absolute workspace path. The only no-argument tool is list_workspaces.

Use get_status first, use ask_context for broad questions, and pass chunk IDs between tools rather than inventing them.

ask_context

Primary high-level tool for architecture, flows, errors, comparisons, and impact analysis. Performs multi-round retrieval and returns synthesized evidence.

Layer: Agentic · Read-only

{
  "workspace": "/home/user/projects/my-app",
  "query": "How does the payment processing pipeline work?",
  "effort": "medium"
}

get_status

Read workspace index state, counts, enrichment status, and capability health.

Layer: System · Read-only

{
  "workspace": "/home/user/projects/my-app",
  "groups": ["index", "capabilities"]
}

list_workspaces

List accepted workspace catalog entries together with their desired daemon watch state. This is a diagnostic ledger, not authorization or an automatic workspace picker.

Layer: System · Read-only · No parameters

{}

index_workspace

Create or update a workspace index. This is the only current public MCP tool that mutates local index state.

Layer: Job · Writes local index · Requires authentication for server-backed phases

{
  "workspace": "/home/user/projects/my-app",
  "force": false
}

fetch_chunks

Read full chunk metadata and content by IDs returned from a previous call on the same workspace.

Layer: Retrieval · Read-only

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

find_definitions

Resolve one or more symbol names to their definition chunks. Follow up with fetch_chunks when you need source content.

Layer: Retrieval · Read-only · Requires graph capability

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

find_usages

Find chunks where a symbol is used through reverse graph edges. It covers callers, implementations, importers, and other selected relations in one contract.

Layer: Graph · Read-only · Requires graph capability

{
  "workspace": "/home/user/projects/my-app",
  "symbol_name": "UserService.create",
  "edge_kinds": ["calls", "implements"],
  "limit": 50
}

graph_neighbors

Return direct one-hop graph neighbors for a chunk, optionally filtered by edge kind and direction.

Layer: Graph · Read-only · Requires graph capability

{
  "workspace": "/home/user/projects/my-app",
  "chunk_id": 142,
  "edge_kinds": ["calls"],
  "direction": "incoming",
  "limit": 20
}

graph_expand

Expand a graph neighborhood from scored seed chunks. Traversal bounds come from graph configuration.

Layer: Graph · Read-only · Requires graph capability

{
  "workspace": "/home/user/projects/my-app",
  "seeds": [{ "chunk_id": 142, "score": 0.92 }],
  "mode": "related"
}

graph_paths

Find shortest or all-simple paths between two chunks.

Layer: Graph · Read-only · Requires graph capability

{
  "workspace": "/home/user/projects/my-app",
  "from_chunk_id": 142,
  "to_chunk_id": 287,
  "strategy": "shortest"
}

get_impact

Find transitive dependents of a chunk through incoming graph edges: “if I change this, what breaks?”

Layer: Graph · Read-only · Requires graph capability

{
  "workspace": "/home/user/projects/my-app",
  "chunk_id": 142,
  "max_hops": 3
}

get_workspace_tree

Return a structured, paginated tree of indexed files with chunk, embedding, enrichment, language, line, size, and indexing-status data.

Layer: File · Read-only

{
  "workspace": "/home/user/projects/my-app",
  "root": "src",
  "max_depth": 2,
  "limit": 200
}

inspect_path

Browse indexed chunks under a relative file or directory. An optional query semantically reranks chunks within that subtree.

Layer: File · Read-only

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

Workspace record tools

Records are structured workspace artifacts. These tools are read-only and return full records, including payloads where applicable.

get_record

Retrieve one workspace record by its local integer ID.

{
  "workspace": "/home/user/projects/my-app",
  "id": 42
}

list_records

List records with optional kind, source, and lifecycle-status filters.

{
  "workspace": "/home/user/projects/my-app",
  "kind": "ask",
  "status": "completed",
  "limit": 20
}

search_records

Full-text search record titles and content, with the same optional filters and pagination as list_records.

{
  "workspace": "/home/user/projects/my-app",
  "query": "authentication",
  "kind": "ask",
  "limit": 20
}

Typical workflow

1. get_status — confirm the active workspace is indexed and healthy.
2. ask_context — understand the architecture or flow.
3. find_definitions / find_usages — locate exact symbols and relationships.
4. graph_neighbors, graph_paths, or get_impact — inspect targeted dependencies.
5. fetch_chunks — read source for IDs returned by the preceding calls.

The AI client can orchestrate this sequence automatically. Keep the same absolute workspace path on every call.