Tools
Tools are reusable definitions that perform one bounded part of query-time retrieval. Their type determines where they can run, what input they receive, and what output CoreCube accepts.
Open Admin Console → Configuration → Tools to search, create, duplicate, import, export, test, or delete tools.
Choose a tool type
| Type | Runs | Produces | Attach it to |
|---|---|---|---|
query | Before candidate retrieval | Bounded, weighted query variants | Pipeline Query stage |
retrieval | During candidate retrieval | Authorized candidate chunks | Pipeline Retrieval stage |
chunk | After candidate retrieval | Selected or reordered candidate references | Pipeline Chunk stage |
action | When selected by the Orchestrator LLM | A schema-validated direct-tool result | Orchestrator mode |
query, retrieval, and chunk tools belong to Pipelines. action tools
do not: eligible action tools are attached under Orchestrator → Modes → Direct evidence tools.
A fresh installation seeds 12 tool definitions. The catalog below describes their capabilities, not fixed assignments. Administrators can change which tools a Pipeline uses and which action tools an Orchestrator configuration may call.
Query tools
A query tool receives the resolved query and conversation history before search. It can preserve, rewrite, or expand the query into weighted retrieval streams. Its output has this shape:
{
"kind": "query_variants",
"queries": [{ "query": "original or rewritten query", "weight": 1 }]
}
The tool's Maximum query variants setting and the active Orchestrator budget limit the number of streams. Query tools run in their displayed Pipeline order. Later retrieval remains constrained by the caller's connections, compartment, scopes, and sensitivity ceiling.
Use a query tool for bounded query rewriting or expansion—not for searching or selecting final evidence.
Seeded query tool
| Tool | What it does |
|---|---|
Multi-query expansion (expand_multi_query) | Keeps the normalized original query and, when product-like identifiers are present, adds one identifier-only variant. The initial weights are 1.0 and 0.8. |
Retrieval tools
A retrieval tool is a settings-only definition; it does not contain Python code. It controls candidate search and processing, including:
- full-text, vector, or hybrid retrieval;
- candidate-pool sizes, score thresholds, and Reciprocal Rank Fusion;
- freshness penalties and HNSW search breadth;
- optional reranking and final evidence limits.
Every ready Pipeline requires one default retrieval tool. Additional retrieval tools can be attached as retrieval capabilities, but only one is marked as the default. See Retrieval Settings for every field.
Seeded retrieval tools
| Tool | What it does |
|---|---|
Lexical-focused retrieval (retrieve-lexical-focused) | Uses full-text search without vector contribution or reranking. Suited to identifiers, exact terms, and names. |
Hybrid coverage retrieval (retrieve-hybrid-coverage) | Combines lexical and vector candidates, then applies the seeded multilingual reranker. |
High-recall retrieval (retrieve-high-recall) | Searches a wider candidate pool and applies deeper reranking for coverage-oriented analysis. |
Chunk tools
A chunk tool receives the original query plus the candidate chunks issued by the retrieval stage. It can filter, deduplicate, reorder, or select those candidates. A typical result contains only opaque evidence references:
{
"chunks": [{ "evidence_ref": "server-issued-reference" }]
}
CoreCube revalidates returned references before admitting evidence. A chunk tool cannot introduce arbitrary content as evidence. Any operation that fetches more governed context must be declared by the tool and remains restricted to the caller's authorization scope.
Attach Pass-through chunk when the Pipeline should keep the issued candidates without additional selection.
Seeded chunk tools
| Tool | What it does |
|---|---|
Bounded candidate selection (llm_select_and_expand) | Deduplicates the issued references and keeps the first configured number in their existing order—30 initially. It does not fetch new evidence. |
Score-ordered candidate selection (iterative-context-chunk) | Deduplicates references, orders them by server-issued score with stable ties, and keeps up to 80 initially. |
Pass-through chunk (noop_chunk) | Returns the issued references in their existing order without additional selection. |
Despite its legacy slug, llm_select_and_expand is deterministic and does not call an LLM.
Action tools
An action tool exposes an LLM-callable function. Its Inputs model defines the arguments visible to
the Orchestrator, and its output must match the stored output schema.
CoreCube currently accepts action tools in Orchestrator modes only when they satisfy the governed direct-evidence contract: they must be read-only, require no confirmation, use strict input and output schemas, and return references that CoreCube can validate and admit into the evidence ledger. They are not a general workflow or write-action mechanism.
Direct evidence tools handle focused work such as searching for a source, reading a bounded page, fetching neighboring chunks, or expanding context without rerunning a complete Pipeline.
Seeded action tools
| Tool | Use it when | What it returns |
|---|---|---|
Context expansion (context_expansion) | The evidence gap is broad, comparative, conflicting, or coverage-sensitive. | References selected from one bounded batch of targeted searches. |
Search documents (search_documents) | The relevant source is not yet known. | Bounded document matches with snippets and opaque sourceRef values, not full documents. |
Fetch source document (fetch_source_document) | A known source needs verified content from its committed original text or structured document. | A bounded reader page, admitted evidence references, and a cursor when more remains. |
Fetch document chunks (fetch_document_chunks) | A known source needs more of its indexed chunks. | The next bounded page—up to eight chunks initially—and a cursor when more remains. |
Fetch neighbors (fetch_neighbors) | An admitted chunk needs nearby context from the same document. | Adjacent admitted chunk references within the requested radius, capped at four initially. |
All five seeded action-tool definitions are read-only and answer-bearing. When one is assigned, the runtime makes it available only after a qualifying Pipeline has completed; an empty or unrelated Pipeline cannot merely unlock Discovery evidence for an answer.
Paging chunks from a known document
fetch_document_chunks continues from evidence already found by a Pipeline:
- A qualifying Pipeline returns initial chunks and server-issued
sourceRefmappings. - In a later orchestration round, the Orchestrator can call
fetch_document_chunksdirectly for one or more known sources, with each source's optional cursor. - CoreCube validates the reference, reads the next bounded page from the same indexed document revision, and admits the returned chunks into the evidence ledger.
This does not invoke run_pipeline again. Another Pipeline run is needed only when the Orchestrator
chooses a new search strategy, not when it only needs more chunks from a known source. Expired,
invalid, or stale references and cursors are rejected.
Do not confuse the seeded action with the executor capability of the same name:
| Layer | Who calls it | Purpose |
|---|---|---|
fetch_document_chunks action | The Orchestrator after a qualifying Pipeline | Exposes a schema-validated direct evidence call and admits the validated result into the evidence ledger. |
ctx.fetch_document_chunks capability | Code inside a custom tool | Performs the low-level governed read declared in that tool's evidence manifest. It is not a separate Orchestrator decision. |
Code tools
Query, chunk, and action tools run Python in CoreCube's isolated executor. Code tools share:
- an
async def run(input, ctx)entry point; - an optional
Settingsmodel for administrator-configured values; - timeout, memory, and outbound-network limits;
- the governed
ctxoperations required by the code.
Action tools additionally use an Inputs model to define the arguments visible to the
Orchestrator.
The editor validates the source and derives its settings, action inputs, source hash, and evidence
manifest before saving. At runtime, undeclared context operations and outbound requests to origins
outside the egress allowlist are rejected. Select a tool model only when the code uses ctx.llm.
Retrieval tools use their dedicated settings editor instead of the code editor.
Test and activate changes
Open a saved tool's Test tab to run it as the current administrator, a personal API key, or a service API key and user. Retrieval tests accept a query; code-tool tests accept JSON input. Select a Pipeline context when a tool is shared by several Pipelines. Each test run creates an audit record.
Saving changes updates the reusable tool definition, not an active Orchestrator snapshot. To put a change into service, save the affected Pipeline or Orchestrator draft, resolve readiness problems, and apply a new Orchestrator revision.
Tool type is fixed after creation. Duplicate or create a tool when you need a different type.