Designing Tools an Agent Can Actually Use
Write tool names, descriptions, inputs and error messages that make agents choose and call tools correctly
A taste of a lesson
My tool is called get_data with the description 'Gets data from the system'. The agent uses it for everything. What should I change?
The model is doing its best with no information. 'Gets data from the system' matches almost any request, so it becomes the default. First, ask what job this tool really does. If it looks up a customer by email, call it find_customer_by_email and describe it: 'Returns name, plan and account status for one customer. Use when the user gives an email address. Do not use for order history.' Then add a required email parameter. Your turn: what does get_data actually return today, and in which situations should the agent avoid it?
Written by the teacher as an example. In your lesson the tutor answers your own questions, and like any AI it can be wrong.
What you will be able to do
- Write tool names and descriptions that tell a model when and when not to use each tool
- Design input schemas with types, enums and formats that reduce invented arguments
- Shape tool outputs and errors so the agent can decide its next step
- Consolidate overlapping tools into fewer task shaped tools
- Test a tool set by reading which tools an agent chose across varied tasks
Lesson plan
- 1 Tools are documentation for a model Understand that a model knows a tool only through its name, description, schema and results. Start
- 2 Input schemas that prevent guessing Design parameters that guide the model to valid, complete arguments. Start
- 3 Task shaped tools versus endpoint wrappers Decide how to group operations into tools that match what the agent needs to do. Start
- 4 Outputs the model can use Return results that help the model decide its next step without flooding its context. Start
- 5 Errors and safe write actions Design failures and side effects so agents recover and do no harm by repetition. Start
- 6 Testing a tool set Evaluate tool design by running varied tasks and reviewing which tools were called. Start
Try asking
About this tutor
For developers who have built a first agent and noticed it calling the wrong tool, inventing arguments or giving up after an error. Tool design is the most underrated part of agent work: the model only knows your tools through their names, descriptions, schemas and results. In these lessons you will review real looking tool sets, rewrite weak descriptions, decide how many tools to expose, shape outputs so the model can use them, and design error messages that help it recover. You will finish with a checklist you can apply to any tool set before it ships.
Reviews
4.7
3 ratingsSample
- Tom B.Sample
Pasted my real tool set and got a line by line critique. Humbling and useful.
- Elif K.Sample
Practical and specific. The error message lesson changed how I write all my functions, not only agent tools. Slightly fast in the schema part.
- Rahul M.Sample
We merged eleven tools into four after lesson three and the wrong tool calls mostly disappeared. The 'documentation for a new teammate' framing is exactly right.
About the teacher
I teach how AI agents are built: the loop, the tools, the memory, and when a plain workflow is the better choice
9 tutors 310 lessons taught Sample
I build and teach the inner workings of AI agents. Most of my working life has been spent on backend systems, so I approach agents the way I approach any distributed system: what runs, in what order, what can fail, and what it costs. I like to start every topic with a drawing of the loop on a whiteboard and...
See Hiroshi's profile and tutorsMore like this
Other tutors on the same or nearby topics.