Skip to content

Commit 2e17f05

Browse files
alegaussalegauss
committed
docs(turing): introduce DSL search tools
Replace the previous Semantic Navigation tools section with a new DSL Search section that documents Elasticsearch-compatible Query DSL tools (6 tools). Update the top-level description to mention DSL-based search, remove the hardcoded "27 tools" phrasing, and add usage guidance, query examples, and a how-the-LLM-uses flow for dsl_list_indices, dsl_get_mappings, dsl_search, dsl_get_document and dsl_suggest. Add links to the new DSL Query API and DSL Compatibility Matrix docs, adjust related link text to reference DSL tools, and make minor wording tweaks around native/external tools and MCP servers.
1 parent a461206 commit 2e17f05

1 file changed

Lines changed: 76 additions & 32 deletions

File tree

‎docs-turing/tool-calling.md‎

Lines changed: 76 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,91 @@
11
---
22
sidebar_position: 5
33
title: Tool Calling
4-
description: Native tool calling capabilities available to AI Agents in Turing ES — 27 tools across 7 categories.
4+
description: Native tool calling capabilities available to AI Agents in Turing ES — DSL-based search tools, RAG, web crawling, and more.
55
---
66

77
# Tool Calling
88

99
A **Tool Calling** is a function that the LLM can invoke autonomously during a conversation to retrieve information or perform an action. Instead of relying purely on training data, the LLM calls tools to fetch live data, search indexed content, execute code, and more — then incorporates the results into its reasoning.
1010

11-
Turing ES includes **27 native tools** organized into 7 categories, plus support for external tools via [MCP Servers](./mcp-servers.md). Tools are enabled per [AI Agent](./ai-agents.md) — each agent selects only the tools it needs.
11+
Turing ES includes native tools organized into categories, plus support for external tools via [MCP Servers](./mcp-servers.md). Tools are enabled per [AI Agent](./ai-agents.md) — each agent selects only the tools it needs.
1212

1313
---
1414

15-
## Semantic Navigation — 15 tools
15+
## DSL Search — 6 tools
1616

17-
These tools allow the LLM to interact with any Semantic Navigation Site as a structured knowledge source, enabling rich search-based reasoning over your indexed content.
17+
These tools provide **Elasticsearch-compatible Query DSL** access to any Semantic Navigation Site. Inspired by the [Elasticsearch MCP Server](https://github.com/elastic/mcp-server-elasticsearch), they allow the LLM to build and execute full DSL queries, aggregations, and analytics — automatically translated to the site's configured search engine (Elasticsearch, Solr, or Lucene).
1818

1919
| Tool | Description |
2020
|---|---|
21-
| `list_sites` | Lists all available SN Sites with their locales |
22-
| `get_site_fields` | Returns valid facet fields for filtering a specific site |
23-
| `get_valid_filter_values` | Returns valid values for a specific filter or facet |
24-
| `search_site` | Searches a site and returns compact results (ID, title, URL, snippet) |
25-
| `get_document_details` | Retrieves full text and metadata of a document by ID |
26-
| `get_search_suggestions` | Autocomplete and spelling corrections for a search query |
27-
| `find_similar_documents` | Finds semantically similar documents (More Like This) |
28-
| `get_aggregated_stats` | Calculates totals and distributions by category via facet aggregation |
29-
| `get_document_highlights` | Extracts snippets from a document where search terms appear |
30-
| `compare_items` | Compares specific fields of two or more documents side by side |
31-
| `search_recent_updates` | Retrieves the most recently updated content on a topic |
32-
| `get_facet_summary` | Statistical summary of all available categories and attributes |
33-
| `search_by_date_range` | Searches documents within a date range |
34-
| `lookup_facet_value` | Searches a term across all facets to find exact values |
35-
| `discover_facet_values` | Splits a phrase into words and searches across all facets |
36-
37-
**Prompt examples:**
38-
39-
- *"Search for documents about authentication in the Sample site"* → triggers `search_site`
40-
- *"What fields can I filter by on the Sample site?"* → triggers `get_site_fields`, then `get_valid_filter_values`
41-
- *"Show me the full content of document ID abc-123"* → triggers `get_document_details`
42-
- *"Find documents similar to the article about Solr configuration"* → triggers `find_similar_documents`
43-
- *"How many documents do we have per content type?"* → triggers `get_aggregated_stats` or `get_facet_summary`
44-
- *"What articles were updated in the last 7 days about security?"* → triggers `search_recent_updates` or `search_by_date_range`
45-
- *"Compare the features of Product A and Product B"* → triggers `search_site` then `compare_items`
21+
| `dsl_list_indices` | Lists all available SN Sites with engine type, locales, and status |
22+
| `dsl_get_mappings` | Returns field mappings (types, facets, multi-valued) in Elasticsearch format |
23+
| `dsl_search` | Executes a full Elasticsearch Query DSL search (40 query types, 35 aggregations) |
24+
| `dsl_get_document` | Retrieves a document by ID with all stored fields |
25+
| `dsl_suggest` | Autocomplete suggestions and spell-check corrections |
26+
| `dsl_get_shards` | Shard/core information: document counts, engine type, endpoints, locales |
27+
28+
### How the LLM uses DSL tools
29+
30+
The LLM follows a pattern similar to how a developer uses the Elasticsearch API:
31+
32+
1. **Discover** → `dsl_list_indices("*")` to find available sites
33+
2. **Understand schema** → `dsl_get_mappings("mySite")` to see fields and types
34+
3. **Search** → `dsl_search("mySite", "en", queryBody)` with full DSL
35+
4. **Deep dive** → `dsl_get_document("mySite", "en", "doc-123")` for full content
36+
5. **Correct typos** → `dsl_suggest("mySite", "en", "enterprse")` for corrections
37+
38+
### The `dsl_search` tool
39+
40+
This is the most powerful tool. The `queryBody` parameter accepts the complete Elasticsearch `_search` request body as a JSON string. The LLM constructs the query based on the user's intent:
41+
42+
**Simple search:**
43+
```json
44+
{"query":{"match":{"title":"machine learning"}},"size":5}
45+
```
46+
47+
**Filtered search with aggregations:**
48+
```json
49+
{
50+
"query":{"bool":{"must":[{"match":{"title":"security"}}],"filter":[{"term":{"type":"article"}}]}},
51+
"size":10,
52+
"aggs":{"by_author":{"terms":{"field":"author","size":5}}},
53+
"highlight":{"fields":{"title":{},"body":{}}}
54+
}
55+
```
56+
57+
**Date range with sorting:**
58+
```json
59+
{
60+
"query":{"range":{"date":{"gte":"2025-01-01"}}},
61+
"sort":[{"date":"desc"}],
62+
"size":20
63+
}
64+
```
65+
66+
**Similar documents (More Like This):**
67+
```json
68+
{"query":{"more_like_this":{"fields":["title","body"],"like":"enterprise search platform","min_term_freq":1}}}
69+
```
70+
71+
**Facet value discovery (terms aggregation):**
72+
```json
73+
{"query":{"match_all":{}},"size":0,"aggs":{"categories":{"terms":{"field":"category","size":50}}}}
74+
```
75+
76+
For the complete DSL reference, see [DSL Query API](./dsl-query.md) and [DSL Compatibility Matrix](./dsl-compatibility.md).
77+
78+
### Prompt examples
79+
80+
- *"Search for documents about authentication in the Sample site"* → `dsl_search` with `match` query
81+
- *"What fields can I filter by on the Sample site?"* → `dsl_get_mappings`
82+
- *"Show me the full content of document ID abc-123"* → `dsl_get_document`
83+
- *"How many documents do we have per content type?"* → `dsl_search` with `terms` aggregation
84+
- *"Find documents similar to the article about Solr configuration"* → `dsl_search` with `more_like_this`
85+
- *"What articles were updated in the last 7 days about security?"* → `dsl_search` with `range` + `sort`
86+
- *"Compare the features of Product A and Product B"* → `dsl_get_document` called for each product
87+
- *"What categories are available?"* → `dsl_search` with `size:0` and `terms` aggregation
88+
- *"How many documents per locale does the site have?"* → `dsl_get_shards`
4689

4790
---
4891

@@ -152,7 +195,7 @@ The Python executable path is configured in **Administration → Settings → Py
152195

153196
## External Tools via MCP Servers
154197

155-
Beyond the 27 native tools, AI Agents can access tools from any external server implementing the **Model Context Protocol (MCP)**. This covers company-internal systems, proprietary data APIs, and the growing ecosystem of public MCP servers.
198+
Beyond the native tools, AI Agents can access tools from any external server implementing the **Model Context Protocol (MCP)**. This covers company-internal systems, proprietary data APIs, and the growing ecosystem of public MCP servers.
156199

157200
See [MCP Servers](./mcp-servers.md) for configuration details.
158201

@@ -164,8 +207,9 @@ See [MCP Servers](./mcp-servers.md) for configuration details.
164207
|---|---|
165208
| [AI Agents](./ai-agents.md) | How to compose agents with the tools they need |
166209
| [MCP Servers](./mcp-servers.md) | Extend agents with external tools via MCP |
210+
| [DSL Query API](./dsl-query.md) | Full reference for the Elasticsearch-compatible DSL |
211+
| [DSL Compatibility Matrix](./dsl-compatibility.md) | Engine compatibility for all DSL features |
167212
| [Assets](./assets.md) | Knowledge Base files queried by RAG tools |
168-
| [Semantic Navigation](./semantic-navigation.md) | The search experience powering SN tools |
213+
| [Semantic Navigation](./semantic-navigation.md) | The search experience powering DSL tools |
169214

170215
---
171-

0 commit comments

Comments
 (0)