Semantic Search Tool

Overview

The Semantic Search tool enables Tool Agents to search your document repository (Content Lake) using semantic similarity. Unlike RAG agents — which are dedicated to retrieval and answer generation — Semantic Search is a tool that can be combined with other tools (functions, structured output, MCP, code execution) within a single Tool Agent.

This is useful when you need an agent that can both search documents and perform other actions in a single conversation.

Configuration

Add a rag tool type with funcName: "semantic_search" to your Tool Agent:

{
    "name": "DocumentSearcher",
    "description": "Assistant that can search documents and answer questions",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-sonnet-4-20250514-v1:0",
        "systemPrompt": "You are a helpful assistant with access to semantic search. Use it to find information in the document repository when needed.",
        "tools": [
            {
                "toolType": "rag",
                "name": "semantic_search",
                "description": "Searches documents using semantic search",
                "funcName": "semantic_search",
                "semanticSearchConfig": {
                    "hxqlQuery": "SELECT * FROM SysContent",
                    "hybridSearch": true,
                    "limit": 10,
                    "rerankerTopN": 5
                }
            }
        ]
    }
}

Semantic Search Config

Parameter	Type	Description	Default
hxqlQuery	string	HxQL query to filter Content Lake documents. When blank or omitted, falls back to the platform default (SELECT * FROM SysContent).	""
hybridSearch	boolean	Enable hybrid search (embeddings + full-text)	true
limit	integer	Maximum number of chunks to retrieve	50
rerankerTopN	integer	Number of top results to keep after reranking	13
adjacentChunkRange	integer	Number of adjacent chunks to fetch around each result (0 = disabled)	0
adjacentChunkMerge	boolean	Merge adjacent chunks into parent chunk in document order	false
enableHallucinationCheck	boolean	Validate that the response is grounded in retrieved context	false
enableMultihopQueryRefinement	boolean	Refine and re-retrieve if initial results are irrelevant	false

When to Use Semantic Search vs RAG Agent

Scenario	Use
Document Q&A is the only capability needed	RAG Agent
Need document search combined with other tools	Semantic Search tool
Need to search documents and execute code	Semantic Search + code_execution tools
Need to search documents and call external APIs	Semantic Search + mcp or function tools

Examples

Basic Document Search

{
    "tools": [
        {
            "toolType": "rag",
            "name": "semantic_search",
            "description": "Searches documents using semantic search",
            "funcName": "semantic_search",
            "semanticSearchConfig": {
                "hxqlQuery": ""
            }
        }
    ]
}

Filtered Search with HxQL

Scope the search to specific document types:

{
    "tools": [
        {
            "toolType": "rag",
            "name": "hr_search",
            "description": "Searches HR policy documents",
            "funcName": "semantic_search",
            "semanticSearchConfig": {
                "hxqlQuery": "SELECT * FROM SysContent WHERE sys_docType = 'HR'",
                "hybridSearch": true,
                "limit": 5,
                "rerankerTopN": 5
            }
        }
    ]
}

Combined with Other Tools

An agent that can search documents and extract structured data:

{
    "name": "Policy Analyzer",
    "description": "Searches policies and extracts key information",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-sonnet-4-20250514-v1:0",
        "systemPrompt": "You are a policy analyst. Use semantic search to find relevant policies, then extract structured information.",
        "tools": [
            {
                "toolType": "rag",
                "name": "semantic_search",
                "description": "Searches policy documents",
                "funcName": "semantic_search",
                "semanticSearchConfig": {
                    "hxqlQuery": "SELECT * FROM SysContent",
                    "hybridSearch": true,
                    "limit": 10
                }
            },
            {
                "toolType": "structured_output",
                "name": "policy_summary",
                "description": "Extracts key policy details",
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "policyName": { "type": "string" },
                        "effectiveDate": { "type": "string" },
                        "keyPoints": {
                            "type": "array",
                            "items": { "type": "string" }
                        }
                    },
                    "required": ["policyName", "keyPoints"]
                }
            }
        ]
    }
}

Tuning Retrieval

Goal	Configuration
Faster responses	hybridSearch: false, lower limit
Better accuracy	hybridSearch: true, enableHallucinationCheck: true
More context	Higher limit, adjacentChunkRange: 1
Precision over recall	Lower rerankerTopN (e.g., 3-5)
Broad coverage	Higher rerankerTopN (e.g., 13+)

Best Practices

1. Use HxQL filters — narrow results to relevant document sets for better accuracy and performance
2. Enable hybrid search — combining embeddings with full-text search improves recall for most use cases
3. Set appropriate limits — use lower limit values for simple queries, higher for complex multi-topic questions
4. Use hallucination checks — enable enableHallucinationCheck when accuracy is critical
5. Combine tools strategically — pair semantic search with structured output for extraction workflows, or with code execution for data analysis