daBongo LMS AI Training Courses

← Back to Course

Claude API in Practice – A Complete Developer Reference

Lesson 3: Tool Use – Connecting Claude to Your Code

Lesson Objectives

By the end of this lesson, students should be able to:

  • Define a tool in the API request format
  • Implement the tool use request/response cycle
  • Handle tool results correctly in the conversation
  • Distinguish when tool use is the right approach vs. alternatives

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.

“json { "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.

Practical Example

A customer support chatbot uses a get_order_status tool.

First implementation: the description says "look up an order." Claude calls it for questions that do not relate to order status – product questions, return requests.

Second implementation: description says "look up the current shipping status and estimated delivery date for a specific order ID.

Use this only when a customer asks about the status or location of an existing order." Irrelevant tool invocations drop by 90%.

The description change – not a code change – fixed the behavior.

Safety Notes

Tool use gives Claude the ability to trigger real actions in your application. For tools that write data, spend money, send communications, or take other real-world actions: implement a confirmation step before execution rather than executing immediately on Claude's tool call. Claude may invoke tools with unexpected parameters. Validate all tool parameters in your application code before executing – treat Claude's tool call parameters as untrusted input.

Log in and enroll to access lesson quizzes.

← Back to Course

Scroll to Top