Agent tools overview for Foundry Agent Service

Tools extend what your agents can do in Microsoft Foundry Agent Service. An agent on its own can generate text, but tools let it take action — searching the web, running code, querying your data, or calling your own APIs. This article explains what tools are, the types of tools available, how to use a tool in an agent, and how to manage authentication. It also introduces the Foundry tool catalog where you discover and configure tools. To use tools, you need access to a Foundry project and permission to manage tools in that project.

What are tools?

A tool is a capability that an agent can invoke during a conversation to perform a specific task. When an agent receives a user message, the model decides whether to call a tool based on the agent's instructions and the available tool definitions. The agent sends the tool request, your application or the service executes it, and the result flows back into the conversation so the agent can continue with accurate, up-to-date information.

Tools enable agents to go beyond text generation. For example, an agent can:

• Search the web for current information before answering.
• Run Python code to analyze a dataset and generate a chart.
• Query a vector store of your documents to ground its response in your data.
• Call an external API to look up a customer record or create a support ticket.

Types of tools

Foundry Agent Service provides two categories of tools: built-in tools that are ready to use after basic configuration, and custom tools that let you bring your own capabilities.

Built-in tools

Built-in tools are preconfigured capabilities provided by Foundry Agent Service. You enable them on your agent and the service handles execution. No external hosting or custom code is required.

The most commonly used built-in tools include:

• Web search — Add web search to your agent. The agent retrieves real-time information from the public web and returns answers with inline citations. This is the recommended way to add web grounding. For advanced scenarios such as market-specific filtering, see Grounding with Bing tools and the web grounding overview.
• Code Interpreter — Let agents write and run Python code in a sandboxed environment for data analysis, math, and chart generation.
• File Search — Augment agents with knowledge from uploaded files or proprietary documents using vector search.
• Function calling — Define custom functions that the agent can call. Your application executes the function and returns the result.

For the complete list of built-in tools, see All built-in tools.

Custom tools

Custom tools let you extend your agent with your own APIs, services, or other agents. Use custom tools when built-in tools don't cover your scenario.

The most common custom tool options include:

• Model Context Protocol (MCP) — Connect your agent to tools hosted on an MCP server endpoint. Best for tools shared across multiple agents or maintained by a different team.
• Agent-to-Agent (A2A) (preview) — Connect your agent to other agents through A2A-compatible endpoints for cross-agent communication.
• OpenAPI tool — Connect your agent to external HTTP APIs using an OpenAPI 3.0 or 3.1 specification.

For the complete list of custom tool options, see All custom tools.

Use a tool in an agent

To add a tool to an agent, include it in the agent's tool list when you create or update the agent definition. The following example creates an agent with the web search tool enabled and sends a query:

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

project = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Create an agent with web search enabled
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_NAME"],
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)

# Start a conversation and send a query
openai = project.get_openai_client()
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

Each tool type has its own configuration. For detailed setup and code samples in all supported languages, see the individual tool how-to guides linked in the types of tools section.

Customize tool behavior at runtime with structured inputs

By default, tool configurations such as file IDs, vector store IDs, and MCP server endpoints are fixed when you create the agent. Structured inputs in tool properties allows you to override these values at runtime without creating a new agent version.

Structured inputs are useful when:

• Different users need different vector stores or files based on their context.
• You want to reuse the same agent definition across environments (development, staging, production).
• MCP server endpoints or authentication tokens vary per request.

The following tool properties support customization via structured inputs:

For example, an agent definition with a templated vector store:

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

At runtime, provide the actual value:

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

Manage authentication for tools

Different tools require different authentication approaches. Understanding these options helps you connect tools securely.

Built-in tools

Most built-in tools such as Code Interpreter and File Search authenticate through Foundry Agent Service automatically and require no extra configuration. Tools that connect to external data sources (for example, Azure AI Search or SharePoint) use the connections configured in your Foundry project.

MCP servers

MCP servers support multiple authentication methods depending on the server: key-based authentication (API key or token), Microsoft Entra authentication (managed identity), and OAuth for user-level identity passthrough.

The following example connects to an MCP server using key-based authentication. Store the credential in a project connection, then reference the connection name when you create the tool:

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

For Microsoft Entra authentication, use agent identity or project managed identity instead of a connection. The service requests a token automatically. For OAuth identity passthrough (per-user auth), Agent Service generates a consent link that users authorize on first use.

For detailed setup steps for all methods, see Set up MCP server authentication.

OpenAPI tools

OpenAPI tools support anonymous, API key, and managed identity authentication. The auth configuration is part of the tool definition.

Anonymous authentication — use when the API doesn't require credentials:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

API key authentication — store the key in a project connection, then reference it. Your OpenAPI spec must include securitySchemes and security sections:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

For managed identity configuration, see Connect agents to OpenAPI tools.

All built-in tools

The following table lists all built-in tools available in Foundry Agent Service.

All custom tools

The following table lists all custom tool options for connecting your own capabilities to an agent.

Key concepts

Use these definitions to keep terminology consistent:

Considerations for using non-Microsoft services and servers

Your use of connected non-Microsoft services and servers ("non-Microsoft services") is subject to the terms between you and the service provider. Non-Microsoft services are non-Microsoft products under your agreement governing use of Microsoft online services. When you connect to non-Microsoft services, some of your data (such as prompt content) is sent to the non-Microsoft service, or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft services and data, along with any charges associated with that use.

Third parties (not Microsoft) create the non-Microsoft services, including remote MCP servers, that you choose to connect. Microsoft doesn't test or verify these servers. Microsoft has no responsibility to you or others in relation to your use of any non-Microsoft services.

Carefully review and track the MCP servers you add to Foundry Agent Service. Rely on servers hosted by trusted service providers themselves rather than proxies.

The MCP tool can pass custom headers that a remote MCP server might require for authentication. Treat any credentials as secrets:

• Only provide the minimum required headers.
• Don't include credentials in prompts.
• If you log requests for auditing, avoid logging secrets or sensitive prompt content.
• Review the provider's data handling practices, including retention and data location.

Discover and manage tools in the portal

In the Foundry portal, go to your project and select Build > Tools to open Foundry Tools. From there, you can browse the tool catalog, configure tools, and add them to agents or workflows. If you need tools that are only visible within your organization, create a private tool catalog.

To explore tools while you build, use the Agents playground. For more information, see Microsoft Foundry Playgrounds.

Tool types in the catalog

The tool catalog includes three types of entries:

Remote MCP server: The publisher hosts the server and provides a static or dynamic endpoint. Follow the configuration guidance to provide the required settings, such as an endpoint and authentication details.

Local MCP server: You host the server yourself, then connect it to Foundry by providing its endpoint. To build and register your own server, see Build and register an MCP server. To connect an MCP endpoint to an agent, see Connect to MCP servers.

Custom: MCP servers converted from Azure Logic App Connectors. These servers require additional configuration to convert to remote MCP servers.

Filter and search

Foundry Tools provides the following filters to help you find the right tools:

When you select a tool, Foundry Tools shows the setup details you need to configure it.

Manage configured tools

In your tools list, you can find the tools you configured, along with details such as endpoints and authentication settings. You can also add tools to agents and workflows.

Before you delete a tool, check which agents or workflows use it. Deleting a tool can break runs that depend on it.

Availability and limitations

Tool availability varies by model and region.

For the latest model and region support details across tools, see Best practices for using tools in Foundry Agent Service.

Troubleshooting

Use these checks to resolve common issues:

• You can't find the tool catalog: Confirm you're in the correct project, and then go to Build > Tools.
• A tool is visible but you can't configure it: Review the tool's required authentication and configuration inputs, and verify you have access to any dependent services.
• Your agent doesn't call a tool: Use the validation guidance in Best practices for using tools in Foundry Agent Service.

Related content

• Tool best practices for Foundry Agent Service
• Set up MCP server authentication
• Govern MCP tools by using an AI gateway
• Create a private tool catalog
• Build and register an MCP server
• Foundry MCP Server best practices and security guidance