knowledge.search
Search knowledge datasets for relevant documents using natural language queries and semantic similarity to retrieve information quickly.
Instructions
Search a knowledge dataset for relevant documents using semantic similarity
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset | Yes | Dataset ID to search (must be a registered dataset) | |
| query | Yes | Natural language search query | |
| topK | No | Number of results to return (defaults to dataset's defaultTopK) |
Implementation Reference
- src/tools/search.ts:42-166 (handler)Core handler function for knowledge.search tool. Validates input with SearchQuerySchema, retrieves dataset from registry, performs semantic search using knowledgeStoreCache, formats results with scores, paths, and snippets, handles all errors comprehensively.export async function handleSearch(args: unknown): Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean; }> { const startTime = Date.now(); try { // Validate input with Zod const validationResult = SearchQuerySchema.safeParse(args); if (!validationResult.success) { const error = validationResult.error.issues[0]; logger.warn( { args, error: error.message, path: error.path }, 'Search validation failed' ); return { content: [{ type: 'text', text: `Invalid search parameters: ${error.message} at ${error.path.join('.')}` }], isError: true }; } const query: SearchQuery = validationResult.data; // Get dataset from registry const registry = getDatasetRegistry(); const dataset = registry.get(query.dataset); if (!dataset || dataset.status !== 'ready') { const availableDatasets = registry.listReady().map(d => d.id); logger.warn( { datasetId: query.dataset, availableDatasets }, 'Dataset not found or not ready' ); return { content: [{ type: 'text', text: `Dataset '${query.dataset}' not found. Available datasets: ${availableDatasets.join(', ')}` }], isError: true }; } // Get or create KnowledgeStore for this dataset const store = knowledgeStoreCache.getStore(dataset); // Execute search logger.info( { datasetId: query.dataset, query: query.query.substring(0, 100), // Truncate for logging topK: query.topK ?? dataset.defaultTopK }, 'Executing search' ); const results: SearchResult[] = await store.search(query.query, query.topK); const duration = Date.now() - startTime; // Log successful search logger.info( { datasetId: query.dataset, query: query.query.substring(0, 100), resultCount: results.length, duration }, 'Search completed' ); // Format response if (results.length === 0) { return { content: [{ type: 'text', text: `No results found for query: "${query.query}" in dataset "${query.dataset}"` }] }; } // Format results as text const resultText = results.map((result, index) => { return `${index + 1}. ${result.title} (score: ${result.score.toFixed(4)}) Path: ${result.path} Snippet: ${result.snippet.substring(0, 200)}${result.snippet.length > 200 ? '...' : ''} `; }).join('\n'); const summary = `Found ${results.length} result${results.length === 1 ? '' : 's'} for "${query.query}" in ${duration}ms:\n\n${resultText}`; return { content: [{ type: 'text', text: summary }] }; } catch (error) { const duration = Date.now() - startTime; const errorMessage = error instanceof Error ? error.message : String(error); logger.error( { error: errorMessage, args, duration }, 'Search failed' ); return { content: [{ type: 'text', text: `Search failed: ${errorMessage}` }], isError: true }; } }
- src/types/searchQuery.ts:7-11 (schema)Zod schema defining input validation for knowledge.search tool parameters: dataset (required string), query (required string), topK (optional number 1-100).export const SearchQuerySchema = z.object({ dataset: z.string().min(1).max(64).describe('Dataset ID to search (must be a registered dataset)'), query: z.string().trim().min(1).max(1024).describe('Natural language search query'), topK: z.number().int().min(1).max(100).optional().describe('Number of results to return (defaults to dataset\'s defaultTopK)') });
- src/server.ts:114-135 (registration)Tool registration in ListToolsRequestHandler: declares knowledge.search tool with name, description, and input schema (mirroring SearchQuerySchema).{ name: 'knowledge.search', description: 'Search a knowledge dataset for relevant documents using semantic similarity', inputSchema: { type: 'object', properties: { dataset: { type: 'string', description: 'Dataset ID to search (must be a registered dataset)' }, query: { type: 'string', description: 'Natural language search query' }, topK: { type: 'number', description: 'Number of results to return (defaults to dataset\'s defaultTopK)' } }, required: ['dataset', 'query'] } },
- src/server.ts:155-172 (registration)Tool dispatch registration in CallToolRequestHandler: switch case routes 'knowledge.search' invocations to handleSearch function.switch (name) { case 'knowledge.search': return await handleSearch(args); case 'knowledge.listDatasets': return await handleListDatasets(args); default: logger.warn({ tool: name }, 'Unknown tool requested'); return { content: [ { type: 'text', text: `Unknown tool: ${name}`, }, ], isError: true, };
- src/tools/search.ts:12-21 (helper)Error codes defined for use in knowledge.search tool error responses.export const SearchErrorCodes = { /** Dataset ID not found in registry or not ready */ DATASET_NOT_FOUND: 'DATASET_NOT_FOUND', /** Query string is empty or invalid */ INVALID_QUERY: 'INVALID_QUERY', /** topK parameter is out of valid range (1-100) */ INVALID_TOP_K: 'INVALID_TOP_K', /** Python bridge or FAISS service unavailable */ SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE' } as const;