Week 7: Tool Use — Giving Claude Real Actions to Take

1. Defining Tools with JSON Schema

A tool definition tells Claude three things: a name, a description of what it does and when to use it, and a JSON Schema describing its inputs. Claude reads the description the same way a junior engineer would read a function's docstring — vague descriptions produce misuse, specific ones don't.

tools = [
    {
        "name": "get_weather",
        "description": (
            "Get the current weather for a specific city. Use this "
            "whenever the user asks about current conditions, temperature, "
            "or forecast for a named location."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "The city name, e.g. 'Kolkata' or 'Tokyo'."
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit. Default to celsius."
                }
            },
            "required": ["city"]
        }
    }
]

You pass this tools list alongside the normal messages request. Claude decides on its own whether a given user message calls for a tool at all — passing tools doesn't force their use, it just makes them available.

2. The Tool-Use Loop

Claude never executes a tool itself — it only ever requests that your code run one, with specific arguments. Your application executes the real function, sends the result back, and Claude continues from there. This request-execute-return cycle is the whole mechanism behind tool use.

messages = [{"role": "user", "content": "What's the weather in Kolkata right now?"}]

response = client.messages.create(
    model="claude-sonnet-4-5", max_tokens=1024, tools=tools, messages=messages
)

while response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = run_the_real_tool(block.name, block.input)  # YOUR code
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(result),
            })

    messages.append({"role": "user", "content": tool_results})
    response = client.messages.create(
        model="claude-sonnet-4-5", max_tokens=1024, tools=tools, messages=messages
    )

print(response.content[0].text)  # the final, tool-informed answer

Note the tool_use_id — it links a specific result back to the specific call that requested it, which matters once there's more than one tool call to track. The loop keeps going as long as Claude keeps asking for more tools; it ends when stop_reason comes back as end_turn instead.

3. Chaining & Parallel Tool Calls

A single Claude turn can request more than one tool call at once — asking for the weather in three cities produces three tool_use blocks in one response, which your loop should execute and return together. Multi-step tasks (search, then calculate using the search result) chain naturally: each pass through the loop can trigger a different tool based on what came before.

# response.content might contain THREE tool_use blocks in one turn:
# [tool_use(get_weather, city="Kolkata"),
#  tool_use(get_weather, city="Tokyo"),
#  tool_use(get_weather, city="Berlin")]
#
# Your loop already handles this correctly because it iterates over
# EVERY block in response.content, not just the first one — execute
# each, collect all three tool_results, and send them back together.

This is a strong argument for making the loop generic (iterate over all blocks) rather than hardcoding "expect exactly one tool call" — real usage very quickly produces multi-tool turns once you give Claude more than one capability at a time.

4. Designing Tools Claude Can Use Reliably

A few concrete habits separate tools Claude uses correctly from ones it keeps misusing:

# 1. Narrow, single-purpose tools beat one giant do-everything tool
BAD:  manage_database(action, table, data)   # "action" hides 5 behaviors
GOOD: get_record(table, id) / create_record(table, data) / ...

# 2. Return structured, informative errors — not silent failures
BAD:  return None   # Claude has no idea it failed or why
GOOD: return {"error": "city not found", "suggestion": "check spelling"}

# 3. Descriptions state WHEN to use the tool, not just what it does
BAD:  "Searches the database."
GOOD: "Searches the customer database by email or name. Use this before
       claiming you don't have information about a specific customer."

Informative errors matter more than they seem: if a tool fails silently, Claude has no signal to try a different approach and may confidently report success anyway. A clear error message gives Claude something to react to — retry with different arguments, try a different tool, or tell the user what actually went wrong.

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.