Giving an AI Assistant Real Tools

Errors are instructions

When a tool fails, whatever you return goes straight back into the model's context and shapes what it tries next. A generic failure message gives it nothing to work with, so it retries the same call. A message that says what was wrong and what is valid gets a corrected call instead.

That makes error text part of your interface rather than an afterthought. Treat it with the same care as the schema, because it is read by the same reader.

Start with what users repeat

The best first tools are the actions users perform constantly and find tedious. They are well understood, easy to validate, and the assistant is immediately useful. Ambitious tools that chain many steps are better added once the simple ones are proven, because a failure deep in a chain is much harder to diagnose.

Frequently Asked Questions

What should a tool return when it fails?

A specific message describing what was wrong and what would be valid. The model reads it and adjusts, whereas a generic failure produces an identical retry.

Which tools should I add first?

The actions users already repeat. They are easy to validate and immediately useful, unlike multi-step tools that are hard to debug when they fail midway.