AI Agents and Tool Use

Gains:

• Defining an agent as 'model + tools + loop' and deciding when it is needed
• Writing the tool definition with name, description and input_schema
• Monitoring the flow and error handling of the tool_use and tool_result loop

Until now, the model has always done one job: receive text input, produce text responses. But real work often requires more than text; performing a calculation, querying a database, calling an API, finding out a current exchange rate. The model cannot do these things herself — but she can decide when they need to be done and ask someone to do them. This is what tool use gives the model, and this is the basis of AI agents. In this unit, we will learn what an agent is, how the tool is defined, and how the tool_use loop works.

What is an Agent? Model + Tools + Loop

An AI agent consists of three parts: the model (the brain that makes the decision), the tools (the functions the model can call: weather, database query, send email), and the loop (the loop; the model calls the tool, gets the result, decides again what to do, and so on).

Critical distinction: A single pattern call is not an agent. Agent is a process in which the model proceeds step by step, at each step choosing the next move based on the tool outcome. "Think like a human, use your hands, look at the result, think again."

An important fact: The model itself does not operate the vehicle. The model just says "I want to call this tool with these inputs". Your application (called a harness) runs the tool and returns the result to the model. This is vital for security: the model does not directly touch your system; Every action is under your control.

Tip: Don't try to solve every problem with the agent. Agent; increases the risk of delays, costs and errors. Ask first: “Will this be solved with a single call or a fixed workflow?” If the answer is yes, there is no need for an agent. Agent is for open-ended tasks where the steps cannot be known in advance.

Tool Definition: name, description, input_schema

To introduce a tool into the model, you give three things:

• name: Identity of the vehicle, e.g. get_weather.
• description: What the tool does and when to call it. This is the most important area that allows the model to choose the right tool at the right time. Write not just "what does" but also "call when."
• input_schema (input schema): JSON schema that defines which parameters the tool expects, in which type.

# Vehicle definition (conceptual — JSON schema){ "name": "get_order_status", "description": "Retrieves the current shipping status of an order. Call when the user asks where an order number is or when it will arrive.", "input_schema": { "type": "object", "properties": { "order_no": {"type": "string", "description": "Order number, e.g. SP-1024"} }, "required": ["order_no"] }}

Rules for a good tool description: clear and concise name, description with "when to use", description for each parameter, putting the truly mandatory ones in required. Keep the number of vehicles focused; Dozens of similar vehicle models are surprising.

area

What does it do?

good example

bad example

name

Vehicle ID

order_status_getir

bring

description

What it does + when to call

"Returns the cargo status; call when the user asks where the order is"

"fetches data"

input_schema

Parameter type and requirement

{order_no: string, annotated}

no diagram / no description

tool_use → tool_result Loop

The cycle works like this, step by step:

1. You send the user question + tool descriptions to the model.
2. The model either responds directly or generates a tool_use block: "call order_durumu_getir with order_no=SP-1024."
3. Your application actually runs the tool (queries the database).
4. You send the result back to the model as tool_result.
5. With this result, the model either produces the final answer or calls another tool. The cycle continues until the model says "I'm done."

# Agent loop (conceptual)messages = [user_question]while True: response = model.uret(messages, tools=tool_definitions) if response.tur == "tool_use": result = harness.run(response.tool_name, response.entries) # APPLICATION runs messages += [response, tool_result(result)] # return result else: break # final response; loop ends

Modern SDKs offer tool runners that run this loop for you; you just write the tool functions. But that's exactly what's happening behind the scenes.

Error Management

Tools may fail: order not found, API times out, input is invalid. If you cannot run the tool, return the error to the model as a descriptive tool_result ("error: Order number SP-9999 not found") and the error flag. The model can see this and gently explain it to the user, or try a different way. Do not swallow the error and return empty results; The model must know what went wrong.

Weak/Strong Vehicle Description

Weak (indefinite noun, no "when"):

name: "data", description: "fetches data"# The model does not know when and how to call; It either doesn't call at all or calls incorrectly.

Strong (net name + when + parameter description):

name: "musteri_bakiyesi_getir"description: "Returns the current account balance of a customer. Call when the user asks for debit, credit or balance. DOES NOT make payment."input_schema: {custeri_id: string ("Customer ID")}# The model calls at the right time, with the right parameters, knowing its limit.

Three Mini Cases

Case 1 — Unnecessary agent. One team built the “summarize text” business with a multi-tool agent; Each recap takes 4 model calls and 9 seconds. The job was actually a one-call job. When we removed the agent and reduced it to a single call, the time decreased to 1.5 seconds and the cost decreased to one quarter. Lesson: use the agent when really necessary.

Case 2 — Weak explanation, wrong call. In a support agent, an obscure tool called fetch was randomly called by the model in both the balance question and the shipping question. When the vehicles were divided into balance_getir and cargo_durumu_getir and "call when" explanations were added, wrong vehicle selection decreased from 18 to 1 in 50 examples.

Case 3 — Error swallowed. An agent was returning empty results when the order was not found; The model interpreted this as "the order was delivered" and misled the customer. When the error message is written explicitly to tool_result ("order not found"), the model correctly says "I couldn't find this number, can you check it?" he started to say.

Common mistakes

• Turning everything to an agent: While one call is enough, the agent adds cost and delay.
• Vague vehicle description: The model does not know when to call; chooses wrong.
• Thinking that the model runs the vehicle: The harness runs the vehicle; the model just wants.
• Swallowing the error: The model must know what went wrong; Give the error as open tool_result.
• Too many similar vehicles: Model gets confused; Keep the toolset focused and minimal.

Attention: Just because the model says "call that vehicle" does not mean that action should be taken. On destructive tools (delete, checkout, email) your application should not blindly execute the call — this is the core of the security topic in the next unit.

In summary

• Agent = model (decision) + tools (functions) + loop (call tool, get result, decide again).
• A single pattern call is not an agent; agent is a step-by-step process.
• The model does not run the vehicle; Your application runs (harness) and returns the result as tool_result.
• The tool is identified by name, description (specifically "call when"), and input_schema.
• The loop continues as tool_use → harness runs → tool_result → model continues until the model says "done"; errors are explicitly reported to the model.

Application task

Design 3 tools from your own business that can be given to the agent. (1) Write name, description with "call when", and input_schema for each; Let at least one be a non-destructive reading tool and one a calculation. (2) Choose a realistic user question and manually write step by step (in a loop) which of these tools the model will call with which inputs and what it will do after the tool_result arrives. (3) Set up a scenario in which one of the tools fails and show how the error message will return to the model.

checklist

• [ ] I can define the agent as "model + tools + loop" and decide when it is needed.
• [ ] I know that the harness runs the vehicle, the model just wants it.
• I can write a solid vehicle description with [ ] name, description ("call when") and input_schema.
• I can follow the [ ] tool_use → tool_result cycle step by step.
• [ ] I report tool errors to the model as open tool_result.