- Home
- AI agents
- Tools, MCP and agent-to-agent
- Tool calling and actions
Build · Tools, MCP and agent-to-agent
How does tool calling work in AI agents?
Tool calling, also called function calling, is how an AI model asks your software to act. The model picks a named tool and fills in its inputs, usually as JSON that matches a schema; your code checks and runs the call, returns the result, and the model decides the next step. The model never executes anything itself.
In this guide: 83 pages
Key takeaways
- A tool is a name, a description and a JSON Schema. The model reads the description when it decides whether to call the tool, so write it for the model.
- Anthropic names the wrong tool and wrong parameters as the most common failures. Distinct names, clear descriptions and strict schemas are the first fixes.
- Keep the active set small: OpenAI suggests fewer than 20 functions at the start of a turn, Google 10 to 20, and Anthropic sees selection accuracy fall past 30 to 50. Beyond that, load tools on demand with tool search.
- Treat every write as something that may run twice. Approval does not guarantee exactly-once execution, so side-effecting tools need idempotency keys.
What happens during one tool call?
Your application sends the model the conversation and the definitions of the tools it may use. The model replies with a structured call naming one tool and its arguments, your code runs it and sends back the result, and the model either answers or asks for another call. Google’s Gemini documentation states the point directly: the model does not execute the function itself.
Each vendor names the pieces differently, as the table shows, but the loop is the same. That shared shape is what lets a framework switch models without rewriting its tools, and it is why MCP clients can turn any MCP tool into a function-calling tool for whichever model they use.
Some tools run on the vendor’s side. Client tools run in your code. Server or hosted tools, such as web search, code execution and tool search, run on the vendor’s infrastructure and come back in the same response; with remote MCP, the vendor makes the call to a server that runs wherever its owner hosts it. Hosted calls save plumbing and also leave your own network logs, so decide per tool which side should make the call.
A model can ask for several calls in one turn. Parallel calls run independent lookups at once, and chained calls, which Gemini calls compositional, feed one result into the next. OpenAI exposes parallel_tool_calls, which you can set to false to allow at most one call per turn; Claude has disable_parallel_tool_use inside tool_choice. We turn parallel calls off for agents that write, so a person or a policy reviews one change at a time.
The same loop in three APIs, as their documentation showed on 2 Nov 2026.
| Step | OpenAI Responses API | Claude Messages API | Gemini API |
|---|---|---|---|
| Call from the model | function_call | tool_use block, with stop_reason tool_use | function_call |
| Result back to the model | function_call_output | tool_result | function_result |
| Force or forbid calls | tool_choice: auto, required, a named function or none; allowed_tools narrows the set without changing the list | tool_choice; on Claude Fable 5.1 and Opus 5.5 the any and tool types return a 400 error, and Anthropic says to use auto with strict tool use | Modes auto, any, none and validated |
| Several calls per turn | parallel_tool_calls; false allows at most one call | disable_parallel_tool_use inside tool_choice | Parallel and compositional calls |
How do you write tool definitions a model uses correctly?
Write each tool for the model that has to choose it. Give it a name that cannot be confused with its neighbours, a description that says when to use it and when to leave it alone, and a JSON Schema that encodes your conventions, such as date formats, so the model does not have to guess them.
The description works as prompt text. Anthropic reports that choosing the wrong tool and passing incorrect parameters are the most common failures, and gives look-alike names such as notification-send-user and notification-send-channel as a cause. Merge near-duplicates or rename them, and add one or two example inputs to the description when a format is not obvious.
Strict mode makes the arguments match the schema. OpenAI’s strict mode needs additionalProperties set to false on every object and every property listed as required, with optional fields allowed to be null. On Claude you add strict: true to the tool; structured outputs left beta on the Claude API on 29 Jan 2026 and were still beta on Bedrock and Foundry at that date. Strict mode guarantees shape. Your code still has to validate values, permissions and business rules before anything runs. OpenAI also offers custom tools that take free-form text instead of JSON, optionally constrained by a grammar, for inputs such as code or queries.
Keep the active set small. OpenAI’s soft guideline is fewer than 20 functions at the start of a turn and Google’s is 10 to 20. Anthropic sees selection accuracy fall once more than 30 to 50 tools are available, and Microsoft 365 Copilot warns that quality might degrade beyond 10 functions or tools. Past those numbers, load tools on demand with tool search, which the guide’s context engineering page covers.
How should you design actions that change data?
Treat writes differently from reads. A bad read wastes a turn or exposes data, so reads need access checks and their results count as untrusted input; a bad write changes a record someone relies on, so writes get their own tools, a way to be retried safely and, where the stakes are high, a person who approves them.
- Split read and write tools. Microsoft 365 Copilot plugins already treat them differently: read-only calls skip confirmation after the first consent, and calls that modify data ask the user. A separate write tool also lets a gateway withhold writes from agents that run unattended.
- Use idempotency keys. In the OpenAI Agents SDK a tool marked needs_approval pauses the run, saves its state and resumes after approve or reject, and the documentation warns that approval does not guarantee exactly-once execution. Send a key with every write so a retried call returns the first result instead of creating a second order.
- Return errors the model can act on. A result that names the field that failed and the format it expects lets the model correct itself. A stack trace wastes a turn and can expose internals.
- Keep tool annotations out of your security model. MCP’s readOnlyHint and destructiveHint are hints from the server, and a dishonest server can label a delete tool read-only. Enforce read-only in the token scope or at the gateway.
- Check whose credentials a tool uses. Copilot Studio connectors run with the end user’s credentials by default or with credentials the maker provides, and Microsoft warns that sharing an agent set up with the maker’s credentials lets anyone using it act with the author’s access.
OpenAI’s guide to building agents asks for human oversight on actions that are sensitive, irreversible or high-stakes, with cancelling orders and payments among its examples, until confidence in the agent grows. The guide’s human-in-the-loop page covers the approval patterns each platform ships.
Should a system become a function, an OpenAPI action, a connector or an MCP server?
Use a function in your own code when one agent needs the tool, and an OpenAPI action or an MCP server when several agents or platforms share it. Prebuilt connectors save the most work for common SaaS systems, and computer use is the fallback for a system with no API.
Ways to give an agent a tool, and where each one ships on 2 Nov 2026.
| Option | Good for | Where it ships | Watch for |
|---|---|---|---|
| Function in your code | One agent, logic you own, fast changes | Every model API and agent framework | You own packaging, reuse and instrumentation |
| OpenAPI action | An existing REST API with a good description | Foundry tool catalogue; Microsoft 365 Copilot API plugins; AgentCore Gateway OpenAPI targets | A large specification becomes many tools; expose only the operations the agent needs |
| Prebuilt connector | Common SaaS systems, with credentials managed for you | Power Platform connectors in Copilot Studio; Microsoft 365 Copilot connectors, synced or federated over MCP; Gemini Enterprise connectors; AgentCore Gateway integrations for Salesforce, Slack, Jira, Asana and Zendesk | Whose credentials run the call; preview or GA status varies per connector |
| MCP server | Tools shared across agents, IDEs and platforms | Copilot Studio, Foundry, AgentCore Gateway, the Gemini, OpenAI and Claude APIs | Server review, pinned tool lists and a gateway, as the MCP security page describes |
| Computer use | Systems with no API | Copilot Studio (GA May 2026), Claude, Gemini, AgentCore Browser | Cost per screenshot or step, missed clicks, instructions hidden on the screen |
Platform churn is a good reason to keep tools in a neutral format. OpenAI deprecated its built-in connector IDs for models released after 1 Sep 2026 in favour of remote MCP. Amazon Bedrock Agents became Bedrock Agents Classic and closed to new customers on 30 Jul 2026, and AWS now points action groups to MCP tools behind AgentCore Gateway. Tools described once in MCP or OpenAPI move between platforms with less rework than tools written against one vendor’s format.
How do Microsoft, AWS and Google implement it?
How the three clouds wrap tool calling for agents, with statuses as the vendor pages showed on 2 Nov 2026.
Capability, Microsoft, AWS, Google
| Capability | Microsoft | AWS | |
|---|---|---|---|
| Defining tools | Foundry tool catalogue: function calling, OpenAPI, MCP, A2A, Azure Functions and more; Copilot Studio connectors, agent flows and MCP servers | AgentCore Gateway turns OpenAPI, Smithy and Lambda into MCP tools; action groups in Bedrock Agents Classic for existing customers only | Gemini API function calling; Agent Platform tools governed by Agent Gateway (GA 18 Jun 2026) |
| Confirmation before writes | Microsoft 365 Copilot asks before plugin calls that modify data; require_approval on the Foundry MCP tool | AgentCore managed harness inline function tools for return of control and human approval | Computer use tool with a human-in-the-loop safety policy constraint (GA 30 Oct 2026) |
| Many tools | Foundry Toolbox meta-tools tool_search and call_tool | Gateway built-in semantic search tool, x_amz_bedrock_agentcore_search | Documented guidance to keep 10 to 20 tools active |
| Policy on each call | API Management policies in front of MCP tools | AgentCore Policy, Cedar rules on each tool call (GA 3 Mar 2026) | Semantic governance policies on tool calls (preview since 29 Jun 2026) |
Claude models are also served through Bedrock, Foundry and Google Cloud, where a feature can trail the Claude API: structured outputs were still beta on Bedrock and Foundry when they left beta on the Claude API, and tool search on Bedrock works through InvokeModel and is unavailable in Converse.
Frequently asked questions
What is the difference between tool calling and function calling?
None in practice. OpenAI and Google say function calling, Anthropic says tool use, and platforms say actions, plugins or connectors. All of them describe the same loop: the model returns a structured request, and your code or the vendor’s runs it.
How many tools can one agent have?
Far fewer at any one moment than in total. Vendor guidance converges on 10 to 20 active tools per turn. With tool search, Anthropic supports up to 10,000 deferred tools per request, but the agent still sees only the few it loads for each step.
Can the model run code or call APIs on its own?
Only through tools that you or the vendor provide. The model returns a request and a runtime executes it. Hosted tools such as code execution run on the vendor’s infrastructure, and programmatic tool calling lets the model write code that calls tools inside a sandbox, so intermediate results stay out of the context window.
How do we stop an agent from calling the wrong tool?
Narrow what it can see before you tune what it says. Use allowed_tools or a gateway allow list so each agent sees only its own tools, give look-alike tools distinct names, and run a test set of real requests that checks tool choice and arguments on every change.
More in Tools, MCP and agent-to-agent
Sources
Each source was read on 2 November 2026. The date shown is the date on the page, or the page’s ms.date for Microsoft Learn; an undated page shows the date it was read.
- Function calling guide
- Tool use overview
- Gemini function calling
- Advanced tool use
- Tool search tool
- Claude Platform release notes
- Human in the loop, OpenAI Agents SDK
- A practical guide to building agents
- MCP and API plugins for Microsoft 365 Copilot
- Microsoft 365 Copilot connectors overview
- Use connectors in Copilot Studio
- Computer use in Copilot Studio
- Foundry Toolbox overview
- Amazon Bedrock AgentCore Gateway
- Semantic tool search in AgentCore Gateway
- Amazon Bedrock Agents Classic maintenance mode
- Policy for Amazon Bedrock AgentCore is now generally available
- Gemini Enterprise Agent Platform release notes
- Introduction to connectors and data stores
- Connectors and MCP guide
- Deprecations
- Tool annotations as a risk vocabulary
Planning an AI program?
Talk to the team that builds it and runs it after launch.
- Built to SOC 2, HIPAA and GDPR standards
- EU AI Act-aligned delivery
- Microsoft Solutions Partner