Tool best practices for Microsoft Foundry Agent Service

Learn tool best practices for Foundry Agent Service: configure tool_choice, secure tool usage, and troubleshoot tool-calling issues.

When you build agents in Microsoft Foundry Agent Service, tools extend what your agent can do—retrieving information, calling APIs, and connecting to external services. This article helps you configure tools effectively, control when the agent calls them, and keep your data secure.

In your agent instructions, describe what each tool is for and when to use it. For example:

When you need information from my indexed documents, use File Search. When you need to call an API, use the OpenAPI tool. When a tool call fails or returns no results, explain what happened and ask a follow-up question.

Prerequisites

• Access to a Foundry project in the Foundry portal with the Azure AI Developer role or equivalent permissions.
• A model deployed in the same project.
• Any required connections configured for the tools you plan to use (for example, Azure AI Search, SharePoint, or Bing grounding).

Configure and validate tool usage

• Configure tools and connections in the Foundry tool catalog. See Discover and manage tools in the Foundry tool catalog (preview).
• Review run traces to confirm when your agent calls tools and to inspect tool inputs and outputs. For end-to-end tracing setup, see Trace your application.

Improve tool-calling reliability

Control tool calling with tool_choice

Use tool_choice for the most deterministic control over tool calling.

• auto: The model decides whether to call tools.
• required: The model must call one or more tools.
• none: The model doesn’t call tools.

For details, see tool_choice in Foundry project REST (preview).

Write effective tool instructions

• Keep instructions specific and consistent with your tool setup.
• Tell the model what each tool is for.
• If you have multiple tools that overlap, add a decision rule (for example, “Use File Search before Web Search for internal content.”).

Secure tool usage

Tools send and receive data outside the model. Reduce security and privacy risks with these practices:

• Treat tool outputs as untrusted input and validate critical values before acting on them.
• Send only the information required to complete the task.
• Don’t include keys, tokens, or other credentials in prompts.
• Avoid logging secrets in traces or application logs.
• If you connect to non-Microsoft services (for example, third-party MCP servers), review the considerations in Discover and manage tools in the Foundry tool catalog (preview).
• If you need centralized routing and policy enforcement for MCP tools, see Tools governance with AI Gateway (preview).

Tool support by region and model

Region and model determine which tools are available to your agent.

In the tables below: Yes means fully supported, No means not supported, and Limited means partial support that varies by tool configuration. Check individual tool documentation for details.

The following table shows tool availability by region.

This region availability table only accounts for service availability. You need to make sure the model you want to use is also available in the same region.

Region Name	Agent2Agent	Azure AI Search	Browser Automation	Code Interpreter	Computer Use	Fabric Data Agent	File Search	Function	Grounding with Bing Custom Search	Grounding with Bing Search	Image Generation	MCP	OpenAPI	SharePoint	Web Search
australiaeast	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
brazilsouth	yes	yes	yes	yes	no	yes	yes	no	yes	yes	yes	yes	yes	yes	yes
canadaeast	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
eastus	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
eastus2	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
francecentral	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
germanywestcentral	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
italynorth	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
japaneast	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
koreacentral	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
northcentralus	yes	yes	yes	yes	no	yes	yes	no	yes	yes	yes	yes	yes	yes	yes
norwayeast	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
polandcentral	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
southafricanorth	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
southcentralus	yes	yes	yes	no	no	yes	yes	no	yes	yes	yes	yes	yes	yes	yes
southeastasia	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
southindia	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
spaincentral	yes	yes	yes	no	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
swedencentral	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
switzerlandnorth	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
uaenorth	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
uksouth	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes
westus	yes	yes	yes	yes	no	yes	yes	no	yes	yes	yes	yes	yes	yes	yes
westus3	yes	yes	yes	yes	no	yes	yes	yes	yes	yes	yes	yes	yes	yes	yes

Tools are supported by the following models.

For the image generation tool, you need both the gpt-image-1 model and a large language model (LLM) as the orchestrator in the same Microsoft Foundry project.

Model	Agent2Agent	Azure AI Search	Azure Functions	Grounding Bing Custom	Grounding Bing Search	Browser Automation	Code Interpreter	Computer Use	Fabric Data Agent	File Search	Functions	Image Generation	MCP	OpenAPI	SharePoint	Web Search	Work IQ (preview)
Cohere-command-r	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
Cohere-command-r-plus	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
DeepSeek-R1-0528	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
DeepSeek-V3-0324	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
DeepSeek-V3.1	No	No	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
FW-DeepSeek-V3.1	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-DeepSeek-V3.2	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-GLM-4.7	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-GLM-5	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-GLM-5.1	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-GPT-OSS-120B	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Kimi-K2-Instruct-0905	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Kimi-K2-Thinking	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Kimi-K2.5	No	No	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Kimi-K2.6	No	No	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-MiniMax-M2.5	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Qwen3.5-122B-A10B	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
FW-Qwen3.5-397B-A17B	No	Yes	No	No	No	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	Yes
GROK-4-20-REASONING	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
Llama-3.3-70B-Instruct	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
Llama-4-Maverick-17B-128E-Instruct-FP8	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
Llama-4-Scout-17B-16E-Instruct	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
MAI-DS-R1	Yes	No	No	No	No	Yes	Yes	No	No	Yes	Yes	No	Yes	No	No	No	No
Meta-Llama-3.1-405B-Instruct	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
Mistral-large-2407	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
claude-haiku-4-5	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-mythos-preview	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-opus-4-1	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	No	Yes	Yes	Yes	Yes
claude-opus-4-5	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-opus-4-6	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-opus-4-7	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-sonnet-4-5	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
claude-sonnet-4-6	Yes	Yes	No	No	No	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
codex-mini	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
computer-use-preview	No	No	No	No	No	No	No	Yes	No	No	No	No	No	No	No	No	No
gpt-35-turbo	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-4	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	Yes
gpt-4.1	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-4.1-mini	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-4.1-nano	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-4.5-preview	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-4o	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-4o-mini	Yes	No	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-5	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
gpt-5-chat	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	Yes
gpt-5-codex	No	No	No	No	No	No	Yes	No	No	Yes	No	No	Yes	No	No	No	Yes
gpt-5-mini	No	No	No	No	No	No	Yes	No	No	Yes	No	No	Yes	No	No	Yes	Yes
gpt-5-nano	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	Yes
gpt-5-pro	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-5.1	No	Yes	Yes	No	Yes	No	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-5.1-chat	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-5.1-codex	No	No	No	No	No	No	Yes	No	No	Yes	No	No	Yes	No	No	No	Yes
gpt-5.1-codex-max	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-5.1-codex-mini	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
gpt-5.2	No	Yes	Yes	No	Yes	No	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
gpt-5.2-chat	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	No	Yes	Yes
gpt-5.2-codex	No	No	No	No	No	No	Yes	No	No	Yes	No	No	Yes	No	No	No	Yes
gpt-5.3-chat	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.3-codex	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.4	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.4-mini	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.4-nano	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.4-pro	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-5.5	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-chat-latest	Yes	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	Yes	Yes	Yes	Yes	Yes
gpt-oss-120b	No	No	No	No	No	No	Yes	No	No	Yes	Yes	No	Yes	No	No	No	Yes
grok-3	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-3-mini	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
grok-4-1-fast-non-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4-1-fast-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4-20-non-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4-20-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4-fast-non-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
grok-4-fast-reasoning	No	Yes	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	Yes	Yes
mistral-small-2503	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
model-router	No	No	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes
o1	No	Yes	No	Yes	No	Yes	Yes	No	No	Yes	Yes	No	Yes	No	Yes	Yes	Yes
o1-mini	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
o1-preview	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
o3	Yes	Yes	No	Yes	No	Yes	Yes	No	Yes	Yes	Yes	No	Yes	Yes	No	Yes	Yes
o3-deep-research	No	No	No	No	No	No	No	No	No	No	No	No	Yes	No	No	Yes	Yes
o3-mini	Yes	No	No	Yes	Yes	Yes	Yes	No	Yes	Yes	No	No	No	No	No	No	Yes
o3-pro	No	No	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No	No
o4-mini	Yes	No	No	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes	No	Yes	No	Yes	Yes	Yes

Troubleshooting

Use these checks to resolve common issues:

• Your agent doesn’t call a tool:
  • Confirm the tool is attached to the agent.
  • Confirm the model supports the tool.
  • If you need deterministic behavior, set tool_choice to required.
  • Review run traces to confirm whether the model produced a tool call.
• Tool calls return empty or irrelevant results:
  • Improve tool descriptions and agent instructions.
  • For retrieval tools, ensure your data is ingested and searchable.
• Tool calls fail:
  • Verify tool configuration and authentication.
  • For MCP and OpenAPI tools, validate the endpoint is reachable and returns expected responses.
• Foundry returns a “tool not supported” error even though the tables show support:
  • Tool availability requires support from both the model and the region. Check the region availability table for your region and the model support table for your model. If either shows No, the tool can’t run, even if the other shows Yes.
  • Confirm the model is actually deployed in the project and region you’re targeting. A model that supports a tool in general might not be deployed in every region.
  • Try a different region or a different model deployment that supports the tool. For example, code interpreter doesn’t run in regions that show no for Code Interpreter (such as southcentralus and spaincentral), regardless of which model you use.

FAQ

How do I validate whether a tool was called?

Review run traces to confirm whether your agent called a tool and to inspect tool inputs and outputs. For end-to-end tracing setup, see Trace your application.

How do I make tool usage more reliable?

Start with clear tool instructions. If you need deterministic tool calling, use tool_choice. For details, see Control tool calling with tool_choice.

Related content

Tool management

• Discover and manage tools in the Foundry tool catalog (preview)
• Tools governance with AI Gateway (preview)

Retrieval and search tools

• Azure AI Search
• File search
• Web search
• Grounding with Bing tools
• SharePoint (preview)

Data and integration tools

• Fabric data agent (preview)
• Model Context Protocol (MCP) (preview)
• OpenAPI tool
• Function calling

Automation and generation tools

• Code interpreter
• Browser automation (preview)
• Computer Use (preview)
• Image generation (preview)
• Agent2Agent (A2A) tool (preview)