Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
Knowledge base tools functionality is in public preview and is subject to the Supplemental Terms of Use for Microsoft Azure Previews.
For preview terms specific to this feature, see Preview functionality.
Knowledge base tools let one knowledge base support multiple task-specific retrieval workflows for applications and agents. Each tool selects knowledge sources and sets reusable retrieval behavior, such as reasoning effort and output limits. Clients can call a tool through REST or discover and invoke it through the MCP endpoint.
Use knowledge base tools when clients need a consistent retrieval entry point without rebuilding the same knowledge sources and defaults for every request. In this article, you create a tool, test how its saved settings interact with request-time controls, invoke it through MCP, and update or remove it.
Usage support
| Azure portal | Microsoft Foundry portal | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ❌ | ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Prerequisites
- Permission to create and query the sample resources. Configure keyless authentication with the Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader roles assigned to your user account.
- The most recent preview version of
azure-search-documents, and theazure-identitypackage. See the Python client library.
- A .NET 8 or later console project with the most recent preview version of
Azure.Search.Documents. See the .NET client library.
Create a sample knowledge base
Create an index, knowledge source, and knowledge base.
Sign in as described in Connect to Foundry IQ (Azure AI Search). Run the SDK snippets in order.
from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient
search_endpoint = "<search-endpoint>"
index_name = "kb-tools-policy-index"
knowledge_source_name = "kb-tools-policy-source"
knowledge_base_name = "kb-tools-policy-kb"
credential = DefaultAzureCredential()
index_client = SearchIndexClient(search_endpoint, credential)
search_client = SearchClient(search_endpoint, index_name, credential)
Reference: DefaultAzureCredential, SearchClient, SearchIndexClient.
Create the index and upload three synthetic policies.
from azure.search.documents.indexes.models import (
SearchFieldDataType,
SearchIndex,
SearchableField,
SimpleField,
)
index = index_client.create_index(SearchIndex(
name=index_name,
fields=[
SimpleField(
name="id", type=SearchFieldDataType.STRING, key=True,
),
SearchableField(name="title"),
SearchableField(name="content"),
SimpleField(
name="jurisdiction",
type=SearchFieldDataType.STRING,
filterable=True,
),
],
))
documents = [
{
"id": "ca-leave",
"title": "Canadian parental leave",
"jurisdiction": "CA",
"content": (
"Canadian employees receive four weeks of paid parental leave."
),
},
{
"id": "ca-request",
"title": "Canadian leave requests",
"jurisdiction": "CA",
"content": (
"Canadian employees submit parental leave requests through "
"the HR portal at least 30 days before leave."
),
},
{
"id": "us-leave",
"title": "US parental leave",
"jurisdiction": "US",
"content": "US employees receive six weeks of paid parental leave.",
},
]
search_client.upload_documents(documents=documents)
Reference: SearchIndexClient, SearchIndex, SearchClient.upload_documents.
Sign in as described in Connect to Foundry IQ. Run the SDK snippets in order.
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
string searchEndpoint = "<search-endpoint>";
string indexName = "kb-tools-policy-index";
string knowledgeSourceName = "kb-tools-policy-source";
string knowledgeBaseName = "kb-tools-policy-kb";
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var searchClient = new SearchClient(
new Uri(searchEndpoint), indexName, credential);
Reference: DefaultAzureCredential, SearchClient, SearchIndexClient.
Create the index and upload three synthetic policies.
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
var index = (await indexClient.CreateIndexAsync(
new SearchIndex(indexName,
[
new SimpleField("id", SearchFieldDataType.String)
{
IsKey = true,
},
new SearchableField("title"),
new SearchableField("content"),
new SimpleField("jurisdiction", SearchFieldDataType.String)
{
IsFilterable = true,
},
])).Value;
var documents = new SearchDocument[]
{
new()
{
["id"] = "ca-leave",
["title"] = "Canadian parental leave",
["jurisdiction"] = "CA",
["content"] =
"Canadian employees receive four weeks of paid parental leave.",
},
new()
{
["id"] = "ca-request",
["title"] = "Canadian leave requests",
["jurisdiction"] = "CA",
["content"] =
"Canadian employees submit parental leave requests through " +
"the HR portal at least 30 days before leave.",
},
new()
{
["id"] = "us-leave",
["title"] = "US parental leave",
["jurisdiction"] = "US",
["content"] =
"US employees receive six weeks of paid parental leave.",
},
};
await searchClient.UploadDocumentsAsync(documents);
Reference: SearchIndexClient, SearchIndex, SearchClient.UploadDocumentsAsync.
Create the knowledge source.
from azure.search.documents.indexes.models import ( SearchIndexFieldReference, SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, ) source = index_client.create_knowledge_source( SearchIndexKnowledgeSource( name=knowledge_source_name, search_index_parameters=SearchIndexKnowledgeSourceParameters( search_index_name=index_name, source_data_fields=[ SearchIndexFieldReference(name="id"), SearchIndexFieldReference(name="title"), SearchIndexFieldReference(name="content"), SearchIndexFieldReference(name="jurisdiction"), ], ), ), )Reference: SearchIndexClient.
Create a model-free knowledge base with Minimal reasoning and extractive output.
from azure.search.documents.indexes.models import ( KnowledgeBase, KnowledgeSourceReference, ) from azure.search.documents.knowledgebases.models import ( KnowledgeRetrievalMinimalReasoningEffort, KnowledgeRetrievalOutputMode, ) knowledge_base = index_client.create_knowledge_base(KnowledgeBase( name=knowledge_base_name, knowledge_sources=[KnowledgeSourceReference(name=source.name)], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA, ))Reference: KnowledgeBase, SearchIndexClient.
Create the knowledge source.
using Azure.Search.Documents.Indexes.Models; var source = (await indexClient.CreateKnowledgeSourceAsync( new SearchIndexKnowledgeSource(knowledgeSourceName, new SearchIndexKnowledgeSourceParameters(indexName) { SourceDataFields = { new SearchIndexFieldReference("id"), new SearchIndexFieldReference("title"), new SearchIndexFieldReference("content"), new SearchIndexFieldReference("jurisdiction"), }, }))).Value;Reference: SearchIndexClient.
Create a model-free knowledge base with Minimal reasoning and extractive output.
using Azure.Search.Documents.Indexes.Models; using Azure.Search.Documents.KnowledgeBases.Models; var knowledgeBase = (await indexClient.CreateKnowledgeBaseAsync( new KnowledgeBase(knowledgeBaseName, [new KnowledgeSourceReference(source.Name)]) { RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData, })).Value;Reference: KnowledgeBase, SearchIndexClient.
Set the Foundry IQ service endpoint and access token. To get an access token, see Connect to Foundry IQ.
@searchEndpoint = <search-endpoint> @searchAccessToken = <search-access-token> @indexName = kb-tools-policy-index @knowledgeSourceName = kb-tools-policy-source @knowledgeBaseName = kb-tools-policy-kbCreate the index with searchable policy text and a filterable jurisdiction field.
PUT {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{indexName}}", "fields": [ { "name": "id", "type": "Edm.String", "key": true }, { "name": "title", "type": "Edm.String", "searchable": true }, { "name": "content", "type": "Edm.String", "searchable": true }, { "name": "jurisdiction", "type": "Edm.String", "filterable": true } ] }Reference: Indexes - Create or update.
Upload three synthetic policies.
POST {{searchEndpoint}}/indexes/{{indexName}}/docs/index?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "value": [ { "@search.action": "upload", "id": "ca-leave", "title": "Canadian parental leave", "jurisdiction": "CA", "content": "Canadian employees receive four weeks of paid parental leave." }, { "@search.action": "upload", "id": "ca-request", "title": "Canadian leave requests", "jurisdiction": "CA", "content": "Canadian employees submit parental leave requests through the HR portal at least 30 days before leave." }, { "@search.action": "upload", "id": "us-leave", "title": "US parental leave", "jurisdiction": "US", "content": "US employees receive six weeks of paid parental leave." } ] }Reference: Documents - Index.
Create the knowledge source.
PUT {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{knowledgeSourceName}}", "kind": "searchIndex", "searchIndexParameters": { "searchIndexName": "{{indexName}}", "sourceDataFields": [ { "name": "id" }, { "name": "title" }, { "name": "content" }, { "name": "jurisdiction" } ] } }Reference: Knowledge sources - Create or update.
Create the knowledge base with Minimal reasoning and extractive output.
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{knowledgeBaseName}}", "knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData" }Reference: Knowledge bases - Create or update.
Add a custom tool to the knowledge base
A tool references knowledge sources already defined on the knowledge base. The knowledge base stores the tool's name, description, and defaults.
Configure the Canadian knowledge source reference.
from azure.search.documents.indexes.models import ( KnowledgeBaseToolKnowledgeSourceReference, ) tool_source = KnowledgeBaseToolKnowledgeSourceReference( name=source.name, filter_add_on="jurisdiction eq 'CA'", reranker_threshold=0, max_output_documents=50, fail_on_error=True, )Reference: Index models.
Add the tool to the knowledge base.
from azure.search.documents.indexes.models import ( KnowledgeBaseRetrieveDefaults, KnowledgeBaseTool, ) from azure.search.documents.knowledgebases.models import ( KnowledgeRetrievalMinimalReasoningEffort, ) tool = KnowledgeBaseTool( name="canada-hr-search", description="Find Canadian employee leave and benefits policies.", knowledge_sources=[tool_source], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), retrieve_defaults=KnowledgeBaseRetrieveDefaults( max_runtime_in_seconds=30, max_output_size_in_tokens=5000, max_output_documents=12, ), ) knowledge_base.tools = [tool] knowledge_base = index_client.create_or_update_knowledge_base( knowledge_base, )Reference: SearchIndexClient.
Configure the Canadian knowledge source reference.
using Azure.Search.Documents.Indexes.Models; var toolSource = new KnowledgeBaseToolKnowledgeSourceReference(source.Name) { FilterAddOn = "jurisdiction eq 'CA'", RerankerThreshold = 0, MaxOutputDocuments = 50, FailOnError = true, };Reference: Index models.
Add the tool to the knowledge base.
using Azure.Search.Documents.Indexes.Models; using Azure.Search.Documents.KnowledgeBases.Models; var tool = new KnowledgeBaseTool( "canada-hr-search", "Find Canadian employee leave and benefits policies.", [toolSource]) { RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), RetrieveDefaults = new KnowledgeBaseRetrieveDefaults { MaxRuntimeInSeconds = 30, MaxOutputSizeInTokens = 5000, MaxOutputDocuments = 12, }, }; knowledgeBase.Tools.Add(tool); knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync( knowledgeBase)).Value;Reference: SearchIndexClient.
Send the complete knowledge base definition with one tool.
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"name": "{{knowledgeBaseName}}",
"knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"tools": [{
"name": "canada-hr-search",
"description": "Find Canadian employee leave and benefits policies.",
"knowledgeSources": [{
"name": "{{knowledgeSourceName}}",
"filterAddOn": "jurisdiction eq 'CA'",
"rerankerThreshold": 0,
"maxOutputDocuments": 50,
"failOnError": true
}],
"retrievalReasoningEffort": { "kind": "minimal" },
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputSizeInTokens": 5000,
"maxOutputDocuments": 12
}
}]
}
Reference: Knowledge bases - Create or update.
The CA filter belongs on the tool's knowledge source reference, not the knowledge source definition. Selecting the tool limits retrieval to its configured knowledge sources before retrieval begins. In this one-source example, the filter restricts retrieval to Canadian documents.
Invoke the tool
Select the tool on the existing retrieve operation. Use one semantic intent containing the complete question.
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
KnowledgeBaseRetrievalRequest,
KnowledgeRetrievalMinimalReasoningEffort,
KnowledgeRetrievalOutputMode,
KnowledgeRetrievalSemanticIntent,
)
question = "What parental leave do Canadian employees receive and how do they request it?"
retrieval_client = KnowledgeBaseRetrievalClient(
search_endpoint, credential, knowledge_base_name=knowledge_base.name,
)
request = KnowledgeBaseRetrievalRequest(
tool_name="canada-hr-search",
intents=[KnowledgeRetrievalSemanticIntent(search=question)],
retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
include_activity=True,
)
response = retrieval_client.retrieve(request)
Reference: KnowledgeBaseRetrievalClient.
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;
string question = "What parental leave do Canadian employees receive and how do they request it?";
var retrievalClient = new KnowledgeBaseRetrievalClient(
new Uri(searchEndpoint), knowledgeBase.Name, credential);
var request = new KnowledgeBaseRetrievalRequest
{
ToolName = "canada-hr-search",
Intents = { new KnowledgeRetrievalSemanticIntent(question) },
RetrievalReasoningEffort =
new KnowledgeRetrievalMinimalReasoningEffort(),
OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
IncludeActivity = true,
};
var response = await retrievalClient.RetrieveAsync(request);
Reference: KnowledgeBaseRetrievalClient.
Send one semantic intent containing the complete question.
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"toolName": "canada-hr-search",
"intents": [{
"type": "semantic",
"search": "What parental leave do Canadian employees receive and how do they request it?"
}],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"includeActivity": true
}
Reference: Knowledge retrieval - Retrieve.
Confirm that the response contains both Canadian policies and excludes us-leave. To inspect the returned evidence and source execution, see Extracted response, References array, and Activity array.
Omit the tool name to use ordinary knowledge base-wide retrieval. An empty or unknown tool name fails instead of falling back to knowledge base-wide retrieval.
Apply defaults and intersect filters
Tool defaults override knowledge base defaults. Explicit request values override ordinary tool defaults, but request filters don't replace tool filters: they combine with AND.
Use these controls after the Canadian baseline. A request can't add knowledge sources to the tool or replace its filter. Request source exclusion takes precedence over a tool's alwaysQuerySource setting.
Request US policies without selecting a tool.
from azure.search.documents.knowledgebases.models import ( KnowledgeBaseRetrievalRequest, KnowledgeRetrievalMinimalReasoningEffort, KnowledgeRetrievalOutputMode, KnowledgeRetrievalSemanticIntent, SearchIndexKnowledgeSourceParams, ) us_request = KnowledgeBaseRetrievalRequest( intents=[KnowledgeRetrievalSemanticIntent( search="What parental leave do US employees receive?", )], knowledge_source_params=[SearchIndexKnowledgeSourceParams( knowledge_source_name=source.name, filter_add_on="jurisdiction eq 'US'", )], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA, include_activity=True, ) us_response = retrieval_client.retrieve(us_request)Reference: KnowledgeBaseRetrievalClient.
Select the Canadian tool on the same US request.
us_request.tool_name = "canada-hr-search" intersection_response = retrieval_client.retrieve(us_request)Reference: KnowledgeBaseRetrievalClient.
The effective filter is CA AND US, so no results are returned.
Set a one-document budget on the original Canadian request.
request.max_output_documents = 1 limited_response = retrieval_client.retrieve(request)Reference: KnowledgeBaseRetrievalClient.
Request US policies without selecting a tool.
using Azure.Search.Documents.KnowledgeBases.Models; var usRequest = new KnowledgeBaseRetrievalRequest { Intents = { new KnowledgeRetrievalSemanticIntent( "What parental leave do US employees receive?"), }, KnowledgeSourceParams = { new SearchIndexKnowledgeSourceParams(source.Name) { FilterAddOn = "jurisdiction eq 'US'", }, }, RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData, IncludeActivity = true, }; var usResponse = await retrievalClient.RetrieveAsync(usRequest);Reference: KnowledgeBaseRetrievalClient.
Select the Canadian tool on the same US request.
usRequest.ToolName = "canada-hr-search"; var intersectionResponse = await retrievalClient.RetrieveAsync(usRequest);Reference: KnowledgeBaseRetrievalClient.
The effective filter is CA AND US, so no results are returned.
Set a one-document budget on the original Canadian request.
request.MaxOutputDocuments = 1; var limitedResponse = await retrievalClient.RetrieveAsync(request);Reference: KnowledgeBaseRetrievalClient.
Request US policies without
toolName, using an explicit US source filter.POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "intents": [{ "type": "semantic", "search": "What parental leave do US employees receive?" }], "knowledgeSourceParams": [{ "knowledgeSourceName": "{{knowledgeSourceName}}", "kind": "searchIndex", "filterAddOn": "jurisdiction eq 'US'" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true }Reference: Knowledge retrieval - Retrieve.
Repeat the same US question and request filter with the Canadian tool selected.
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "toolName": "canada-hr-search", "intents": [{ "type": "semantic", "search": "What parental leave do US employees receive?" }], "knowledgeSourceParams": [{ "knowledgeSourceName": "{{knowledgeSourceName}}", "kind": "searchIndex", "filterAddOn": "jurisdiction eq 'US'" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true }Reference: Knowledge retrieval - Retrieve.
The effective filter is CA AND US, so no results are returned.
Override the tool's ordinary output-document default with a one-document request budget.
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "toolName": "canada-hr-search", "intents": [{ "type": "semantic", "search": "What parental leave do Canadian employees receive and how do they request it?" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true, "maxOutputDocuments": 1 }Reference: Knowledge retrieval - Retrieve.
Source-level filterAddOn is supported for compatible search-index sources; incompatible source kinds fail validation when saved. Refer to query-time filtering for the request shape, and Agentic retrieval limits for shared limits.
Discover and call the tool through MCP
To discover and call canada-hr-search, follow the steps in Call the MCP endpoint, with two changes for custom knowledge base retrieval tools. Use the 2026-11-01-preview MCP endpoint because custom tools aren't available in earlier API versions. When you allow or call a tool, use the configured name canada-hr-search instead of knowledge_base_retrieve; discovery returns that same name.
Remove the tool
Clear the tools and update the knowledge base.
knowledge_base.tools = []
knowledge_base = index_client.create_or_update_knowledge_base(
knowledge_base,
)
Reference: SearchIndexClient.
Clear the tools and update the knowledge base.
knowledgeBase.Tools.Clear();
knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(
knowledgeBase)).Value;
Reference: SearchIndexClient.
Send the complete knowledge base definition with an empty tools array.
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"name": "{{knowledgeBaseName}}",
"knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"tools": []
}
Reference: Knowledge bases - Create or update.
Troubleshooting
For more comprehensive troubleshooting, see Query a knowledge base using the retrieve action or MCP endpoint.
Clean up sample resources
Removing a tool doesn't delete the knowledge base or its source. Delete only resources you created for this sample, in dependency order: knowledge base, knowledge source, then index.
index_client.delete_knowledge_base(knowledge_base_name)
index_client.delete_knowledge_source(knowledge_source_name)
index_client.delete_index(index_name)
Reference: SearchIndexClient.
await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
await indexClient.DeleteIndexAsync(indexName);
Reference: SearchIndexClient.
### Delete the owned sample KB
DELETE {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}
### Delete the owned sample knowledge source
DELETE {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}
### Delete the owned sample index
DELETE {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}
Reference: Knowledge bases, Knowledge sources, and Indexes.