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 that names a tool and its arguments. A runtime executes that request against a real system. The result is fed back so the model can continue. Every agent action on Gmail, Notion, or Slack is a tool call underneath.

The model never runs code. It acts as a probabilistic planner, and the runtime acts as the deterministic executor that validates arguments and handles errors. That split is the whole design.

Key takeaways

• Tool calling is a loop with three phases: the model hands off a structured call, the runtime executes it, and the observation goes back to the model.
• The model never executes anything. It only names a tool and supplies arguments.
• Function calling is the model capability. Tool calling is the same idea in production, with real systems behind it.
• MCP is the standard for how tools are advertised to the agent, so one server works across clients.
• Bad arguments are the most common failure, ahead of permissions and rate limits.
• Tool descriptions are prompt engineering. Vague descriptions produce wrong tool choices.

How does the tool calling loop work?

Three phases repeat until the model stops asking for tools.

1. Handoff. The model reads the request and outputs a structured call, usually JSON, with a tool name and arguments. The model does no work beyond choosing and formatting.
2. Execution. The runtime intercepts the call, validates the arguments against the tool's schema, runs the action in a controlled environment, and collects a result.
3. Observation. The runtime feeds the result back to the model as a new message. The model either calls another tool or writes the final answer.

The loop continues until the model produces a response with no tool call. IBM's explainer on tool calling describes the same three-step shape, checked on 16 September 2026.

The model chooses and formats the call. The runtime is what actually holds the credential and makes the request.

What does a multi-step tool call look like?

Take the prompt "find unread emails from my accountant this week and add a reminder to reply." Here is the 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 newer_than:7d.
2. The runtime validates the query, executes it against Gmail, and returns two matching messages.
3. The model reads the result and still needs the reminder, so it calls a second tool, todoist_create_task, with a title referencing the emails and a due date.
4. The runtime executes that call and returns a confirmation with the new task id.
5. Only now does the model stop calling tools and reply: "Found 2 unread emails from your accountant and added a reminder to reply, due today."

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

Function calling vs tool calling vs MCP: what is the difference?

These terms get used as if they were the same. They describe different layers of one system.

Function calling is the capability. Tool calling is the capability put to work. MCP standardizes discovery, so a tool defined once can appear in Claude, Cursor, OpenClaw, or any other MCP client. RAG is a different job: it supplies text, not actions. See what is an MCP server? for the discovery layer.

Why do tool calls fail?

The usual causes are practical, not mysterious.

• Bad arguments. The model omits a required field, uses the wrong type, or passes a placeholder where a real id belongs. This was the top actionable failure class in ClawLink's logs: 11,687 calls in the 90 days to 16 September 2026.
• A stale tool catalog. The agent calls a tool name that no longer exists, or one it never loaded.
• A stale credential. The connection's login expired or was revoked.
• A missing permission. The connected account lacks the scope, role, or plan feature the action needs.
• Provider limits. Rate limits and provider outages happen after a valid call reaches the app.

The fixes differ by cause, so identify the cause before retrying. The full checklist is in why is my OpenClaw tool call failing?, and the error codes are in MCP tool call failed.

Where do the tools come from?

Someone has to define each tool, describe it, and wire it to the app's API with authentication. The open standard for packaging that is MCP, described in what is an MCP server?.

You can write tools yourself, per app, or use a hosted app connector that provides the app's tools as soon as the user connects it. With ClawLink, a user connects an app once through a browser login and its tools appear in the agent's catalog, with no API keys or tool definitions to write. Browse what is available.

The definition a model reads before it calls Gmail's fetch_emails, on 16 September 2026.

How do you design tools an agent can use?

Tool design is prompt engineering, because the description is the only thing the model sees when it chooses. Four rules matter most.

• Say what the tool does in one plain sentence, and when to use it. Include the trigger, not just the action.
• Name arguments in words a human would use. channel_id beats cid. Say whether an id is required and what format it takes.
• Make the description distinguish near-duplicates. If three tools can create a task, each description should say which app it belongs to and when it is the right one.
• Return errors a model can act on. "Missing scope chat:write, reconnect the app" is actionable. "403" is not.

Anthropic publishes longer guidance aimed at tool authors in writing effective tools for AI agents, checked on 16 September 2026.

What are the limits of tool calling?

• The model has to pick the right tool. With many similar tools, it can pick the wrong one or supply subtly wrong arguments.
• Multi-step chains compound errors. A malformed result at step two can poison steps three to five, often silently.
• Tools cannot exceed the account's access. A provider-side missing permission is not fixable by prompting.
• Every tool description costs context. Large catalogs crowd the window, which is why hosts increasingly load tools on demand.
• Latency adds up. Each phase is a round trip, so long chains are slow and expensive.

What changed in this review

This page was rebuilt on 16 September 2026. It names the three phases of the loop (handoff, execution, observation), adds a function calling versus tool calling versus MCP versus RAG table, a tool-design section for tool authors, current production failure counts, and a six-entry FAQ.

FAQ

Keep reading