Lesson Content

What tool use is.

Tool use (also called function calling) is a mechanism that allows Claude to request that your application run a function and return the result. Claude does not execute code – it generates a structured request containing the function name and parameters. Your application executes the function, captures the result, and returns it to Claude in the next turn.

This enables Claude to access: real-time data (current prices, inventory, weather), application state (user account, order history), and external APIs (database queries, third-party services) – things Claude cannot know from training data alone.

Defining a tool.

{
"name": "get_order_status",
"description": "Look up the current status of a customer order by order ID. Returns the order status, estimated delivery date, and last tracking update.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order ID from the customer's confirmation email, format ORD-XXXXXX"
}
},
"required": ["order_id"]
}
}

The description field is read by Claude when deciding whether and how to use the tool. Write it precisely – it is a prompt to Claude about when to invoke the tool and what information it returns.

The tool use cycle.

1. Application sends a request with tools array defined
2. Claude decides a tool is needed and responds with stop_reason: "tool_use" and a tool_use content block containing the function name and parameters
3. Application executes the function with Claude's parameters
4. Application sends a new request appending: the assistant turn (Claude's tool use request) and a user turn containing the tool_result block
5. Claude generates the final response using the tool result

Steps 3-5 happen in your application code. Claude sees the tool result as a user message and uses it to generate the final response to the user.

Tool description quality matters.

The description field is the primary signal Claude uses to decide when to call a tool. A vague description produces incorrect or missed tool calls. A precise description – including what data the tool returns, when it applies, and the format of required parameters – produces reliable tool invocation.