Tool calling for AI agents, explained

Tool calling is the mechanism that lets an AI agent do things rather than just say things: the model outputs a structured request naming a tool and its arguments, the agent's runtime executes that request against a real app, and the result is fed back so the model can continue. Every agent action on Gmail, Notion, Slack, or any other app is a tool call underneath.

How tool calling works

The runtime presents the model with a catalog of tools, each with a description and an input schema. When the user asks for something a tool can do, the model emits a call — a tool name plus structured arguments, like send_email with a recipient and body. The runtime executes it, returns the output or the error, and the model reads that result to decide what to do next: answer the user, fix its arguments, or call another tool.

That loop repeats as many times as the task needs. A request like "find last week's invoices and put the totals in a spreadsheet" might be five or six tool calls across two different apps.

A worked example: a multi-step request

Take the prompt "find unread emails from my accountant this week and add a reminder to reply." Here's the tool-calling loop that actually runs:

1. The model recognizes two apps are involved and starts with search. It calls gmail_fetch_emails with a query like from:accountant is:unread after:2026/7/1.
2. The runtime executes the call against Gmail's API and returns a list of matching messages — say, two emails — back to the model.
3. The model reads the result. It now has enough information to describe what it found, and it still needs to create the reminder, so it calls a second tool: todoist_create_task (or whichever task app is connected) with a title referencing the accountant's emails and a due date.
4. The runtime executes that call, gets back a confirmation with the new task's ID, and returns it.
5. Only now does the model stop calling tools and respond to the user: "Found 2 unread emails from your accountant and added a reminder to reply, due today."

Nothing here required the user to specify which tools to use or in what order — the model chose based on the tool descriptions and the result of each step. That adaptiveness is what separates tool calling from a fixed automation script.

Why tool calls fail

The usual causes are practical, not mysterious: the app connection's login expired, the model passed a placeholder instead of a real ID, the connected account is missing a permission, or the tool's schema wasn't available when the model composed the call. We keep a plain-language checklist in why is my OpenClaw tool call failing? — the same fixes apply to any agent.

Where the tools come from

Someone has to define each tool and wire it to the app's API, with authentication handled. The open standard for packaging this is MCP — see what is an MCP server?. You can build tools yourself per app, or use a hosted app connector where connecting an app instantly gives your agent that app's tools.

With ClawLink, you connect an app once through a browser login and its tools appear in your agent's catalog — no API keys or tool definitions to write. Browse what's available.

Limits of tool calling

Tool calling isn't infallible, and it's worth knowing where it tends to break down:

The model has to pick the right tool. With a large catalog of similar tools — several apps that can all "create a task," say — the model can call the wrong one, or the right one with subtly wrong arguments. Clear, specific tool descriptions reduce this; vague ones make it worse.

Multi-step chains compound errors. If step two of a five-step chain returns a slightly malformed result, everything downstream can go wrong silently instead of failing loudly. This is why reviewing agent actions on sensitive tasks (sending, deleting, paying) matters more than on reads.

Tools can't do what the underlying account can't. A tool call fails at the provider, not at the agent, if the connected account lacks the permission or plan tier the action needs — no amount of prompt engineering fixes that. See OAuth for AI agents for how scopes constrain this.

FAQ

Keep reading