The tool-use loop

A model can't query your database or call an API. It can only produce text. Tool use, also called function calling, lets it request an action: you describe tools with a name, a description and a JSON Schema for the input. When the model decides it needs one, it stops and returns a structured tool call instead of a final answer. Your code runs the tool and sends back the result.

user: "Is order 1042 shipped?"
  → model:  tool_use get_order({"id": 1042})          (stop_reason: tool_use)
  → you:    run get_order → {"status": "shipped", "carrier": "UPS"}
  → send:   tool_result for that call
  → model:  "Yes — order 1042 shipped via UPS."         (stop_reason: end_turn)

#The loop

messages = [{"role": "user", "content": question}]
for _ in range(10):                                   # always cap the steps
    response = client.messages.create(model=MODEL, max_tokens=1024, tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason != "tool_use":
        break                                         # final answer
    results = [
        {"type": "tool_result", "tool_use_id": block.id, "content": run_tool(block.name, block.input)}
        for block in response.content if block.type == "tool_use"
    ]
    messages.append({"role": "user", "content": results})

The model may ask for several tools in one turn. Run them, in parallel if they're independent, and return every result. That loop, given a goal and run until it finishes, is an agent.

#Designing tools

• Descriptions are prompts. Say what the tool does, when to use it, what each parameter means, and what it returns. Most "the model picked the wrong tool" bugs are description bugs.
• Make tools few and task-shaped. search_orders(customer_email, status) beats exposing raw SQL, and five clear tools beat thirty overlapping ones.
• Return compact, useful results. Large payloads fill the context window. Return what the model needs plus an ID it can use to fetch more.
• Return errors as results. "No order with id 1042" lets the model recover. Throwing ends the loop.

#Safety

• Validate tool input like any untrusted input. The model's arguments are only well-formed if you check them; structured outputs can enforce the schema.
• Apply least privilege. Use read-only tools by default, scoped to the current user's data.
• Require confirmation for anything irreversible, like sending, paying or deleting, because text the model reads can carry instructions. See prompt injection.
• Cap steps, tokens and time, and log every call.