8.1 Tool Use and the Function-Calling Loop

Every extension of Claude beyond plain text starts with the same primitive: tool use, also called function calling. You pass a `tools` array in your request; each entry has a `name`, a `description`, and an `input_schema` written as JSON Schema. Claude reads those definitions alongside the conversation and decides, on its own, whether one of them would help it answer. If it decides yes, it doesn't just say so in prose — it stops with `stop_reason: "tool_use"` and emits a `tool_use` content block carrying the tool's `name` and the `input` arguments it wants to pass.

Here is the detail the exam leans on hardest: Claude's turn ends there. It has only made a REQUEST. Your application code is what actually runs the function, hits the API, queries the database, or does whatever the tool represents. You then package the outcome as a `tool_result` block, place it inside a new `user` message, and — critically — tag it with the same `tool_use_id` that Claude's request carried, so Claude can match the answer to the question it asked. Only after that round trip does Claude continue the turn, possibly requesting another tool, until it reaches a natural `end_turn`.

Not every tool is executed the same way. The default pattern — and the one most function-calling questions assume unless told otherwise — is client-side: your application is the one that runs the code behind the tool. But some built-in tools are server-side, meaning they execute within Anthropic's own infrastructure rather than in your process. Knowing which category a given tool belongs to tells you where the executing code lives and who is responsible for it.

Inside an actual agent, this dispatch is usually handled by a harness: a small piece of routing logic that looks at the `name` on each incoming `tool_use` block and calls the corresponding function in your codebase. For tools that are sensitive or destructive — deleting a record, sending a payment, force-pushing to a repository — that dispatcher is also where you insert an approval pattern: pause and require a human (or a hook-based automated check) to sign off before the tool actually runs. This is the same idea as the permission gates covered elsewhere in the agentic-workflow material, applied specifically to the tool-execution step.

• •Client-side tools: your application executes the code (the default assumption for custom function calling).
• •Server-side tools: certain Anthropic-provided built-ins run within Anthropic's own infrastructure, not your process.
• •Agentic harness dispatch: a router maps each tool_use name to its implementing function.
• •Approval pattern: gate sensitive or destructive tool calls behind human or hook-based sign-off before execution.

If there is one lever that matters more than any other in tool design, it's the natural-language `description`. Claude decides WHETHER to call a tool and WHICH tool to call almost entirely based on how well the description explains what the tool does, when it should be used, and what each parameter means. A vague description — "looks things up" — gets a tool ignored when it would have helped, or misused when it shouldn't have been called at all. A precise one — "searches the internal product catalog by SKU or free-text name; use this instead of web search for any question about products this company sells" — gives Claude exactly the signal it needs to pick correctly.

This is worth sitting with because it's counterintuitive to engineers who default to thinking in schemas and types: the schema shapes the ARGUMENTS once a tool has already been chosen, but the description is what drives the choice itself. Spend your effort accordingly. If Claude keeps picking the wrong tool, or ignoring the right one, the fix is almost always to rewrite the description — not to add more fields to the schema.

Once Claude has picked a tool, the `input_schema` is what shapes the arguments it produces. Write it as real JSON Schema: give every field a type, mark the ones that are `required`, constrain free-form choices with `enum` where the valid values are known, and add a per-field description so ambiguous parameters (what format is this date in? what units?) don't have to be guessed. A precise schema reduces malformed calls, but it's a different lever from the description — the description governs whether and when the tool gets called; the schema governs how well-formed the arguments are once it has.

The other half of a well-behaved tool is what happens when it fails. Don't return a bare failure or a raw stack trace. Return a structured, informative error — commonly an `is_error` flag on the `tool_result` plus a clear message describing what went wrong ("order ID not found" vs. "invalid date format, expected YYYY-MM-DD"). That lets Claude reason about the failure and recover intelligently: retry with corrected arguments, try a different tool, or explain the limitation to the user — instead of guessing blindly at what broke.

Current Claude models default to requesting multiple independent tool calls in a single turn whenever the subtasks don't depend on each other -- Claude emits several tool_use blocks in one assistant turn, your code executes them concurrently, and you return all the corresponding tool_result blocks together in a single follow-up user message. This is a throughput win when the calls really are independent: three unrelated lookups don't need three separate round trips.

That default assumes independence, though, and not every pair of tool calls is independent. When one tool's output feeds the next call's arguments -- the second call literally cannot be constructed until the first result comes back -- letting the model issue both as if they were parallel produces malformed or guessed arguments for the second call. `disable_parallel_tool_use` is the fix: set it to force the model to request at most one tool call per turn, so a genuine dependency gets modeled as separate turns instead of a single batch.

• •Genuine sequential dependency -- each tool call's result determines the next call's arguments, so batching them would require guessing inputs that don't exist yet.
• •Auditability or replay invariants -- some systems require a strict one-call-per-turn trace for logging, replay, or compliance reasons, independent of whether the calls are logically independent.

It's tempting to think more tools is strictly more capability. In practice, a large catalog of overlapping tools actively hurts selection: every tool definition sits in context on every turn, and when two or three tools could plausibly handle the same request, Claude has to guess among near-duplicates instead of picking confidently. The fix is to right-size the tool set — give Claude a focused, non-overlapping list scoped to the actual task, rather than exposing every capability your system happens to have.

Put the whole lesson together and a pattern emerges: every piece of tool design — the loop, the execution model, the description, the schema, the error handling, the set size — exists to make one thing true as often as possible: Claude picks the right tool, calls it with well-formed arguments, and can recover cleanly if something goes wrong. That's the entire job of tool implementation.