Tools Reference

The CtxE MCP server exposes two tools: semantic_search finds the code for a behavior you cannot name yet, and ask_context explains how it works across files. Both are read-only, so agents can call them in plan mode. Every request carries the absolute workspace path of the repository being explored.

Readiness, indexing, chunk bodies and saved Ask records are CLI steps: ctxe status, ctxe index, ctxe fetch and ctxe records. The installer ships the ctxe and ctxe-explore agent skills, which tell an agent when to call each tool.

semantic_search

Finds code for one behavior, mechanism or symptom and returns one ranking fused over up to four phrasings of the request. A chunk ranks high when it matches most of them.

Read-only

workspacerequired — Absolute path of the repository

queriesrequired — 1–4 facets of the one thing to find, each nonblank and at most 2048 UTF-8 bytes: the request itself plus facets written as action + object + qualifier, keeping exact names

pathoptional — Relative file or directory that scopes the search; omission searches the whole workspace

limitoptional — Results per page (default 12, at most 50)

offsetoptional — Position in the ranking to start from (default 0); pass the returned next_offset for the next page

body_limitoptional — How many of the first results carry source bodies (default the smaller of 8 and limit, at most limit)

bodyoptional boolean — false returns metadata only

{
  "workspace": "/home/user/projects/my-app",
  "path": "src",
  "queries": [
    "apply a discount code at checkout",
    "validate the discount code against its rules",
    "recalculate the order total after a discount"
  ]
}

Each result has its chunk_id, rank, file path and lines, symbol, and the facets that rank it. facets[].matched counts the returned results each facet ranks; a facet with disjoint: true shares none of its top files with the others, so rephrase or drop it. Results past body_limit, or marked content_status: "omitted_budget", have no body: read them with ctxe fetch.

ask_context

Runs a goal-driven investigation of one question across files and returns a synthesized answer with direct and related evidence chunk IDs. Use it for the logic between hops: order of steps, conditions, who calls what.

Read-only · Requires ctxe login

workspacerequired — Absolute path of an indexed root, or a directory below it to hard-scope the investigation; returned paths stay relative to the root

queryrequired — One complete question that keeps every exact name you know

effortoptional — min, medium or high (up to 3, 6 or 48 retrieval rounds); omission uses the configured default (built-in: min)

response_languageoptional — Language for the answer, at most 256 bytes

{
  "workspace": "/home/user/projects/my-app",
  "query": "How does applyDiscount validate a discount code, and where is the applied discount stored on the order?",
  "effort": "min"
}

diagnostics.evidence_validity covers the cited evidence. An Ask takes one to three minutes. If the MCP client times out, do not repeat the call: the Ask keeps running and is saved as a record you can read with ctxe records.

CLI follow-ups

# Is the workspace indexed and ready?
ctxe status /home/user/projects/my-app

# Index it (ask the user first)
ctxe index /home/user/projects/my-app

# Read chunk bodies by the IDs a tool returned
ctxe fetch --workspace /home/user/projects/my-app 412 418

# Find and read an Ask whose client stopped waiting
ctxe records list --workspace /home/user/projects/my-app --kind ask --limit 5
ctxe records get --workspace /home/user/projects/my-app 42

Chunk and record IDs are local to one workspace. Reuse an ID only with the workspace that returned it.

Typical workflow

Run ctxe status on the project; if it is not indexed, get approval and run ctxe index.
Call semantic_search once per thing you cannot name yet, scoped with path.
Call ask_context when the change depends on how that code works across files.
Read bodies and cited evidence with ctxe fetch.