Agents & Tool Use

An agent is a loop: the model reads the situation, picks a tool, the tool runs, the result goes back into context, and it decides again. Everything hard about agents comes from that loop being open-ended.

Tool descriptions are the interface. The model selects a tool by reading its name, description, and parameter schema. A vague description is a bug — it produces wrong tool choices that look like model failures. Write them for a competent stranger: what it does, when to use it, when not to, and what it returns.

Fewer, sharper tools beat many overlapping ones. Twenty tools with fuzzy boundaries produce worse selection than six with crisp ones. If two tools are frequently confused, that is a design problem, not a prompting problem.

Errors are context, not exceptions. A tool that fails should return a message the model can act on — "no user with that id; try search_users" — because the model's only view of the world is what comes back. An opaque stack trace wastes a turn.

Bound the loop. Cap iterations, cap cost, and detect repetition: an agent that calls the same failing tool five times needs to stop, not persist. Without limits, a confused agent burns budget indefinitely.

Decide what needs a human. Reads are cheap to get wrong; writes are not. Sending an email, moving money, deleting data, or pushing code deserve confirmation, and the boundary should be explicit in the design rather than emergent.

Prompt injection is the defining risk. Anything the agent reads — a web page, an issue, a file, a tool result — may contain text aimed at the model. Treat all of it as data, never as instructions, and never let retrieved content silently escalate what the agent is permitted to do.

Evaluate the trajectory, not just the answer. An agent that reaches the right result after twelve wasted calls is a different system from one that takes two, and only trajectory-level evaluation tells them apart.