Implementing Claude API Tool Use in Next.js: Full Code, 27 Minutes

I opened the editor at 16:42 and it was running in production at 17:09.
Here's the full code for implementing Claude API tool use — 27 minutes of actual work.
I expected it to be complicated. It wasn't.

What I built

Added a natural language interface to a SaaS admin dashboard. Type "show me last month's revenue" or "how many active users do we have?" and Claude queries the DB and returns the answer.

The mechanic is simple: you tell Claude "you're allowed to call these functions." Claude decides when to call them and constructs the arguments. Your code actually executes the function and sends the result back to Claude. Claude generates the final text answer.

Stack:

Next.js 14 (App Router)
@anthropic-ai/sdk 0.20+
TypeScript
Supabase (DB)

Step 1: Define the tools

Tools are defined with JSON Schema. The description field is the most important part — write it so Claude clearly understands when to call the tool and what it returns. Vague descriptions cause misfires or missed calls.

// lib/claude-tools.ts
import Anthropic from '@anthropic-ai/sdk'

export const tools: Anthropic.Tool[] = [
  {
    name: 'get_revenue',
    description:
      'Fetches total revenue and transaction count for a given period. ' +
      'Supports daily, weekly, and monthly aggregation. ' +
      'Returns the latest 12 entries if no date range is specified.',
    input_schema: {
      type: 'object',
      properties: {
        period: {
          type: 'string',
          enum: ['daily', 'weekly', 'monthly'],
          description: 'Aggregation unit',
        },
        date_from: {
          type: 'string',
          description: 'Start date (YYYY-MM-DD)',
        },
        date_to: {
          type: 'string',
          description: 'End date (YYYY-MM-DD)',
        },
      },
      required: ['period'],
    },
  },
  {
    name: 'list_users',
    description:
      'Returns a list of users. Filterable by status (active/canceled/trial). Max 100 results.',
    input_schema: {
      type: 'object',
      properties: {
        status: {
          type: 'string',
          enum: ['active', 'canceled', 'trial'],
        },
        limit: {
          type: 'number',
          description: 'Number of results (max 100, default 20)',
        },
      },
      required: [],
    },
  },
]

"Get data" isn't a good description. Write 1–2 sentences covering when to use it, what data it returns, and what the constraints are. Skimping here makes Claude hesitate or call the wrong tool.

Step 2: Wire it into the API Route

The core of tool use is a loop. As long as Claude responds with "I want to use a tool," you execute it, return the result, and ask Claude again.

// app/api/chat/route.ts
import Anthropic from '@anthropic-ai/sdk'
import { tools } from '@/lib/claude-tools'
import { executeToolCall } from '@/lib/tool-handlers'

const client = new Anthropic()

export async function POST(req: Request) {
  const { messages } = await req.json()
  let currentMessages = [...messages]

  let response = await client.messages.create({
    model: 'claude-opus-4-6',
    max_tokens: 1024,
    tools,
    messages: currentMessages,
  })

  // Loop while Claude wants to use tools
  while (response.stop_reason === 'tool_use') {
    const toolUseBlocks = response.content.filter(
      (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use'
    )

    // Claude can call multiple tools in parallel — handle them concurrently
    const toolResults: Anthropic.ToolResultBlockParam[] = await Promise.all(
      toolUseBlocks.map(async (block) => ({
        type: 'tool_result' as const,
        tool_use_id: block.id,
        content: JSON.stringify(
          await executeToolCall(block.name, block.input as Record<string, unknown>)
        ),
      }))
    )

    // Append assistant turn + tool results to conversation history
    currentMessages = [
      ...currentMessages,
      { role: 'assistant' as const, content: response.content },
      { role: 'user' as const, content: toolResults },
    ]

    response = await client.messages.create({
      model: 'claude-opus-4-6',
      max_tokens: 1024,
      tools,
      messages: currentMessages,
    })
  }

  const textBlock = response.content.find(
    (block): block is Anthropic.TextBlock => block.type === 'text'
  )

  return Response.json({ reply: textBlock?.text ?? '' })
}

Loop on stop_reason === 'tool_use'. Using !== 'end_turn' is dangerous — on max_tokens overflow or API error, you get an infinite loop.

Step 3: Implement the handlers

Functions that actually hit the DB. Type them explicitly and always include the default case.

// lib/tool-handlers.ts
import { supabase } from '@/lib/supabase'

export async function executeToolCall(
  name: string,
  input: Record<string, unknown>
): Promise<unknown> {
  switch (name) {
    case 'get_revenue': {
      const { period, date_from, date_to } = input as {
        period: 'daily' | 'weekly' | 'monthly'
        date_from?: string
        date_to?: string
      }

      const { data, error } = await supabase.rpc('get_revenue_by_period', {
        p_period: period,
        p_from: date_from ?? null,
        p_to: date_to ?? null,
      })

      if (error) return { success: false, error: error.message }
      return { success: true, data, period }
    }

    case 'list_users': {
      const { status, limit = 20 } = input as {
        status?: string
        limit?: number
      }

      let query = supabase
        .from('users')
        .select('id, email, status, created_at')
        .order('created_at', { ascending: false })
        .limit(Math.min(limit, 100))

      if (status) query = query.eq('status', status)

      const { data, error } = await query
      if (error) return { success: false, error: error.message }
      return { success: true, data, count: data?.length }
    }

    default:
      // Hallucination guard: Claude occasionally calls a tool that doesn't exist
      return { success: false, error: `Unknown tool: ${name}` }
  }
}

The default case is required. Claude occasionally calls a non-existent tool. Returning undefined breaks the conversation entirely.

Step 4: Verification script

Verify the tool behavior in isolation before wiring it into production. Run this first to see how tool_use actually works.

// scripts/test-tool-use.ts
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

const response = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 512,
  tools: [
    {
      name: 'get_current_time',
      description: 'Returns the current time for a given timezone',
      input_schema: {
        type: 'object',
        properties: {
          timezone: {
            type: 'string',
            description: 'Timezone string (e.g. Asia/Tokyo)',
          },
        },
        required: ['timezone'],
      },
    },
  ],
  messages: [{ role: 'user', content: "What time is it in Tokyo right now?" }],
})

console.log('stop_reason:', response.stop_reason)
// → tool_use

console.log(
  'tool call:',
  JSON.stringify(
    response.content.find((b) => b.type === 'tool_use'),
    null,
    2
  )
)
// → { type: 'tool_use', name: 'get_current_time', input: { timezone: 'Asia/Tokyo' }, id: '...' }

If you see stop_reason: tool_use and input.timezone: "Asia/Tokyo", you're good. Confirm this before putting it in your production API.

Step 5: Combining with streaming

Tool use and streaming don't mix well. During streaming, tool arguments aren't fully assembled, so you can't build the execution loop.

I went with a hybrid approach: run the tool loop non-streaming, then stream only the final text response.

// Tool loop runs without streaming
let response = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  tools,
  messages: currentMessages,
})

while (response.stop_reason === 'tool_use') {
  // ... execute tools + update conversation history ...
  response = await client.messages.create({ ... })
}

// Stream only the final answer
const stream = client.messages.stream({
  model: 'claude-opus-4-6',
  max_tokens: 2048,
  messages: [
    ...currentMessages,
    { role: 'assistant', content: response.content },
  ],
})

return new Response(
  new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        if (
          chunk.type === 'content_block_delta' &&
          chunk.delta.type === 'text_delta'
        ) {
          controller.enqueue(
            new TextEncoder().encode(
              `data: ${JSON.stringify({ text: chunk.delta.text })}\n\n`
            )
          )
        }
      }
      controller.enqueue(new TextEncoder().encode('data: [DONE]\n\n'))
      controller.close()
    },
  }),
  {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
    },
  }
)

While tools are executing, show a "Fetching data..." spinner on the frontend. Execution can take a few seconds — skip the spinner and your UX dies.

Landmines I hit

Landmine 1: tool_result content must be a string
Passing content: toolResult directly threw a TypeError. JSON.stringify(toolResult) is required. The type definition says string, but TypeScript will sometimes let an object through without complaint — it's a trap.

Landmine 2: didn't handle parallel tool calls
Claude can call multiple tools in a single turn. I was using for...of to execute them serially, and the second tool_result wasn't mapping correctly. Use Promise.all for parallel execution.

Landmine 3: wrote descriptions in English for a Japanese-language app
Claude stopped calling tools as often when I wrote English descriptions in a Japanese-language context. Match descriptions to the conversation language. If your users write in Japanese, write Japanese descriptions.

Landmine 4: wrong loop condition
while (response.stop_reason !== 'end_turn') caused an infinite loop on max_tokens overflow or API error. === 'tool_use' is the correct condition.

Landmine 5: skipped authorization in the handler
Tool handlers can be hit through Claude or hit directly as API endpoints. Authorization logic belongs in the handler — not in the description. Writing "admins only" in the description doesn't guarantee Claude will respect it.

The implementation itself took 27 minutes. It's not hard. What's hard is designing which tools to define and how to write the descriptions. Your Claude's quality is your description's quality.

Next up: structured output with forced JSON using tool_choice: {type: "tool"} — forcing a specific tool call to return data matching a JSON schema. Master this and you escape the AI response parsing hell.

Originally posted on note (Japanese): https://note.com/mintototo1/n/nbe89d68cd5c5

推荐订阅源

DEV Community