Tools and Agents

Introduction

A model by itself only produces text. It cannot check today's weather, query your database or send an email. Tools let it ask your code to do those things. Combine tools with a loop, and you get an agent, an AI that works toward a goal in several steps.

Tool use, step by step

1. You tell the model which tools exist, each with a name, a description and the parameters it takes, usually described as JSON.
2. The user asks something: "What is the status of order 1042?"
3. The model decides a tool is needed, and replies with a tool call, such as get_order_status with order_id: 1042. It does not run anything itself.
4. Your code runs the real function, and sends the result back.
5. The model uses the result to write the final answer.

A tool definition looks like this, in simplified form:

{
  "name": "get_order_status",
  "description": "Look up the status of a customer order by its number.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "integer" }
    },
    "required": ["order_id"]
  }
}

Clear names and descriptions matter. The model chooses tools by reading them.

The agent loop

An agent repeats a cycle until the task is done:

1. Think: the model decides what to do next, given the goal and what has happened so far.
2. Act: it calls a tool.
3. Observe: your code returns the result.
4. Repeat, or give the final answer.

Examples: a research agent that searches, reads pages and writes a summary, or a coding agent that edits files and runs tests. Always set a maximum number of steps so a confused agent cannot loop forever or run up a huge bill.

Design principles

• Start simple. A fixed workflow of prompts often beats a free-roaming agent, and is easier to test and cheaper.
• Few, well-described tools beat many vague ones.
• Return clear results and clear errors so the model can recover.
• Keep a log of every step and tool call for debugging and audit.

Guardrails

Agents can take actions with real consequences, so limit them.

• Least privilege: give tools only the access they need. Prefer read-only tools.
• Human approval for risky actions such as sending messages, spending money, deleting data or changing production systems.
• Validate inputs to tools. Never run model-generated text directly as code or commands without checks, ideally in a sandbox.
• Limits on steps, time, spending and data touched.
• Treat all fetched content as untrusted. A web page or email can contain hidden instructions aimed at the model. This is called indirect prompt injection, and it is one of the main risks of agents. Do not let content from outside override your instructions or trigger sensitive tools.

When agents are worth it

Use an agent when the steps cannot be known in advance, and a wrong action is cheap or reversible. Use a fixed workflow when the steps are known. Measure results before trusting an agent with more.

Try it yourself

Design an agent that helps customers track orders. List its tools, which ones are read-only, which action would need human approval, the step limit, and one prompt injection attack you must defend against.

Summary

• Tool use lets a model request actions, while your code runs them and returns the results.
• An agent loops through think, act and observe, with step limits.
• Use least privilege, human approval, sandboxes and logging, and treat outside content as untrusted.