Search & Indexing Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Search & Indexing Engine provides discovery capabilities for agents and users to locate available Operations and Saved Functions. It allows agents to search for specific capabilities using natural language keywords rather than loading all tool definitions into every prompt. This reduces context size and minimizes round trips.
The engine indexes OpenAPI documents and Saved Functions, providing metadata, signatures, and documentation snippets. It supports filtered searches by provider and specific call paths. Users can review these search interactions in the Coral UI to understand how agents discovered and utilized system capabilities.
Sources: README.md, crates/coral-mcp/src/arguments.rs:20-22
Search Architecture and Data Flow
The search system follows a multi-retriever architecture where different entity kinds—Operations and Saved Functions—are queried to find matches. The MCP (Model Context Protocol) server exposes tools that agents use to interact with this engine.
Search Interaction Flow
The diagram shows the flow from an agent's search request through the MCP server to the retrievers, followed by the merger returning ranked results.
Sources: apps/reef/app/views/activity/discovery/response.ts:40-52, crates/coral-mcp/src/arguments.rs:20-22
MCP Search Tools
The engine exposes two primary tools to agents: search and describe. These tools allow for discovery and detailed inspection of available capabilities.
The Search Tool
The search tool finds Operations and Saved Functions based on keywords. It supports pagination via cursors and filtering by provider namespace.
| Parameter | Type | Description |
|---|---|---|
task_id | String | The identifier of the current task. |
intent | String | Short phrase explaining why the call is needed. |
query | String (Optional) | Keywords for the required capability. |
provider | String (Optional) | Narrows search to one provider or coral.workspace. |
limit | Number (Optional) | Maximum results per page (Default: 20). |
cursor | String (Optional) | Pointer for pagination. |
Sources: crates/coral-mcp/src/arguments.rs:48-84
The Describe Tool
The describe tool retrieves the exact signature and documentation for a specific call path. Agents use this when search results are truncated or when they need to inspect complex input types before making a call.
Sources: crates/coral-mcp/src/arguments.rs:86-107
Result Ranking and Evaluation
The engine ranks hits based on field matches. Rankings are assessed using metrics like "hit@10" (whether the correct operation appears in the top 10 results) and Mean Reciprocal Rank (MRR).
Match Evidence
The system tracks why a specific result matched the query. Matching can occur in several fields:
- Call Path: The technical identifier (e.g.,
github.issues.create). - Provider Name: The display name of the service.
- Tags: Metadata labels attached to operations.
- Input Fields: Parameter names within the operation's declaration.
Sources: apps/reef/app/views/activity/discovery/discovery.tsx:313-332, apps/reef/app/views/activity/discovery/response.ts:160-164
Evaluation Logic
The search_eval module runs smoke tests against documents like the GitHub OpenAPI spec to ensure search quality remains above established floors.
fn matches(pattern: &str, path: &str) -> bool {
let mut parts = pattern.split('*');
let first = parts.next().unwrap_or_default();
let Some(mut rest) = path.strip_prefix(first) else {
return false;
};
// ... logic to verify if path matches wildcard pattern
}
Sources: crates/coral-administration/src/tests/search_eval.rs:55-73
Search Coverage and Error Handling
Search results include coverage metadata that indicates if any retrievers failed or returned partial results. This state is communicated via retriever_statuses.
Coverage States
- results_found: Retriever successfully found matches.
- empty: Retriever searched but found no matches.
- skipped: Retriever was bypassed (e.g., by a provider filter).
- partial: Search completed but might be missing units.
- error: Retriever failed to search its units.
Sources: apps/reef/app/views/activity/discovery/response.ts:78-83, apps/reef/app/views/activity/discovery/discovery.tsx:112-140
User Interface and Discovery Evidence
The Coral UI displays discovery interactions as "Discovery Evidence." This allows users to audit how the agent found operations.
Component Structure
- SearchLedger: Lists ranked hits and shows pagination status.
- Hit: Displays the title, kind (Operation/Function), and match reasons for a single result.
- HitDetails: A collapsible section containing the full signature, description snippet, and guidance.
- DescriptionResult: Shows the full declaration and source code (for Saved Functions) resulting from a
describecall.
Sources: apps/reef/app/views/activity/discovery/discovery.tsx:143-220, apps/reef/app/views/activity/discovery/discovery.tsx:353-418
Result Attributes
| Attribute | Description |
|---|---|
readOnly | Indicates if the operation makes no state changes. |
destructive | Indicates if the operation deletes or significantly alters data. |
idempotent | Indicates if repeated calls have the same effect as one. |
openWorld | Indicates operations with side effects outside the system's tracking. |
approvalRequired | Policy flag requiring human intervention before execution. |
Sources: apps/reef/app/views/activity/discovery/discovery.tsx:231-255
Conclusion
The Search & Indexing Engine facilitates efficient capability discovery through a combination of keyword-based retrieval and detailed path inspection. By providing rich match evidence and coverage metadata, it enables agents to navigate large provider catalogs while allowing users to monitor the discovery process through the Coral UI.