Tool Use and Function Calling

Building an agent requires more than just processing text prompts; it needs the ability to perform real-world actions. Imagine your agent is like a specialized office assistant who manages your schedule but lacks the authority to book actual flights. Without the power to interact with external systems, the assistant remains trapped inside the digital office, unable to finish the tasks you assigned. By integrating tools, you grant your agent the necessary access to bridge the gap between intent and execution.

Defining Capabilities through Function Declarations

To enable these capabilities, you must provide the Claude SDK with clear function declarations. These declarations act as a formal contract between the model and the external service, outlining the required parameters and the expected output format. When you define these functions, you are essentially creating a menu of services the agent can choose from based on the user request. The agent analyzes the available options, selects the one that matches the task, and generates a structured request for that function. This process ensures that the agent only attempts actions it is authorized to perform, maintaining a secure boundary between the model and your underlying infrastructure.

Mapping Agent Logic to Executable Code

Once the agent identifies the need for a specific function, it produces a tool use request instead of a standard text response. Your application code must intercept this signal, execute the actual logic, and pass the results back into the conversation history to complete the loop. Think of this as a restaurant order system where the agent is the waiter, the function declaration is the printed menu, and your backend code is the kitchen that prepares the meal. If the waiter tries to serve a dish that is not on the menu, the system rejects the request to prevent errors. By mapping these capabilities carefully, you ensure that the agent can reliably fetch data, update databases, or trigger external processes without confusion.

const weatherTool = {
  name: "get_weather",
  description: "Fetch current weather data",
  input_schema: { type: "object", properties: { city: { type: "string" } } }
}; // [1]
const response = await client.messages.create({ ...tools: [weatherTool] }); // [2]
if (response.stop_reason === "tool_use") { // [3]
  const toolCall = response.content.find(c => c.type === "tool_use");
}

Managing State and Context for Reliable Execution

Successful tool use depends on maintaining a clean and accurate conversation history. Every time a tool is executed, the resulting data must be appended to this history to inform the model of the outcome. If the agent calls a weather function, it needs the temperature data in the next turn to provide a helpful answer to the user. Without this state management, the agent would lose track of what it just did, leading to repetitive or disconnected interactions. Proper state handling allows the agent to reason about the results of its actions, enabling complex multi-step workflows where one tool output feeds into the next input parameter.

Handling Errors and Unexpected Inputs

Even with perfect definitions, external services may fail or return data that the agent does not expect. You must implement robust error handling to guide the agent when a tool call does not go as planned. If a weather service is offline, the agent should receive an error message in the history rather than a silent failure. This allows the model to explain the situation to the user or attempt a different strategy. By treating errors as just another type of message, you keep the agent in control of the conversation flow even when underlying systems encounter technical difficulties.

---

Tool use transforms a static language model into an active agent capable of interacting with external data and services.

The next station will explore how to chain multiple tool calls together to automate complex multi-step workflows.