Merge pull request #4629 from aahill/tool-catalog-update

Tools update

Author: JillGrant615

articles/ai-services/agents/how-to/tools/catalog.md

@@ -1,7 +1,7 @@
 ---
-title: 'What is the tool catalog in Azure AI Agents Service?'
+title: 'What are tools in Azure AI Foundry Agent Service'
 titleSuffix: Azure AI Foundry
-description: Learn how to use the various tools available in the Azure AI Agents Service.
+description: Learn how to use the various tools available in the Azure AI Foundry Agent Service.
 services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
@@ -12,17 +12,49 @@ ms.author: aahi
 ms.custom: azure-ai-agents
 ---
 
-# What is the tool catalog in the Azure AI Agent Service? 
+# What are tools in Azure AI Foundry Agent Service?
 
-The tool catalog in Azure AI Foundry portal is the hub to discover and use a wide range of tools for building AI agents with Azure AI Agent Service. The tool catalog features tools for extending your agents' abilities using hosted tools, and ones offered from partners such as Tripadvisor, and Morningstar. 
+To empower your AI agent with grounded data or the capability to take actions and automating workflows, the Foundry Agent service provides a wide range of built-in tools, such as Grounding with Bing Search, Azure AI Search, Azure Logic Apps, as well as third-party parter tools, such as Tripadvisor. This page is designed to provide an overview of tools provided in the Foundry Agent Service. 
+
+## Knowledge tools
+
+To keep your AI agent informed with richer context from various data sources. The Foundry Agent Service has covered a wide range of data types:
+
+- **private data**: Azure AI Search, File Search, Microsoft Fabric, and more
+- **public web data**: Grounding with Bing Search
+- **licensed data**: Tripadvisor, Morningstar
+- **unstructured data**: Azure AI Search, File Search
+- **structured data**: Microsoft Fabric and more
+
+## Action tools
+
+To streamline workflows with your AI agent with capabilities to take actions. The Foundry Agent Service provides different action tools for you with different level of flexibility, control, and ease of integration:
+
+- **Azure Logic Apps**: Low-code / no-code solution to add a workflow to your AI Agent
+- **OpenAPI Spec tool**: Bring an existing OpenAPI specification of a service API you want to add to your AI agent, with no or minor changes.
+- **Function calling**: Write your own custom, stateless functions to define the expected behaviors.
+- **Azure Functions**: Write and manage your own custom, stateful functions. 
+
+## How does a tool work in the Foundry Agent Service?
+
+Tools are optional capabilities you can add to your AI agent for AI models to decide and pick based on the user query and context. When a user sends a query, the AI model identifies the intent with the context and potentially rewrite the user query. Then the AI model decides which tools to be called for each run. For example, if you add both the Grounding with Bing Search tool and the Azure AI Search tool to your agent and ask "*what is the weather in Seattle today?*", the model will identify your intent to ask about real-time information and more likely to invoke the Grounding with Bing Search tool.
+
+You can add tools at the agent, thread, or run level. By providing tools at a narrower level, the tool resources will **override** tool resources at a broader level. For example, tool resources at the run level override tool resources at thread level. Currently, you can add multiple tools but you can add **one instance of each** of the following tools: File Search, Azure AI Search, Grounding with Bing Search, Grounding with Bing Custom Search, Microsoft Fabric, and other tools under `knowledge` section. 
+
+When a user sends a query to the agent, it will create a [thread, run, and message](../../concepts/threads-runs-messages.md). For each run, the AI model decides what tools to invoke based on the user intent and available tool resources. Based on the tool outputs, the AI model might decide to invoke another tool or call the same tool again to get more context. For example, when you use Grounding with Bing Search tool, you might see multiple Bing Search queries when [tracing a thread](../../concepts/tracing.md). This means the AI model actually calls the Grounding with Bing Search tool multiple times with different queries to get more information. If you want to learn more about what tools are called and how the AI model invokes them, check the run step details.
+
+There are various ways to influence how your AI agent invokes tools:
+
+- The `tool_choice` parameter: Most deterministic, controls which (if any) tool is called by the model. By default, it is set to `auto`, which means the AI model will decide. If you want to **force** the model to call a specific tool, you can provide the specification of this tool, for example `{"type": "function", "function": {"name": "my_function"}}`.
+- The `instructions` parameter: Nondeterministic. Use the instructions to help the AI model understand your use case and the purposes of each tool. You want to tell the AI model what information or actions each tool can do. For example "*use the AI Search tool `<tool_name>` for product related information, use the Fabric tool `<tool_name>` for sales related information*." Sometimes the user query can be responded by the model's base knowledge or by the tools, you want to provide instructions like "*use the tool outputs to generate a response, don't use your own knowledge.*"
 
 ## Prerequisites 
 
 * [A created agent](../../quickstart.md) 
 
-## Supported tools 
+## Built-in tools 
 
-The following is a list of tools supported by Azure AI Agent Service. 
+The Foundry Agent Service provides the following built-in tools. You can use them with the REST API, SDK, and Azure AI Foundry portal.  
 
 |Tool  |Description  |
 |---------|---------|
@@ -33,13 +65,17 @@ The following is a list of tools supported by Azure AI Agent Service.
 |[Function calling](./function-calling.md)     |Describe the structure of functions you create to an agent and have them be called when appropriate during the agent's interactions with users.         |
 |[Grounding with Bing Search](./bing-grounding.md)     | Enable your agent to use Bing Search to access and return information from the internet.         |
 | [Microsoft Fabric](./fabric.md) | Integrate your agent with the [Microsoft Fabric data agent](https://go.microsoft.com/fwlink/?linkid=2312815) to unlock powerful data analysis capabilities. |
+| [Microsoft Fabric (preview)](./fabric.md) | Integrate your agent with the [Microsoft Fabric data agent](https://go.microsoft.com/fwlink/?linkid=2312815) to unlock powerful data analysis capabilities. |
 | [OpenAPI 3.0 Specified tool ](./openapi-spec.md) | Connect your Azure AI Agent to external APIs using functions with an OpenAPI 3.0 specification. |
+|[SharePoint (preview)](./sharepoint.md) | Ground your agents using your SharePoint sites. | 
+
+## Non-microsoft tools
 
-## Licensed data tools
+The following tools are authored by third-party partners. Use the links below to view the documentation and code samples. 
 
 > [!IMPORTANT]
 > * Your use of connected non-Microsoft services is subject to the terms between you and the service provider. By connecting to a non-Microsoft service, you acknowledge that some of your data, such as prompt content, is passed to the non-Microsoft service, and/or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft data. 
-> * Using tools from tool catalog may incur usage with tool providers, review the pricing plan with your selected tool data providers. 
+> * Using tools from tool catalog might incur usage with tool providers, review the pricing plan with your selected tool providers. 
 
 |Tool  |Description  |
 |---------|---------|