Tool Use & Function Calling

// Step 1: Define your tools
tools = [
  { name: "calculator", description: "...", input_schema: {...} },
  { name: "get_weather", description: "...", input_schema: {...} }
]

// Step 2: Send initial request to Claude
response = claude.messages.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [{ role: "user", content: "What's 25 * 47?" }],
  tools: tools
})

// Step 3: Check if Claude wants to use tools
if response.stop_reason === "tool_use":
  // Extract tool use information
  for tool_use in response.content:
    if tool_use.type === "tool_use":
      tool_name = tool_use.name
      tool_input = tool_use.input

      // Step 4: Execute the tool
      result = execute_tool(tool_name, tool_input)

      // Step 5: Send results back to Claude
      final_response = claude.messages.create({
        model: "claude-sonnet-4-5-20250929",
        messages: [
          ...previous_messages,
          response,  // Claude's tool request
          { role: "user", content: [
            { type: "tool_result", tool_use_id: tool_use.id, content: result }
          ]}
        ],
        tools: tools
      })

// Now final_response contains Claude's answer using the tool results

// Auto (default) - Claude decides
claude.messages.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [...],
  tools: tools,
  tool_choice: {"type": "auto"}  // Optional, this is default
})

// Any - Force at least one tool use
claude.messages.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [...],
  tools: tools,
  tool_choice: {"type": "any"}  // Guarantees tool execution
})

// Specific tool - Force exact tool
claude.messages.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [...],
  tools: tools,
  tool_choice: {"type": "tool", "name": "get_weather"}  // Must use get_weather
})

// User request:
"What's the weather in New York, London, and Tokyo?
Also calculate 25 * 47 and what's 15% of 200?"

// Claude makes PARALLEL tool calls:
[
  { name: 'get_weather', input: { location: 'New York' } },
  { name: 'get_weather', input: { location: 'London' } },
  { name: 'get_weather', input: { location: 'Tokyo' } },
  { name: 'calculator', input: { expression: '25 * 47' } },
  { name: 'calculator', input: { expression: '200 * 0.15' } }
]

// Result: All 5 operations complete in the time of 1!

• • Automatic behavior: Claude decides when to use parallel execution - no special configuration needed
• • Design for parallelism: Make tools stateless and independent when possible
• • Handle all responses: Your code must process multiple tool_use blocks in a single API response
• • Test edge cases: Ensure your tools can handle concurrent execution safely
• • Monitor performance: Track actual speedups in your specific use cases

// Claude's response with multiple tool_use blocks
response = {
  "content": [
    { "type": "tool_use", "id": "toolu_1", "name": "get_weather", "input": {"location": "NYC"} },
    { "type": "tool_use", "id": "toolu_2", "name": "get_weather", "input": {"location": "London"} },
    { "type": "tool_use", "id": "toolu_3", "name": "calculator", "input": {"expression": "25*47"} }
  ],
  "stop_reason": "tool_use"
}

// Your code must handle ALL tool_use blocks
tool_results = []
for content_block in response.content:
  if content_block.type === "tool_use":
    // Execute the tool
    result = execute_tool(content_block.name, content_block.input)

    // Collect result with original ID
    tool_results.append({
      "type": "tool_result",
      "tool_use_id": content_block.id,  // Must match original ID!
      "content": result
    })

// Send ALL results back together
final_response = claude.messages.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [
    ...previous_messages,
    response,  // Claude's tool request
    { "role": "user", "content": tool_results }  // All results
  ]
})