Claude API Function Calling: Tools, Streaming and MCP

Claude API function calling works by passing tool definitions (a name, description and JSON Schema) in the Messages API's tools parameter; when Claude wants one, the response stops with stop_reason "tool_use" and a tool_use block holding the arguments. Your code runs the function and sends the output back as a tool_result in the next user message, and the loop repeats until Claude answers in plain text.

API shapes checked October 2026 against Anthropic's tool use documentation and the official TypeScript SDK, @anthropic-ai/sdk. Model IDs and prices change; confirm them on Anthropic's models page before shipping.

Anthropic's docs cover each piece separately. This tutorial builds the whole loop once, in production shape: typed tools, parallel calls, error results, a turn limit, and the tool-choice rules that changed with the current model generation. It ends with the question most teams hit next: when to stop hand-writing tools and put them behind an MCP server. For setup basics first, see our Claude API tutorial.

What you will have at the end

• A reusable ask() function that runs Claude's tool loop to completion.
• Tools with strict schemas, so arguments always validate.
• Correct handling of parallel calls and tool errors.
• A decision rule for function calling versus an MCP server.

Prerequisites

If you do not have a key yet, our guide on getting a Claude API key walks through it. For what each call costs, see our Claude API pricing breakdown.

Claude API function calling: the tool-use loop in TypeScript

The code below is the whole pattern. It defines one tool, calls the API, runs every tool Claude asks for, returns results, and stops when Claude answers in text or after ten turns.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY

const tools: Anthropic.Tool[] = [
  {
    name: "get_order_status",
    description: "Look up the status of a customer order by order ID.",
    input_schema: {
      type: "object",
      properties: { order_id: { type: "string", description: "e.g. ORD-1042" } },
      required: ["order_id"],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function runTool(name: string, input: unknown): Promise<string> {
  if (name === "get_order_status") {
    const { order_id } = input as { order_id: string };
    return JSON.stringify(await lookupOrder(order_id)); // your code
  }
  throw new Error("Unknown tool: " + name);
}

export async function ask(question: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: question }];

  for (let turn = 0; turn < 10; turn++) {            // hard stop on runaway loops
    const response = await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 16000,
      tools,
      messages,
    });

    if (response.stop_reason !== "tool_use") {
      return response.content
        .filter((b): b is Anthropic.TextBlock => b.type === "text")
        .map((b) => b.text)
        .join("\n");
    }

    messages.push({ role: "assistant", content: response.content });

    const calls = response.content.filter(
      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
    );
    const results = await Promise.all(
      calls.map(async (call): Promise<Anthropic.ToolResultBlockParam> => {
        try {
          return { type: "tool_result", tool_use_id: call.id, content: await runTool(call.name, call.input) };
        } catch (err) {
          return { type: "tool_result", tool_use_id: call.id, content: String(err), is_error: true };
        }
      }),
    );
    messages.push({ role: "user", content: results }); // all results, one message
  }
  throw new Error("Tool loop did not finish in 10 turns");
}

The official SDK also ships a beta tool runner that drives this loop for you, with hooks for approvals and logging. Write the manual loop once to understand it, then consider the runner for production; Anthropic's docs cover both.

Controlling tool choice on current models

The tool_choice parameter decides whether Claude may, must or must not call tools. On the current generation the rules changed: forcing a call with any or a named tool returns a 400 error on Claude Opus 5.5, Claude Sonnet 5.5 and Claude Fable 5.1. Older models still accept it.

To get a reliable call on current models, keep auto, say in the user or system message which tool to use, and keep strict: true on the tool. Then check whether a tool_use block came back and re-prompt if not. If the only reason for forcing a tool was to get JSON, use structured outputs instead; it is the cleaner tool for that job.

Streaming tool input

For chat interfaces, stream the response with client.messages.stream(...) and take the complete message from finalMessage(). Tool arguments arrive as partial JSON while streaming. Setting eager_input_streaming: true on a tool definition streams large arguments as they are generated rather than in one burst at the end; the trade-off is that the API no longer validates those streamed inputs for you, so parse them defensively and validate against your schema before running the tool. Leave it off for non-streaming requests.

Anthropic tool use API: details that matter in production

• Descriptions do the routing. Claude chooses tools from their descriptions. Say what the tool does, when to use it and when not to.
• Parse inputs, do not string-match them. Tool inputs arrive as objects; treat them as data and validate them.
• Keep results small. Return the fields Claude needs, not a whole database row. Large results cost input tokens on every later turn.
• Gate side effects. For tools that send email, charge cards or delete data, require a confirmation step in your code before running them.
• Log every call. Name, input, output and duration make debugging an agent possible.

If you are building a product on top of this loop, our AI SaaS Builder program covers turning it into a shipped app with auth, billing and deployment.

What tool use costs

Tool use is billed like any other Messages API call: input and output tokens at the model's rates. Three things make tool-heavy apps more expensive than they look. First, tool definitions are sent with every request, so long descriptions and many tools add input tokens to each turn. Second, every turn resends the whole conversation, including earlier tool results, so a ten-turn loop pays for the early results ten times. Third, the model may think before calling tools, and thinking is billed as output.

The fixes are simple. Keep descriptions precise rather than long, return only the fields Claude needs, and cap the loop. Put the stable parts of the request, the tools and system prompt, first and use prompt caching so repeated turns read them from cache at a fraction of the price. Then measure: log the usage object from each response and look at cost per completed task, not per request, because a cheaper request that needs more turns is not cheaper.

Claude MCP API: when to move tools to an MCP server

Function calling keeps tools inside one app. The Model Context Protocol packages tools on a server so any MCP client can use them. With Anthropic's MCP connector (beta), the Messages API connects to a remote MCP server for you: you list the server in mcp_servers and reference it with an mcp_toolset entry in tools. Both halves are required.

const response = await client.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  betas: ["mcp-client-2025-11-20"],
  mcp_servers: [
    { type: "url", url: "https://mcp.example.com/sse", name: "orders" },
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "orders" }],
  messages: [{ role: "user", content: "Where is order ORD-1042?" }],
});

A practical path: start with function calling inside your app, and extract tools into an MCP server once a second consumer needs them. For workflow tools such as n8n, our guide to Claude with n8n covers a no-code route to the same idea.

Troubleshooting

• 400 on tool_choice. You are forcing a tool on a current model. Switch to auto and instruct in the prompt.
• Error about missing tool_result. A tool_use block went unanswered. Return a result, even an error result, for every call.
• Claude never calls the tool. The description does not say when to use it, or the question does not need it. Rewrite the description and test again.
• Arguments fail your validation. The schema is too loose or the description is vague. Add strict: true with additionalProperties: false, tighten enums and required fields, and describe each property with an example.
• Loop never ends. A tool keeps returning something Claude retries on. Keep the turn limit, and return clear error messages.

Claude API function calling: FAQ