Back to Blog

Claude Tool Use - How Client Tools and Server Tools Actually Work

April 16, 2026•7 min read•Michael Ridland

Tool use is what turns a language model from a text generator into an agent that can actually do things. Without tools, Claude can only talk about doing things. With tools, it can check your database, call your APIs, search the web, run code, and take real actions. The gap between "I would suggest checking the weather API" and actually checking the weather API is the entire gap between a chatbot and a useful agent.

We build AI agents professionally at Team 400, and tool use is the foundation of every agent we ship. Understanding how it works - really works, not just the happy path from the quickstart guide - matters a lot when you're building something that needs to run reliably.

The Two Types of Tools

Claude's tool system splits into two categories based on where the code executes. This distinction sounds academic until you're debugging a failing agent at 10pm and realising you're looking in the wrong place for the error.

Client Tools

Client tools run in your application. You define a tool with a name, description, and input schema. When Claude decides to use that tool, the API response comes back with stop_reason: "tool_use" and one or more tool_use blocks containing the tool name and input parameters. Your code then executes whatever that tool does - queries a database, calls an API, reads a file - and sends the result back as a tool_result message. Claude reads the result and continues.

This is the agentic loop. Claude thinks, calls a tool, gets a result, thinks again. It might call several tools in sequence before giving a final answer. Or it might call multiple tools in a single response if it needs information from several sources simultaneously.

Client tools give you complete control. You decide what the tool does, how it handles errors, what data it has access to. The tradeoff is that you're responsible for everything - execution, error handling, timeout management, security.

Here's a minimal Python example:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{
        "name": "get_customer",
        "description": "Look up a customer by their ID",
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_id": {
                    "type": "string",
                    "description": "The customer's unique ID"
                }
            },
            "required": ["customer_id"]
        }
    }],
    messages=[{"role": "user", "content": "Find customer C-12345"}],
)

When Claude decides to use this tool, you get back a tool_use block with the input {"customer_id": "C-12345"}. You execute the lookup, format the result, and send it back. Simple in concept. The complexity is in the details.

Server Tools

Server tools run on Anthropic's infrastructure. You include them in your request, and Anthropic handles the execution. You see the results in the response without having to do anything.

The currently available server tools are:

  • web_search - searches the web and returns results
  • code_execution - runs Python code in a sandboxed environment
  • web_fetch - fetches content from a URL
  • tool_search - discovers available tools

Using a server tool is simpler than a client tool because there's no loop to manage:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)

Claude searches the web, processes the results, and gives you a final answer. You don't handle the search execution.

The tradeoff is obvious: less control. You can't customise how the search works, what sources it prioritises, or how results are filtered. For many use cases that's fine. For agents that need to search specific internal knowledge bases or restricted data sources, you'd build a client tool instead.

The Agentic Loop in Practice

The documentation describes the tool use loop as: Claude responds with tool calls, you execute them, you send results back, Claude continues. In practice, there are several things to think about.

Claude can call multiple tools in one response. If Claude needs both weather data and stock prices, it might emit two tool_use blocks in a single response. Your code needs to handle this - execute both, send both results back together.

The loop can go several rounds. Claude might call a search tool, examine the results, decide it needs to refine the search, call the tool again with different parameters, then call a second tool based on what it found. We've seen agents go through 5-6 tool calls before reaching a final answer. Set reasonable loop limits to prevent runaway agents.

Error handling is your responsibility for client tools. If your tool throws an exception, you need to decide what to send back. You can send an error result with is_error: true, which tells Claude the tool failed. Claude will often try to recover - maybe by calling the tool with different parameters or by explaining to the user what went wrong. Don't swallow errors silently. Claude is surprisingly good at adapting when it knows something failed.

Tool descriptions matter more than you'd think. Claude decides whether and how to use a tool based on its description. A vague description leads to Claude misusing the tool or not using it when it should. Spend time on your descriptions. Be specific about what the tool does, what inputs it expects, and what it returns. Include constraints and edge cases.

Strict Tool Use

If you've been bitten by Claude sending unexpected parameter formats, strict: true is worth knowing about. Adding this to your tool definition guarantees that Claude's tool calls will exactly match your input schema. No extra fields, no wrong types, no creative interpretation of your schema.

Without strict mode, Claude generally follows your schema but might occasionally improvise. With strict mode, you get a hard guarantee. For production agents where your tool execution code expects exact types, this removes an entire class of bugs.

Pricing Considerations

Tool use adds tokens to your API calls. The tools parameter itself costs tokens (tool names, descriptions, and schemas are included in the input). Each tool_use and tool_result block costs tokens too. And Anthropic adds a system prompt to enable tool use, which adds between 159 and 530 tokens depending on the model and tool choice setting.

For agents that make many tool calls, this adds up. A few things we've done to manage costs:

  • Keep tool descriptions concise. Long descriptions burn input tokens on every request.
  • Use tool_choice to constrain which tools are available in each turn, rather than sending all tools every time.
  • For server tools like web_search, there's additional usage-based pricing per search performed. Factor this in when estimating costs for high-volume agents.

What Claude Does When Information is Missing

This is a behaviour difference worth understanding. When a required parameter is missing from the user's message, Claude Opus is more likely to ask the user for clarification. Claude Sonnet is more likely to guess a reasonable value and proceed.

For example, if you have a get_weather tool that requires a location parameter and the user just says "What's the weather?", Sonnet might guess "New York, NY" while Opus would ask "Which location would you like the weather for?"

Neither approach is wrong - it depends on what you want. For internal tools where guessing is acceptable, Sonnet's behaviour is fine. For customer-facing agents where accuracy matters more than speed, Opus's tendency to clarify is preferable. You can also influence this through your system prompt.

When to Use Client vs Server Tools

Our general approach:

Use server tools when they fit. Web search, code execution, URL fetching - if the built-in server tools do what you need, use them. Less code to write, less infrastructure to maintain.

Use client tools for everything else. Database queries, internal API calls, file operations, custom business logic. Anything that touches your systems or data needs to be a client tool because Anthropic's servers can't reach your internal infrastructure.

Mix them freely. A single agent can use both client and server tools in the same conversation. A common pattern is web search (server tool) for external information plus database queries (client tools) for internal data, combined in a single agent response.

The full Claude tool use documentation covers the API specification, including MCP connector support and additional examples. We've also written about handling tool calls in detail and defining custom tools if you want to go deeper on specific parts of the implementation.

If you're building AI agents and want help getting the tool architecture right - or if you've got an agent that's misbehaving and you can't figure out why - talk to us. Tool design is one of those areas where getting it right from the start saves you a lot of rework later, and we've made enough mistakes ourselves to know what to avoid.