AI Agents fundamentals · Lesson 2
Tool use: how to describe tools
Good practices for describing tools, handling errors, and validating inputs/outputs.
A tool description is an API contract
When you give the model a tool, it reads the description as a contract. The quality of the description directly affects the quality of the choice and arguments.
What to write in the description
- What it does. "Search across our document corpus via an embedding DB."
- When to use it. "If the user asks about internal company documents."
- When NOT to use it. "If the question is about current news — that's not our corpus."
- Arguments. Name, type, description.
- What it returns. The response structure.
Error handling
- Every tool should be able to return
status: "error", message: "..."in a clear way. - The agent must see the error and have a chance to try a different path.
Validation
- Tool arguments — via JSON Schema / zod.
- If the model returned invalid arguments — return an error and ask it to correct itself, don't fail silently.
Practical exercise
What to do after this lesson
Describe 3 tools for your scenario using the structure "what it does / when to use / when NOT to / arguments / returns."
Task grader
Describe 3 tools for your scenario using the structure "what it does / when to use / when NOT to / arguments / returns."
Ready-to-use prompt
Template for this lesson
Copy and adapt to your context. Text in angle brackets should be replaced.
Describe a tool by its contract: name: <…> description (what it does): <…> when_to_use: <…> when_not_to_use: <…> arguments: <…> returns: <…> errors: <…> This will be passed to the LLM as the tool description.
Prompt sandbox
Common mistakes
What people get wrong
- Describing the tool as a "function," with no "when to use."
- Not providing for error returns.
- Not validating arguments.
Pro tips
What works but no one documents
- "When NOT to use it" is the most valuable item in the description.
- Return structured JSON, not free text.
- Log every tool call with its arguments and responses.
When to use
Any agentic system.
When not to use
A chat with no tools.
Official sources
Quiz — 2 questions
1.The most valuable item in a tool description?
2.What does a well-designed tool return?
Answered: 0 of 2
Discussion
No comments yet. Be the first!