Claude tool use: building agents that take real actions

How tool use works under the hood

Tool use in the Claude API works through a specific message format. You provide Claude with a list of tool definitions — each with a name, description, and JSON Schema for the input parameters. When Claude decides a tool should be called, it returns a tool_use content block instead of (or alongside) text, specifying the tool name and the parameter values it wants to pass. Your code executes the actual function call and returns the result in a tool_result content block. Claude then continues generating with the tool result in context.

The model doesn't actually call any functions. It generates a structured request for a function call, and you execute it. This separation is important: it means you have full control over what actually happens when Claude 'calls' a tool. You can validate the parameters, check permissions, rate-limit, log the call, and handle errors before anything reaches your actual API or database. The model is making requests; your code is deciding whether to fulfil them.

Claude can call multiple tools in a single turn and can call tools iteratively — looking at the result of one tool call and deciding to call another based on what it finds. This is what makes tool-using Claude capable of complex multi-step tasks: it can query a database, examine the results, formulate a follow-up query, examine those results, and produce a final answer that synthesises information from multiple sources.

Designing tools that Claude uses reliably

Tool design is the most underrated part of building tool-using agents. A tool with a clear name, a precise description, and a well-typed parameter schema will be called correctly in situations where a vaguely described tool with loose parameter types will be called with wrong arguments or not called at all. The description is how Claude understands when to use the tool and what to expect from it.

Write tool descriptions from Claude's perspective. The description should answer: what does this tool do, when should I call it, what parameters does it need, and what does it return? Be explicit about what the tool does and doesn't do. If a tool queries only the current user's orders, the description should say 'retrieves orders for the currently authenticated user' rather than just 'retrieves orders' — this prevents Claude from trying to use it in contexts where it would be wrong.

Keep tools narrow and single-purpose. A tool that does one thing is easier for Claude to use correctly than a tool that does many things based on a 'mode' parameter. If you find yourself building tools with complex branching logic inside them, consider whether they should be separate tools. The model is good at choosing between multiple simple tools; it's worse at managing complex internal logic within a single tool.

Safety patterns: confirmation, permissions, and audit trails

The most important safety pattern for tool-using agents is the confirmation step for irreversible or high-impact actions. Before executing any action that can't be easily undone — sending an email, processing a payment, deleting data — show Claude's planned action to a human and require explicit approval. This breaks the autonomy of the agent for high-stakes operations and puts a human in the loop where it matters.

Implement permission scoping at the tool level. The tools you provide to Claude define what it can do. If Claude doesn't have a tool to delete user accounts, it can't delete user accounts, regardless of what it's asked to do. Define the minimum set of tools required for the agent's task and resist the temptation to give Claude broad access 'in case it needs it.' The smallest permission set is the safest permission set.

Log every tool call with the full request and response. This isn't just for debugging — it's for accountability. If an agent takes an action that causes a business impact, you need to be able to trace exactly what input led to the tool call, what Claude's reasoning was (available from the text around the tool_use block), and what the tool returned. Without this audit trail, AI agents are accountability black boxes.

• Read-only tools: no confirmation required, log all calls
• Write tools with easily reversible effects: log, enforce rate limits
• Write tools with hard-to-reverse effects: require explicit confirmation
• Irreversible actions (delete, send, pay): require human approval + double confirmation
• All tool calls: log request, response, timestamp, model version, and calling context

Error handling in tool use flows

Tool calls fail. APIs return errors, required data is missing, permissions are denied. Claude needs to receive these errors in a way that allows it to respond appropriately — either by trying a different approach, asking the user for the missing information, or communicating clearly that it can't complete the requested action.

Return structured errors in tool_result blocks, not unhandled exceptions. The error should include a machine-readable error code and a human-readable message. Claude uses the error message to understand what went wrong and formulate a response or retry strategy. A generic '500 Internal Server Error' gives Claude nothing to work with. 'Error: customer ID CUST-12345 not found in the system' allows Claude to tell the user specifically what happened.

Decide how you want Claude to handle specific error types before they occur in production. API rate limits should trigger a backoff and retry. Missing required permissions should cause Claude to explain the limitation to the user, not attempt a workaround. Data validation errors should cause Claude to ask the user to correct the input. Documenting these expected behaviours in your system prompt helps Claude respond consistently.

Deploying tool-using agents in production

The gap between a tool-using demo and a production tool-using agent is mostly operational infrastructure. The demo works when the happy path executes correctly. Production needs to handle every unhappy path, maintain an audit trail, enforce rate limits, monitor for unusual behaviour, and degrade gracefully when any component fails.

Set token budgets for production agents. An agent that can consume unlimited tokens per conversation is a financial and operational risk. Set a maximum token budget per conversation and per user per day. When the budget is approaching, have the agent summarise its progress and stop rather than continuing indefinitely. Most legitimate use cases complete well within reasonable token budgets; runaway behaviour is usually a signal of a prompt or input problem.

Test your agents against adversarial inputs before deploying them broadly. Give them prompts designed to elicit tool calls they shouldn't make, inputs designed to confuse the intent classification, and instructions that contradict your system prompt. The goal isn't to find every possible attack — it's to find the obvious ones and fix them before real users try them. Security testing for AI agents is an ongoing process, not a one-time gate.