Anthropic tool_use

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

const client = new Anthropic();

const tools: Anthropic.Messages.Tool[] = [
  {
    name: "get_weather",
    description: "Get current weather for a location",
    input_schema: {
      type: "object" as const,
      properties: {
        location: {
          type: "string",
          description: "City name, e.g. 'San Francisco, CA'",
        },
        units: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
        },
      },
      required: ["location"],
    },
  },
];

async function callWithToolsClaude(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    tools,
    messages: [{ role: "user", content: userMessage }],
  });

  return response;
}

Tool execution loop

User message
     │
     ▼
┌─────────────┐
│  LLM call   │ ◄──────────────────────────┐
│  with tools  │                             │
└──────┬──────┘                             │
       │                                     │
       ▼                                     │
  Has tool_use?                              │
  ├── No → Return text response              │
  └── Yes                                    │
       │                                     │
       ▼                                     │
┌─────────────┐                             │
│Execute tool  │                             │
│  function    │                             │
└──────┬──────┘                             │
       │                                     │
       ▼                                     │
  Return tool result ────────────────────────┘
  as next message

Tool selection patterns

Workflow

Step 1: Define tool schemas

// Type-safe tool definitions with Zod
import { z } from "zod";

const toolSchemas = {
  get_weather: z.object({
    location: z.string().describe("City and state, e.g. 'San Francisco, CA'"),
    units: z.enum(["celsius", "fahrenheit"]).default("fahrenheit"),
  }),

  search_docs: z.object({
    query: z.string().describe("Search query for the documentation"),
    section: z.enum(["api", "guides", "examples"]).optional(),
    limit: z.number().min(1).max(20).default(5),
  }),

  create_ticket: z.object({
    title: z.string().min(1).max(200),
    description: z.string(),
    priority: z.enum(["low", "medium", "high", "critical"]),
    labels: z.array(z.string()).default([]),
  }),
} as const;

Step 2: Implement tool handlers

type ToolName = keyof typeof toolSchemas;

const toolHandlers: Record<ToolName, (args: unknown) => Promise<string>> = {
  async get_weather(args) {
    const { location, units } = toolSchemas.get_weather.parse(args);
    const data = await weatherApi.getCurrent(location, units);
    return JSON.stringify(data);
  },

  async search_docs(args) {
    const { query, section, limit } = toolSchemas.search_docs.parse(args);
    const results = await docsSearch.query(query, { section, limit });
    return JSON.stringify(results);
  },

  async create_ticket(args) {
    const { title, description, priority, labels } =
      toolSchemas.create_ticket.parse(args);
    const ticket = await ticketService.create({
      title, description, priority, labels,
    });
    return JSON.stringify({ id: ticket.id, url: ticket.url });
  },
};

Step 3: Build the tool execution loop (OpenAI)

async function agentLoop(userMessage: string, maxIterations = 10) {
  const messages: OpenAI.Responses.ResponseInput = [
    { role: "user", content: userMessage },
  ];

  for (let i = 0; i < maxIterations; i++) {
    const response = await client.responses.create({
      model: "gpt-4o",
      tools,
      input: messages,
    });

    const toolCalls = response.output.filter(
      (item): item is OpenAI.Responses.FunctionToolCall =>
        item.type === "function_call"
    );

    if (toolCalls.length === 0) {
      return response.output_text;
    }

    // Execute tools in parallel when possible
    const results = await Promise.allSettled(
      toolCalls.map(async (call) => {
        const handler = toolHandlers[call.name as ToolName];
        if (!handler) throw new Error(\`Unknown tool: \${call.name}\`);
        const args = JSON.parse(call.arguments);
        return { callId: call.call_id, result: await handler(args) };
      })
    );

    // Append tool results
    for (const result of results) {
      if (result.status === "fulfilled") {
        messages.push({
          type: "function_call_output",
          call_id: result.value.callId,
          output: result.value.result,
        });
      } else {
        messages.push({
          type: "function_call_output",
          call_id: toolCalls[results.indexOf(result)].call_id,
          output: JSON.stringify({ error: result.reason?.message }),
        });
      }
    }
  }

  throw new Error("Max iterations reached");
}

Step 4: Build the tool execution loop (Anthropic)

async function agentLoopClaude(userMessage: string, maxIterations = 10) {
  const messages: Anthropic.Messages.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  for (let i = 0; i < maxIterations; i++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 4096,
      tools,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      const textBlocks = response.content.filter(b => b.type === "text");
      return textBlocks.map(b => b.text).join("");
    }

    const toolUseBlocks = response.content.filter(
      (b): b is Anthropic.Messages.ToolUseBlock => b.type === "tool_use"
    );

    // Append assistant response and tool results
    messages.push({ role: "assistant", content: response.content });

    const toolResults: Anthropic.Messages.ToolResultBlockParam[] = [];
    for (const block of toolUseBlocks) {
      try {
        const handler = toolHandlers[block.name as ToolName];
        const result = await handler(block.input);
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: result,
        });
      } catch (err) {
        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: \`Error: \${(err as Error).message}\`,
          is_error: true,
        });
      }
    }

    messages.push({ role: "user", content: toolResults });
  }

  throw new Error("Max iterations reached");
}

Examples

Example 1: Parallel tool execution

// Model requests weather for 3 cities simultaneously
const response = await client.responses.create({
  model: "gpt-4o",
  tools,
  input: [{ role: "user", content: "Compare weather in NYC, London, and Tokyo" }],
});

// response.output may contain 3 parallel function_call items
// Execute all 3 in parallel with Promise.all
const results = await Promise.all(
  toolCalls.map(call => toolHandlers.get_weather(JSON.parse(call.arguments)))
);

Example 2: Error recovery with retry

async function executeWithRetry(
  handler: (args: unknown) => Promise<string>,
  args: unknown,
  maxRetries = 2
): Promise<string> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await handler(args);
    } catch (err) {
      if (attempt === maxRetries) {
        return JSON.stringify({
          error: (err as Error).message,
          suggestion: "Try a different approach or ask the user for help",
        });
      }
      await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
    }
  }
  return JSON.stringify({ error: "Exhausted retries" });
}

Example 3: Tool choice strategies

// Force the model to call a specific tool
const response = await client.responses.create({
  model: "gpt-4o",
  tools,
  tool_choice: { type: "function", name: "create_ticket" },
  input: messages,
});

// Prevent tool calling (text-only response)
const textOnly = await client.responses.create({
  model: "gpt-4o",
  tools,
  tool_choice: "none",
  input: messages,
});

Decision tree

Does the model need to interact with external systems?
├── No
│   ├── Need structured output? → Use response_format / structured outputs
│   └── Free text is fine? → No tools needed
└── Yes
    ├── How many tools?
    │   ├── 1-3 → Define inline, auto tool_choice
    │   ├── 4-10 → Group by domain, add clear descriptions
    │   └── 10+ → Split into sub-agents with focused tool sets
    ├── Tool calls independent?
    │   ├── Yes → Enable parallel tool calling
    │   └── No → Sequential execution with state passing
    ├── Side effects?
    │   ├── Read-only → Auto execute, no confirmation
    │   └── Writes / deletes → Add confirmation step or human-in-the-loop
    └── Error handling?
        ├── Transient errors → Retry with backoff
        ├── Permanent errors → Return error to model, let it adapt
        └── Critical errors → Abort and escalate to user

Edge cases and gotchas

• Hallucinated tool names: The model may try to call tools that don't exist — always validate tool names before execution
• Argument type coercion: Models sometimes send strings where numbers are expected — Zod .coerce handles this
• Parallel call ordering: When the model requests parallel calls, execution order is not guaranteed — don't assume ordering
• Tool call in text: Some models include tool call syntax in text responses — parse the structured response, not the text
• Infinite tool loops: The model may keep calling tools without converging — always set a max iteration limit
• Empty arguments: Some calls come with {} arguments — ensure defaults handle this
• Large tool results: Sending huge JSON back as tool results bloats the context — truncate or summarize
• Streaming with tools: Tool calls arrive as deltas during streaming — accumulate before executing
• Tool description length: Longer descriptions improve selection accuracy but cost tokens — aim for 1-2 sentences
• Cross-provider differences: OpenAI uses function_call / call_id; Anthropic uses tool_use / tool_use_id — abstract the difference

Evaluation criteria

Research-backed changes

The biggest delta is News. Fold the concrete changes into the operating notes, then discard the fluff.

Fresh signals

• News · Anthropic News
• Research · Anthropic News
• Economic Futures · Anthropic News
• Try Claude · Anthropic News

Next edits

• Add one new tactic based on News.
• Rewrite one stale section with today's source language.
• Turn the top signal into a reusable agent prompt.