Tools & Agentic Loops

Why tool calling?

LLMs are powerful at language — but they can't do everything alone. Tool calling lets the model delegate to systems better suited for each sub-task.

Example: weather forecast

1. User:    "What's the weather in Paris tomorrow?"
2. LLM:     → tool_call: get_weather(city="Paris", date="tomorrow")
3. Tool:    → {"forecast": "Partly cloudy, 18C, 30% chance of rain"}
4. LLM:     "Tomorrow in Paris: partly cloudy, around 18C with a 30% chance of rain."

The model can't check the weather — but it can call a tool that does, then synthesize the result into a natural answer.

Manual vs API-native tool calling

Side by side

Native tool calling gives you better plumbing. It does not eliminate the orchestration problem.

Registering tools & the single-call round trip

Tool schemas

You describe each tool as a JSON schema. The model never sees your Python code — only these descriptions.

{
  "type": "function",
  "function": {
    "name": "explore_data",
    "description": "Inspect dataset schema, missing values, and candidate targets. Call first when the dataset structure is unknown.",
    "parameters": {
      "properties": {
        "sample_rows": {"type": "integer", "description": "Number of sample rows to return"}
      },
      "required": ["sample_rows"]
    }
  }
}

The round trip (single tool call)

# Step 1: send query + tool schemas
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": user_query}],
    tools=TOOL_SCHEMAS,
    tool_choice="auto",
)
msg = response.choices[0].message

# Step 2: model wants to call a tool
tc = msg.tool_calls[0]
args = json.loads(tc.function.arguments)
result = explore_data(**args)

# Step 3: send result back → model produces final answer
response2 = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": user_query},
        msg,
        {"role": "tool", "tool_call_id": tc.id, "content": json.dumps(result)},
    ],
    tools=TOOL_SCHEMAS,
)
print(response2.choices[0].message.content)

Built-in tools

LLM providers also offer ready-made tools executed on their infrastructure — zero tool code from you:

Convenient for general capabilities, but for domain-specific work you need your own tools.

Observe → Decide → Act → Observe → …

Real questions often need multiple tool calls before the model can answer.

while has_budget:
    response = LLM(messages, tools)
    if response has tool_calls:
        execute each tool; append results
    else:
        return response.text  # model decided it's done

Two critical design choices:

1. Max iterations — prevent infinite loops
2. The model decides when to stop — it produces text (not a tool call) when it has enough info

Example: data analyst agent

Three tools with natural preconditions and dependencies:

Different queries → different tool traces

"What kind of data is this?"
  → explore_data → ANSWER

"Are there natural customer segments?"
  → explore_data → cluster_data → ANSWER

"Segments AND churn prediction for age=29, income=42k..."
  → explore_data → cluster_data → classify_data → ANSWER

The model must reason about which tool to call next based on what it's learned so far.

When to continue, when to stop

APIs solve the syntax of tool calling. The hard part is the control policy.

After each tool result, continue only if all three are true:

1. Some part of the original goal is still unresolved
2. Another available tool can resolve it
3. The next tool call is necessary, not merely interesting

Common failure modes

Asking instead of guessing

The model has three options at each step:

1. Call a tool — if it knows which tool and has all parameters
2. Ask a question — if information is missing or ambiguous
3. Answer directly — if it already has enough information

Without vs with clarification instructions

This is just a system prompt instruction — the model chooses to produce text (a question) instead of a tool call:

IMPORTANT: If the user's request is ambiguous or missing required information
(e.g., which columns to use, what to predict, how many clusters), ask a
clarification question instead of guessing. Respond with text, not a tool call.

Full clarification flow

User:      "Predict something for a customer."
Assistant: "What should I predict? And what are the customer's details?"
User:      "Predict churn. age=29, income=42k, spend=180, visits=4, tickets=3."
Assistant: → explore_data(...)  → classify_data(...)  → "This customer has a 73% churn risk."

Good names and descriptions directly impact accuracy

The model picks tools based on their name, description, and parameter names. Bad metadata = wrong tool calls.

Good vs bad

Best practices

Key points

1. Tool calling turns an LLM into a controller of external capabilities.
2. Provider APIs give you reliable structure — no more parsing JSON from text.
3. The real challenge is the loop: when to call another tool, when to stop, when to ask the user.
4. Preconditions matter: explore first, then decide which tools are valid.
5. Good tool names and descriptions directly impact model accuracy.
6. Asking for clarification is itself a powerful capability — the model's most flexible "tool."