Open this lesson in your favourite AI. It'll walk you through the why, explain the demo, and quiz you on the try-it list.
Tool descriptions are prompts. The model decides whether to call a tool based on its description, picks input values based on the schema's descriptions, and interprets results based on what the tool returns. Bad tool docs = the agent picks wrong tools, passes wrong arguments, misinterprets results. Good tool design is half the agent's behavior. Treat your tool surface like the API your model is consuming — because it is.
Rules: (1) Tool name should be a verb_noun ('search_docs', not 'docs'). (2) Description starts with WHEN to use it, not what it does. (3) Input parameters have descriptions, not just types. (4) Return values are structured (JSON), not free-form text. (5) Errors are explicit ('city not found' vs raising an exception). (6) ≤ 5-7 tools at once — more confuses the model. Apply these and your agent's tool-picking accuracy jumps significantly.
Use these three in order. Each builds on the one before.
Name 3 rules of good tool design and explain why each matters.
Walk me through what happens internally when the model picks a tool: how does the description factor in, and what makes one tool 'more likely' than another?
Design tool descriptions for a 5-tool catalog: docs search, DB query, web search, calendar, email. What's the WHEN-to-use heuristic for each, and how do they not overlap?
# BAD tool design
{
"name": "lookup",
"description": "looks up info",
"input_schema": {"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]},
}
# Issues: vague name, no when-to-use, no input description
# GOOD tool design
{
"name": "search_internal_docs",
"description": (
"Search the company's internal documentation. Use this when the user asks about "
"company policies, internal procedures, or product features specific to CapstokApp. "
"Do NOT use for general programming questions (the model knows those). "
"Returns up to 5 relevant document excerpts."
),
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "A focused search phrase, 3-10 words. Prefer the vocabulary used in the user's question.",
},
"filter_section": {
"type": "string",
"enum": ["engineering", "policy", "support"],
"description": "Optional: narrow to a section if the question clearly belongs to one.",
}
},
"required": ["query"],
},
}
# Return structured JSON, not prose
def search_internal_docs(query, filter_section=None):
hits = retrieve(query, filter_section)
return {
"hits": [
{
"title": h.title,
"section": h.section,
"snippet": h.text[:400],
"url": h.url,
}
for h in hits[:5]
],
"n_total": len(hits),
}python3 main.py